NAME
LATS - Library of AMIP II Transmission Standards -- I/O
functions for creating lon/lat gridded datasets in the GRIB
and/or the netCDF format.
VERSION
LATS 1.0 - First Official Release
SYNOPSIS (FORTRAN ROUTINES)
include "lats.inc"
integer function latsbasetime(integer fileid, integer year,
integer month, integer day, integer hour)
integer function latsclose(integer fileid)
integer function latscreate(character*(*) pathname,
integer convention, integer calendar,
integer frequency, integer delta,
character*(*) center, character*(*) model,
character*(*)comments)
subroutine latserropt(integer erropt)
integer function latsgrid(character*(*) gridname,
integer gridtype, integer nlon,
double precision lons(*), integer nlat,
double precision lats(*))
integer function latsmissreal(integer fileid, integer varid,
real missing, real delta)
integer function latsmissint(integer fileid, integer varid,
integer missing)
integer function latsparmtab(character*(*) parm_file_path)
integer function latsvar(integer fileid,
character*(*) varname, integer datatype,
integer timestat, integer gridid, integer levid,
character*(*) comments)
integer function latsvertdim(character*(*) name,
character*(*) type, integer nlev,
double precision levs(*))
integer function latswrite(integer fileid, integer varid,
double precision lev, integer year, integer month,
integer day, integer hour, datatype data)
SYNOPSIS (C ROUTINES)
#include "lats.h"
int lats_basetime(int fileid, int year, int month, int day,
int hour)
int lats_close(int fileid)
int lats_create(char* pathname, int convention,
int calendar, int frequency, int delta, char* center,
char* model, char* comments)
int lats_grid(char* gridname, int gridtype, int nlon,
double lons[], int nlat, double lats[])
int lats_miss_float(int fileid, int varid, float missing,
float delta)
int lats_miss_int(int fileid, int varid, int missing)
int lats_parmtab(char* parm_file_path)
int lats_var(int fileid, char* varname, int datatype,
int timestat, int gridid, int levid, char* comments)
int lats_vert_dim(char* name, char* type, int nlev,
double levs[])
int lats_write(int fileid, int varid, double lev, int year,
int month, int day, int hour, void* data)
DESCRIPTION
LATS is a subroutine library developed by the Program for
Climate Model Diagnosis and Intercomparison to output
lon/lat gridded data for the AMIP II (Atmospheric Model In-
tercomparison Project II) and other intercomparison pro-
jects. In addition to outputting data, LATS optionally per-
forms basic quality control on the data written. LATS out-
puts data in the GRIB and/or netCDF formats and provides an
interface to GrADS and VCS. FORTRAN and C interfaces are
provided. See the WEB RESOURCES section below for more in-
formation on these formats and systems.
The main features are:
o LATS is designed to output rectilinear, generally glo-
bal, gridded, spatio-temporal data. The amount of data
written with a single function call is a horizontal
longitude-latitude slice of a variable.
o Data may be output in the machine-independent formats
GRIB and/or netCDF and are directly readable by GrADS
and VCS.
o 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 file'. If no
parameter file is specified, a default list of AMIP II
parameters is used.
o More than one LATS file may be open simultaneously for
output.
o Data must be written in increasing time sequence. All
variables in a file share a common time frequency
(e.g., hourly, monthly, etc.).
o For a given timepoint, variables, and multiple levels
for a variable, may be written in any order.
o All data are floating-point or integer. Only FORTRAN
REAL*4 (Cray REAL*8), C float, FORTRAN INTEGER*4 (Cray
INTEGER*8), and C int data can be written.
o Data written to GRIB files are packed to a predefined
bit width or numerical precision depending on the vari-
able. The precision and bit width is specified in the
parameter 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 in-
tegers.
GUIDELINES
For any data associated with intervals of time, (e.g., accu-
mulations, 6-hour averages, etc.) it is strongly recommended
that the time value be specified as the start time of the
interval.
USAGE
The skeleton of a LATS program is as follows:
1. Optionally, specify an external parameter file, with
lats_parmtab.
2. Define all grid(s), with lats_grid. Define all verti-
cal dimensions (e.g., pressure level) with
lats_vert_dim. If a default surface dimension is de-
fined for a variable (see lats(5)), it does not have to
be redefined with lats_vert_dim. Grids and vertical
dimensions may be shared across variables and files.
NOTE: At present, only one grid may be defined for a
GrADS/GRIB file (the LATS_GRADS_GRIB convention).
3. Create a LATS file, with lats_create.
4. Optionally, set the basetime, with lats_basetime.
5. For EACH AND EVERY variable to be written in EACH AND
EVERY file:
Declare the variable with lats_var. (Note: this is re-
quired even if the variable has been declared for a
different file)
If there are "missing" or "undefined" data, flag the
missing value using lats_miss_float or lats_miss_int.
The LATS requirement that ALL variables be declared "up
front" (before writing) is necessitated by the netCDF
interface. When writing, a netCDF application is ex-
plicitly put in either a "define" mode (set dimension,
variables and attributes) or "data" a mode (output
data). Easing this restriction would require addition-
al routines (e.g., comparable to ncendef) and added
complexity.
6. 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
lats_write.
7. Close the file, with lats_close.
ERROR HANDLING
By default, all errors are reported, and the program exits
after a fatal error. From a C routine, setting the global
variable lats_fatal to 0 causes LATS routines to return from
fatal errors; the default value is 1 (exit on error). Simi-
larly, from a C routine, setting the global variable
lats_verbose to 0 suppresses error and warning messages from
LATS; the default value is 1 (report errors to the standard
error stream).
For FORTRAN, the subroutine latserropt is used to set the
error parameters.
QUALITY CONTROL
LATS performs some basic quality control on the data writ-
ten. The intention is to provide a quick check of data vali-
dity. 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 vari-
ables.
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
file. If no entry in this section is found for the given
(variable,level_type,level), then no quality control is per-
formed for that level.
Data are always written, regardless of whether a QC excep-
tion 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.
FUNCTION DESCRIPTIONS
(FORTRAN) integer latsbasetime(integer fileid, integer year,
integer month, integer day, integer hour))
(C) int lats_basetime(int fileid, int year, int month, int
day, int hour))
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.
(FORTRAN) integer function latsclose(integer fileid))
(C) int lats_close(int fileid))
Close the file with ID fileid. The function returns 1 if
successful, 0 if an error occurs.
NOTE: It is important to call lats_close, to ensure that
any buffered output is written to the file.
(FORTRAN) integer function latscreate(character*(*) path-
name, integer convention, integer calendar, integer fre-
quency, integer delta, character*(*) center, charac-
ter*(*) model, character*(*) comments))
(C) int lats_create(char* pathname, int convention, int
calendar, int frequency, int delta, char* center, char*
model, char* comments))
Create a LATS file with the given pathname, a string of
length <= 256. If pathname does not end in the proper
extension ('.nc' for netCDF, '.grb' for GRIB), the ex-
tension will be appended to the path.
convention defines the data format to be written, and
the metadata convention to be followed when writing the
format. The options are:
LATS_PCMDI netCDF format, observing the PCMDI
convention. This option permits
the use of calendars other than
the standard Gregorian calendar.
Other than the calendar options,
the PCMDI convention is consistent
with the COARDS convention. Files
with this convention may be used
with VCS, but may not be readable
with GrADS. NOTE: This convention
is NOT to be used in AMIP II; use
LATS_COARDS instead for netCDF
output.
LATS_GRADS_GRIB WMO GRIB format, plus a GrADS (see
WEB RESOURCES section) control
file and the ancillary GRIB map
file. If this convention is used
delta 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 VCS
and GrADS. The GRIB data may be
processed by the included utility
wgrib (see WEB RESOURCES section)
LATS_GRIB_ONLY WMO GRIB format only. The delta
may be zero. This convention is
the most general, but may not be
readily interfaced to VCS and
GrADS. Appropriate for straight
data transmission with no need for
direct interface.
LATS_COARDS netCDF format, observing the
COARDS metadata standard (see WEB
RESOURCES section). If this con-
vention is specified, calendar
must be LATS_STANDARD. Climatolo-
gies are indicated by specifying
year = 2 in lats_write. For the
LATS_CLIM, LATS_CLIM365,
LATS_CLIM360 calendars, the year
is automatically set to 2. This
convention is readable with VCS
and GrADS.
calendar is the calendar type, one of the following
values:
LATS_STANDARD Standard Gregorian calendar
LATS_JULIAN Julian calendar, years divisible
by four are leap years
LATS_NOLEAP 365 days/year, no leap years
LATS_360 Each year is 12 30-day months
LATS_CLIM Climatological time (no associated
year), 365 days
LATS_CLIMLEAP Climatological time, 366 days
LATS_CLIM360 Climatological time, 360 days
calendar is ignored if frequency is LATS_FIXED.
frequency is the time frequency of variables to be writ-
ten to the file, and has one of the values:
LATS_YEARLY Only the year component of time is
significant. delta is expressed in
years.
LATS_MONTHLY The year and month components of
time are significant. delta is ex-
pressed in months. Floating-point
data in the LATS_GRADS_GRIB con-
vention are compressed to 16-bits.
LATS_MONTHLY_TABLE_COMP
The year and month components of
time are significant. delta is ex-
pressed in months. Floating-point
data in the LATS_GRADS_GRIB con-
vention are compressed according
to the specification in the param-
eter table.
LATS_WEEKLY The year, month, and day component
of time are significant. delta is
expressed in weeks.
LATS_DAILY The year, month, and day component
of time are significant. delta is
expressed in days.
LATS_HOURLY The year, month, day, and hour
component of time are significant.
delta is expressed in hours.
LATS_FIXED Data are not time-dependent, e.g.,
for surface type, orography, etc.
delta is ignored and year is set
to 1 by convention.
delta is the number of time units in the time increment,
where the units are specified by frequency. For exam-
ple, data which are defined at multiples of 6 hours
would be specified with frequency = LATS_HOURLY and del-
ta = 6. Similarly, monthly average data would be indi-
cated by frequency = LATS_MONTHLY and delta = 1. Note
that times may be skipped for conventions other than
LATS_GRADS_GRIB; the only requirement imposed by the
LATS interface is that timepoints, as specified via
lats_write, be at a multiple of the time increment, re-
lative to the base time (the first time written).
Irregular time points may be written, by specifying del-
ta = 0, for conventions other than LATS_GRADS_GRIB.
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, see lats(5). 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 function returns an integer file ID, or
0 if the file cannot be created.
(FORTRAN) subroutine latserropt(integer erropt)
Set the LATS error control options. erropt is the logi-
cal combination of LATS_FATAL (exit when a fatal error
occurs, the default), and LATS_VERBOSE (report errors
and warnings). For example, setting erropt = LATS_FATAL
+ LATS_VERBOSE causes the default behavior, namely, that
the program exits immediately on a fatal error, and re-
ports all errors and warnings. To cause LATS routines to
return control to the calling routine after a fatal, and
report errors, set erropt = LATS_VERBOSE. To cause re-
turns after errors, and suppress error messages, set er-
ropt=0.
(FORTRAN) integer function latsgrid(character*(*) gridname,
integer gridtype, integer nlon, double precision
lons(*), integer nlat, double precision lats(*))
(C) int lats_grid(char* gridname, int gridtype, int nlon,
double lons[], int nlat, double lats[])
Define a horizontal, longitude-latitude grid. This grid
may be shared between variables. The gridname must be
unique relative to other grids, not contain whitespace
characters, and be of length <= 128 characters.
gridtype is LATS_GAUSSIAN for Gaussian grids,
LATS_LINEAR for evenly spaced grids, or LATS_GENERIC
otherwise.
lons is the vector of longitude zone (center of a grid
box) centers, of length nlon. lats is the vector of la-
titude zone centers, of length nlat. If there are data
associated with the north and/or south pole, the values
+90 and/or -90 should be included in lons (see
lats_write). Longitude values must not wrap around
(e.g., if the first longitude is 0 degrees, the last
longitude should not be 360 degrees). Longitude values
must be specified in degrees east, latitude values in
degrees north. lons and lats must be strictly monotonic,
either increasing or decreasing.
There is a maximum number of grids which can be defined,
specified by the parameter LATS_MAX_GRIDS (default value
is 256) in the LATS include file. The function returns
an integer grid ID on success, 0 on failure.
(FORTRAN) integer function latsmissreal(integer fileid, in-
teger varid, real missing, real delta))
(FORTRAN) integer function latsmissint(integer fileid, in-
teger varid, integer missing))
(C) int lats_miss_float(int fileid, int varid, float miss-
ing, float delta))
(C) int lats_miss_int(int fileid, int varid, int missing))
Define the missing data flag for variable varid, in file
fileid, to be the value missing. Any element of the
variable which is equal to the missing data value is
treated as missing data. For floating-point variables, a
value is equal to missing if abs(value -
missing) <= delta. If the variable is floating point,
use lats_miss_float (FORTRAN latsmissreal); if the vari-
able is integer, use lats_miss_int (FORTRAN latsmis-
sint). Note: if the GRIB output option is used, integer
data are converted to floating point. Also, LATS is
somewhat more efficient if the missing data flag is not
defined for that variable.
The function returns 1 on success, 0 on failure.
(FORTRAN) integer function latsparmtab(character*(*)
parm_file_path))
(C) int lats_parmtab(char* parm_file_path))
Specify an external parameter file. parm_file_path is
the pathname of a file containing a list of variable
descriptions, and is a string of length <= 256 charac-
ters.
Use of lats_parmtab is optional. The location of the
parameter table is determined as follows: (1) if
lats_parmtab is called, the value of parm_file_path 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 function returns 1 on success, 0 on failure.
(FORTRAN) integer function latsvar(integer fileid, charac-
ter*(*) varname, integer datatype, integer timestat, in-
teger gridid, integer levid, character*(*) comments))
(C) int lats_var(int fileid, char* varname, int datatype,
int timestat, int gridid, int levid, char* comments))
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 (see lats(5)) , and is a string of length <= 128
characters.
datatype is the data type of each element of the vari-
able, either LATS_INT for integer data, or LATS_FLOAT
for floating-point data. It is an error if the datatype
does not match the prescribed datatype for the variable,
as defined in the parameter table. Note: for GRIB out-
put, integer data are cast to floating-point values be-
fore being written.
timestat is a time statistic identifier, one of:
LATS_AVERAGE An average over the delta time in-
terval frequency defined by
lats_create.
LATS_INSTANT The field is valid at the instan-
taneous time set by the year,
month, day, hour.
LATS_ACCUM Accumulation during delta time in-
terval frequencyfR defined by
lats_create.
LATS_OTHER_TIME_STAT
A different time statistic. Can-
not be used with the
LATS_GRADS_GRIB or LATS_GRIB_ONLY
convention.
gridid is a grid ID, returned from lats_grid.
levid is the ID of the vertical dimension of the vari-
able, as returned from lats_vert_dim. If the variable
has a default surface defined in the parameter table
(see lats(5)) , or has no associated vertical dimension,
levid should be 0. (Note: if levid is 0 and the vari-
able has a default surface defined, the netCDF represen-
tation of the variable will not have an explicit verti-
cal dimension, but will have a 'level_description' at-
tribute).
lats_var should be called exactly once for each variable
to be written to a LATS file and must be called BEFORE
lats_write. The function returns the integer variable
ID on success, or 0 on failure.
(FORTRAN) integer function latsvertdim(character*(*)
name, character*(*) type, integer nlev,
double precision levs(*))
(C) int lats_vert_dim(char* name, char* type, int nlev,
double levs[])
Define a vertical dimension. Vertical dimensions
may be shared across variables and files. name is
the name of the vertical dimension (e.g., "height",
"depth", "level"), and must be unique with respect
to other vertical dimension names. name should not
contain any whitespace characters.
type is the vertical dimension type. It must match
one of the level types defined in the vertical di-
mension types section of the parameter file (see
lats(5)) , e.g., "plev". This argument is case-
insensitive.
nlev is the number of levels in the dimension, and
levs is the strictly monotonic vector of level
values. Vertical dimensions may be shared by vari-
ables. There is a maximum number of vertical dimen-
sions which may be defined for a single file,
specified by the parameter LATS_MAX_VERT_DIMS in
the LATS include file.
Multi-level variables must have a vertical dimen-
sion defined. If a single-level (e.g., surface)
variable has a default level type specified in the
parameter table (see lats(5)), it is not necessary
to call lats_vert_dim, 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.
The function returns an integer level ID on suc-
cess, or 0 on failure.
(FORTRAN) integer function latswrite(integer fileid, in-
teger varid, double precision lev, integer year,
integer month, integer day, integer hour, datatype
data))
(C) int lats_write(int fileid, int varid, double lev,
int year, int month, int day, int hour, void* data))
Write a horizontal longitude-latitude cross-section
of a variable. fileid is the integer file ID re-
turned from lats_create. varid is the integer vari-
able ID returned from lats_var. lev 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 lev is ig-
nored.) 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). FOR-
TRAN Note: if the value of lev is a literal, be
sure to use a 'D' exponent, e.g.,
The ordering of data should match the ordering of
the grid defined by lats_grid, with the longitude
dimension varying most rapidly. In other words,
FORTRAN data arrays should be dimensioned
data(longitude,latitude), while C data arrays
should be dimensioned data[latitude][longitude].
The number of longitudes and latitudes is defined
by the arguments nlon and nlat, respectively, to
function lats_grid. For example, if in lats_grid,
lons= (0.0, 5.0, 10.0, ... , 355.0), lats = (-86.0,
-82.0,... , 86.0) , then the first data value
corresponds to (0.0,-86.0), the second value to
(5.0,-86.0), and so on. If the latitude array in-
cludes the poles, then the data values should be
duplicated at the appropriate positions.
The datatype of data should be as follows: if the
variable is defined to be floating-point, then (in
C) data must be an array of floats (NOT doubles),
in FORTRAN an array of reals (NOT double preci-
sion). For integers (in C) data must be an array of
ints (NOT longs), in FORTRAN an array of integers.
DEC Alpha/OSF Note: if using netCDF, it is impor-
tant to link with netCDF library included in the
distribution (version 2.4.3 or greater if writing
integer data.
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 vari-
ables, lev is ignored.
The function returns 1 if successful, 0 on failure.
ENVIRONMENT VARIABLES
LATS_PARMS Parameter table file (supersedes inter-
nal table if defined)
LATS_LOG Log file (default: lats.log)
FILES
liblats.a LATS library
libnetcdf.a netCDF library (V 2.4.3); required for
linking
lats.h LATS include file for C applications
lats.inc LATS include file for FORTRAN applica-
tions
WEB RESOURCES
PCMDI http://www-pcmdi.llnl.gov
LATS http://www-pcmdi.llnl.gov/software/lats
VCS http://www-
pcmdi.llnl.gov/williams/vcs/vcshome.html
GrADS http://grads.iges.org/grads
netCDF http://www.unidata.ucar.edu/packages/netcdf
GRIB ftp://ncardata.ucar.edu/docs/grib/guide.txt
COARDS http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html
wgrib http://wesley.wwb.noaa.gov/wgrib.html
SEE ALSO
lats(5), netcdf(3)
DEVELOPMENT PLANS
Version 1.1 of LATS will feature:
o LATS_GRADS_IEEE convention to output 32-bit IEEE floats
vice GRIB. Otherwise, this convention will be identi-
cal to LATS_GRADS_GRIB. Data will be accessible by
GrADS and VCS. This physical format is universally
readable by all versions of GrADS and is more appropri-
ate for formatting small grid such as zonal averages.
o LATS_FORECAST_HOURLY for writing numerical weather
prediction forecast data.
o Set the GRIB parameter table number in the LATS table
and add QC marks to the standard AMIP II LATS table.
MINOR BUGS
The return code from a successful lats_close for the
LATS_GRIB_ONLY convention is 0 vice 1. A 0 return code nor-
mally indicates a failure, however, the data for this case
are correct.
BUGS
There is limited checking of parameters passed to subrou-
tines in the fortran interface. Passing improper (e.g., an
integer argument when a float array is required), or unde-
fined arguments (e.g., an undefined character string) may
cause core dumps and segmentation faults (memory errors).
Send bug reports to lats@pcmdi.llnl.gov.