cdfread

Read data from Common Data Format (CDF) file

Syntax

data = cdfread(filename)
data = cdfread(filename,Name1,Value1,...,NameN,ValueN)
[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 datasets 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 differing 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,Name1,Value1,...,NameN,ValueN) reads data from the file, where Name1, …, NameN can be any of the name-value arguments listed in the following table.

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

Name-Value Argument	Value
"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 string scalar or character vector specifying the name of a single variable to read from the file, or a 1-by-n or n-by-1 cell array specifying the names of one or more 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, and so on), 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 name-value argument describes how to process a single variable, it must be used with the Variables name-value argument.
"DatetimeType"	A string scalar or character vector that controls the return type of CDF_TIME_TT2000 and CDF_EPOCH data types. If DatetimeType is set to "datetime" (the default for CDF_TIME_TT2000), then cdfread returns values as type datetime. If DatetimeType is set to "native", then cdfread returns CDF_TIME_TT2000 values as type int64 and CDF_EPOCH values as type double.
"CombineRecords"	A logical value that determines how cdfread returns the CDF datasets read from the file. If CombineRecords is set to false (the default), then 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 CombineRecords is set to true, then 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 name-value argument to specify which records to read, you cannot use the CombineRecords name-value argument. Note: When using the Variables name-value argument to read one variable, if the CombineRecords name-value argument is true, then 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 CombineRecords name-value argument.

Note

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

Examples

Read CDF Data

Read all the data from a CDF file.

data = cdfread("example_364.cdf");
whos data

  Name       Size            Bytes  Class    Attributes

  data      24x8             35200  cell               

Read CDF Variables

Read data from the CDF variables Time and Temperature.

data = cdfread("example_364.cdf","Variables",{"Time","Temperature"});
whos data

  Name       Size            Bytes  Class    Attributes

  data      24x2              9792  cell               

Read Selected CDF Data

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.

dataSlice = cdfread("example_364.cdf","Variables","multidimensional", ...
                    "Slices",[0 1 1; 1 1 1; 0 2 2]);
dataSlice

dataSlice = 1x1 cell array
    {1x1x2x4 uint8}

Alternatively, read the whole variable into data and then use matrix indexing.

data = cdfread("example_364.cdf","Variables","multidimensional");
dataIndex = data{1}(1,2,[1 3],:);
whos dataIndex

  Name           Size               Bytes  Class    Attributes

  dataIndex      1x1x2x4                8  uint8              

Collapse CDF Data

Collapse the records from a dataset, and convert CDF_EPOCH and CDF_TIME_TT2000 data types to MATLAB datetime values.

data = cdfread("example_364.cdf","CombineRecords",true, ...
               "DatetimeType","datetime");
whos data

  Name      Size            Bytes  Class    Attributes

  data      1x8              7536  cell               

Read and Convert CDF_TIME_TT2000 Data

Explore data in the example_364.cdf file.

info = cdfinfo("example_364.cdf");
info.Variables

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

Read CDF_TIME_TT2000 data. cdfread converts the data to datetime values by default.

tt2000Data = cdfread("example_364.cdf","Variables","tt2000");

Examine the third, fourth, and fifth data values.

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

Read and Convert CDF_TIME_TT2000 Data in Native Form

Read CDF_TIME_TT2000 data in native form as CDF_TIME_TT2000 timestamps.

tt2000Data = cdfread("example_364.cdf","Variables","tt2000", ...
                     "DatetimeType","native");

Decompose the data into individual time components. Display the components of the third, fourth, and fifth timestamps.

timeArr = cdflib.breakdownTT2000([tt2000Data{:}]);
timeArr(:,3:5)

ans = 9×3

        2016        2016        2017
          12          12           1
          31          31           1
          23          23           0
          59          59           0
          59          60           0
         100         100         100
         200         200         200
         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

R2023b: ConvertEpochToDatenum name-value argument is not recommended

There are no plans to remove the ConvertEpochToDatenum name-value argument. However, ConvertEpochToDatenum is not recommended. Use the DatetimeType name-value argument instead.

If you do not specify the DatetimeType argument or you specify ConvertEpochToDatenum as false, then cdfread wraps CDF_EPOCH data in cdfepoch objects, which are not recommended. If you specify ConvertEpochToDatenum as true, then cdfread converts CDF_EPOCH data to serial date numbers, which are not recommended. Update your code to convert CDF_EPOCH data to datetime or double values instead. For example, use cdfread(filename,"DatetimeType","datetime").

You cannot specify the ConvertEpochToDatenum argument if you also specify the DatetimeType argument.

R2022b: Read CDF_INT8 and CDF_TIME_TT2000 data

You can read CDF_INT8 and CDF_TIME_TT2000 data.

R2022b: Specify output type by using DatetimeType

You can use the DatetimeType name-value argument to specify the output type of CDF variables of type CDF_EPOCH and CDF_TIME_TT2000.