MATLAB NetCDF Capabilities

Network Common Data Form (netCDF) is a set of software libraries and machine-independent data formats that support the creation, access, and sharing of array-oriented scientific data. NetCDF is used by a wide range of engineering and scientific fields that want a standard way to store data so that it can be shared.

MATLAB^® high-level functions make it easy to export data to a netCDF file. MATLAB low-level functions provide access to the routines in the NetCDF C library. To use the low-level functions effectively, you should be familiar with the netCDF C Interface. The NetCDF documentation is available at the Unidata website.

Create New NetCDF File from Existing File or Template

This example shows how to create a new NetCDF file that contains the variable, dimension, and group definitions of an existing file, but uses a different format.

Create a file containing one variable, using the nccreate function.

nccreate('myfile.nc','myvar')

Write data to the file.

A = 99;
ncwrite('myfile.nc','myvar',A)

Read the variable, dimension, and group definitions from the file using ncinfo. This information defines the file's schema.

S = ncinfo('myfile.nc');

Get the format of the file.

file_fmt = S.Format

file_fmt = 
'netcdf4_classic'

Change the value of the Format field in the structure, S, to another supported NetCDF format.

S.Format = 'netcdf4';

Create a new version of the file that uses the new format, using the ncwriteschema function. A schema defines the structure of the file but does not contain any of the data that was in the original file.

ncwriteschema('newfile.nc',S)
S = ncinfo('newfile.nc');

Note: When you convert a file's format using ncwriteschema, you might get a warning message if the original file format includes fields that are not supported by the new format. For example, the netcdf4 format supports fill values but the NetCDF classic format does not. In these cases, ncwriteschema still creates the file, but omits the field that is undefined in the new format.

View the format of the new file.

new_fmt = S.Format

new_fmt = 
'netcdf4'

The new file, newfile.nc, contains the variable and dimension definitions of myfile.nc, but does not contain the data.

Write data to the new file.

ncwrite('newfile.nc','myvar',A)

Merge Two NetCDF Files

This example shows how to merge two netCDF files using high-level functions. The combined file contains the variable and dimension definitions of the files that are combined, but does not contain the data in these original files.

nccreate('ex1.nc','myvar');
ncwrite('ex1.nc','myvar',55)
ncdisp('ex1.nc')

Source:
           pwd\ex1.nc
Format:
           netcdf4_classic
Variables:
    myvar
           Size:       1x1
           Dimensions: 
           Datatype:   double

nccreate('ex2.nc','myvar2');
ncwrite('ex2.nc','myvar2',99)
ncdisp('ex2.nc')

Source:
           pwd\ex2.nc
Format:
           netcdf4_classic
Variables:
    myvar2
           Size:       1x1
           Dimensions: 
           Datatype:   double

info1 = ncinfo('ex1.nc')

info1 = 

      Filename: 'pwd\ex1.nc'
          Name: '/'
    Dimensions: []
     Variables: [1x1 struct]
    Attributes: []
        Groups: []
        Format: 'netcdf4_classic'

info2 = ncinfo('ex2.nc')

info2 = 

      Filename: 'pwd\ex2.nc'
          Name: '/'
    Dimensions: []
     Variables: [1x1 struct]
    Attributes: []
        Groups: []
        Format: 'netcdf4_classic'

ncwriteschema('combined.nc',info1)
ncdisp('combined.nc')

Source:
           pwd\combined.nc
Format:
           netcdf4_classic
Variables:
    myvar
           Size:       1x1
           Dimensions: 
           Datatype:   double
           Attributes:
                       _FillValue = 9.969209968386869e+36

ncwriteschema('combined.nc',info2)

ncdisp('combined.nc')

Source:
           pwd\combined.nc
Format:
           netcdf4_classic
Variables:
    myvar 
           Size:       1x1
           Dimensions: 
           Datatype:   double
           Attributes:
                       _FillValue = 9.969209968386869e+36
    myvar2
           Size:       1x1
           Dimensions: 
           Datatype:   double
           Attributes:
                       _FillValue = 9.969209968386869e+36

Write Data to NetCDF File Using Low-Level Functions

This example shows how to use low-level functions to write data to a netCDF file. The MATLAB® low-level functions provide access to the routines in the netCDF C library. MATLAB groups the functions into a namespace, called netcdf. To call one of the functions in the namespace, you must prefix the function name with the namespace.

To use the MATLAB netCDF functions effectively, you should be familiar with the information about the netCDF C Interface.

To run this example, you must have write permission in your current folder.

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

my_data = linspace(0,49,50);

Create a netCDF file named my_file.nc, using the netcdf.create function. The NOCLOBBER parameter is a netCDF file access constant that indicates that you do not want to overwrite an existing file with the same name.

ncid = netcdf.create("my_file.nc","NOCLOBBER");

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

Define a dimension in the file, using the netcdf.defDim function. This function corresponds to the nc_def_dim function in the netCDF library C API. You must define dimensions in the file before you can define variables and write data to the file. In this case, define a dimension named my_dim with length 50.

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

netcdf.defDim returns a dimension identifier that corresponds to the new dimension. Identifiers are zero-based indexes.

Define a variable named my_var on the dimension, using the netcdf.defVar function. This function corresponds to the nc_def_var function in the netCDF library C API. Specify the netCDF data type of the variable, in this case, NC_BYTE.

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

netcdf.defVar returns a variable identifier that corresponds to my_var.

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

netcdf.endDef(ncid)

Write the data from the MATLAB workspace into the variable in the netCDF file, using the netcdf.putVar function. 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)

Close the file, using the netcdf.close function.

netcdf.close(ncid)

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.

ncid2 = netcdf.open("my_file.nc","NC_NOWRITE");
x = netcdf.getVar(ncid2,0);

View the data type of x.

whos x

  Name       Size            Bytes  Class    Attributes

  x         50x1                50  int8               

MATLAB stores data in column-major order while the netCDF C API uses row-major order. x represents the data stored in the netCDF file and is therefore 50-by-1 even though the original vector in the MATLAB workspace, my_data, is 1-by-50. Because you stored the data in the NetCDF file as NC_BYTE, MATLAB reads the data from the variable into the workspace as class int8.

Close the file.

netcdf.close(ncid2)