NetCDF Data Processing Scripts

Matlab: NetCDF Data Processing Scripts

This page describes several Matlab scripts used to process NetCDF data. These scripts are located in the matlab/netcdf sub-directory in the repository. They are high level scripts on top of the native NetCDF interface if using Matlab Version 2008b or newer for local NetCDF files and Matlab Version 2012a or newer for OpenDAP files. For older Matlab versions, the MEXNC interface is used for local files whereas the SNCTOOLS java interface is used for OpenDAP files. Notice that processing of OpenDAP files is only possible for reading.

nc_attadd.m

Adds or modifies a global or variable attribute in a NetCDF file. If the Vname argument is missing, it is assumed that Aname is a global attribute.

status = nc_attadd  (ncfile, Aname, Avalue, Vname)

On Input:

ncfile:   NetCDF file name (string)

Aname:   Attribute name (string)

Avalue:   Attribute value (numeric or string)

Vname:   Variable name (string; optional)

On Output:

status:   Error flag

nc_attdel.m

Deletes requested global or variable attribute in a NetCDF file. If the Vname argument is missing, it is assumed that Aname is a global attribute.

status = nc_attdel  (ncfile, Aname, Vname)

On Input:

ncfile:   NetCDF file name (string)

Aname:   Attribute name (string)

Vname:   Variable name (string; optional)

On Output:

status:   Error flag

nc_check.m

Checks the information structure returned from calls to nc_inq or native ncinfo for compliance and changes new variable types and attributes. For example, it updates the spherical switch to integer and fixes the land/sea masking attributes for compliance. Notice that this information structure is very convenient to create new NetCDF files having the dimensions and variable schema of and old NetCDF file.

I = nc_check  (Info)

On Input:

Info:   NetCDF file information structure (struct array)

On Ouput:

I:   Updated NetCDF file information structure (struct array)

nc_create.m

creates a new NetCDF file according to the file creation mode. If a structure S is provided, it defines the dimensions, global attributes, variables and attributes stored in the structure. This structure can be created using:

S = nc_inq('roms_his.nc')

or

S = ncinfo('roms_his.nc')     native Matlab function

If the user wants different dimension values than those returned by nc_inq or ncinfo, see S.Dimensions(:).Length, make sure that such values are overwritten before calling this function. Therefore, it is possible to replicate the schema of a particular NetCDF file with identical or different dimensions. This facilitates the extraction of smaller sub-domain data from a large (coarser) dataset. This function does not write the variable data. It just creates the NetCDF file.

ncid = nc_create  (ncfile, mode, S)

On Input:

ncfile:   NetCDF file name to create (string)

mode: NetCDF file creation mode (string):

'clobber',   overwrite existing files

'noclobber',   do not overwrite existing files

'shared',   allow for synchronous file updates

'64bit_offset',   allow the creation of 64-bit files instead of the classic format

'netcdf4',   creates a netCDF-4/HDF-5 file

'classic_model',   enforce classic model, has no effect unless used in a bitwise-or with 'netcdf4'

S:   NetCDF file Schema Structure (struct array)

On Ouput:

ncid:   NetCDF file ID. If no function output arguments are given, the file is closed after it is created.

nc_dinfo.m

Gets all the dimension information about the requested NetCDF file.

D = nc_dinfo  (ncfile)

On Input:

ncfile:   NetCDF file name or URL file name (string)

On Ouput:

D:   Dimensions information (Struct array):

D(:).Name :   dimension name (string)

D(:).Length :   dimension length (double)

D(:).Unlimited:   unlimited dimension (logical)

D(:).dimid :   NetCDF dimension id (double)

nc_drename.m

Renames requested dimension in a NetCDF file.

status = nc_drename  (ncfile, Dname_old, Dname_new)

On Input:

ncfile :   NetCDF file name (string)

Dname_old:   Old dimension name (string)

Dname_new:   New dimension name (string)

On Output:

status:   Error flag

nc_getatt.m

Reads global or variable attributes from input NetCDF file. If the Vname argument is missing, it is assumed that Aname is a global attribute. If both Aname and Vname arguments are missing, it returns all global attributes.

A = nc_getatt  (ncfile, Aname, Vname)

On Input:

ncfile:   NetCDF file name or URL file name (string)

Aname :   Attribute name (string; optional)

Vname :   Variable name (string; optional)

On Output:

A:   Attribute value (numeric, string, or struct array)

Usage:

A = nc_getatt ('ocean_his.nc')

will return a structure array with all the global attributes names and values: A.Name(:), A.Value(:)

