The netCDF ncgen and ncdump utilities

The ncgen and nc dump utilities allow the user to convert between netCDF binary and ASCII text files.

Introduction

Although netCDF is a binary data format, there are utilities such as ncdump which will produce an ASCII text file of the dataset, and ncgen which will produce a netCDF file from an ASCII file.

There are several sections following:

• Installing netCDF in Unix
• Installing netCDF in Windows
• Using ncgen and ncdump
• The next stage - importing files

1. Installing the netCDF package

Firstly, you should check if the netCDF package is installed on your computer. Either ask your system manager or hunt for the package yourself.

1. You should visit http://www.unidata.ucar.edu/packages/netcdf/ and click on one of the download options (e.g. a compressed tar file and/or zip file).
2. Unzip and extract the contents of the tar file (using whatever decompression-utility you have handy, such as gunzip and tar).
3. You should now have uncompressed the filedata to reveal a directory full of files such as 'Makefile', 'Readme', 'Release_notes' etc. Locate the file named 'INSTALL.html' and open it in a web-browser. This file will instruct how to install the software on the computing platform that you are using. (If you do not know which platform you are using then ask your system manager.) The INSTALL.html document is also available at: http://www.unidata.ucar.edu/packages/netcdf/INSTALL.html if you have problems locating it.
4. Follow the instructions in the INSTALL.html document for your relevant platform.
5. To test that the software has been correctly installed you should be able to type 'ncdump -help' which displays a message of how to use the utility. Depending on your set-up you may have to include the full directory path such as '/usr/local/bin/ncdump -help'.

1. Visit http://www.unidata.ucar.edu/packages/netcdf/faq.html#win and click on one of the download options. At the time of writing there are two options given:
   • "We have pre-built netCDF 3.5.0 libraries for Win32 systems (Windows 95, 98, NT, Millennium, XP), available here": ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/win32/netcdf-3.5.0.win32bin.ZIP - this is probably the easiest way if this sort of thing is new to you.
   • "To do your own source build, get this zip file" - only use this if you know what you are doing.
2. Assuming you have downloaded via the first option, you will need to unzip the file using whatever decompression-utility you have handy. This is usually Winzip which is freely available from http://www.winzip.com/, if it is not already available on your machine. Winzip will give you the option of extracting the files to whatever directory you wish, for example, in a folder called 'C:\Program Files\netCDF\' On Winzip you just click 'Extract' and then specify where you want the data to be placed.
3. The folder you chose to extract the data to should now contain the folders 'lib', 'include', 'bin' and 'src'. Inside the 'bin' folder you will find the ncdump.exe and ncgen.exe utilities that you need.

In order to test the ncdump and ncgen utilities you need some data. The beauty of the utilities is that they allow conversion between binary netCDF (file extension .nc) code and the ASCII (text) representation of that code in the network Common data form Description Language (CDL - file extension .cdl). For a thorough understanding of the CDL language and the utilities mentioned here you should consult http://www.unidata.ucar.edu/packages/netcdf/guide_12.html.

However, we can start with a very simple example. The description of the file gives a brief overview of the basic concepts of netCDF and CF conventions.

Preparation

Check you know where the netCDF utilities are stored. Now you are ready to play with the simple.cdl file. Note that if you have saved the file to a Unix/Linux file system you should remove the Carriage Return characters at the end of each line in the file. If you are using Windows then you will need to open a Command Prompt window or an MS-DOS window. If you are using this type of system for the first time you can find out about commands by simply typing 'help' and pressing Return. (e.g. ncgen -help)

Accessing the utilities

With the file simple.cdl, ncgen will create a new netCDF file called simple.nc. To test this has worked, you can then use ncdump to create another text file, simple2.cdl, via the commands:

[netcdf_bin_directory]ncgen -o [your_directory]simple.nc [your_directory]simple.cdl

[netcdf_bin_directory]ncdump [your_directory]simple.nc > [your_directory]simple2.cdl

Where [netcdf_bin_directory] and [your_directory] are the locations of the netCDF utilities and your samples files respectively.

Here is a list of commands for ncdump and their interpretation:

ncdump [-c|-h] [-v ...] [[-b|-f] [c|f]] [-l len] [-n name] [-p n[,n]] file

[-c]	Coordinate variable data and header information
[-h]	Header information only, no data
[-v var1[,...]]	Data for variable(s) ,... only
[-b [c|f]]	Brief annotations for C or Fortran indices in data
[-f [c|f]]	Full annotations for C or Fortran indices in data
[-l len]	Line length maximum in data section (default 80)
[-n name]	Name for netCDF (default derived from file name)
[-p n[,n]]	Display floating-point values with less precision
file	File name of input netCDF file

The ncdump utility has now written out another text file called 'simple2.cdl'. You can now compare this with 'simple.cdl' to check that everything is working correctly. Now you have generated and re-generated a netCDF file. You might now like to make some changes to your .cdl file and check that they are acceptable. If ncgen locates a syntax error in the .cdl file it will report where the error has been found so that you can trace it.

Once you feel comfortable with ncgen and ncdump you can branch out by importing netCDF files from elsewhere and looking at their .cdl representations. It is also useful to open the files in software package packages that are available to read netCDF. Packages we use at the BADC include XCONV/CONVSH and CDAT. There is also a long list of other packages available on the netCDF software pages.

Many researchers install the C, Fortran and Perl libraries so that they can write netCDF files directly from their programmes. More information about these libraries is available on the Unidata netCDF pages.

Some scientists have also developed their own independent software for reading and writing netCDF, it would be very useful for this software to be shared within the community so the BADC welcomes any code that you would like to offer so that it can be passed on to others. You can contact us via BADC@rl.ac.uk

The BADC netCDF homepage

The BADC CF conventions homepage