NAME
lats4d - LATS for Dummies (Version 1.7 of 10 May 2006)
SYNOPSIS
lats4d [-i fn] [-o fn] [-cal calendar] [-center ctr] [-de fn]
[-format fmt] [-ftype ctl|sdf|xdf] [-freq ...]
[-func expr] [-h] [-grid type]
[-lat y1 y2] [-levs ...] [-lon x1 x2]
[-model mod] [-mean] [-precision nbits] [-table tab]
[-time t1 t2 [tincr]] [-title ...]
[-v] [-vars ...] [-xvars] [-zrev] [-q]
DESCRIPTION
A minimum fuss gs script for writing NetCDF, HDF-SDS or
GRIB files from GrADS using the PCMDI LATS interface
(http://www-pcmdi.llnl.gov). This script can serve as a
general purpose file conversion and subsetting utility.
Any GrADS readable file (GrADS IEEE, GSFC Phoenix, GRIB,
NetCDF or HDF-SDS) can be subset and converted to GRIB,
NetCDF, HDF-SDS, flat binary (direct access) or sequential
(FORTRAN) binary using a single command line. When writing
binary files, the user can request the files to be little
or big endian, regardless of the endianess of the hardware.
When invoked without arguments this script will create a
COARDS compliant NetCDF or HDF-SDS file named
"grads.lats.nc", with all the contents of the default
file (all variables, levels, times). The file name and
several other attributes can be customized at the command
line, see OPTIONS below.
NetCDF files are obtained by running this script under the
executable "gradsnc". HDF-SDS files can be produced with
the "gradshdf" executable. Notice that the classic version
of grads, "gradsc", does not include support for LATS and
therefore cannot be used with lats4d. This script requires
GrADS Version 1.7.beta.9 or later.
OPTIONS
-i fn input file name; it can be any
of the following:
- an ASCII control (ctl) file
used for GRIB, IEEE files, and
as of GrADS v1.9, for NetCDF/HDF
files as well.
- a binary NetCDF file/template
- a binary HDF-SDS file/template
- an ASCII data descriptor file (ddf)
used for non-COARDS compliant
NetCDF/HDF-SDS files through
the "xdfopen" command
If the option "-ftype" is not
specified lats4d attempts to
determine the file type using
a heuristic algorithm.
NOTE: When the option "-i" is
specified a GrADS "reinit" is
issued before the file is opened.
For NetCDF/HDF-SDS templates in
GrADS consult the SDFopen home
page listed under SEE ALSO
-o fn output (base) file name; default:
"grads.lats"
-be when format is "stream" or "sequential"
this option forces the file to be
BIG ENDIAN, regardless of the native
endianess
-cal calendar calendar type: "standard", "noleap",
"clim", or "climleap"; default:
"standard"
-center ctr center, e.g., PCMDI, GSFC, NCEP, etc
-de fn Dimension environment file name;
defaut: same as "-i" argument.
This option is useful for using
lats4d with the user defined function
(udf) regrid2. See REGRIDDING below
for more information.
-format fmt LATS file format: coards, grib,
grads_grib, sequential or stream; specify
"grads_grib" instead of "grib" for
getting ctl and gribmap files as well.
NOTE: The option "stream" creates
a flat binary file using the GrADS
command "set gxout fwrite" which
is not part of LATS.
-ftype ctl|sdf|xdf Specifies the input file type:
ctl standard GrADS control (ctl)
file used for IEEE and GRIB
files
sdf COARDS compliant NetCDF/HDF-SDS
binary data file
xdf data descriptor file (ddf)
used for non-COARDS compliant
NetCDF/HDF-SDS files through
the "xdfopen" command
By default lats4d attempts to
determine the file type using a
heuristic algorithm; use this
option if lats4d fails to properly
detect the input file type
-freq [n] unit Time frequency of the input file.
LATS4D usually detects this from
the GrADS metadata, but sometimes
it fails with an error message.
In such cases use this option.
Example: -freq 6 hourly
NOTE: unlike GrADS, LATS does not
support time frequency in minutes
Default: n=1, e.g., -freq daily
-func expr Evaluates the expression "expr"
before writing to the output
file. The character "@" is used
to denote the variable name in
"expr". Example:
-func ave(@,t-1,t+1)
will replace "@" with each
variable name and produce a file
with running means. Default:
expr = @
-grid type Grid type: linear, gaussian or
generic; default: linear
-h displays this man page
-lat y1 y2 latitude range, e.g., "-30 30" for
30S thru 30N; default: latitude
dimension environment
-le when format is "stream" or "sequential"
this option forces the file to be
LITTLE ENDIAN, regardless of the
native endianess
-levs lev1 ... levN list of levels; default: all levels
-lon x1 x2 longitude range, e.g., "-50 20" for
50W thru 20E; default: longitude
dimension environment
-mean saves time mean to file; the actual
averaging period is specified with
the "-time" option; the "tincr"
parameter is the time increment
for the average (see GrADS ave()
function)
-model mod model name, e.g., GEOS/DAS
-precision nbits specify the number of bits of
precision when storing in GRIB.
This option is only used when
lats4d automatically generates
a parameter table file (see option
-table below), and the output
format is "grib" or "grads_grib".
Default: nbits = 16
-table tab LATS parameter table file, e.g.,
"dao.lats.table". If the table name
starts with "@" (e.g., @my.table)
then lats4d automatically generates
a LATS parameter table appropriate
for the current file and saves it
to a file; the file name in this
case is the same as "tab" with the
@ character removed (e.g., my.table).
Specify tab as "=" for using the
internal LATS parameter table.
See below for additional info on
parameter tables.
Default: @.grads.lats.table
-time t1 t2 [tincr] time range and time increment in
units of the "delta t" in the
input file; "tincr" is optional;
Example: "0z1dec91 18z31dec91 2"
to write every other
time step
Defaults: (t1,t2) is taken from
the time dimension environment,
and tincr=1. Note: enter "= ="
for keeping the default values
for (t1,t2) while specifying tincr
-title text output dataset TITLE for GRIB files,
COMMENTS for NetCDF/HDF files
-v verbose mode
-vars var1 ... varN list of variables; default: all
variables on the current file will
be written to the output file
-xsfc exclude all surface variables
-xvars var1 ... varN list of variables to exclude;
default: none
-xupper exclude all upper air variables
-zrev reverse order of vertical levels
-q quits GrADS upon return
LATS PARAMETER TABLES
LATS maintains an internal parameter table that prescribes
variable names, description, units, datatype, basic
structure (e.g., upper air or surface), and compression
(GRIB options). These descriptors are inferred from the
parameter name only, and thus most of the metadata needed
to write GRIB and/or netCDF data are located in the
parameter table and need not be specified at the command
line. The option "-table" is provided to override the
internal table with an external parameter file. For
additional information on LATS parameter tables
consult http://www-pcmdi.llnl.gov/software/lats/.
The only inconvenience of this approach is that variables
names being written to file must match those defined in
this internal parameter table (which is essentially the
same as the "AMIPS2" LATS table, see URL above).
To circumvent this problem lats4d can automatically
generate a parameter table based on the current file
metadata. Since GrADS keeps no units or GRIB packing
information, this parameter file sets the units entry
to blank and uses defaults for the GRIB packing parameters.
The default GRIB packing algorithm is "16-bit fixed width
compression" and produces GRIB files which are about half
the size of NetCDF/HDF-SDS files. The option "-precision"
allows the user to define the number of bits of precision
at the command line; see EXAMPLES ex2a,b,c below.
If you care about having proper metadata written to
your file or need more efficient GRIB packing then you can
either change your variable names to match those in the
internal LATS table, or customize an existing LATS parameter
table; see URL above for sample parameter tables.
LATS QUALITY CONTROL WARNINGS
Quality control (QC) information is included in some
LATS parameter tables to help the user ensure that their
data is being written properly. In such cases, if LATS
detects suspect data it writes a warning message to the
screen and saves additional information in a log file.
Consult the LATS home page for additional information.
REGRIDDING
This script can be used with Mike Fiorino s user
defined function (udf) regrid2(). This combination
allows you to convert any GrADS redable file to any
other horizontal resolution/domain of your choice.
Here is a quick roadmap:
1. Start by installing regrid2() available from
ftp://grads.iges.org/grads/sprite/udf/regrid2beta.tar
2. If you already have a sample file at the desired new
resolution, great! Otherwise you can get one by creating
a fake GrADS control file. There are a few samples
on the last4d home page: geos1x1.ctl, geos4x5.ctl and
geos2x25.ctl. This file is used to define the dimension
environment at the new desired resolution through the
"-de" option.
3. Here is an example which converts the sample model.???
data file from 4x5 (latxlon) resolution to 1x1:
lats4d -i model -de geos1x1 -func regrid2(@,1,1,bs_p1,-180,-90)
The resulting "grads.lats.nc" file is at 1x1 degree
resolution.
EXAMPLES
Download files "model.ctl", "model.gmp" and "model.grb"
from http://dao.gsfc.nasa.gov/software/grads/lats4d/.
Then start "gradsnc" or "gradshdf" and try these,
carefully examining the files produced:
lats4d -h
lats4d -v -q -i model -o ex1
lats4d -v -q -i model -o ex2a -format grads_grib
lats4d -v -q -i model -o ex2b -format grads_grib -precision 8
lats4d -v -q -i model -o ex3 -levs 700 500 -vars ua va
lats4d -v -q -i model -o ex4 -time 1jan1987 3jan1987
lats4d -v -q -i model -o ex5 -time = = 2
lats4d -v -q -i model -o ex6 -mean
lats4d -v -q -i model -o ex7 -mean -time = = 2
lats4d -v -q -i model -o ex8 -lat 20 70 -lon -140 -60
Note: the "-q" option above is to make sure you
restart GrADS; see BUGS below. You may want to
enter these from your OS shell, e.g.,
% gradsnc -blc "lats4d -v -q -i model -o ex1"
The sh(1) script "lats4d" allows you to enter lats4d
options directly from the Unix command line, e.g.,
% lats4d -v -i model -o ex1
BUGS
Sometimes lats4d will only work if you exit and
restart GrADS.
The option "-precision 32" does not quite work. This
appears to be a LATS bug.
Because of a limitation in the GRIB format, "grib" or
"grads_grib" output cannot have levels where p<1.
To circumvent this problem, a hybrid level number is
is used in such cases.
SEE ALSO
GrADS http://grads.iges.org/grads/
LATS http://www-pcmdi.llnl.gov/software/lats
LATS4D http://gmao.gsfc.nasa.gov/software/lats4d
SDFopen http://www.cdc.noaa.gov/~hoop/grads.html
XDFopen http://www.cdc.noaa.gov/~hoop/xdfopen.shtml
NetCDF http://www.unidata.ucar.edu/packages/netcdf/
HDF http://hdf.ncsa.uiuc.edu/
GRIB ftp://ncardata.ucar.edu/docs/grib/prev-vers/guide.txt
http://www.wmo.ch/web/www/reports/Guide-binary-2.html
LICENSING
Copyright (c) 1998-2006 A. da Silva
This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; using
version 2 of the License.
NO WARRANTY
Because lats4d is provided free of charge, it is provided
"as is" WITHOUT WARRANTY OF ANY KIND, either expressed or
implied, including, but not limited to, the implied
warranties of merchantability and fitness for a particular
purpose. USE AT YOUR OWN RISK.
CREDITS
Arlindo da Silva (NASA/GSFC) wrote the lats4d.gs script.
Mike Fiorino (PCMDI/LLNL) wrote the LATS interface to
GrADS. Robert Drach, Mike Fiorino and Peter Gleckler
(PCMDI/LLNL) wrote the LATS library.
© 1994 Man-cgi 1.15, Panagiotis Christias <christia@theseas.ntua.gr>