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’ |
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.