Main Content

cdfread

Read data from Common Data Format (CDF) file

Syntax

data = cdfread(filename)
data = cdfread(filename,param1,val1,param2,val2,...)
[data,info] = cdfread(filename,...)

Description

data = cdfread(filename) reads all the data from the Common Data Format (CDF) file specified by filename. Specify filename as a string scalar or character vector. CDF data sets typically contain a set of variables of a specific data type, each with an associated set of records. A variable might represent time values with each record representing a specific time that an observation was recorded. cdfread returns all the data in a cell array where each column represents a variable and each row represents a record associated with a variable. If the variables have varying numbers of associated records, cdfread pads the rows to create a rectangular cell array, using pad values defined in the CDF file.

Note

Because cdfread creates temporary files, the current working directory must be writable.

data = cdfread(filename,param1,val1,param2,val2,...) reads data from the file, where param1, param2, and so on, can be any of the parameters listed in this table.

[data,info] = cdfread(filename,...) returns details about the CDF file in the info structure.

ParameterValue
"Records"

A vector specifying which records to read. Record numbers are zero-based. cdfread returns a cell array with the same number of rows as the number of records read and as many columns as there are variables.

"Variables"

A 1-by-n or n-by-1 cell array specifying the names of the variables to read from the file. n must be less than or equal to the total number of variables in the file. cdfread returns a cell array with the same number of columns as the number of variables read, and a row for each record read.

"Slices"

