3.1 High-level functions

3.1.1 nccreate

Function File: nccreate(filename,varname)
Function File: nccreate(filename,varname,"property",value,...)

Create the variable varname in the file filename.

Properties

The following properties can be used:

  • "Dimensions": a cell array with the dimension names followed by their length or Inf if the dimension is unlimited. If the property is omitted, a scalar variable is created.
  • "Datatype": a string with the Octave data type name (see ncinfo for the correspondence between Octave and NetCDF data types). The default data type is a "double".
  • "Format": This can be "netcdf4_classic" (default), "classic", "64bit" or "netcdf4".
  • "FillValue": the value used for undefined elements of the NetCDF variable.
  • "ChunkSize": the size of the data chunks. If omitted, the variable is not chunked.
  • "DeflateLevel": The deflate level for compression. It can be the string "disable" (default) for no compression or an integer between 0 (no compression) and 9 (maximum compression).
  • "Shuffle": true for enabling the shuffle filter or false (default) for disabling it.

Example

 nccreate("test.nc","temp","Dimensions",{"lon",10,"lat",20},"Format","classic");
 ncdisp("test.nc");

See also: ncwrite.

3.1.2 ncdisp

Function File: ncdisp (filename)

Display meta-data of the NetCDF file filename

Example

 ncdisp("test.nc");

See also: ncinfo.

3.1.3 ncinfo

Function File: info = ncinfo (filename)
Function File: info = ncinfo (filename, varname)
Function File: info = ncinfo (filename, groupname)

Return information about an entire NetCDF file filename (i.e. the root group "/"), about the variable called varname or the group called groupname.

The structure info has always the following fields:

  • Filename: the name of the NetCDF file
  • Format: one of the strings "CLASSIC", "64BIT", "NETCDF4" or "NETCDF4_CLASSIC"

The structure info has additional fields depending on whether a group of variable is queried.

Groups

Groups are returned as an array structure with the following fields:

  • Name: the group name. The root group is named "/".
  • Dimensions: a array structure with the dimensions.
  • Variables: a array structure with the variables.
  • Attributes: a array structure with global attributes.
  • Groups: a array structure (one for each group) with the same fields as this structure.

Dimensions

Dimensions are returned as an array structure with the following fields:

  • Name: the name of the dimension
  • Length: the length of the dimension
  • Unlimited: true of the dimension has no fixed limited, false

Variables

Variables are returned as an array structure with the following fields:

  • Name: the name of the dimension
  • Dimensions: array structure of all dimensions of this variable with the same structure as above.
  • Size: array with the size of the variable
  • Datatype: string with the corresponding octave data-type (see below)
  • Attributes: a array structure of attributes
  • FillValue: the NetCDF fill value of the variable. If the fill value is not defined, then this attribute is an empty array ([]).
  • DeflateLevel: the NetCDF deflate level between 0 (no compression) and 9 (maximum compression).
  • Shuffle: is true if the shuffle filter is activated to improve compression, otherwise false.
  • CheckSum: is set to "fletcher32", if check-sums are used, otherwise this field is not defined.

Attributes

Attributes are returned as an array structure with the following fields:

  • Name: the name of the attribute
  • Value: the value of the attribute (with the corresponding type)
  • Unlimited: true of the dimension has no fixed limited, false

Data-types

The following the the correspondence between the Octave and NetCDF data-types:

Octave typeNetCDF type
int8NC_BYTE
uint8NC_UBYTE
int16NC_SHORT
uint16NC_USHORT
int32NC_INT
uint32NC_UINT
int64NC_INT64
uint64NC_UINT64
singleNC_FLOAT
doubleNC_DOUBLE
charNC_CHAR

The output of ncinfo can be used to create a NetCDF file with the same meta-data using ncwriteschema.

Note: If there are no attributes (or variable or groups), the corresponding field is an empty matrix and not an empty struct array for compatibility with matlab.

