MATLAB®

Network Common Data Form (netCDF) Files

Note   For information about working with Common Data Format (CDF) files, which is a completely separate, incompatible format, see Common Data Format (CDF) Files.

Overview

MATLAB provides access to the routines in the netCDF C library that you can use to read data from netCDF files and write data to netCDF files. MATLAB provides this access through a set of MATLAB functions that correspond to the functions in the netCDF C library. MATLAB groups the functions into a package, called netcdf. To call one of the functions in the package, you must specify the package name. For a complete list of all the functions, see netcdf.

Note   The MATLAB netCDF functions support netCDF Version 3.6.2.

This section does not attempt to describe all features of the netCDF library or explain basic netCDF programming concepts. To use the MATLAB netCDF functions effectively, you should be familiar with the information about netCDF contained in the NetCDF C Interface Guide for version 3.6.2.. The following sections provide details about how to use the MATLAB netCDF functions.

Back to Top

Mapping netCDF API Syntax to MATLAB Function Syntax

For the most part, the MATLAB netCDF functions correspond directly to routines in the netCDF C library. For example, the MATLAB function netcdf.open corresponds to the netCDF library routine nc_open. In some cases, one MATLAB function corresponds to a group of netCDF library functions. For example, instead of creating MATLAB versions of every netCDF library nc_put_att_type function, where type represents a data type, MATLAB uses one function, netcdf.putAtt, to handle all supported data types.

The syntax of the MATLAB functions is similar to the netCDF library routines, with some exceptions. For example, the netCDF C library routines use input parameters to return data, while their MATLAB counterparts use one or more return values. For example, the following is the function signature of the nc_open routine in the netCDF library. Note how the netCDF file identifier is returned in the ncidp argument.

int nc_open (const char *path, int omode, int *ncidp); /* C syntax */

The following shows the signature of the corresponding MATLAB function, netcdf.open. Like its netCDF C library counterpart, the MATLAB netCDF function accepts a character string that specifies the file name and a constant that specifies the access mode. Note, however, that the MATLAB netcdf.open function returns the file identifier, ncid, as a return value.

ncid = netcdf.open(filename, mode)

To see a list of all the functions in the MATLAB netCDF package, see the netCDF reference page.

Mapping MATLAB Classes to netCDF Data Types

MATLAB attempts to map netCDF data types to the corresponding MATLAB class that best matches. For example, netCDF functions map the MATLAB double class to the netCDF NC_DOUBLE data type. The following table shows this mapping. For more information about netCDF data types, you should be familiar with the information about netCDF contained in the NetCDF C Interface Guide for version 3.6.2.

Back to Top

Example: Exploring the Contents of a netCDF File

This example shows how to use the MATLAB netCDF functions to explore the contents of a netCDF file. The section uses the example netCDF file included with MATLAB, example.nc, as an illustration. For an example of reading data from a netCDF file, see Example: Reading Data from a netCDF File

1. Open the netCDF file using the netcdf.open function. This function returns an identifier that you use thereafter to refer to the file.

   ncid = netcdf.open('example.nc','NC_NOWRITE');

2. Explore the contents of the file using the netcdf.inq function. This function returns the number of dimensions, variables, and global attributes in the file, and returns the identifier of the unlimited dimension in the file. The unlimited dimension can grow.

   [ndims,nvars,natts,unlimdimID]= netcdf.inq(ncid)
   ndims =
   
        4
   
   
   nvars =
   
        4
   
   
   natts =
   
        1
   
   
   unlimdimID =
   
        3
   

3. Get more information about the dimensions, variables, and global attributes in the file by using netCDF inquiry functions. For example, to get information about the global attribute, first get the name of the attribute, using the netcdf.inqAttName function. After you get the name, 'creation_date' in this case, you can use the netcdf.inqAtt function to get information about the data type and length of the attribute.

   To get the name of an attribute, you must specify the ID of the variable the attribute is associated with and the attribute number. To access a global attribute, which isn't associated with a particular variable, use the constant 'NC_GLOBAL' as the variable ID. The attribute number is a zero-based index that identifies the attribute. For example, the first attribute has the index value 0, and so on.

   global_att_name = netcdf.inqAttName(ncid,netcdf.getConstant('NC_GLOBAL'),0)
   
   global_att_name =
   
   creation_date
   
   [xtype attlen] = netcdf.inqAtt(ncid,netcdf.getConstant('NC_GLOBAL'),global_att_name)
   
   xtype =
   
        2
   
   
   attlen =
   
       11

4. Get the value of the attribute, using the netcdf.getAtt function.

   global_att_value = netcdf.getAtt(ncid,netcdf.getConstant('NC_GLOBAL'),global_att_name)
   
   global_att_value =
   
   09-Jun-2008

