CSIRO Marine Research
 

CSIRO matlab/netCDF interface

Index

Short Description of the matlab/netCDF interface
Portability issues
Downloading and installation
Summary of functions
Detailed discussion of getnc
Further documentation
Backwards compatibility issues
Latest changes
Disclaimer
People involved in the development of the matlab/netCDF interface
Contact details

Short Description of the matlab/netCDF interface

This page describes an interface between NetCDF and MATLAB version 5. The interface has been developed since 1991 by a number of people.

The basis of the interface is a machine-dependent mex-file called mexcdf53 (an older version running under matlab4 used mexcdf). Rather than call the mex-file directly users are advised to employ both Chuck Denham's netCDF toolbox and the CSIRO matlab/netCDF interface described here.

The CSIRO matlab/netCDF interface has a simple syntax. It has options for automatically handling missing values, scale factors, and permutation of hyperslabs. It is however limited to retrieving data from, and information about, existing netCDF files.

By contrast, Chuck's netCDF toolbox allows users to create and manipulate netCDF files as well as to read and examine them. It does this by making full use of new matlab 5 features such as cells and structures.

The rest of this web page describes the interface between matlab 5 and netCDF files. There is an older, no longer supported, version of the CSIRO interface that runs under matlab4; this web document tells you how to get that version but does not describe it.

Portability issues

Almost all of the machine dependence of the system is in the mex-file which is downloaded separately. The m-files that make up the CSIRO matlab/netCDF interface have been tested on a number of unix machines as well as a windows-95 box. No problems have been found with the latest (matlab5) version.

Earlier versions, however, did not work properly on pc operating systems because they used file names with more than 8 characters. This has been changed for the latest version. The m-file 'whatnc' will produce prettier output on a unix machine (where it is able to make unix function calls) but it will still work on non-unix machines.

Downloading and installation

What you should get depends on whether you are using matlab4 or matlab5 and also whether you want backwards compatibility to older versions of the matlab/netCDF interface that ran under matlab3 and 4.
matlab 5 users
First you should install Chuck Denham's netCDF toolbox and the appropriate mex-file.

Next get the CSIRO matlab/netCDF interface. There are 2 versions of this according to whether you are a new user or whether you already have code requiring the previous version of the interface (in this case you will get all of the code needed for the latest version of the interface as well as extra m-files to mimic the previous version). Each version of the interface is available in 2 forms - as a tar'ed and compressed file or as a p-code file. The contents of these files are identical but the tar'ed and compressed file is very small (~56 kb) and is convenient for unix users while the p-code version is much larger(~256 kb) but will work for everyone.

New users download one of the following

Users wanting backwards compatibility download one of the following
matlab 4 users
An older, no longer supported, version of the CSIRO interface is also available as matlab-netcdf-4.0.tar.Z. This requires an older mex-file which can be obtained from Rich Signell's "MEXCDF: The Matlab/NetCDF Interface" home page.
The installation of the m-files is easy.
  1. If you have a tar'ed and compressed file then just type

    2. zcat matlab_netcdf_5_0.tar.Z | tar -xf -
    or
    zcat matlab_netcdf_4x5.tar.Z | tar -xf -
    as appropriate. This will put all of the m-files into a suitable directory (called something like matlab_netcdf_5_0).

    If you have a p-code version then put this into a new directory (called something like matlab_netcdf_5_0), start matlab, and type in the name of the p-code file (without the .p). This will automagically put the required m-files into the directory.

  2. Put the directory containing the matlab/netCDF interface into matlab's path - perhaps by using the 'path' command. It is possible to store the m-files in the directory containing Chuck's files (this would usually be $TOOLBOX/local/netcdf). The only trouble with this is that matlab will then see a conflict between the Contents.m file is this distribution and chuck's netCDF help file.
  3. Edit the m-file pos_cds.m; it returns the path to the common data set directory. pos_cds.m is called by whatnc, inqnc and getnc and so any netCDF file in the common data set will be accessible to users without them needing to specify path names.
  4. You may edit the the function y_rescale.m although this is strongly advised against. The function y_rescale determines whether getnc applies the attributes scale_factor and add_offset to relevant variables and attributes. The default is that any variable will be automatically rescaled; if a variable has attributes valid_range, valid_min, valid_max or _FillValue then these will be automatically rescaled also. This behaviour can be changed by editing y_rescale.m but you should be very cautious in doing so. In particular, if the variable is rescaled and its attributes not, or vice versa, then the options to replace 'invalid' data will not work in the way expected in the netCDF standard.

