World Ocean Circulation Experiment (WOCE) netCDF format

This page has been retained for historical reasons. It should, however, be noted that much of the information it contains is now redundant as Mathworks has introduced a native netcdf toolbox in MATLAB. For more information please refer to the MATLAB documentation on the Mathworks web site.


The following describes some simple tools that are available for the reading of netCDF files found in the WOCE Global Data Version 3.0 DVD. These tools allow the netCDF files to be read quickly and easily and to be manipulated by many common analysis packages such as ncBrowse and Ferret in addition to traditional languages such as Fortran, C/C++ and Java.

Because netCDF format is now used for all of the different data products on the WOCE Global Data Version 3.0 DVD, the skills required to read one data set are the same as those needed to read all the others data sets. This reduces the hurdles involved in reading all the different data sets and allows the analyst to concentrate on the interpretation of the observations from many different sources.

As the netCDF files are self-describing, the attributes of each variable (such as units) and name are defined in the data set (along with other information such as the source, creation date, investigator, position, etc). This documentation preserves much of the original information in the data set reducing the chance of errors occurring during analysis.

Why use netCDF for the WOCE Global Data Version 3.0 DVD?

All of the WOCE Global Data is now in netCDF format. This data format has many advantages, the most important of which is that it is self-describing. This means that software packages can directly read the data and determine their structure, the variables' names and essential metadata such as the units.

This self-describing aspect of netCDF file format means that the information needed to ensure accurate work (i.e. reducing the incidence of errors) is available with the data themselves. Secondly, it means that programs described below can read a netCDF file and generate the code needed to read the file whether it be Fortran, C/C++, Java or Perl. Thirdly, plotting and analysis packages (e.g. Ferret, IDL, MATLAB) can directly read the netCDF files for plotting or analysis. In many of these packages the axes can be labelled without intervention from the user.

Although there is an initial learning curve for the inexperienced netCDF user, high efficiency in reading netCDF files and multiple data can be readily achieved as shown in the examples below. These savings translate to more time for analysing data and addressing the synthesis of the WOCE Global Data.

It is assumed that netCDF libraries have already been installed on your system. They can be obtained from Unidata and are available for Unix, Windows and Macintosh based systems. This site also contains excellent description of the Fortran (also Fortran 90), Java and Perl interfaces for netCDF files. Freely available and commercial software that uses netCDF for input are also listed at these sites and includes products such as Ferret, GMT and GrADs and commercial products such as MATLAB, NCAR Graphics, IDL and others. Here we focus on reading netCDF files with ncBrowse, Matlab, IDL, Fortran, C, ncdump, and Ferret.

The WOCE Global Data V3 are now in a Cooperative Ocean/Atmosphere Research Data Service (COARDS) compliant format. This means that the variables names associated with the data, the attributes of the data and the time convention follow a common standard for all the different data types within the WOCE Global Data set, and also are common to other data sets that are used by the oceanographic and meteorology communities.

Using ncBrowse to read netCDF files

This command is a Java application and can be obtained at the EPIC web site. This command allows the contents of variables, global attributes to be viewed graphically. It can run on UNIX (and linux), Windows and Macintosh's (Max OSX) which have the Java Virtual Machine installed. Further information may be obtained from the EPIC web site or the Java web site.

NcBrowse has been extended over the earlier versions. It now works with both COARDS and EPIC compliant netcdf files. The WOCE Global Data V3 set are COARDS compliant and therefore should allow the automatic display of plot elements such as labels and variable names and units. The interface is largely self explanatory and provides a wonderful method for browsing generic netCDF files.

Exporting netCDF files

ncBrowse allows the user to export parts (or all) of a file in the same format as the ncdump command (described elsewhere in this document). Thus, for many users who require the analysis of relatively few data files, ncBrowse can provide the first quick look at the WOCE data, and should the data require further calculation allow export of the data to a flat ascii file.

OPenDAP files (formerly DODS)

