| liblats.gex - GrADS Extension Library for File Subsetting and Reformatting |
liblats.gex - GrADS Extension Library for File Subsetting and Reformatting
run set_lats PARAMETER VALUE - Set internal parameters
run query_lats - Print internal paramaters
run lats_grid EXPR - Set horizontal grid
run lats_data EXPR - Write data to file
This library provides GrADS extensions (gex) for interfacing to LATS (Library of AMIP II Transmission Standards), a collection of I/O functions for creating lon/lat gridded datasets in the GRIB, NetCDF-3, NetCDF-4/HDF-5 and HDF-4 formats. This is the low level LATS interface in GrADS. Usually, one uses the wrapper lats4d.gs script (http://opengrads.org/doc/scripts/lats4d/) for a more user friendly interface which has reasonable defaults for most internal parameters.
The GrADS interface to LATS is implemented by means of 4 User Defined Commands (UDCs). Most parameters defining the output file are set by means of the set_lats command; the current LATS state can queried with command query_lats. Command lats_grid is used to define the horizontal longitude/lattude grid (vertical levels are set with the set_lats command.) Command lats_data is used to write a 2-dimensional (longitude x latitude) slice of a variable, for a given time and level.
The following sub-section describes the main attributes of the LATS library which this extension interfaces to. It has been adapted from the original LATS manual page.
LATS is a subroutine library developed by the Program for Climate Model Diagnosis and Intercomparison (PCMDI) to output lon/lat gridded data for the AMIP II (Atmospheric Model Intercomparison Project II) and other intercomparison projects. In addition to outputting data, LATS optionally performs basic quality control on the data written. LATS outputs data in the GRIB and/or netCDF formats and provides an interface to GrADS and VCS. The LATS library is no longer supported by the original developers at PCMDI but remains as a viable mechanism for producing GRID-1, NetCDF and HDF output from GrADS.
The main features of LATS are:
LATS is designed to output rectilinear, generally global, gridded, spatio-temporal data. The amount of data written with a single function call is a horizontal longitude-latitude slice of a variable.
Data may be output in the machine-independent formats GRIB and/or netCDF and are directly readable by GrADS.
Acceptable variable names are prescribed. The units, datatype, and basic structure (e.g., single-level or multi-level) are inferred from the variable name. This information is tabled in an external, ASCII parameter table. If no parameter table is specified, a default list of AMIP II parameters is used.
More than one LATS file may be open simultaneously for output. In GrADS, one usually write one file at a time.
Data must be written in increasing time sequence. All variables in a file share a common time frequency (e.g., hourly, monthly, etc.). Originally LATS did not support minutes, but a patch has ben developed in version used by GrADS to allow minutes are a valid time sequence.
For a given timepoint, variables, and multiple levels for a variable, may be written in any order.
Although GrADS Version 2 uses doubles (64 bits) to store variable data, all data written to file by this interface are floating-point or integer. INTEGER*8), and C int data can be written.
Data written to GRIB files are packed to a predefined bit width or numerical precision depending on the variable. The precision and bit width is specified in the parameter table file. Floating-point data written to netCDF files are saved as 32-bit IEEE floating-point values; integer data are written as 32-bit 2's complement integers.
The skeleton of a GrADS script using the LATS interface is as follows:
Optionally, specify an external parameter file, with set_lats parmtab.
Define the horizontal grid with lats_grid. Define all vertical dimensions (e.g., pressure level) with set_lats vertdim. If a default surface dimension is defined for a variable, it does not have to be redefined with set_lats vertdim. Grids and vertical dimensions are shared across variables. NOTE: At present, only one grid may be defined for a GrADS/GRIB file.
Create a LATS file, with set_lats create.
Optionally, set the basetime, with set_lats basetime.
For EACH AND EVERY variable to be written, declare the variable with set_lats var. The LATS requirement that ALL variables be declared up front (before writing) is necessitated by the netCDF interface.
For each time-point, in increasing time order and, for each horizontal level of each variable, write the data for this level, time-point, with set_lats write and lats_data.
Close the file, with set_lats close.
By default, all errors are reported.
LATS performs some basic quality control on the data written. The intention is to provide a quick check of data validity. For each level written the following statistics are calculated: range (maximum-minimum) and area-weighted average. If a missing data flag is defined for the variable, any missing data are ignored in calculating the statistics. Quality control is not performed on integer-valued variables.
A QC exception is generated if abs(average - observed_average) > (tolerance * observed_standard_deviation). Similarly, an exception is generated if range > (range_tolerance * observed_range). In either case, a warning is issued, and an entry is written to the QC log file. The values of observed_average, tolerance, observed_standard_deviation, range_tolerance, and observed_range are tabled in the QC section of the Parameter Table file. If no entry in this section is found for the given (variable,level_type,level), then no quality control is performed for that level.
Data are always written, regardless of whether a QC exception is generated.
The default name of the log file is lats.log. This name is superseded by the value of the environment variable LATS_LOG, if defined.
Set the basetime for file with ID fileid. The basetime is the initial time in which the file can be referenced. The function returns 1 if successful, 0 if an error oc- curs.
Close the file. The function returns 1 if successful, 0 if an error occurs.
Create a LATS file with the given FILENAME, a string of length <= 256. If FILENME does not end in the proper extension ('.nc' for netCDF, '.grb' for GRIB), the extension will be appended to the path.
Deprecated. Same as set_lats format.
The parameter FORMAT defines the data format to be written, and the metadata convention to be followed when writing the format. The options are:
WMO GRIB format, plus a GrADS control file and the ancillary GRIB map file. If this format is used the time step (see set_lats deltat) must be non-zero, implying that timepoints are evenly-spaced. All variables in a file must share the same horizontal grid. This convention is readable with GrADS. The GRIB data may be processed by the utility wgrib shipped with most GrADS distributions.
Similar to grads_grib but without a GrADS control file and the ancillary GRIB map file.
NetCDF-3 format, observing the COARDS metadata standard. When this format is specified, the calendar must be STANDARD. Climatologies are indicated by specifying year = 2 in set_lats write. For the clim and climleap calendars, the year is automatically set to 2. Files wiritten with this format are readable with GrADS.
Like the netcdf format, except that the files are in the new NetCDF-4 (actually HDF-5) format.
Like the netcdf format, except that the files are in the new HDF-4 format. Notice that in GrADS v2, NetCDF and HDF-4 files are produced with the same GrADS executables.
CALENDAR is the calendar type, one of the following values:
Standard Gregorian calendar. This is the default.
365days/year, no leap years
Climatological time (no associated year), 365 days
Climatological time, 366 days
CENTER is the name of the modeling center or group creating the file, a string of <= 128 characters. For GRIB output, center must match one of the centers listed in the parameter file.
DeltaT is the number of time units in the time increment, where the units are specified by frequency. For example, data which are defined at multiples of 6 hours would be specified with
ga-> set_lats frequency hourly ga-> set_lats deltat 6
Similarly, monthly average data would be indicated by
ga-> set_lats frequency monthly ga-> set_lats deltat 1
Note that times may be skipped for formats other than GRADS_GRIB; the only requirement imposed by the LATS interface is that timepoints, as specified via set_lats write, be at a multiple of the time increment, relative to the base time (the first time written).
FREQUENCY is the time frequency of variables to be written to the file, and has one of the values:
Only the year component of time is significant. DeltaT (see set_lats) is expressed in years.
The year and month components of time are significant. DeltaT (see set_lats) is expressed in months. Floating-point data in the GRADS_GRIB format are compressed to 16-bits.
The year and month components of time are significant. DeltaT (see set_lats) is expressed in months. Floating-point data in the GRADS_GRIB format are compressed according to the specification in the parameter table.
The year, month, and day component of time are significant. DeltaT is expressed in weeks.
The year, month, and day component of time are significant. delta is expressed in days.
The year, month, day, and hour component of time are significant. DeltaT is expressed in hours.
The year, month, day, hour, and minute component of time are significant. DeltaT is expressed in minutes.
The year, month, day, and hour component of time are significant. DeltaT is expressed in hours.
The year, month, day, hour, and minute component of time are significant. DeltaT is expressed in minutes.
Data are not time-dependent, e.g., for surface type, orography, etc. DeltaT is ignored and year is set to 1 by convention.
Define the type of horizontal grid. GRIDTYPE is GAUSSIAN for Gaussian grids, LINEAR for evenly spaced grids, or GENERIC otherwise. The actual horizontal grid definition is performed with command lats_grid.
When writing NetCDF-4 files, specifes the level of GZIP compression to be employed. The higher the level, the harder the library works doing compression, usually (but not always) producing smaller files. The default is -1, meaning no compression. Notice that only NetCDF-4 files can be compressed. When COMPRESION_LEVEL > 0 is specified with NetCDF-3 files, the format is automatically changed to NetCDF-4. For improving the compression effectiveness see set_lats shave.
MODEL is the name of the model version which created this data. comments is a string of length 256 or less , including any null- terminator. The command returns an integer file ID, or 0 if the file cannot be created.
Specify an external parameter table file. TABLE_FILENAME is the pathname of a file containing a list of variable descriptions, and is a string of length <= 256 characters. Use of an external parameter table is optional. The location of the parameter table is determined as follows: (1) if the command set_lats parmtab is issued, the value of TABLE_FILENAME is used, otherwise (2) if the environment variable LATS_PARMS is defined, its value is used, else (3) an internally-defined table of AMIP parameters is used. The command returns 1 on success, 0 on failure.
Shave NBITS off the mantissa of float-point numbers. By definition, IEEE float numbers have 24 bits dedicated for the mantissa. This command set to zero the last NBITS of the mantissa, this way reducing entropy and improving the effectiveness of GZIP compression (see set_lats gzip). NBITS must be in the range [1,23]. When NBITS > 0 is specified, it automatically sets GZIP compression on at level 2, unless the compression level has already been set. (Currently compression is implemented only for NetCDF04 output.)
NOTE: The actual shaving algorithm, first scales the variable being written for each horizontal layer, and then shaves bits off the mantissa. See http://en.wikipedia.org/wiki/Ieee_float for additional information on IEEE float-point numbers.
Declare a variable to be written to a LATS file. fileid is the integer file ID returned from lats_create. The variable name VARNAME must match a name in the parameter table, and is a string of length <= 128 characters.
TIMESTAT is a time statistic identifier, one of:
An average over the delta time interval frequency defined by lats_create.
The field is valid at the instan- taneous time set by the year, month, day, hour.
Accumulation during delta time interval DeltatT (see set_lats deltat).
LEVID is the ID of the vertical dimension of the variable, as returned from set_lats vertdim. If the variable has a default surface defined in the parameter table, or has no associated vertical dimension, LEVID should be 0. (Note: if levid is 0 and the variable has a default surface defined, the netCDF representation of the variable will not have an explicit vertical dimension, but will have a level_description attribute).
set_lats var should be called exactly once for each variable to be written to a LATS file and must be called BEFORE set_lats write. The function returns the integer variable ID on success, or 0 on failure.
DIM_NAME is the name of the vertical dimension (e.g., ``height'', ``depth'', ``level''), and it should not contain any whitespace characters.
LEV_TYPE is the vertical dimension type. It must match one of the level types defined in the vertical dimension types section of the parameterfile, e.g., plev, hybrid, etc.
LEV_1, ..., LEV_N is a strictly monotonic list of level values.
Multi-level variables must have a vertical dimension defined. If a single-level (e.g., surface) variable has a default level type specified in the parameter table, it is not necessary to call set_lats vertdim, since the level type will be associated with the variable by default. Note that the level units are determined from the vertical dimension type table entry for name.
This command returns an integer level ID on success, or 0 on failure.
Specifies which variable in the file will be written next.
VAR_ID is the integer variable ID returned from set_lats var.
LEVEL is the level value, and must match one of the levels declared via lats_vert_dim. (Exception: if the variable was declared with levid=0, the value of LEVEL is ignored.) year is the four-digit integer year, month is the month number (1-12), day is the day in month (1-31), and hour is the integer hour (0-23).
Define a horizontal, longitude-latitude grid, based on the dimension environment associated with the GrADS expression EXPR. The grid type is specified with command set_lats gridtype.
Write a horizontal longitude-latitude cross-section of a variable contained in the GrADS expression EXPR. The actual variable on file being written to is specified with he set_lats write command.
For monthly data, as specified by lats_create, day and hour are ignored. For daily and weekly data, the hour is ignored. For fixed data, the year, month, day, and hour are ignored. For surface variables, lev is ignored.
This command returns 1 if successful, 0 on failure.
Prints out the value of all internal parameters.
Parameter table file (supersedes internal table if defined)
Log file (default: lats.log)
LATS was first introduced in GrADS v1.7 in the late 1990's by Mike Fiorino as means of producing GRIB-1/NetCDF output from GrADS. With the introduction of GrADS v2.0 in 2008, COLA removed LATS from the GrADS code base. In 2009, the OpenGrADS Project reintroduced LATS in GrADS v2.0 as a User Defiend Extension, adding support for NetCDF-3, NetCDF-4/HDF-5 and HDF-4 all from the same executable.
http://opengrads.org/ - OpenGrADS Home Page
http://cookbooks.opengrads.org/index.php - OpenGrADS Cookbooks
http://opengrads.org/wiki/index.php - OpenGrADS User Defined Extensions
http://www.iges.org/grads/ - Official GrADS Home Page
http://www-pcmdi.llnl.gov - PCMDI
http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html - COARDS
http://en.wikipedia.org/wiki/Ieee_float - IEEE Float numbers
Arlindo da Silva (dasilva@opengrads.org) wrote the GrADS UDXT interface and created this dcumentation from the LATS manual page. Mike Fiorino (mfiorino@gmail) wrote the actual LATS interface to GrADS. Robert Drach, Mike Fiorino and Peter Gleckler (PCMDI/LLNL) wrote the original LATS library.
The code implementing the GrADS extension has been placed in the public domain. Portions (C) 1996, Regents of the University of California.
See the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
| liblats.gex - GrADS Extension Library for File Subsetting and Reformatting |