Summary of functions

The following commands are available (use help in matlab for further information) and will be supported in the future. There is also a detailed discussion of getnc.
attnc
imports attributes of a netCDF file
getnc
imports variables from a netCDF file
inqnc
interactive inquiry of netCDF file
netcdf toolbox
direct calls to netCDF functions - use 'help netcdf' for a detailed description
timenc
finds the time vector and the corresponding base date for a netCDF file that meets COARDS standards
whatnc
lists netCDF files in current directory

Detailed description of getnc

getnc retrieves data from a NetCDF file. It is called from within matlab5 by:

values = getnc(file, varid, corner, end_point, stride, order, ...
change_miss, new_miss, squeeze_it)

DESCRIPTION:
getnc retrieves data from a NetCDF file. The way getnc behaves depends on how many of the input arguments are passed to it. If no arguments are passed then it returns a help message. If one argument is passed then the user is asked questions to determine information necessary for the data retrieval. If more than one argument is passed then getnc returns the data without needing to ask any questions. The input arguments are listed below. INPUT:

file
is the name of a netCDF file but without the .cdf or .nc extent.
varid
may be an integer or a string. If it is an integer then it must be the menu number of the n dimensional variable as used by a call to inqnc or getnc. If it is a string then it should be the name of the variable.
corner
is a vector of length n specifying the hyperslab corner with the lowest index values (the bottom left-hand corner in a 2-space). The corners refer to the dimensions in the same order that these dimensions are listed in the relevant questions in getnc.m and in the inqnc.m description of the variable. A negative element means that all values in that direction will be returned. If a negative scalar is used this means that all of the elements in the array will be returned.
end_point
is a vector of length n specifying the hyperslab corner with the highest index values (the top right-hand corner in a 2-space). The corners refer to the dimensions in the same order that these dimensions are listed in the relevant questions in getnc.m and in the inqnc.m description of the variable. An element in the end_point vector will be ignored if the corresponding element in the corner vector is negative.
stride
is a vector of length n specifying the interval between accessed values of the hyperslab (sub-sampling) in each of the n dimensions. A value of 1 accesses adjacent values in the given dimension; a value of 2 accesses every other value; and so on. If no sub-sampling is required in any direction then it is allowable to just pass the scalar 1 (or -1 to be consistent with the corner and end_point notation).
order
is a vector of length n specifying the order of the dimensions in the returned array. order = -1 or [1 2 3 .. n] for an n dimensional netCDF variable will return an array with the dimensions in the same order as described by a call to inqnc(file) from within matlab or 'ncdump -h' from the command line. Putting order = -2 will reverse this order. More general permutations are given re-arranging the numbers 1 to n in the vector.
change_miss
== 1 causes missing values to be returned unchanged.

== 2 causes missing values to be changed to NaN.
== 3 causes missing values to be changed to new_miss (after rescaling if that is necessary).
< 0 produces the default (missing values to be changed to NaN).
new_miss
is the value given to missing data if change_miss = 3.
squeeze_it
specifies whether the returned array should be squeezed. That is, when squeeze_it is non-zero then the squeeze function will be applied to the returned array to eliminate singleton array dimensions. This is the default. Note also that a 1-d array is returned as a column vector.
OUTPUT:
values
is a scalar, vector or array of values that is read in from the NetCDF file
NOTES:
  1. In order for getnc to work non-interactively it is only strictly necessary to pass the first 2 input arguments to getnc - sensible defaults are available for the rest.

    2. These are:
    corner, end_point = [-1 ... -1], => all elements retrieved
    stride = 1, => all elements retrieved
    order = [1 2 3 .. n] for an n dimensional netCDF variable
    change_miss = 2, => missing values replaced by NaNs
    new_miss = 0;
    squeeze_it = 1; => singleton dimensions will be removed
  2. It is not acceptable to pass only 3 input arguments since there is no default in the case of the corner points being specified but the end points not.
  3. By default the order of the dimensions of a returned array will be the same as they appear in the relevant call to 'inqnc' (from matlab) or 'ncdump -h' (from the command line). (This is the opposite to what happened in an earlier version of getnc.) This actually involves getnc re-arranging the returned array because the netCDF utilities follow the C convention for data storage and matlab follows the fortran convention.

    4. Since the netCDF file follows the C convention this means that in the actual storage of the data lon is the fastest changing index, followed by lat, and then month. However matlab (and fortran) use the opposite convention and so month is the fastest changing index, followed by lat, and then lon. getnc actually used the permute function to reverse the storage order. If efficiency is a concern (because of using very large arrays or a large number of small arrays) then passing order == -2 to getnc will produce the fastest response by returning the data in its 'natural' order (a 180x90x12 array in our example)

  4. If the values are returned in a one-dimensional array then this will be a column vector. This choice provides consistency if there is an unlimited dimension. That is, if the length of the unlimited dimension is n then an m x n array will be returned even for n = 1.)
  5. A strange 'feature' of matlab 5 is that it will not tolerate a singleton dimension as the final dimension. Thus, if you chose to have only one element in the final dimension this dimension will be 'squeezed' whether you want it to be or not - this seems to be unavoidable.
