Next: , Previous: Wrapped Coordinates, Up: Common features


3.18 Auxiliary Coordinates

Availability: ncbo, ncea, ncecat, ncflint, ncks, ncpdq, ncra, ncrcat
Short options: ‘-X lon_min,lon_max,lat_min,lat_max
Long options: ‘--auxiliary lon_min,lon_max,lat_min,lat_max
Utilize auxiliary coordinates specified in values of the coordinate variable's standard_name attributes, if any, when interpreting hyperslab and multi-slab options. Also ‘--auxiliary’. This switch supports hyperslabbing cell-based grids over coordinate ranges. This works on datasets that associate coordinate variables to grid-mappings using the CF-convention (see CF Conventions) coordinates and standard_name attributes described here. Currently, NCO understands auxiliary coordinate variables pointed to by the standard_name attributes for latitude and longitude. Cells that contain a value within the user-specified range [lon_min,lon_max,lat_min,lat_max] are included in the output hyperslab.

A cell-based grid collapses the horizontal spatial information (latitude and longitude) and stores it along a one-dimensional coordinate that has a one-to-one mapping to both latitude and longitude coordinates. Rectangular (in longitude and latitude) horizontal hyperslabs cannot be selected using the typical procedure (see Hyperslabs) of separately specifying ‘-d’ arguments for longitude and latitude. Instead, when the ‘-X’ is used, NCO learns the names of the latitude and longitude coordinates by searching the standard_name attribute of all variables until it finds the two variables whose standard_name's are “latitude” and “longitude”, respectively. This standard_name attribute for latitude and longitude coordinates follows the CF-convention (see CF Conventions).

Putting it all together, consider a variable gds_3dvar output from simulations on a cell-based geodesic grid. Although the variable contains three dimensions of data (time, latitude, and longitude), it is stored in the netCDF file with only two dimensions, time and gds_crd.

     % ncks -m -C -v gds_3dvar ~/nco/data/in.nc
     gds_3dvar: type NC_FLOAT, 2 dimensions, 4 attributes, chunked? no, compressed? no, packed? no, ID = 41
     gds_3dvar RAM size is 10*8*sizeof(NC_FLOAT) = 80*4 = 320 bytes
     gds_3dvar dimension 0: time, size = 10 NC_DOUBLE, dim. ID = 20 (CRD)(REC)
     gds_3dvar dimension 1: gds_crd, size = 8 NC_FLOAT, dim. ID = 17 (CRD)
     gds_3dvar attribute 0: long_name, size = 17 NC_CHAR, value = Geodesic variable
     gds_3dvar attribute 1: units, size = 5 NC_CHAR, value = meter
     gds_3dvar attribute 2: coordinates, size = 15 NC_CHAR, value = lat_gds lon_gds
     gds_3dvar attribute 3: purpose, size = 64 NC_CHAR, value = Test auxiliary coordinates like those that define geodesic grids

The coordinates attribute lists the names of the latitude and longitude coordinates, lat_gds and lon_gds, respectively. The coordinates attribute is recommended though optional. With it, the user can immediately identify which variables contain the latitude and longitude coordinates. Without a coordinates attribute it would be unclear at first glance whether a variable resides on a cell-based grid. In this example, time is a normal record dimension and gds_crd is the cell-based dimension.

The cell-based grid file must contain two variables whose standard_name attributes are “latitude”, and “longitude”:

     % ncks -m -C -v lat_gds,lon_gds ~/nco/data/in.nc
     lat_gds: type NC_DOUBLE, 1 dimensions, 4 attributes, chunked? no, compressed? no, packed? no, ID = 37
     lat_gds RAM size is 8*sizeof(NC_DOUBLE) = 8*8 = 64 bytes
     lat_gds dimension 0: gds_crd, size = 8 NC_FLOAT, dim. ID = 17 (CRD)
     lat_gds attribute 0: long_name, size = 8 NC_CHAR, value = Latitude
     lat_gds attribute 1: standard_name, size = 8 NC_CHAR, value = latitude
     lat_gds attribute 2: units, size = 6 NC_CHAR, value = degree
     lat_gds attribute 3: purpose, size = 62 NC_CHAR, value = 1-D latitude coordinate referred to by geodesic grid variables
     
     lon_gds: type NC_DOUBLE, 1 dimensions, 4 attributes, chunked? no, compressed? no, packed? no, ID = 38
     lon_gds RAM size is 8*sizeof(NC_DOUBLE) = 8*8 = 64 bytes
     lon_gds dimension 0: gds_crd, size = 8 NC_FLOAT, dim. ID = 17 (CRD)
     lon_gds attribute 0: long_name, size = 9 NC_CHAR, value = Longitude
     lon_gds attribute 1: standard_name, size = 9 NC_CHAR, value = longitude
     lon_gds attribute 2: units, size = 6 NC_CHAR, value = degree
     lon_gds attribute 3: purpose, size = 63 NC_CHAR, value = 1-D longitude coordinate referred to by geodesic grid variables

In this example lat_gds and lon_gds represent the latitude or longitude, respectively, of cell-based variables. These coordinates (must) have the same single dimension (gds_crd, in this case) as the cell-based variables. And the coordinates must be one-dimensional—multidimensional coordinates will not work.

This infrastructure allows NCO to identify, interpret, and process (e.g., hyperslab) the variables on cell-based grids as easily as it works with regular grids. To time-average all the values between zero and 180 degrees longitude and between plus and minus 30 degress latitude, we use

     ncra -O -X 0.,180.,-30.,30. -v gds_3dvar in.nc out.nc

NCO accepts multiple ‘-X’ arguments for cell-based grid multi-slabs, just as it accepts multiple ‘-d’ arguments for multi-slabs of regular coordinates.

     ncra -O -X 0.,180.,-30.,30. -X 270.,315.,45.,90. in.nc out.nc

The arguments to ‘-X’ are always interpreted as floating point numbers, i.e., as coordinate values rather than dimension indices so that these two commands produce identical results

     ncra -X 0.,180.,-30.,30. in.nc out.nc
     ncra -X 0,180,-30,30 in.nc out.nc

In contrast, arguments to ‘-d’ require decimal places to be recognized as coordinates not indices (see Hyperslabs). We recommend always using decimal points with ‘-X’ arguments to avoid confusion.