See also: ncread,nccreate,ncwriteschema,ncdisp.

3.1.4 ncread

Function File: x = ncread (filename, varname)
Function File: x = ncread (filename, varname,start,count,stride)

Read the variable varname from the NetCDF file filename.

If start,count and stride are present, a subset of the variable is loaded. The parameter start contains the starting indices (1-based), count is the number of elements and stride the increment between two successive elements. These parameters are vectors whose length is equal to the number of dimension of the variable. Elements of count might be Inf which means that as many values as possible are loaded.

If the variable has the _FillValue attribute, then the corresponding values are replaced by NaN (except for characters). NetCDF attributes scale_factor (default 1) and add_offset (default 0) are use the transform the variable during the loading:

x = scale_factor * x_in_file + add_offset

The output data type matches the NetCDF datatype, except when the attributes _FillValue, add_offset or scale_factor are defined in which case the output is a array in double precision.

Note that values equal to the attribute missing_value are not replaced by NaN (for compatibility).

Example

Read the data from variable ’mydata’ in the file test.nc.

 data  = ncread('test.nc','mydata');

See also: ncwrite,ncinfo,ncdisp.

3.1.5 ncreadatt

Function File: val = ncreadatt(filename,varname,attname)

Return the attribute attname of the variable varname in the file filename.

Global attributes can be accessed by using "/" or the group name as varname. The type of attribute is mapped to the Octave data types. (see ncinfo).

Example

Read global attribute ’creation_date’

 d = ncreadatt('test.nc','/','creation_date')

Read atribute ’myattr’ assigned to variable mydata.

 d = ncreadattr('test.nc', 'mydata', 'myattr');

See also: ncinfo,ncwriteatt.

3.1.6 ncwrite

Function File: ncwrite (filename, varname, x)
Function File: ncwrite (filename, varname, x, start, stride)

Write array x to the the variable varname in the NetCDF file filename.

The variable with the name varname and the appropriate dimension must already exist in the NetCDF file.

If start and stride are present, a subset of the variable is written. The parameter start contains the starting indices (1-based) and stride the increment between two successive elements. These parameters are vectors whose length is equal to the number of dimension of the variable.

If the variable has the _FillValue attribute, then the values equal to NaN are replaced by corresponding fill value NetCDF attributes scale_factor (default 1) and add_oddset (default 0) are use the transform the variable during writing:

x_in_file = (x - add_offset)/scale_factor

Example

Create a netcdf file with a variable of ’mydata’ and then write data to that variable.

 nccreate('myfile.nc','mydata');
 ncwrite('myfile.nc','mydata', 101);

See also: ncread,nccreate.

3.1.7 ncwriteatt

Function File: ncwriteatt(filename,varname,attname,val)

Defines the attribute attname of the variable varname in the file filename with the value val.

Global attributes can be defined by using "/" or the group name as varname. The type of value is mapped to the NetCDF data types. (see ncinfo).

Example

Create a netcdf4 format file with a variable mydata and assign an attribute "units" to it.

 nccreate("myfile.nc", "mydata", "Format", "netcdf4");
 ncwriteatt("myfile.nc", "mydata", "Units", "K");

See also: ncinfo.

3.1.8 ncwriteschema

Function File: ncwriteschema (filename, schema)

Create a NetCDF called filename with the dimensions, attributes, variables and groups given by the structure schema.

The variable schema has the same structure as the results of ncinfo. ncinfo and ncwriteschema can be used together to create a NetCDF using another file as a template:

Example

 schema = ncinfo("template.nc");
 # the new file should be named "new_file.nc"
 ncwriteschema("new_file.nc",schema);

Unused field in schema such as ChunkSize, Shuffle, DeflateLevel, FillValue, Checksum can be left-out if the corresponding feature is not used.

Dimensions are considered as limited if the field Unlimited is missing, unless the dimension length is Inf.

See also: ncinfo.