A = nc_getatt ('ocean_his.nc', 'history')

will return a string with the value of the global 'history' attribute

A = nc_getatt ('ocean_his.nc', [ ], 'temp')

will return a structure array with all the 'temp' variable attributes names and values: A.Name(:), A.Value(:)

A = nc_getatt ('ocean_his.nc', 'FillValue', 'temp')

will return a numeric value for the attribute 'FillValue' in variable 'temp'

nc_inq.m

Inquires about the contents of a NetCDF file: dimensions, global attributes, and variables.

I = nc_inq  (ncfile, Lprint)

On Input:

ncfile:   NetCDF file name or URL file name (string)

Lprint:   Switch to print information (optional; default false)

On Output:

I:   NetCDF information (struct array):

I.Filename,   NetCDF file name (string)

I.Attributes,   NetCDF global attributes (struct array):

I.Attributes(:).Name

I.Attributes(:).Value

I.Dimensions,   NetCDF file dimensions (struct array):

I.Dimensions(:).Name

I.Dimensions(:).Length

I.Dimensions(:).Unlimited

I.Variables(:).Dimensions,   variable dimensions (struct array):

I.Variables(:).Dimensions(:).Name

I.Variables(:).Dimensions(:).Length

I.Variables(:).Dimensions(:).Unlimited

I.Variables(:).Size,   variable size (double array)

I.Variables(:).Attributes,   variable attributes (struct array):

I.Variables(:).Attributes(:).Name

I.Variables(:).Attributes(:).Value

I.Variables(:).Cgridtype,   stagged C-grid type (struct array):

I.Variables(:).Cgridtype.Name

I.Variables(:).Cgridtype.Value

I.Variables(:).Datatype,   original variable data type (string)

I.Variables(:).ncType,   NetCDF data type (numeric)

nc_interface.m

Determines the interface to use when processing a NetCDF file. The strategy is to always use the 'native' method when possible. It was introduced in Matlab version 2008b for NetCDF-3 type files. The NetCDF-4 support was introduced in version 2010b. The support for HDF5 files was completed in version '2011a'. The OpenDAP support started in version '2012a'. The MEXNC and SNCTOOLS interfaces are becoming obsolete. The MEXNC is the oldest interface. It is no longer developed and only has support for NetCDF-3 and NetCDF-4 classic files. It does not have Java support for OpenDAP files. The SNCTOOLS have support for NetCDF-3, NetCDF-4, HDF5, and a Java interface for OpenDAP files.

[method, url, ftype] = nc_interface  (ncfile)

On Input:

ncfile :   NetCDF file name or URL name (string)

On Output:

method :   NetCDF interface for Matlab (string):

'native' ,   Native Matlab interface

'mexnc' ,   MEXNC interface

'java' ,   SNCTOOLS Java interface

url :   Switch indicating an OpenDAP file (logical)

ftype :   File type (string)

'NetCDF' ,   Classic NetCDF-3 file

'NetCDF4' ,   NetCDF-4/HDF5 file

'OpenDAP' ,   OpenDAP file

nc_read.m

Reads in a generic variable from a NetCDF file. If only the water points are available, this function fill the land areas with zero and returns the full field.

f = nc_read  (ncfile, Vname, Tindex, ReplaceValue, PreserveType)

On Input:

ncfile :   NetCDF file name or URL name (string)

Vname :   NetCDF variable name to read (string)

Tindex :   Time record index to read (scalar). If Tindex is provided, only the requested time record is processed when the variable has the unlimited dimension or the word time in any of its dimension names. Otherwise, provide an empty [ ] argument.

ReplaceValue:   Value to use when _FillValue or missing_value attribute is found in variable. If not provided, a zero value will used. In some instances, like plotting, it is advantageous to use NaN to better visualize the land masking or the missing data.

PreserveType:   Switch to preserve numerical data type (logical). If false, convert numerical data to double precision. It has no effect on data that is already in double precision.

On Output:

f:   Field (scalar or array)

nc_slice.m

Computes a horizontal variable slice from a NetCDF file generated by ROMS. It should only be used when the grid has variable bathymetry. The field slice is interpolated at the requested depth from the input terrain-following coordinate data.

[x, y, f] = nc_slice  (Gfile, Hfile, Vname, depth, Tindex, zflag)

On Input:

Gfile :   ROMS Grid NetCDF file name (string). If no grid file, use field file name instead.

Hfile :   Field history NetCDF file name (string)

Vname :   NetCDF variable name to process (string)

depth :   Slice depth (scalar; meters, negative)