An m-by-3 array, where each row specifies where to start reading along a particular dimension of a variable, the skip interval to use on that dimension (every item, every other item, etc.), and the total number of values to read on that dimension. m must be less than or equal to the number of dimensions of the variable. If m is less than the total number of dimensions, cdfread reads every value from the unspecified dimensions ([0 1 n], where n is the total number of elements in the dimension.

Note: Because the 'Slices' parameter describes how to process a single variable, it must be used in conjunction with the 'Variables' parameter.

"ConvertEpochToDatenum"

A Boolean value that determines whether cdfread automatically converts CDF epoch data types to MATLAB® serial date numbers. If set to false (the default), cdfread wraps epoch values in MATLAB cdfepoch objects.

Note: For better performance when reading large data sets, set this parameter to true.

Note: If you use the "ConvertEpochToDatenum" parameter, you cannot use the "DatetimeType" parameter.

"DatetimeType"

A string scalar or character vector that controls the return type of CDF_TIME_TT2000 and CDF_EPOCH data types. If set to "datetime" (the default for CDF_TIME_TT2000), cdfread returns values as type datetime; if set to "native", cdfread returns CDF_TIME_TT2000 values as type int64 and CDF_EPOCH values as type double.

Note: If you use the "DatetimeType" parameter, you cannot use the "ConvertEpochToDatenum" parameter.

"CombineRecords"

A Boolean value that determines how cdfread returns the CDF data sets read from the file. If set to false (the default), cdfread stores the data in an m-by-n cell array, where m is the number of records and n is the number of variables requested. If set to true, cdfread combines all records for a particular variable into one cell in the output cell array. In this cell, cdfread stores scalar data as a column array. cdfread extends the dimensionality of nonscalar and string data. For example, instead of creating 1000 elements containing 20-by-30 arrays for each record, cdfread stores all the records in one cell as a 1000-by-20-by-30 array.

Note: If you use the "Records" parameter to specify which records to read, you cannot use the "CombineRecords" parameter.

Note: When using the "Variable" parameter to read one variable, if the "CombineRecords" parameter is true, cdfread returns the data as an m-by-n numeric or character array; it does not put the data into a cell array.

Note

To improve performance when working with large data files, use the "ConvertEpochToDatenum" and "CombineRecords" options.

Note

To improve performance, turn off the file validation which the CDF library does by default when opening files. For more information, see cdflib.setValidate.

Examples

collapse all

Read all the data from a CDF file.

data = cdfread("example.cdf");

Read data from the CDF variable 'Time'.

data = cdfread("example.cdf","Variable",{"Time"});

Read the first value in the first dimension, the second value in the second dimension, the first and third values in the third dimension, and all values in the remaining dimension of the CDF variable 'multidimensional'.

data = cdfread("example.cdf","Variable",{'multidimensional'},"Slices", [0 1 1; 1 1 1; 0 2 2]);

This is similar to reading the whole variable into data and then using matrix indexing.

data = cdfread("example.cdf","Variable",{'multidimensional'});
data{1}(1,2,[1 3],:);

Collapse the records from a data set and convert CDF epoch data types to MATLAB serial date numbers.

data = cdfread("example.cdf","CombineRecords",true,"ConvertEpochToDatenum",true);

This example shows how to use cdfread to read CDF_TIME_TT2000 data.

Explore data in example CDF file.

info = cdfinfo("example_364.cdf");
info.Variables
ans=8×6 cell array
  Columns 1 through 5

    {'Time'            }    {[    1 1]}    {[24]}    {'epoch' }    {'T/'    }
    {'Longitude'       }    {[    2 2]}    {[ 1]}    {'int8'  }    {'F/FT'  }
    {'Latitude'        }    {[    2 2]}    {[ 1]}    {'int8'  }    {'F/TF'  }
    {'Data'            }    {[  2 2 4]}    {[ 1]}    {'double'}    {'T/TTT' }
    {'multidimensional'}    {[2 2 3 4]}    {[ 1]}    {'uint8' }    {'T/TTTT'}
    {'Temperature'     }    {[    3 2]}    {[10]}    {'int16' }    {'T/TT'  }
    {'multiInt8'       }    {[    2 3]}    {[ 2]}    {'int64' }    {'T/TT'  }
    {'tt2000'          }    {[    1 1]}    {[ 8]}    {'tt2000'}    {'T/'    }

  Column 6

    {'Full'}
    {'Full'}
    {'Full'}
    {'Full'}
    {'Full'}
    {'Full'}
    {'Full'}
    {'Full'}

Read CDF_TIME_TT2000 data and examine the third, fourth, and fifth entries.

tt2000Data = cdfread("example_364.cdf","Variables","tt2000");
tt2000Data{3:5}
ans = datetime
   2016-12-31T23:59:59.100200300Z

ans = datetime
   2016-12-31T23:59:60.100200300Z

ans = datetime
   2017-01-01T00:00:00.100200300Z

This example shows how to use cdfread to read CDF_TIME_TT2000 data in native form as CDF_TIME_TT2000 timestamps, and then decompose those timestamps into individual time components.

Explore data in example CDF file.

info = cdfinfo("example_364.cdf");
info.Variables
ans=8×6 cell array
  Columns 1 through 5

    {'Time'            }    {[    1 1]}    {[24]}    {'epoch' }    {'T/'    }
    {'Longitude'       }    {[    2 2]}    {[ 1]}    {'int8'  }    {'F/FT'  }
    {'Latitude'        }    {[    2 2]}    {[ 1]}    {'int8'  }    {'F/TF'  }
    {'Data'            }    {[  2 2 4]}    {[ 1]}    {'double'}    {'T/TTT' }
    {'multidimensional'}    {[2 2 3 4]}    {[ 1]}    {'uint8' }    {'T/TTTT'}
    {'Temperature'     }    {[    3 2]}    {[10]}    {'int16' }    {'T/TT'  }
    {'multiInt8'       }    {[    2 3]}    {[ 2]}    {'int64' }    {'T/TT'  }
    {'tt2000'          }    {[    1 1]}    {[ 8]}    {'tt2000'}    {'T/'    }

  Column 6

    {'Full'}
    {'Full'}
    {'Full'}
    {'Full'}
    {'Full'}
    {'Full'}
    {'Full'}
    {'Full'}

Read CDF_TIME_TT2000 data in native form and decompose the data into individual time components.

tt2000Data = cdfread("example_364.cdf","Variables","tt2000","DateTimeType","native");
timeArr = cdflib.breakdownTT2000([tt2000Data{:}])
timeArr = 9×8

        2016        2016        2016        2016        2017        2017        2017        2017
          12          12          12          12           1           1           1           1
          31          31          31          31           1           1           1           1
          23          23          23          23           0           0           0           0
          59          59          59          59           0           0           0           0
          57          58          59          60           0           1           2           3
         100         100         100         100         100         100         100         100
         200         200         200         200         200         200         200         200
         300         300         300         300         300         300         300         300

Limitations

  • The cdfread function does not support non-ASCII encoded data. All the variable names, attribute names, variable values, and attribute values in the CDF file must have 7-bit ASCII encoding. Attempting to read non-ASCII encoded files results in errors or data with corrupted characters.

Version History

Introduced before R2006a

expand all