Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Importing NetCDF Files and OPeNDAP Data

Overview

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. For more information, read the NetCDF documentation available at the Unidata Web site.

MATLAB® provides two methods to import data from a NetCDF file or from an OPeNDAP source:

  • High-level functions that simplify the process of importing data

  • Low-level functions that enable more complete control over the importing process, by providing access to the routines in the NetCDF C library

    Note   For information about importing to Common Data Format (CDF) files, which have a completely separate, incompatible format, see Importing CDF Files.

Using the MATLAB High-Level NetCDF Functions to Import Data

MATLAB includes several functions that you can use to examine the contents of a NetCDF file and import data from the file into the MATLAB workspace.

  • ncdisp — View the contents of a NetCDF file or OPeNDAP URL

  • ncinfo — Create a structure that contains all the metadata that defines a NetCDF file

  • ncread — Read data from a variable in a NetCDF file or OPeNDAP URL

  • ncreadatt — Read data from an attribute associated with a variable in a NetCDF file or with the file itself (a global attribute).

For details about how to use these functions, see their reference pages, which include examples. The following section illustrates how to use these functions to perform a common task: finding all the unlimited dimensions in a NetCDF file.

Finding All Unlimited Dimensions in a NetCDF File

This example shows how to find all unlimited dimensions in an existing NetCDF file, visually and programmatically.

  1. To determine which dimensions in a NetCDF file are unlimited, display the contents of the example NetCDF file, using ncdisp. The ncdisp function identifies unlimited dimensions with the label UNLIMITED.

    Source:
               \\matlabroot\toolbox\matlab\demos\example.nc
    Format:
               netcdf4
    Global Attributes:
               creation_date = '29-Mar-2010'
    Dimensions:
               x = 50
               y = 50
               z = 5
    .
    .
    .
    Groups:
        
        /grid2/
            Attributes:
                       description = 'This is another group attribute.'
            Dimensions:
                       x    = 360
                       y    = 180
                       time = 0     (UNLIMITED)
            Variables:
                temp
                       Size:       []
                       Dimensions: x,y,time
                       Datatype:   int16
  2. To determine all unlimited dimensions programmatically, first get information about the file using ncinfo. This example gets information about a particular group in the file.

    ginfo = ncinfo('example.nc','/grid2/');
    
  3. Get a vector of the Boolean values that indicate, for this group, which dimension is unlimited.

    unlimDims = [finfo.Dimensions.Unlimited]
    
    unlimDims =
    
         0     0     1
  4. Use this vector to display the unlimited dimension.

    disp(ginfo.Dimensions(unlimDims))
             Name: 'time'
           Length: 0
        Unlimited: 1
    

Using the MATLAB Low-Level NetCDF Functions to Import Data

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.

This section does not 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.

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.

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 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. The example opens the file for read-only access, but you can specify other access modes. For more information about modes, see netcdf.open.

    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. (An unlimited dimension can grow.)

    [ndims,nvars,natts,unlimdimID]= netcdf.inq(ncid)
    ndims =
    
         3
    
    
    nvars =
    
         3
    
    
    natts =
    
         1
    
    
    unlimdimID =
    
         -1
    
  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 =
    
    29-Mar-2010
  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
  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 data type information returned in vartype is the numeric value of the NetCDF data type constants, such as, NC_INT and NC_BYTE. See the NetCDF documentation for information about these constants.

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, 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 Exporting (Writing) Data to 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. The following table shows the default mapping. For more information about NetCDF data types, see the NetCDF C Interface Guide.

NetCDF Data TypeMATLAB ClassNotes
NC_BYTEint8 or uint8NetCDF interprets byte data as either signed or unsigned.
NC_CHARchar 
NC_SHORTint16 
NC_INTint32 
NC_FLOATsingle 
NC_DOUBLEdouble 

Troubleshooting OPeNDAP Connections

If you have trouble reading OPeNDAP data, consider the following:

  • OPeNDAP data is being pulled over the network from a server on the Internet. Pulling large data could be slow. Speed and reliability depends on their network connection

  • OPeNDAP capability does not support proxy servers or any kind of authentication

  • Failure to open an OPeNDAP link could have multiple causes:

    • Invalid URL

    • Local machine firewall/network firewall does not allow any external connections.

    • Local machine firewall/network firewall does not allow external connections on the OPeNDAP protocol.

    • Remote server is down.

    • Remote server will not serve the amount of data being requested. In this case, you can read data in subsets or chunks.

    • Remote server is incorrectly configured.

Was this topic helpful?