5. Get information about the dimensions defined in the file through a series of calls to netcdf.inqDim. This function returns the name and length of the dimension. The netcdf.inqDim function requires the dimension ID, which is a zero-based index that identifies the dimensions. For example, the first dimension has the index value 0, and so on.

   [dimname, dimlen] = netcdf.inqDim(ncid,0)
   
   dimname =
   
   x
   
   dimlen =
   
       50

   The following table describes the dimensions in the example file.

   Dimension Name	Dimension Length
   x	50
   y	50
   z	5
   t	0 (unlimited)

6. Get information about the variables in the file through a series of calls to netcdf.inqVar. This function returns the name, data type, dimension ID, and the number of attributes associated with the variable. The netcdf.inqVar function requires the variable ID, which is a zero-based index that identifies the variables. For example, the first variable has the index value 0, and so on.

   [varname, vartype, dimids, natts] = netcdf.inqVar(ncid,0)
   
   varname =
   
   avagadros_number
   
   
   vartype =
   
        6
   
   
   dimids =
   
        []
   
   
   natts =
   
        1

   The following table describes the variables in the example file. The data type information is the numeric value of the netCDF data type constants, such as, NC_INT and NC_BYTE. See the official netCDF documentation for information about these constants.

   Variable Name	Variable Type	Variable Dimension IDs	Number of Attributes
   avagadros_number	6	[]	1
   temperature	3	0	4
   peaks	5	[0 1]	1
   time_series	4	[2 3]	1

Back to Top

Example: Reading Data from a netCDF File

After you understand the contents of a netCDF file, by using the inquiry functions, you can retrieve the data from the variables and attributes in the file. To read the data associated with the variable avagadros_number in the example file, use the netcdf.getVar function. The following example uses the netCDF file identifier returned in the previous section, Example: Exploring the Contents of a netCDF File. The variable ID is a zero-based index that identifies the variables. For example, the first variable has the index value 0, and so on. (To learn how to write data to a netCDF file, see Example: Storing Data in a netCDF File.)

A_number = netcdf.getVar(ncid,0)

A_number =

  6.0221e+023

The netCDF functions automatically choose the MATLAB class that best matches the netCDF data type, but you can also specify the class of the return data by using an optional argument to netcdf.getVar.

Back to Top

Example: Storing Data in a netCDF File

To store data in a netCDF file, you can use the MATLAB netCDF functions to create a file, define dimensions in the file, create a variable in the file, and write data to the variable. Note that you must define dimensions in the file before you can create variables. To run the following example, you must have write permission in your current directory.

1. Create a variable in the MATLAB workspace. This example creates a 50-element vector of numeric values named my_data. The vector is of class double.

   my_data = linspace(0,49,50);
   

2. Create a netCDF file (or open an existing file). The example uses the netcdf.create function to create a new file, named my_file.nc, and opens it for write access.

   ncid = netcdf.create('my_file.nc','NC_WRITE');
   

   When you create a netCDF file, the file opens in define mode. You must be in define mode to define dimensions and variables.

3. Define a dimension in the file, using the netcdf.defDim function. You must define dimensions in the file before you can define variables and write data to the file. When you define a dimension, you give it a name and a length. To create an unlimited dimension, i.e., a dimension that can grow, specify the constant NC_UNLIMITED in place of the dimension length.

   dimid = netcdf.defDim(ncid,'my_dim',50);
   

4. Define a variable on the dimension, using the netcdf.defVar function. When you define a variable, you give it a name, data type, and a dimension ID. You must use one of the netCDF constants to specify the data type, listed in Mapping MATLAB Classes to netCDF Data Types.

   varid = netcdf.defVar(ncid,'my_var','NC_BYTE',dimid);
   

5. Take the netCDF file out of define mode. To write data to a file, you must be in data mode.

   netcdf.endDef(ncid);
   

6. Write the data from the MATLAB workspace into the variable in the netCDF file, using the netcdf.putVar function. Note that the data in the workspace is of class double but the variable in the netCDF file is of type NC_BYTE. The MATLAB netCDF functions automatically do the conversion.

   netcdf.putVar(ncid,varid,my_data);
   

7. Close the file, using the netcdf.close function.

   netcdf.close(ncid);
   

8. Verify that the data was written to the file by opening the file and reading the data from the variable into a new variable in the MATLAB workspace. Because the variable is the first variable in the file (and the only one), you can specify 0 (zero) for the variable ID—identifiers are zero-based indexes.

   ncid2 = netcdf.open('my_file.nc','NC_NOWRITE');
   
   data_in_file = netcdf.getVar(ncid2,0)
   
   data_in_file =
   
       0
       1
       2
       3
       4
       5
       6
       7
       8
       9
       .
       .
       .
   

   Because you stored the data in the file as NC_BYTE, MATLAB reads the data from the variable into the workspace as class int8.

Back to Top

Common Data Format (CDF) Files

Flexible Image Transport System (FITS) Files

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit