4.18 Options for COARDS-compliant netCDF files
Keywords: GMT_Docs

Next: 4.19 The NaN data Up: 4. General features Previous: 4.17 Grdfile format specifications Contents Index

#
4.18 Options for COARDS-compliant netCDF files

When the netCDF file contains more than one 2-dimensional variable, GMT programs will load the first such variable in the file and ignore all others. Alternatively, the user can select the required variable by adding the suffix ``?varname'' to the file name. For example, to get information on the variable ``slp'' in file file.nc, use:

    	grdinfo "file.nc?slp"

Since COARDS-compliant netCDF files are the default, the additional suffix ``=nf'' can be omitted.

In case the named variable is 3-dimensional, GMT will load first (bottom) layer. If another layer is required, either add ``[index]'' or ``(level)'', where index is the index of the third (depth) variable (starting at 0 for the first layer) and level is the numerical value of the third (depth) variable associated with the requested layer. To indicate the second layer of the 3-D variable ``slp'' use as file name: file.nc?slp[1].

When you supply the numerical value for the third variable using ``(level)'', GMT will pick the layer closest to that value. No interpolation is performed.

Note that the question mark, brackets and parentheses have special meanings on Unix-based platforms. Therefore, you will need to either escape these characters, by placing a backslash in front of them, or place the whole file name plus modifiers between single quotes or double quotes.

A similar approach is followed for loading 4-dimensional grids. Consider a 4-dimensional grid with the following variables:

    	lat(lat): 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
    	lon(lon): 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
    	depth(depth): 0, 10, 20, 30, 40, 50, 60, 70, 80, 90
    	time(time): 0, 12, 24, 36, 48
    	pressure(time,depth,lat,lon): (5000 values)

To get information on the 1010 grid of pressure at depth 10 and at time 24, one would use:

    	grdinfo "file.nc?pressure[2,1]"

or (only in case the coordinates increase linearly):

    	grdinfo "file.nc?pressure(24,10)"

The COARDS conventions set restrictions on the names that can be used for the units of the variables and coordinates. For example, the units of longitude and latitude are "degrees_east" and "degrees_north", respectively. Here is an example of the header of a COARDS compliant netCDF file (to be obtained using ncdump:

    netcdf M2_fes2004 {
    dimensions:
            lon = 2881 ;
            lat = 1441 ;
    variables:
            float lon(lon) ;
                    lon:long_name = "longitude" ;
                    lon:units = "degrees_east" ;
                    lon:actual_range = 0., 360. ;
            float lat(lat) ;
                    lat:long_name = "latitude" ;
                    lat:units = "degrees_north" ;
                    lat:actual_range = -90., 90. ;
            short amp(lat, lon) ;
                    amp:long_name = "amplitude" ;
                    amp:unit = "m" ;
                    amp:scale_factor = 0.0001 ;
                    amp:add_offset = 3. ;
                    amp:_FillValue = -32768s ;
            short pha(lat, lon) ;
                    pha:long_name = "phase" ;
                    pha:unit = "degrees" ;
                    pha:scale_factor = 0.01 ;
                    pha:_FillValue = -32768s ;

This file contains two grids, which can be plotted separately using the names M2_fes2004.nc?amp and M2_fes2004.nc?pha. The attributes `long_name` and `unit` for each variable are combined in GMT to a single unit string. For example, after reading the grid `y_unit` equals `latitude [degrees_north]`. The same method can be used in reverse to set the proper variable names and units when writing a grid. However, when the coordinates are set properly as geographical or time axes, GMT will take case of this. The user is, however, still responsible for setting the variable name and unit of the z-coordinate. The default is simply "z".

Next: 4.19 The NaN data Up: 4. General features Previous: 4.17 Grdfile format specifications Contents Index