3.0 Using MATLAB to read netCDF files

There are two methods for reading netCDF files within Matlab.  The first method is perhaps the simplest, and most powerful, but is only available for Matlab 5 and 6.  The second method, described below, is also available for those who only have access of to Matlab 4.  

A general purpose script to load all of a netcdf file using getnc in MATLAB.

3.1 using the netcdf command

The netcdf command is a toolbox that needs to be installed with your matlab toolboxes and was developed by Chuck Denham (http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/  ).  It makes use of structures and objects and it is important that the user has some familiarity with these facilities in matlab.

A simple example of the netcdf  command

The above example shows just how easy it is to read an arbitrary netcdf file into matlab.  It took just one line of code to read the information needed to read the entire file into matlab.  The other lines of code are there to illustrate how one might examine the file, how to load the specific variables (such as latitude, longitude, and sea-surface temperature), and create a preliminary quick look plot of the data.  

Because of the WOCE Global Data V3 have a common structure there is always a 'time', 'latitude', 'longitude' variables and that the data fields follow the COARDS naming convention.  In principle the user doesnot need to know anything about the structure and size of the data (ie format and dimenions) and consequently makes programming very easy.

To do more sophisticated manipulations of the netcdf files with the netcdf command the reader should read the help file from the matlab command line

>> netcdf()

for help, and

>> netcdf('version')

The netcdf command also allows the writing of output files, which means that intermediate analysis files can also be in the netCDF format for further analysis.

3.2 reading netCDF using the CSIRO matlab/netcdf interface

Commonwealth Scientific Industrial Research Organisation (CSIRO) distributes an interface for the reading of netCDF files ( http://www.marine.csiro.au/sw/matlab-netcdf.html  ). This is a  powerful interface for those who are only interested in reading netCDF files. For those who want to create netCDF files from within matlab then you should use Chuck Denhams interface ( http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/  ). You will also need this software to use the CSIRO matlab/netCDF anyway. Follow the install instructions at the above two web sites.

3.21 Sample commands of CSIRO matlab/netCDF interface

Of the 6 main commands, the two most important commands are getnc (getcdf) and inqnc (inqcdf). The detailed instructions on their use is given at the web site (http://www.marine.csiro.au/sw/matlab-netcdf.html  ) and only the bare bones description is given here. The use of inqnc allows the interactive interrogation of the netCDF file. In matlab, for example:

>> inqnc('rcm01037')

--- Global attributes ---

experiment_name: Deep Currents (PCM6)

mooring_name: WHOI 947

pi_name: B.Owens/B.Warren

instrument_type: VACM

latitude: 40.6000

longitude: 147.3492

instrument_depth: 1999.0 m

seafloor_depth: 5280 m

sampling_interval: 30 min

earliest_start_time: 12-jun-1993 12:15:00

latest_stop_time: 01-jul-1995 12:45:00

null_value: -999.9

The 1 dimensions are 1) time = 35954.

time is unlimited in length

----- Get further information about the following variables -----

-1) None of them (no further information)

0) All of the variables

1) date 2) time 3) speed

4) direction 5) u 6) v

7) temperature 8) pressure

>>

creates a description of the contents of the file 'rcm01037'. The global attributes are the information about the data, in this example includes the principal investigator, the instrument name, experiment name etc etc. In addition the routine gives a list of the variables that are contained within the file, in this case there are 8 different variables (date, time, speed etc). In the case of this file the data are organised as vectors with each element corresponding to time and all vectors have a length of 35954. Because 'inqnc' is interactive it is possible to determine the attributes of each of the variables. To retrieve one of the variables within the above data set, such as speed, the getnc command is used.

>> speed=getnc('rcm01037','speed');

This is the simplest use of the getnc command. Because only two arguments are provided getnc assumes that the data are to be automatically scaled, flagged data will be changed to NaN (not a number), and all data are required. The matlab script in Appendix 2 shows how all of the matlab data in the above test file can be read with just 7 lines of code. Considerably less than the FORTRAN example that reads a slightly different netcdf file but has exactly the same variables shown in Appendix 1 . However the development time for the fortran and matlab examples is similar and quick.

The getnc command also has arguments that allows changing the missing values, the stride length (ie allows sub-sampling of the variable) etc. In this way the user can sub-sample, scale the data and read only the variables that are required from the netCDF file. In very large files this represents an important advantage to the user. A nice example of this capability is shown on the above website (by Jim Mansbridge), and also by using the matlab command help where all of the arguments are listed.

>> help inqnc

All of the matlab scripts, designed to read the netCDF files that appear in the WOCE Global Data V2 are based on just these two matlab commands. The use of the simplest form of getnc means that most of the netCDF files provided from a single WOCE Data Assembly Centre will be readable with a single script. It means that it is very easy and quick to create macros that can read the different netCDF files from the WOCE Data Assembly Centre, leading to significant savings in time and effort. Other important commands are whatnc (gives a list of .nc (.cdf) files in local directory) and attnc (gets the attributes of particular variables like scale).

If necessary the scale factor applied to data can be obtained from the netCDF file by using the attnc comand. For example, in matlab

>>Latitude=getnc(file,'Latitude')*attnc(file,'Latitude','Scale');

would force the Latitude to be correctly scaled by the Scale factor from within the netcCDF file. Only the wind data needs this treatment.