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>