EXAMPLES:

To be more explicit, suppose that we use inqnc to examine a netCDF file. Then 2 lines in the output might read:

The 3 dimensions are 1) month = 12 2) lat = 90 3) lon = 180.
--- Information about airtemp(month lat lon ) ---

Likewise using 'ncdump -h' from the command line would have the corresponding line:

short airtemp(month, lat, lon);

1) The simplest possible call to getnc will get all the elements of the variable (note the order of the dimensions):

>> airtemp = getnc('oberhuber', 'airtemp');
>> size(airtemp) = 12 90 180

2) Get a subsample of the variable, note the stride:

 >> airtemp = getnc('oberhuber', 'airtemp', [-1 1 3], [-1 46 6], [1 5 1]);
>> size(airtemp)
ans = 12 10 4

3) Get all the elements of the variable, but with dimensions permuted:

 >> airtemp = getnc('oberhuber', 'airtemp', -1, -1, -1, [2 3 1]);
>> size(airtemp)
ans = 90 180 12

4) Get all the elements of the variable, but with missing values replaced with 1000. Note that the corner, end_point, stride and order vectors have been replaced by -1 to indicate that the whole range is required in the default order:
>> airtemp = getnc('oberhuber', 'airtemp', -1, -1, -1, -1, 3, 1000);

>> size(airtemp)
ans = 12 90 180

5) Get a subsample of the variable, a singleton dimension is squeezed:

 >> airtemp = getnc('oberhuber', 'airtemp', [-1 7 -1], [-1 7 -1]);
>> size(airtemp)
ans = 12 180

6) Get a subsample of the variable, a singleton dimension is not squeezed:

 >> airtemp = getnc('oberhuber','airtemp',[-1 7 -1],[-1 7 -1],-1,-1,-1,-1,0);
>> size(airtemp)
ans = 12 1 180

Further documentation

There used to be a user manual in latex and postscript form. I have not yet updated the manual and so have not put it in this distribution. In fact it should not be necessary for an experienced matlab and netCDF user to read the manual at all. Simply do a help on the 5 m-files that would be commonly used - attnc, getnc, inqnc, timenc and whatnc.

Backwards compatibility issues

Earlier versions of these m-files had names like getcdf, whatcdf, etc and were used for matlab versions 3.5 and 4.2. If you have a lot of legacy code that you don't wish to change then you should download and install matlab-netcdf-4.2-5.0.tar.Z. This runs under matlab 5 and mimics the older matlab/netCDF interface.

Latest changes

Disclaimer

This software is provided "as is" without warranty of any kind. It is covered by a general CSIRO Legal Notice and Disclaimer.

People involved in the development of the matlab/netCDF interface

Julie Allen: jallen@whoi.edu
Chuck Denham: cdenham@usgs.gov
Jim Mansbridge: jim.mansbridge@marine.csiro.au
Rich Signell: rsignell@usgs.gov

Contact details

This web page is maintained by Jim Mansbridge, CSIRO Division of Marine Research

Postal address: GPO Box 1538, Hobart, Tasmania 7001, Australia 
Phone: +61-3-62 32 5416
Fax: +61-3-62 32 5123 
Email: Jim.Mansbridge@marine.csiro.au

This page is http://www.marine.csiro.au/sw/matlab-netcdf.html.
It was last revised $Date: 1998/09/07 05:39:54 $. 
Further details on the research of the CSIRO Division of Marine Research are available through the Division's Home Page.
CSIRO Marine Home Page

For more information contact reception@marine.csiro.au or telephone +61-3-62325222. Unless otherwise indicated all contents in these web documents are copyright © 1997 CSIRO. Use of this web site and information available from it is subject to our Legal Notice and Disclaimer