Tindex:   Time index to read (integer). If tindex = 0, all time records are processed. Otherwise if tindex > 0, only the specified record is processed.

zflag :   Variable depths computation switch (scalar). If zflag = 0, use zero free-surface. Otherwise if zflag = 1, use Tindex record free-surface.

On Output:

x:   Slice X-positions (2D array)

y:   Slice Y-positions (2D array)

f:   Field slice (array)

nc_test.m

Creates a NetCDF using data from the peaks(40) function. Several data type variables are created from the original double precision data and packed into byte (int8), short (int16), integer (int32), and single precision. It is used to test the writing and reading of NetCDF data in Matlab using the various interfaces. It computes and reports the processing and truncation RMSE.

nc_test  (ncfile, Interface, Lplot)

On Input:

ncfile :   NetCDF file name to create (string)

Dname_old:   NetCDF interface for Matlab (string):

'native' ,   Native Matlab interface

'mexnc' ,   MEXNC interface

'roms' ,   ROMS nc_write.m and nc_read.m functions

'snctools',   SNCTOOLS inteface

Lplot :   Switch to plot the data (Optional, default false)

nc_vdef.m

Defines a variable in a NetCDF file.

[varid, status] = nc_vdef  (ncid, Var)

On Input:

ncid :   NetCDF file ID (scalar)

Var :   NetCDF interface for Matlab (string):

Var.name ,   variable name (string)

Var.type ,   external data type (string or numeric)

Var.dimid,   dimension IDs (numeric). If not present or empty [ ], the variable is a scalar

Var.field,   Values, if any, for 'field' in the structure are processed as variable attributes. The values of the attribute can be numeric (scalar or vector) or strings (character array or cell array). For example,

Var.long_name = 'temp',   'long_name' attribute (string)

Var.FillValue = 1.0E+37,   '_FillValue' attribute (numeric)

On Output:

varid :   Variable ID (scalar)

status :   Error flag

nc_vinfo.m

Gets information about requested NetCDF variable.

V = nc_vinfo  (ncfile, Vname)

On Input:

ncfile :   NetCDF file name or URL name (string)

Dname_old:   Variable name (string)

On Output:

V:   Requested variable information (struct array):

V.Filename,   NetCDF file name (string)

V.Dimensions,   variable dimensions (struct array):

V.Dimensions(:).Name

V.Dimensions(:).Length

V.Dimensions(:).Unlimited

V.Size,   variable size (double array)

V.Attributes,   variable attributes (struct array):

V.Attributes(:).Name

V.Attributes(:).Value

V.Cgridtype,   stagged C-grid type (struct array):

V.Cgridtype.Name

V.Cgridtype.Value

V.Datatype,   original variable data type (string)

V.ncType,   NetCDF data type (numeric)

nc_vnames.m

gets the names and informaton of all variables available in a NetCDF file

S = nc_vnames  (ncfile)

On Input:

ncfile :   NetCDF file name or URL name (string)

On Output:

S:   NetCDF file variables information (struct array):

S.Filename,   NetCDF file name (string)

S.Variables(:).Dimensions,   variable dimensions (struct array):

S.Variables(:).Dimensions(:).Name

S.Variables(:).Dimensions(:).Length

S.Variables(:).Dimensions(:).Unlimited

S.Variables(:).Size,   variable size (double array)

S.Variables(:).Attributes,   variable attributes (struct array):

S.Variables(:).Attributes(:).Name

S.Variables(:).Attributes(:).Value

S.Variables(:).Cgridtype,   stagged C-grid type (struct array):

S.Variables(:).Cgridtype.Name

S.Variables(:).Cgridtype.Value

S.Variables(:).Datatype,   original variable data type (string)

S.Variables(:).ncType,   NetCDF data type (numeric)

nc_vrename.m

Renames requested variable in a NetCDF file.

status = nc_vrename  (ncfile, Vname_old, Vname_new)

On Input:

ncfile :   NetCDF file name (string)

Vname_old:   Old variable name (string)

Vname_new:   New variable name (string)

On Output:

status:   Error flag

nc_write.m

Writes a generic variable into a NetCDF file.

status = nc_read  (ncfile, Vname, f, Tindex)

On Input:

ncfile:   NetCDF file name or URL name (string)

Vname :   NetCDF variable name to read (string)

f :   variable values (scalar or array)

Tindex:   If Tindex is not provided as an argument during function call, it is assumed that the entire variable is to be written. If the variable has an unlimited record dimension, Tindex can be used to increase that dimension or replace an existing record. If the variable has the word time in its dimension name, Tindex can be used to write at the specified the time record.

On Output:

status:   Error flag