The WOCE Global Data Version 3.0 DVD data are also to be delivered over the world wide web. ncBrowse also includes the capability to browse the WOCE netCDF files over the web using the OPenDAP protocol (formerly know as DODS). This feature means that the WOCE Global Data V3 data set does not need to be resident on your local hardware.

Installation of Java is straightforward under Windows and Linux (Redhat 7.1) and ncBrowse installs very easily on top of this.

This product is well worth installing and using for the quick plotting and export of netCDF files as part of the WOCE Global Data V3.

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.

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 (Chuck Denham interface). 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 example in Appendix 2 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 the WOCE Global Data V3 has a common structure there is always a 'time', 'latitude', 'longitude' variable and the data fields follow the Cooperative Ocean/Atmosphere Research Data Service (COARDS) naming convention. In principle the user does not need to know anything about the structure and size of the data (i.e. format and dimensions) 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.

Reading netCDF using the CSIRO MATLAB/netCDF interface

Commonwealth Scientific Industrial Research Organisation (CSIRO) distributes an interface for the reading of netCDF files. 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 the Chuck Denham interface . You will also need this software to use the CSIRO matlab/netCDF anyway. Follow the install instructions at the above two web sites.

Sample commands of CSIRO MATLAB/netCDF interface

Of the six main commands, the two most important commands are getnc (getcdf) and inqnc (inqcdf). The detailed instruction on their use is given at the CSIRO web site 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. 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 eight 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 seven 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 (i.e. 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 web site (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 command. For example, in matlab


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

Using IDL to read netCDF files

IDL can read netCDF files and specifically has a browser to do this (see page 137 of What's new in IDL 5.3). In addition IDL has specific routines for reading netCDF files. However, the simplest way to create the IDL code you need to read a netCDF file is to use the IDL programs cdf2idl from C4 Integrated Data System (CIDS). The concept of this program is similar cdf2fortran.f, cdf2c.c, and cdf2asc.c programs and is provided by the same group, C4 Interactive Display System. This program reads a netCDF file and creates another IDL script which can read the netCDF file.

Example of using cdf2idl

From within IDL all you need to do, to read the current meter data file shown for the cdf2fortran example is

IDL> .run

IDL> cdf2idl, 'rcm00683.cdf'

IDL> @script.idl

At the completion of this script all of the current meter data are in memory ready to be analysed. A total of three lines of IDL code is needed to read this data set. These three lines of code are so general that they will actually read any of the netCDF files from any of the WOCE Data Assembly Centres provided as part of the WOCE Global Data V3.0.

Using Fortran to read NetCDF files

The simplest way to create the Fortran code you need to read a netCDF is to use the Fortran programs cdf2fortran.f (at the above site or from C4 Integrated Data System (CIDS) or gennet.for from the Center for Ocean-Atmospheric prediction studies (COAPS). These programs read a netCDF file and create another Fortran program with the required calls to the netCDF libraries. This machine generated program only needs to be compiled (with the correct include file and netCDF libraries). When executed this code fragment can then read the netCDF file and is ready for the Fortran code to be added to undertake the analysis required by the user. The variable names reflect the internal structure of the netCDF file and this machine generated code is quite readable by humans.

Worked example of cdf2fortran

The cdf2fortran.f code has been tested on the samples of the netCDF files for the WOCE volume. Retrieve cdf2fortran tar file and use the make file to compile the code. You will have to check that the include directory and the LIBS directory are correct for your particular installation of the netCDF libraries.

To compile cdf2fortran just type

> make cdf2fortran

To execute the cdf2fortran code

> cdf2fortran rcm00683.cdf

Generated fortran program called readnet.f


Either edit readnet.f file and correct the "include ‘’" file for your particular installation and compile

> f77 readnet.f

or compile using the -I option to get the correct include file and the -l option to get the correct library files

> f77 -c readnet.f -I/usr/local/netcdf/include

> f77 -o readnet readnet.o -l/usr/local/netcdf/lib/libnetcdf.a

Sometimes there is a problem at compilation because the variable names may have the same name as a parameter name. Changing the parameter name fixes this problem and now you should have a complete fortran code able to read your particular netCDF file.

The result of compiling the above for a sample of the current meter data on WOCE Global Data CD ROM2 is shown in Appendix 1. Although this piece of code is quite long (compared to the examples shown below) it is reliable and is quick to develop compared  to reading files that are not self-describing (e.g. plain ascii files). The sample code fragment can in principle be generalised to read the netCDF data for all of the different current meter data. The program gennet.for works in a very similar way and produces a slightly better documented fortran code. See Appendix 4 for fixing a bug in the readnet.for programs created by gennet.for.

Using C to read netCDF files

The simplest way to create the C code you need to read a netCDF is to use the C programs cdf2c.c  from C4 Integrated Data System (CIDS). This program reads a netCDF file and creates another C program with the required calls to the netCDF libraries. This machine generated program only needs to be compiled (with correct include file and netCDF libraries). When executed this code fragment can then read the netCDF file and is ready for the C code to be added to undertake the analysis required by the user. The procedure for installing and compiling is described in the documentation from the web site listed above and is similar in operation to the cdf2fortran program described above.

Other methods for examining netCDF files

Obtaining ASCII output of a netCDF file is possible. There are several methods. First is to use ncdump or ncBrowse. Both ncdump and ncBrowse produce the ASCII output in the same format. However this format is not particularly friendly if you want to import the data to a spreadsheet such as Microsoft Excel. The second method is to use Ferret, MATLAB or IDL. An example is given from Ferret below. The third method is to use publicly available routines such as cdf2asc or nc2text commands.


This utility is a very useful program for those who do not have MATLAB, IDL, Ferret, or ncBrowse and want to check the attributes and obtain the data from a netCDF file. On unix machines the main pages describe this command in detail (and its partner ncgen) or in the netCDF User's Guide for Fortran, (Chapter 10). To obtain the attributes of the current meter data one would

>ncdump -h rcm00683.cdf

Appendix 3 shows the output from this command. To obtain the speed data in this file

>ncdump -v speed rcm00683.cdf

or to obtain the speed and the direction data

>ncdump -v speed,direction rcm00683.cdf

The last command can lead to large files ASCII files, but have a relatively simple structure and can be read by programs. However, the value of ncdump is that it allows one to check attributes and structure of netCDF files quickly and easily. A more convenient way to examine netCDF files is to be able to visualise the data using a graphical interface such as ncBrowse or Ferret.

Using Ferret to create ASCII files

Ferret has the capability to read netCDF file directly, and it also has the capability to export variables in ASCII format from a netCDF file. For example the ferret commands

USE sst05d19900108.ncSHADE/X=0.25E:363.25E/Y=89.75S:89.75N SEA_SURFACE_TEMPERATURE[]LIST/X=0.25E:363.25E/Y=0S/file=sea_surface_temperature SEA_SURFACE_TEMPERATURE[]QUIT

will use the sea-surface temperature netCDF file (USE command), plot its contours (SHADE), and list the sea-surface temperature field along the equator around the world to the file called sea_surface_temperature (LIST).

The output of the LIST command in this case is a more friendly format than the output from ncdump, and can be imported into spreadsheet programs.

                    sea surface temperature (1/100 degree C)
                    LATITUDE: 0 (interpolated)
                    DATA SET: ./
0.25E   /       1: 32767.
0.75E   /       2: 32767.
1.25E   /       3: 17644.
1.75E   /       4: 32767.
2.25E   /       5: 32767.
2.75E   /       6: 17704.
3.25E   /       7: 32767.
3.75E   /       8: 32767.
4.25E   /       9: 32767.
4.75E   /     10: 32767.


0.25W  /   720: 17711.
0.25E   /   721: 32767.
0.75E   /   722: 32767.
1.25E   /   723: 17644.
1.75E   /   724: 32767.
2.25E   /   725: 32767.
2.75E   /   726: 17704.
3.25E   /   727: 32767.

Note that Ferret cannot list a large number of columns to a file, and thus the size of two dimensional arrays that are LISTed to a file is limited.

Important web sites

  • Unidata - netCDF libraries and documentation and gennet.for program
  • C4 Interactive Display System (CIDS) - the suite of programs for reading arbitrary netCDF files and generating Fortran, C and IDL code to read the netCDF files
  • WOCE Tools and Utilities  - gennet.for program
  • Scientific Industrial Research Organisation (CSIRO) - MATLAB/netCDF interface
  • Chuck Denham's MATLAB/netCDF interface - needed with CSIRO MATLAB/netCDF interface
  • EPIC web site  - ncbrowse
  • Cooperative Ocean/Atmosphere Research Data Service (COARDS)

Appendix 1: Readnet.for created from cdf2fortran

Sample file produced by the cdf2fortran utility with the netCDF file 'rcm00683.cdf' found in the WOCE CDROM 2. Note that this Fortran routine can be easily generalised to read all of the cm data records on this CD set.

c------------------------------------------------------------------ -----


c readnet.f

c This file is a fortran template file designed to read the given

c netCDF file into memory.


c History:

c Date Name Action

c --------- ------------ --------------------------------------------

c ?? ??? ?? cids Created.



c Do not forget to include the -I path_to_netcdf_includes in your

c compile statement

c Required includes.

c include ''

include '/usr/local/netcdf/include/'

c Define Variables.

c Variable ids run sequentially from 1 to nvars = 08

parameter (nvars = 8) ! number of variables

parameter (nrec= 36434) ! change this 'to generalize

parameter (ndims = 1) ! number of dimensions

parameter (itime = 36434)

integer*4 rcode ! error code

integer*4 recdim ! record dimension

real*8 date(nrec)

real*8 time(nrec)

real*4 speed(nrec)

real*4 direction(nrec)

real*4 u(nrec)

real*4 v(nrec)

real*4 temperature(nrec)

real*4 pressure(nrec)

integer*4 start(ndims) ! hyperslab starting index

integer*4 count(ndims) ! hyperslab count from start

integer vdims(ndims) ! max # of var dims

character*1024 strbuf ! string buffer for var

! and attr names

c Open netCDF file.


c Get info on the record dimension for this file.

call ncinq(ncid,ndims,nvars,ngatts,recdim,rcode)

call ncdinq(ncid,recdim,strbuf,nrecs,rcode)

c nrecs now contains the # of records for this file

c Retrieve data for date variable.

call ncvinq(ncid, 1,strbuf,nctype,nvdim,vdims,nvatts,rcode)


do j=1,nvdim

call ncdinq(ncid,vdims(j),strbuf,ndsize,rcode)




end do

call ncvgt(ncid, 1,start,count,date,rcode)

c Retrieve data for time variable.

call ncvinq(ncid, 2,strbuf,nctype,nvdim,vdims,nvatts,rcode)


do j=1,nvdim

call ncdinq(ncid,vdims(j),strbuf,ndsize,rcode)




end do

call ncvgt(ncid, 2,start,count,time,rcode)

c Retrieve data for speed variable.

call ncvinq(ncid, 3,strbuf,nctype,nvdim,vdims,nvatts,rcode)


do j=1,nvdim

call ncdinq(ncid,vdims(j),strbuf,ndsize,rcode)




end do

call ncvgt(ncid, 3,start,count,speed,rcode)

c Retrieve data for direction variable.

call ncvinq(ncid, 4,strbuf,nctype,nvdim,vdims,nvatts,rcode)


do j=1,nvdim

call ncdinq(ncid,vdims(j),strbuf,ndsize,rcode)




end do

call ncvgt(ncid, 4,start,count,direction,rcode)

c Retrieve data for u variable.

call ncvinq(ncid, 5,strbuf,nctype,nvdim,vdims,nvatts,rcode)


do j=1,nvdim

call ncdinq(ncid,vdims(j),strbuf,ndsize,rcode)




end do

call ncvgt(ncid, 5,start,count,u,rcode)

c Retrieve data for v variable.

call ncvinq(ncid, 6,strbuf,nctype,nvdim,vdims,nvatts,rcode)


do j=1,nvdim

call ncdinq(ncid,vdims(j),strbuf,ndsize,rcode)




end do

call ncvgt(ncid, 6,start,count,v,rcode)

c Retrieve data for temperature variable.

call ncvinq(ncid, 7,strbuf,nctype,nvdim,vdims,nvatts,rcode)


do j=1,nvdim

call ncdinq(ncid,vdims(j),strbuf,ndsize,rcode)




end do

call ncvgt(ncid, 7,start,count,temperature,rcode)

c Retrieve data for pressure variable.

call ncvinq(ncid, 8,strbuf,nctype,nvdim,vdims,nvatts,rcode)


do j=1,nvdim

call ncdinq(ncid,vdims(j),strbuf,ndsize,rcode)




end do

call ncvgt(ncid, 8,start,count,pressure,rcode)

c ******************************************

c Begin writing statements to use the data.

c ******************************************

c End Program.



Appendix 2: Example MATLAB script for current meter data

A MATLAB macro to read the netCDF file 'rcm01037.cdf' found in the WOCE CDROM 2. This file is the equivalent of the Fortran code listed in Appendix 1. Note that this macro routine can be easily generalised to read all of the current meter data records on this CD set.


% A simple Matlab script to read the RCM netcdf file.


% Author: Nathan Bindoff

% Date: 28 March 2000

% The script uses Jim Mansbridge's netcdf routines for matlab.


% Documentation and description of these routines can be found at




% Read the current meter data

















% Example of contents of 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

Appendix 3: Example output from ncdump

The attributes of the file rcm00683.cdf obtained from ncdump -h. This is equivalent to the MATLAB inqnc command. It describes the global attributes, and each of the variables.

netcdf rcm00683 {


time = UNLIMITED ; // (36434 currently)


double date(time) ;

date:long_name = "date (yr, mo, day)" ;

date:units = "YYYYMMDD" ;

date:valid_range = 19800101, 20101231 ;

double time(time) ;

time:long_name = "time of day" ;

time:units = "hhmmss.dd" ;

time:valid_range = 0., 2359.59 ;

float speed(time) ;

speed:units = "m/sec" ;

speed:valid_range = 0., 3. ;

float direction(time) ;

direction:long_name = "true direction (toward)" ;

direction:units = "degrees" ;

direction:valid_range = 0., 360. ;

float u(time) ;

u:long_name = "eastward velocity component" ;

u:units = "m/sec" ;

u:valid_range = -3., 3. ;

float v(time) ;

v:long_name = "northward velocity component" ;

v:units = "m/sec" ;

v:valid_range = -3., 3. ;

float temperature(time) ;

temperature:long_name = "water temperature" ;

temperature:units = "degrees C" ;

float pressure(time) ;

pressure:units = "decibars" ;

// global attributes:

:experiment_name = "Deep Currents (PCM6)" ;

:mooring_name = "WHOI 942" ;

:pi_name = "B.Owens/B.Warren" ;

:instrument_type = "VACM" ;

:latitude = " 36.4025" ;

:longitude = " 150.2307" ;

:instrument_depth = "2001.0 m" ;

:seafloor_depth = " 5829 m" ;

:sampling_interval = " 30 min" ;

:earliest_start_time = "08-jun-1993 12:15:00" ;

:latest_stop_time = "07-jul-1995 12:45:00" ;

:null_value = -999.9 ;


Appendix 4: Bug in gennet.for

The program in gennet.for is not quite perfect. When it creates the readnet.for program it some times places the wrong routine call in readnet.for. If you get a message like

>NCAGT: : Attempt to convert between text & numbers

the following may fix the problem. The line where readnet.for crashes is a call to NCAGT. At this point, readnet.for tries to read a character variable attribute"long_name" using a routine that is designed for numeric attributes (NCAGT). To make the code work substitute a call to NCAGTC at this point in the code and also to assign mtlen=50 (the character width dimension of "name"). With these two changes the code runs like a charm.