List routines by category:
Atmospheric Sciences |
Benchmarking |
Color |
Date/Time |
Doc |
File & I/O |
BPCH Format |
Scientific Data Formats |
GAMAP Examples |
GAMAP Internals |
GAMAP Utilities |
GAMAP Data Manipulation |
GAMAP Models &
Grids |
GAMAP Plotting |
General |
Graphics |
Math & Units |
Plotting |
Regridding |
Strings |
Structures |
Time Series
List routines by alphabetical order:
A |
B |
C |
D |
E |
F |
G |
H |
I |
J |
K |
L |
M |
N |
O |
P |
Q |
R |
S |
T |
U |
V |
W |
X |
Y |
Z
NAME:
CAT_STRUCT
PURPOSE:
Concatenate all tags within 2 or more structures.
Return one structure with the same tags as each individual
structure.
CATEGORY:
Structures
CALLING SEQUENCE:
RESULT = CAT_STRUCT( STR1, STR2, STR3, STR4, STR5 )
INPUTS:
STR1, STR2, STR3, STR4, STR5 -> Structures to concatenate
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The concatenated structure
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The user can concatenate as many structures as desired by
adding extra input arguments: st6, st7, st8, etc.
EXAMPLE:
a = {Name: 'Larry', Age: 46}
b = {Name: 'Chuck', Age: 10}
c = {Name: 'Alice', Age: 35}
d = cat_struct( a, b, c )
print, d.Name
MODIFICATION HISTORY:
cdh, 08 Jul 2010: GAMAP VERSION 2.15
- Initial version
(See /n/home09/ryantosca/IDL/gamap2/structures/cat_struct.pro)
NAME:
CHKSTRU (function)
PURPOSE:
Check validity of a structure and test if necessary
fields are contained
CATEGORY:
Structures
CALLING SEQUENCE:
RESULT = CHKSTRU( STRUCTURE, [ FIELDS, Keywords ] )
INPUTS:
STRUCTURE -> the structure to be tested. If STRUCTURE is
not of type structure, the function will return 0
FIELDS (optional) -> a string or string array with field
names to be contained in STRUCTURE. CHKSTRU returns
1 (true) only if all field names are contained in
STRUCTURE. The entries of FIELDS may be upper or
lowercase.
KEYWORD PARAMETERS:
INDEX -> a named variable that will contain the indices of
the required field names in the structure. They can then
be assessed through structure.(index(i)) . Index will
contain -1 for all fields entries that are not in the
structure.
/VERBOSE -> set this keyword to return an error message
in case of an error.
OUTPUTS:
RESULT -> Returns 1 if successful, otherwise 0.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
TEST = { a:1, b:2, c:3 }
IF CHKSTRU( TEST ) THEN PRINT, 'TEST is a structure!'
TEST is a structure!
; Verify that TEST is a structure rather than
; a scalar or an array variable.
(2)
TEST = { a:1, b:2, c:3 }
REQUIRED = [ 'a', 'c' ]
IF CHKSTRU( TEST, REQUIRED ) THEN PRINT, 'Found a and c.'
Found a and c.
; MAKES sure that structure TEST contains
; the tag names A and C.
MODIFICATION HISTORY:
mgs, 02 Mar 1998: VERSION 1.00
mgs, 07 Apr 1998: - second parameter (FIELDS) now optional
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated documentation
(See /n/home09/ryantosca/IDL/gamap2/structures/chkstru.pro)
NAME:
CREATE3DFSTRU
PURPOSE:
Creates an empty GAMAP fileinfo structure or an array
of such structures. These are used to hold information
about CTM data files.
CATEGORY:
GAMAP Internals, Structures
CALLING SEQUENCE:
FILEINFO = CREATE3DHSTRU( [Elements] )
INPUTS:
ELEMENTS -> Number of individual structures to
be contained in the array of structures. Default
is 1, i.e. return a single structure.
KEYWORD PARAMETERS:
None
OUTPUTS:
A fileinfo structure or an array of fileinfo structures.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
See comments in code below for structure field descriptions.
EXAMPLES:
FILEINFO = CREATE3DFSTRU()
; returns a single structure which will hold
; info about CTM punch file data.
FILEINFO = CREATE3DFSTRU( 20 )
; returns an 20 element array of structures
; which will hold info about 20 records from a
; CTM data file
MODIFICATION HISTORY:
mgs, 14 Aug 1998: VERSION 1.00
bmy, 18 May 2007: GAMAP VERSION 2.06
- added standard doc header
- updated comments, cosmetic changes
MODIFICATION HISTORY:
bmy, 19 Feb 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/create3dfstru.pro)
NAME:
CREATE3DHSTRU
PURPOSE:
Creates an empty GAMAP datainfo structure or an array
of such structures. These are used to hold information
about individual data blocks from CTM data files.
CATEGORY:
GAMAP Internals, Structures
CALLING SEQUENCE:
DATAINFO = CREATE3DHSTRU( [Elements] )
INPUTS:
ELEMENTS -> Number of individual structures to be contained
in the array of structures. Default is 1, (i.e. return
a single structure).
KEYWORD PARAMETERS:
None
OUTPUTS:
A datainfo structure or an array of datainfo structures.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
See comments in code below for structure field descriptions.
EXAMPLES:
DATAINFO = CREATE3DHSTRU()
; returns a single structure which will hold
; info about CTM punch file data.
DATAINFO = CREATE3DHSTRU( 20 )
; returns an 20 element array of structures
; which will hold info about 20 records from a
; CTM data file
MODIFICATION HISTORY:
mgs, 14 Aug 1998: VERSION 1.00
mgs, 10 Nov 1998: - changed default filepos to -1L and scale to 1
bmy, 08 Feb 1999: VERSION 1.10
- changed TAU0, TAU1 from longword to double
- added OFFSET field for I0, J0, L0
bmy, 17 Feb 1999: VERSION 1.20
- changed OFFSET field to FIRST since we
are storing the I, J, L indices of the
first
mgs, 16 Mar 1999: - cosmetic changes
bmy, 03 Jan 2000: VERSION 1.44
- updated comments
bmy, 26 Apr 2000: VERSION 1.45
- TRACER now carries a longword variable
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 02 Dec 2008: GAMAP VERSION 2.13
- DIM tag is 32-bit integer (LONG) now
bmy, 23 Feb 2012: GAMAP VERSION 2.16
- Now make FILEPOS a LONG64 variable, in
order to read files larger than 2.4 GB
- Now make FIRST an array of LONG variables
(See /n/home09/ryantosca/IDL/gamap2/internals/create3dhstru.pro)
NAME:
CTM_DATAINFO (function)
PURPOSE:
Return information about available categories, tracers or
time steps in either a given or the global datainfo structure
array.
CATEGORY:
GAMAP Utilities, Structures
CALLING SEQUENCE:
RESULT = CTM_DATAINFO( [DIAGN] [,DATAINFO] [,keywords] )
INPUTS:
DIAGN -> A diagnostic number or category name for which
information shall be returned on available tracers
or time steps. If not given, CTM_DATAINFO returns
information about all available diagnostics instead.
DATAINFO -> An optional subset of the global DataInfo
structure array. If given, the search will be
restricted to the data records contained in DATAINFO.
KEYWORD PARAMETERS:
/TRACER -> If set, CTM_DATAINFO returns all tracer numbers
that are available with the given diagnostics. This
keyword has no effect if no DIAGN is given.
/TAU0 -> Returns information about all available time steps
for a given diagnostics. This keyword has no effect if
either DIAGN is not given or /TRACER is set.
/TAU1 -> Same as TAU0, but for the end of the time step.
If none of these keywords is set, CTM_DATAINFO returns the
index values for the DATAINFO structure array that match
the requested diagnostics.
STATUS -> restrict search to: 0=unread data, 1=read data.
Default is 2=no restriction
/EXPAND -> For multilevel diagnostics, CTM_DATAINFO normally
returns only the template (with the '$' character). Use
this keyword to get all individual levels as well.
OUTPUTS:
Depending on the keywords and the DIAGN parameter, an array
with diagmostics numbers, index values, tracer numbers, or
time steps is returned.
SUBROUTINES:
External Subroutines Required:
====================================
CTM_SELECT_DATA, CTM_DIAGINFO
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; Must read in some data first
CTM_GET_DATA, 'IJ-AVG-$', TRACER=1, FILE=''
; print all tracers that are available for diag IJ-AVG-$
PRINT, CTM_DATAINFO( 'IJ-AVG-$', /TRACER )
; print all time step endings for diagnostics IJ-AVG-$
PRINT, CTM_DATAINFO( 'IJ-AVG-$', /TAU0 )
; print all diagnostics that are available in the file
; (or in all files previously read)
PRINT, CTM_DATAINFO()
; print all record indices for diagnostics IJ-AVG_$
PRINT, CTM_DATAINFO( 'IJ-AVG-$' )
MODIFICATION HISTORY:
mgs, 07 Oct 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_datainfo.pro)
NAME:
CTM_DIAGINFO
PURPOSE:
Return information about one or all of the diagnostic
used by GEOS-CHEM, GISS, or other CTM's.
CATEGORY:
GAMAP Utilities, Structures
CALLING SEQUENCE:
CTM_DIAGINFO, DIAGN, DIAGSTRU [ , Keywords ]
INPUTS:
DIAGN -> Diagnostic category name for which to extract the
information. To retrieve information about all CTM
diagnostic categories use the /ALL_DIAGS keyword.
KEYWORD PARAMETERS:
/ALL_DIAGS -> Retrieves information about all diagnostics.
CATEGORY -> Returns to the calling program the punch
file category name of the requested diagnostic(s)
FILENAME -> Name of the diaginfo file (default diaginfo.dat)
The file will be searched in the current directory first,
then in the directory where CTM_DIAGINFO.PRO is located.
If not found in either location, a standard data block is
retrieved from this file.
/FORCE_READING -> Read from the diaginfo file (specified in
FILENAME) and overwrite the contents of the common block.
MAXTRACER -> Returns to the calling program the maximum
number of tracers stored in the requested diagnostic(s).
NOTE: This is now only necessary for backwards
compatibility with the GISS-II ASCII punch files.
OFFSET -> Returns to the calling program the offset constant
that is used to locate tracers in the "tracerinfo.dat"
file. OFFSET is needed to locate the proper index from
the "tracerinfo.dat" file.
SPACING -> Returns to the calling program the interval
between diagnostic offsets.
OUTPUTS:
DIAGSTRU -> returns a structure or structure array with the
following tags:
Category : Category name for this diagnostic
Offset : Offset factor used in "tracerinfo.dat" file
Spacing : Spacing between diagnostic offsets
MaxTracer : Max # of tracers stored in this diagnostic
SUBROUTINES:
Internal Subroutines:
=============================================
CD_Is_MaxTracer (function)
External Subroutines Required:
=============================================
FILE_EXIST (function) OPEN_FILE
ROUTINE_NAME (funciton) STRBREAK (function)
REQUIREMENTS:
Requires routines from the TOOLS package.
NOTES:
(1) At first call, the tracer information structure array is
read from a file. Thereafter, the information is stored in a
common block where it is accessible in subsequent calls.
EXAMPLES:
(1)
CTM_DIAGINFO, 'BIOGSRCE', R
PRINT, R.CATEGORY, ':', R.MAXTRACER, ':',R.OFFSET
IDL prints "BIOGSRCE: 0: 4700"
; Returns a structure containing tags CATEGORY,
; MAXTRACER, OFFSET for the "BIOGSRCE" diagnostic.
; as listed in the file "diaginfo.dat".
(2)
CTM_DIAGINFO, /ALL, CATEGORY=CATEGORY
PRINT, CATEGORY
IDL prints "IJ-AVG-$ IJ-24H-$ IJ-INS-$ INST-MAP ..."
; Return information about all category names
; listed in the file "diaginfo.dat".
MODIFICATION HISTORY:
bmy, 19 May 1998: VERSION 1.00
- developed from CTM_TRACERINFO.PRO v. 2.0 by
Martin Schultz (08 May 1998)
see comments to CTM_TRACERINFO.PRO for
modification history of that subroutine
bmy, 20 May 1998: - removed SCALE and UNIT structure tags & keywords
- added OFFSET structure tag & keyword
bmy, 27 May 1998: - changed "tracers" to "diagnostics" in
print statement.
mgs, 13 Aug 1998: - now returns only first diagnostics for a
given number. This permits to keep old
and new diagnostics in one file and use
the old diagnostics by name.
- introduced extra search one level above
current dir.
mgs, 17 Aug 1998: - changed defaults vor void return
- diaginfo.dat: MAXTRACER meaning changed!
bmy, 17 Nov 2003: GAMAP VERSION 2.01
- Removed INDEX and TYPE, they're obsolete
- Now use new file format for "diaginfo.dat"
which allows for 8-digit offset numbers
- Added internal function CD_IS_MAXTRACER
- No longer read defaults from internal datablock
- Added SPACING keyword
- Updated comments
bmy, 09 Mar 2006: GAMAP VERSION 2.05
- Use "./diaginfo.dat" as default in
order to facilitate reading in IDL 5.5-
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now use the FILE_WHICH routine to
locate the "diaginfo.dat" file
phs, 17 Jul 2008: GAMAP VERSION 2.12
- Bug fix: only use FILE_WHICH if the
FILENAME keyword isn't passed.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_diaginfo.pro)
NAME:
CTM_GETDEFAULTSTRUCTURES
PURPOSE:
Return default values for FileInfo and DataInfo for
subsequent analysis. The defaults are taken from the
global common block defined in gamap_cmn.pro
CATEGORY:
GAMAP Internals, Structures
CALLING SEQUENCE:
CTM_GETDEFAULTSTRUCTURES, FileInfo, DataInfo, result=result
INPUTS:
FILEINFO -> A named variable that will contain the global
FileInfo structure array, i.e. information about all
files that have been opened.
DATAINFO -> A named variable that will contain the global
DataInfo structure array, i.e. information about all
data records that have been read from the headers of
all opened CTM files.
KEYWORD PARAMETERS:
RESULT -> returns 1 if assignment was successful, 0 otherwise.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required
==============================
GAMAP_CMN
REQUIREMENTS:
Requires routines from the GAMAP package.
NOTES:
None
EXAMPLE:
CTM_GETDEFAULTSTRUCTURES, $
FileInfo, DataInfo, result=result
if (not result) then return
; the current state of the global FileInfo and DataInfo
; structures will be copied into FileInfo and DataInfo
MODIFICATION HISTORY:
mgs, 20 Aug 1998: VERSION 1.00
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_getdefaultstructures.pro)
NAME:
CTM_GRID (function)
PURPOSE:
Set-up of the model grid for various models. While the
horizontal grid information can be computed from a few
basic parameters, the vertical structure is hardwired
for each model seperately. Currently, the following models
are supported: GEOS1, GEOS_STRAT, GEOS-3, GEOS-4, GEOS-5,
GEOS-57, MERRA, GISS_II, GISS_II_PRIME, FSU, FVCCM, and MATCH.
CATEGORY
GAMAP Utilities, GAMAP Models & Grids, Structures
CALLING SEQUENCE:
RESULT = CTM_GRID( MTYPE [, Keywords ] )
INPUTS:
MTYPE --> a MODELINFO structure as returned from function
CTM_TYPE. This structure must contain the following tags:
resolution (a 2 element vector with DI, DJ), halfpolar,
center180, name, nlayers, ptop, psurf, hybrid.)
OUTPUT:
RESULT -> A structure, scalor, or vector variable depending
on the output keywords below.
KEYWORD PARAMETERS:
PSURF -> specify surface pressure in mb. Overrides
value passed in through modelinfo structure.
The following keywords define output options. If none of these
is set, a structure is returned that contains all parameters.
IMX (int ) -> Maximum I (longitude) dimension [alt: NLON]
JMX (int ) -> Maximum J (latitude ) dimension [alt: NLAT]
DI (flt ) -> Delta-I interval between grid box edges
DJ (flt ) -> Delta-J interval between grid box edges
YEDGE (fltarr) -> Array of latitude edges
YMID (fltarr) -> Array of latitude centers
XEDGE (fltarr) -> Array of longitude edges
XMID (fltarr) -> Array of longitude centers
LMX (int) -> Maximum altitude level (layers) [alt: NLAYERS]
SIGMID (fltarr) -> Array of sigma center values
SIGEDGE (fltarr) -> Array of sigma edges
ETAMID (fltarr) -> Array of ETA center values
ETAEDGE (fltarr) -> Array of ETA edge values
PMID (fltarr) -> Array of approx. pressure values for sigma ctrs
PEDGE (fltarr) -> ditto for sigma edges
ZMID (fltarr) -> Array of approx. mean altitudes for sigma ctrs
ZEDGE (fltarr) -> ditto. for sigma edges
AP (fltarr) -> Hybrid-grid "A" parameters
BP (fltarr) -> Hybrid-grid "B" parameters
/NO_VERTICAL --> do not return vertical grid info in structure
In this case the MTYPE structure only needs to contain
resolution, halfpolar and center180. This keyword is ignored if
a specific (vertical) output option is requested.
DELTAZ_m --> For multi-level 'GENERIC' grids, DELTAZ_m specifies
the height of each grid level in meters. DELTAZ_m does not
apply to any of the GEOS, GISS, etc. grid families.
SUBROUTINES:
External Subroutines Required:
===============================
GETSIGMA (function)
GETETA (function)
USSA_ALT (function)
USSA_PRESS (function)
ZMID (function)
REQUIREMENTS:
Best if used with function CTM_TYPE. Also requires functions
GETSIGMA and GETETA for definition of vertical layers.
NOTES:
This routine is not very efficient in that it always computes
all the available information. But since it will not be
called too often and does not handle large amounts of data,
we won't worry about computational efficiency here.
EXAMPLE:
MTYPE = CTM_TYPE( 'GEOS1' )
MGRID = CTM_GRID( MTYPE )
; This will define the following structure (help,mgrid,/stru)
** Structure <10323808>, 17 tags, length=1624, refs=1:
IMX INT 72
JMX INT 46
DI FLOAT 5.00000
DJ FLOAT 4.00000
XEDGE FLOAT Array[73] (-177.500, -172.500, ...)
YEDGE FLOAT Array[47] (-90, -88, -84, ...)
XMID FLOAT Array[72] (-180.0, -175.0, ...)
YMID FLOAT Array[46] (-89, -86, -82, ...)
LMX INT 20
SIGMID FLOAT Array[20] (0.993936, 0.971301, ...)
SIGEDGE FLOAT Array[21] (1.00000, 0.987871, ...)
ETAMID FLOAT Array[20] (all zeroes)
ETAEDGE FLOAT Array[21] (all zeroes)
PMID FLOAT Array[20] (980.082, 957.990, ...)
PEDGE FLOAT Array[21] (986.000, 974.162, ...)
ZEDGE FLOAT Array[21]
ZMID FLOAT Array[20]
AP
; Or, with the use of output keywords:
PRINT, CTM_GRID( CTM_TYPE( 'GISS_II' ), /PMID )
; IDL will print
986.000 935.897 855.733 721.458 551.109
390.781 255.503 150.287 70.1236 10.0000
; A more awkward example (see yourself):
HELP, CTM_GRID( { RESOLUTION : [3.6,3.0], $
HALFPOLAR : 0, $
CENTER180 : 0 }, /NO_VERT), /STRU
MODIFICATION HISTORY:
bmy, 19 Aug 1997: VERSION 1.00
bmy, 24 Sep 1997: VERSION 1.01
mgs, 26 Feb 1998: Version 2.00 - rewritten as a function
mgs, 27 Feb 1998: - added vertical information
mgs, 02 Mar 1998: - better defined interface with CTM_MODEL_TYPE
bmy, 07 Apr 1998: - Renamed
mgs, 24 Apr 1998: - changed structure to named structure
mgs, 04 May 1998: - changed back because of conflicting sizes
mgs, 07 May 1998: - Renamed to CTM_GRID
- x coordinates now start with -182.5 for
center180 grids
bmy, 19 Jun 1998: - now uses USSA_ALT to compute altitudes
from pressure coordinates
- fixed some comments
- added FORWARD_FUNCTION statement
mgs, 30 Jun 1999: - added PSURF keyword
bmy, 27 Jul 1999: GAMAP VERSION 1.42
- now can compute pressure levels and
edges for hybrid sigma-pressure grids
- a few cosmetic changes
bmy, 03 Jan 2000: - more cosmetic changes
bmy, 20 Apr 2000: GAMAP VERSION 1.45
- now returns correct YMID values for FSU grid
bmy, 15 Sep 2000: GAMAP VERSION 1.46
- fixed bug for computing YMID for grids
w/o halfpolar boxes. This also fixes the
previous problem w/ the FSU grid.
bmy, 03 Jul 2001: GAMAP VERSION 1.48
- If MTYPE.NLAYERS = 0, then create a
return structure w/o vertical level info
bmy, 06 Nov 2001: GAMAP VERSION 1.49
- added ETAMID, ETAEDGE keywords
- added ETAMID, ETAEDGE tags to return structure
- now calls GETETA to return ETA coordinates
for hybrid models (such as GEOS-4/fvDAS)
- updated comments
bmy, 18 Oct 2002: GAMAP VERSION 1.52
- deleted obsolete commented-out code
bmy, 04 Nov 2003: GAMAP VERSION 2.01
- Use STRPOS to test for GEOS4 or
GEOS4_30L model names
- Now treat GISS_II_PRIME 23-layer model
as a hybrid grid instead of using the
obsolete "fake" formulation.
bmy, 28 Jun 2006: GAMAP VERSION 2.05
- bug fix for multi-level GENERIC grids
bmy & phs, 16 Aug 2007: GAMAP VERSION 2.10
- now compute mXEDGE, mXMID, mYEDGE, mYMID
as double precision, and cast back to
float, so that we get correct values for
high-res grids like 0.5 x 0.666,
- cosmetic changes
- Special handling for GEOS-5
- Now use USAGE, ROUTINE_NAME() instead of
function USE_CTM_GRID to display options
- Now return IMX, JMX as type LONG
bmy, 03 Aug 2009: GAMAP VERSION 2.13
- Added DELTAZ_m to specify grid size in
meters for multi-level GENERIC grids
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Added MERRA (identical to GEOS-5 grid,
but retains MERRA name for clarity.)
bmy, 28 Nov 2010: GAMAP VERSION 2.15
- Now use modified GETETA routine to
compute the pressure and ETA coords
consistently.
- Now save hybrid-grid parameters Ap and Bp
to the GRIDINFO structure.
bmy, 02 Feb 2012: GAMAP VERSION 2.16
- Add GEOS57 and GEOS57_47L grids, for
GEOS-5.7.x met data. (These are
identical to the GEOS-5 and MERRA grids,
but we will denote them separately).
bmy, 13 Aug 2015: GAMAP VERSION 2.19
- Add MERRA2 and MERRA2_47L grids
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_grid.pro)
NAME:
CTM_MAKE_DATAINFO (function)
PURPOSE:
Create a datainfo and fileinfo structure from an
"external" data set so that it can be used seamlessly
within the GAMAP package. The dataset can have up to
four dimensions (however, only the first 3 are currently
supported). The new datainfo and fileinfo structures
will be added to the global structure arrays.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, Structures
CALLING SEQUENCE:
RESULT = CTM_MAKE_DATAINFO( DATA, DATAINFO, FILEINFO [,Keywords] )
INPUTS:
DATA -> A 1-D, 2-D, or 3-D data array.
KEYWORD PARAMETERS:
DIAGN -> A diagnostics name (category) or number that describes
the data type. If not given, the user will be prompted.
If DIAGN is a number that is not recognized as valid
diagnostics by CTM_DIAGINFO, the number will be stored
as string value. If DIAGN is a string, it does not have
to be a valid diagnostics category.
DIM -> A 4 element vector with the DATA dimensions as
LON, LAT, LEVEL, TIME. If not given, the dimensions
of DATA will be entered sequentially. Use this keyword
to properly identify e.g. a zonal mean data set as
DIM = [ 0, 46, 20, 0 ] (for the GEOS-1).
The order and magnitude of the dimensions in DIM must
agree with the dimensions of the DATA array
(e.g. if DATA(72,46) then DIM=[46,72,0,0] is not allowed).
FILENAME-> Name of the file which is specified by the
FILEINFO structure. If FILENAME is not specified,
then the default FILENAME = "derived data".
FILETYPE -> A numeric code to identify the file type. If not
specified then the default FILETYPE = -1.
FIRSTBOX -> A 3 element vector containing IFIRST, JFIRST, and
LFIRST, which are the starting indices for the LON,
LAT, and LEVEL dimensions.
FORMAT -> A format string (for ASCII data) or descriptive
string (for binary or self-describing data) that is
saved to the DATAINFO structure. Default is ''.
GRIDINFO -> A gridinfo structure describing the grid set-up
of the data set (see CTM_GRID). If not given,
CTM_MAKE_DATAINFO attempts to use the MODELINFO
structure to construct GRIDINFO.
ILUN -> The file unit number that will be used to identify
FILEINFO and DATAINFO. If not passed, then ILUN will
be negative to denote derived data, and will increment
negatively for each data block, starting at -1.
MODELINFO -> A modelinfo structure containing information
about the model that generated the data (see CTM_TYPE).
If not given, the user is prompted for a selection.
/NO_GLOBAL -> If passed, will prevent the DATAINFO and FILEINFO
structures from being appended to the global GAMAP
common blocks. Useful for saving memory.
/NO_VERTICAL (passed via _EXTRA) -> set this keyword if you only want
to create a 2D gridfinfo structure.
TAU0, TAU1 -> Beginning and end of time interval that is spanned
by DATA (as TAU value). Default is -1 for both.
TOPTITLE -> A user defined string that may describe the data set
in more detail.
TRACER -> A tracer number or name that identifies the chemical
species or physical quantity contained in DATA. If
TRACER is an invalid name, it will be set to -1, and the
string value of TRACER will be used as TRCNAME (see below).
If not given, the user will be prompted.
TRCNAME -> A tracer name. Default is to use the name associated
with that tracer number in CTM_TRACERINFO.
SCALE -> A value that is entered in the SCALE field in DATAINFO.
Default is 1.0.
UNIT -> A unit string. Default is empty.
OUTPUTS:
DATAINFO, FILEINFO -> The datainfo and fileinfo structures
generated from the "external" data array. These are
automatically appended to the global DATAINFO and FILEINFO
structures, unless the /NO_GLOBAL keyword is set.
SUBROUTINES:
External Subroutines Required:
=========================================
CREATE3DHSTRU, CREATE3DFSTRU, TAU2YYMMDD
REQUIREMENTS:
None
NOTES:
In the current version, no error checking is made whether the
DATA dimensions agree with the grid information. This is the
users responsibility.
EXAMPLES:
(1)
DATA = DIST(72,46)
RESULT = CTM_MAKE_DATAINFO( DATA, DATAINFO, FILEINFO )
; Create a 2D array and make a DATAINFO structure.
; The user will be prompted for model type,
; diagnostics and tracer.
(2)
RESULT = CTM_MAKE_DATAINFO( DATA, DATAINFO, FILEINFO, $
MODEL=CTM_TYPE( 'GEOS1' ), DIAGN='IJ-AVG-$', $
TRACER=2, TAU0=NYMD2TAU(940901L), TAU1=NYMD2TAU(940930), $
UNIT='PPBV', DIM=[0,46,20,0], $
TOPTITLE='Zonal mean difference in Ox CLDS/no CLDS')
; Add a zonal mean difference data set (already in DATA)
(3)
HELP, DATAINFO, /STRU
** Structure H3DSTRU, 13 tags, length=72:
ILUN LONG -15
FILEPOS LONG 0
CATEGORY STRING 'ZONE-AVG'
TRACER INT 2
TRACERNAME STRING 'Ox'
TAU0 DOUBLE 84720.000
TAU1 DOUBLE 85416.000
SCALE FLOAT 1.00000
UNIT STRING 'ppbv'
FORMAT STRING ''
STATUS INT 1
DIM INT Array[4]
OFFSET INT Array[3]
DATA POINTER
; Display DATAINFO structure
MODIFICATION HISTORY:
mgs, 09 Oct 1998: VERSION 1.00
mgs, 19 Nov 1998: - bug fix. ILUN now always negative!
- unit now "required" parameter, i.e.
interactively asked for
bmy, 11 Feb 1999: VERSION 1.01
- added OFFSET keyword so that I0, J0, and
L0 offsets can be stored in DATAINFO
- DATAINFO.TAU0 and DATAINFO.TAU1 are now
stored as double precision
- updated comments
mgs, 16 Mar 1999: - cosmetic changes
- OFFSET changed into FIRSTBOX
mgs, 30 Mar 1999: - added _EXTRA keyword for ctm_grid
(use for /NO_VERTICAL)
bmy, 29 Jun 2001: GAMAP VERSION 1.48
- bug fix: now pass CTM_TRACERINFO the
tracer number plus diagnostic offset
bmy, 06 Mar 2002: GAMAP VERSION 1.50
- now take TRACER mod 100L before
adding the diagnostic offset to it
in call to CTM_TRACERINFO
bmy, 26 Nov 2003: GAMAP VERSION 2.01
- added /NO_GLOBAL keyword
- rewrote for clarity; updated comments
- Now get diagnostic spacing from CTM_DIAGINFO
- added ILUN, FILENAME, FILETYPE keywords
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 30 May 2008: GAMAP VERSION 2.12
- Minor fix to restrict FIRSTBOX to 3 elements
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_make_datainfo.pro)
NAME:
CTM_TRACERINFO
PURPOSE:
Return information about one or all tracers for a given
GEOS-Chem, GISS, or other CTM diagnostic.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, Structures
CALLING SEQUENCE:
CTM_TRACERINFO, TRACERN, TRACERSTRU [, Keywords ]
INPUTS:
TRACERN -> Tracer number or name for which to extract the
information. If TRACERN is numeric, it is interpreted as
an index to the FULLCHEM or SMALLCHEM tracernumber
in the global model. If it is a string, it will be compared
to NAME then FULLNAME. TRACERN may contain more than one
element. To retrieve information about all tracers, use the
/ALL_TRACERS keyword.
KEYWORD PARAMETERS:
/ALL_TRACERS -> Retrieve information about all tracers
FILENAME --> Name of the tracerinfo file (default tracerinfo.dat)
The file will be searched in the current directory first, then
in the directory where ctm_tracerinfo.pro is located. If not found
in either location, a standard data block is retrieved from this
file.
/FORCE_READING -> Overwrite the contents of the common block
FULLNAME -> Returns the (long) name of the requested tracer(s)
INDEX -> Returns the CTM index of the requested tracer(s)
MOLC -> Returns the carbon number of the requested tracer(s)
(For hydrocarbons, this is the # moles C/mole tracer)
MOLWT -> Returns the molecular weight (kg/mole) of the
requested tracer(s)
NAME -> Returns the (short) name of the requested tracer(s)
SCALE -> Standard scale factor for tracer
UNIT -> Returns the standard unit of the requested tracer(s)
(i.e. unit as supplied by CTM with standard scale factor
applied (e.g. ppbv instead of V/V))
IS_EDGED -> Returns whether the given tracer is defined on
level edges (IS_EDGED=1) or level centers (IS_EDGED=0).
OUTPUTS:
TRACERSTRU -> returns a structure or structure array with the
following tags:
NAME : short name for tracer as used in the model
FULLNAME : long name for tracer (may be used in titles)
MWT : molec. weight as kg N or kg C
INDEX : tracer number
MOLC : carbon number for NMHC
SCALE : standard scale factor
UNIT : standard unit for tracer with scale factor applied
IS_EDGED : Is tracer defined on level edges?
SUBROUTINES:
External Subroutines Required:
================================================
FILE_EXIST (function) ROUTINE_NAME (function)
OPEN_FILE
REQUIREMENTS:
None
NOTES:
At first call, the tracer information structure array is
either read from file or retrieved from the
DATA block at the end of this program. Thereafter, the information
is stored in a common block where it is accessible in subsequent
calls.
The newer tags MOLC, SCALE and UNIT are optional and defaulted
to 1.0, 1.0, and 'UNDEFINED', resp.
EXAMPLE:
CTM_TRACERINFO, 2, RES
PRINT, RES.NAME, RES.MWT, RES.INDEX
; prints Ox 0.0480000 2
CTM_TRACERINFO,'OX',RES
PRINT, RES.NAME, RES.MWT, RES.INDEX
; prints identical results
CTM_TRACERINFO,[1,3,5],NAME=NAME,MOLWT=MWT,MOLC=MOLC,/FORCE_READING
PRINT, NAME, MWT, MOLC
; reads tracerinfo.dat file and prints
; NOx PAN ALK4
; 0.0140000 0.121000 0.0120000
; 1.00000 1.00000 4.00000
MODIFICATION HISTORY:
mgs, 22 Apr 1998: VERSION 1.00
mgs, 24 Apr 1998: - added NAME keyword
bmy, 07 May 1998: - added MOLC structure field to store
carbon number for NMHC
mgs, 07 May 1998: VERSION 2.00
- substantially revised
mgs, 08 May 1998: - added SCALE and UNIT tags, made them optional
mgs, 28 May 1998: - bug fix with on_ioerror
mgs, 09 Oct 1998: - bug fix for tracern=0, changed CALLING SEQ. entry
mgs, 12 Nov 1998: - unit string now defaulted to 'UNDEFINED'
bmy, 03 Jan 2001: GAMAP VERSION 1.47
- skip tracer lines beginning with '#' character
bmy, 17 Nov 2003: GAMAP VERSION 2.01
- Removed FULLI, SMALLI, they're obsolete
- now use INDEX for tracer number
- Now use new file format for "tracerinfo.dat"
which allows for 8-digit offset numbers
- No longer read defaults from internal datablock
- Updated comments
bmy, 06 Apr 2004: GAMAP VERSION 2.02
- added /VERBOSE keyword
bmy, 09 Mar 2006: GAMAP VERSION 2.05
- Use "./tracerinfo.dat" as default in
order to facilitate reading in IDL 5.5-
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Add IS_EDGED tag to TRACERINFO structure
to denote whether the tracer is defined
on level centers or level edges
- Implement temporary fix: call GET_IS_EDGED
to determine if a tracer is defined on
level edges. There is probably a better way
to do this, work on that later.
- Now use FILE_WHICH to locate the
"tracerinfo.dat" file.
phs, 30 Jun 2008: GAMAP VERSION 2.12
- bug fix to account for FILENAME
phs, 22 Sep 2009: GAMAP VERSION 2.13
- added test on found/not found tracers
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_tracerinfo.pro)
NAME:
CTM_TYPE (function)
PURPOSE:
return basic parameters for various 3D models used in
the Harvard tropospheric modeling group. This information
should be sufficient for CTM_GRID to compute grid box edge
and center vectors.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids, Structures
CALLING SEQUENCE:
MTYPE = CTM_TYPE( NAME [,FAMILY] [,KEYWORDS] )
INPUTS:
NAME -> a string containing the name of the model
(GISS_II, GISS_II_PRIME (or II_PRIME), GEOS1,
GEOS_STRAT, FSU, MOPITT, or GENERIC (=DUMMY) )
FAMILY -> model family (optional, will otherwise be extracted
from NAME). Possible values: GISS or GEOS or FSU or ''
KEYWORD PARAMETERS:
NLAYERS -> number of vertical model layers. This number must
correspond to the number of layers in the model output
files and is used in conjunction with PTOP to convert
sigma levels into pressure altitudes.
[defaults: GEOS1=20, GEOS_STRAT=26, GISS=FSU=9 ]
NTROP -> number of layers in the troposphere
[defaults: GEOS1=14, GISS=7, FSU=12]
PTOP -> pressure at model top
[default 10 mbar except for GEOS_STRAT=0.1 mbar]
PSURF -> average surface pressure (needed for conversion of
sigma levels to altitudes) [default 984 mbar]
RESOLUTION -> either a 2 element vector with [ DI, DJ ] or
a scalar (DJxDI: 8=8x10, 4=4x5, 2=2x2.5, 1=1x1, 0.5=0.5x0.5)
[default for all models is 4x5]
HALFPOLAR = (1 | 0) -> indicates that polar boxes span
(half | same) latitude as all other boxes (DJ=const.)
[default: 1]
HYBRID = (1 | 0) -> indicates that the model is a
(sigma-pressure hybrid | pure sigma level ) model.
[default: 0]
/PRINT -> prints model parameters on the screen
OUTPUTS:
MTYPE -> A structure with the following tag names will be
returned: NAME, FAMILY, NLAYERS, PTOP, PSURF,
RESOLUTION, HALFPOLAR, CENTER180, FULLCHEM. If input
parameters are not correct, the function returns -1.
SUBROUTINES:
Internal Subroutines:
=====================
YES_NO_VAL (function)
CHECK_RESOLUTION
REQUIREMENTS:
None
NOTES:
If you update this routine by adding additional models, make
sure to update "select_model.pro" and "getsigma.pro" as well.
EXAMPLES:
(1)
MTYPE = CTM_TYPE( 'GEOS1', RESOLUTION=2 )
; defines model parameters for the GEOS1 model
; at 2 x 2.5 degree resolution.
(2)
MTYPE = CTM_TYPE( 'GISS_II' )
MGRID = CTM_GRID( MTYPE )
; Use CTM_TYPE in conjunction with CTM_GRID to return
; the grid structure for the standard GISS_II model.
MODIFICATION HISTORY:
mgs, 02 Mar 1998: VERSION 1.00
bmy, 07 Apr 1998: - Renamed to CTM_TYPE to keep
consistent with other CTM subroutines.
mgs, 24 Apr 1998: - made structure named
mgs, 19 May 1998: - added NTROP tag and keyword
bmy, 19 Jun 1998: - now computes FSU model parameters
- GEOS_STRAT and GEOS-1 troposphere tops
are now computed separately
- added small bug fix for fullchem from mgs
mgs, 14 Aug 1998: - added DUMMY name
mgs, 15 Aug 1998: - added GEOS-1 as variant of GEOS1
bmy, 21 Dec 1998: - changed NLAYERS for GEOS STRAT
mgs, 22 Dec 1998: - small bug fix for GEOS family NTROP
mgs, 22 Feb 1999: - added GENERIC (same as DUMMY) and allow
keyword settings for this name
bmy, 23 Feb 1999: - Implemented FSU grid information
mgs, 16 Mar 1999: VERSION 1.21
- cosmetic changes
- changed function name yesno into yesno_val to
avoid conflicts.
- removed online tag because it's never
used
bmy, 26 Jul 1999: VERSION 1.42
- added HYBRID keyword and tag name
- cosmetic changes
bmy, 15 Sep 1999: VERSION 1.43
- fixed bug for NTROP in GISS-II-PRIME, 9L
bmy, 15 Oct 1999: VERSION 1.44
- now reset model names "GEOS-STRAT" and
"GEOS-2" to "GEOS_STRAT" and "GEOS2"
bmy, 03 Jan 2000: - added GEOS-2 model parameters
- changed NTROP to 16 for GEOS1
- changed NTROP to 22 for GEOS_STRAT
bmy, 16 May 2000: VERSION 1.45
- reset NTROP to 19 for GEOS-STRAT
- now use GEOS-2 47 layer grid
bmy, 01 Aug 2000: VERSION 1.46
- added GEOS-3 48-layer grid
- added internal function CHECKRESOLUTION
- cosmetic changes, updated comments
bmy, 26 Jun 2001: GAMAP VERSION 1.48
- fixed NTROP for GEOS-3 met fields
- for generic grids, return "GENERIC" in
uppercase as model name and family name
bmy, 09 Oct 2001: GAMAP VERSION 1.49
- now accepts modelname "GEOS3_30L", and
returns a structure for 30-layer GEOS-3 grid
bmy, 06 Nov 2001: - now recognizes "GEOS-4" as a modelname
- changed default PSURF from 986 mb to 984 mb
clh & bmy, 18 Oct 2002: GAMAP VERSION 1.52:
- Now supports 7-layer MOPITT grid
bmy, 12 Dec 2003: GAMAP VERSION 2.01
- Now supports "GEOS4_30L" grid
- Set NTROP=18 for GEOS-4 grid
- Now set CENTER180=1 for GISS_II_PRIME
- Now supports 52-layer NCAR-MATCH model
- Cleaned up code and straightened out logic
- Removed SMALLCHEM, HELP keywords
bmy, 18 Feb 2004: GAMAP VERSION 2.01a
- The actual NTROP from the GEOS-4 annual
mean tropopause is 17, not 18
bmy, 17 Jun 2004: GAMAP VERSION 2.02a
- added GCAP model type for the 23L hybrid
GCAP grid (which is the same grid as the
winds for the GISS-II-PRIME)
bmy, 01 Jun 2006: GAMAP VERSION 2.05
- Bug fix: GISS-II model needs CENTER180=0
bmy & phs, 16 Aug 2007: GAMAP VERSION 2.10
- Modified for 47 layer GEOS-5 grid
- Now return NLAYERS, NTROP, HALFPOLAR,
CENTER180, FULLCHEM, HYBRID as type long
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Added MERRA (identical to GEOS-5 grid,
but retains MERRA name for clarity.)
bmy, 28 Nov 2010: GAMAP VERSION 2.15
- Make the default PSURF value 1013.25 hPa,
(i.e. 1 atm) instead of 984hPa.
bmy, 02 Feb 2012: GAMAP VERSION 2.16
- Add GEOS57 and GEOS57_47L grids, for
GEOS-5.7.x met data. (These are
identical to the GEOS-5 and MERRA grids,
but we will denote them separately).
- Added shorthand for 0.25 x 0.3125 resolution
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_type.pro)
NAME:
CTM_VALIDATESTRUCTURES
PURPOSE:
Test validity of a FILEINFO and DATAINFO structure
or array of structures.
CATEGORY:
GAMAP Internals, Structures
CALLING SEQUENCE:
CTM_VALIDATESTRUCTURES,FILEINFO,DATAINFO,result=result, $
print_warn=print_warn
INPUTS:
FILEINFO -> A FileInfo structure (array) to be tested
DATAINFO -> A DataInfo (array) to be tested
Both arguments must be present!
KEYWORD PARAMETERS:
RESULT -> A named variable that will be set to 1 if
both structures are valid. This keyword is mandatory.
PRINT_WARN -> print a warning message on the screen if
a structure is non-existent or corrupt.
OUTPUTS:
None
SUBROUTINES:
Uses ROUTINE_NAME and CHKSTRU functions
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
CTM_VALIDATESTRUCTURES,FileInfo,DataInfo,result=result
if (not result) then return
MODIFICATION HISTORY:
mgs, 20 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_validatestructures.pro)
NAME:
GETMODELANDGRIDINFO
PURPOSE:
Given a DATAINFO structure, returns the corresponding
MODELINFO and GRIDINFO structures.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids, Structures
CALLING SEQUENCE:
CTM_GETMODELANDGRIDINFO, THISDATAINFO, MODELINFO, GRIDINFO
INPUTS:
THISDATAINFO -> A single of DATAINFO structure which
contains the following fields:
** Structure H3DSTRU, 13 tags, length=72:
ILUN LONG
FILEPOS LONG
CATEGORY STRING
TRACER INT
TRACERNAME STRING
TAU0 DOUBLE
TAU1 DOUBLE
SCALE FLOAT
UNIT STRING
FORMAT STRING
STATUS INT
DIM INT
OFFSET INT
DATA POINTER
KEYWORD PARAMETERS:
LON -> set to a variable that will hold the longitude
centers of the data set. Grid Offsets of data that
do not cover the globe are accounted for.
LAT -> same as LON, but for Latitude centers.
LEVEL -> same as LON, but holds levels indices, starting at 1.
OUTPUTS:
MODELINFO -> Returns to the calling program the model
information structure (see "ctm_type.pro") which
corresponds to THISDATAINFO.
GRIDINFO -> Returns to the calling program the grid
information structure (see "ctm_grid.pro") which
corresponds to THISDATAINFO.
SUBROUTINES:
External Subroutines Required:
==============================
GAMAP_CMN (include file)
CTM_GRID (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; Read data from "myfile.bpch"
; DATAINFO is an array of structures
CTM_GET_DATA, DATAINFO, FILE='myfile.bpch'
; Loop over all data blocks in the file
FOR D = 0L, N_ELEMENTS( DATAINFO )-1L DO BEGIN
; Pick the DATAINFO structure for the Dth data block
THISDATAINFO = DATAINFO[D].DATA
; Get MODELINFO and GRIDINFO structures for the Dth data block
GETMODELANDGRIDINFO, THISDATAINFO, MODELINFO, GRIDINFO
...
ENDFOR
MODIFICATION HISTORY:
bmy, 24 Apr 2002: GAMAP VERSION 1.50
bmy, 28 Jun 2006: GAMAP VERSION 2.05
- Bug fix for multi-level GENERIC grids
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 13 May 2008: GAMAP VERSION 2.12
- Added LON and LAT keyword to return data
(not global grid) longitude and latitude centers.
phs, 8 Oct 2008: GAMAP VERSION 2.13
- Added LEVEL keyword to return levels.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/getmodelandgridinfo.pro)
NAME:
SORT_STRU
PURPOSE:
Returns an sort index array a structure data field.
CATEGORY:
Structures
CALLING SEQUENCE:
INDEX = SORT_STRU( STRU, SORT_TAG )
INPUTS:
STRU -> The structure containing the data to be sorted.
SORT_TAG -> A string containing the name of the structure
tag for which to compute the sort index array.
KEYWORD PARAMETERS:
/REVERSE_SORT -> Set this switch to return an sort
index array in reverse order.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
STRU = { DATA : [5,3,2,1,4] }
IND = SORT_STRU( STRU, 'DATA' )
PRINT, STRU.DATA[IND]
1 2 3 4 5
; Returns an sort index array for the DATA
; tag of the structure STRU. STRU.DATA[IND]
; will be in ascending order.
(2)
STRU = { DATA : [5,3,2,1,4] }
IND = SORT_STRU( STRU, 'DATA', /REVERSE_SORT );
PRINT, STRU.DATA[IND]
5 4 3 2 1
; Returns an sort index array for the DATA
; tag of the structure STRU. STRU.DATA[IND]
; will be in descending order.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/structures/sort_stru.pro)
NAME:
STRUADDVAR (function)
PURPOSE:
Add additional variables (tags) to an exisiting
structure. The new variables will be inserted after
the old ones, '__' tags will be appended at the end.
The function renames new tags if they would cause
duplicate names by adding a '_A'.
CATEGORY:
Structures
CALLING SEQUENCE:
NEWSTRU = STRUADDVAR( OLDSTRU, NEWVAR [, NEWNAME, Keywords ] )
INPUTS:
OLDSTRU -> the exisiting structure. This must be a structure,
otherwise the program will complain and exit.
NEWVAR -> A new variable (any type) or a new structure
that shall be incorporated into OLDSTRU. If NEWVAR
is *not* a structure, then NEWNAME must be present.
If you want to add an array with several named columns,
use Arr2Stru first.
NEWNAME -> The name of the new variable. Only used if
NEWVAR is no structure.
KEYWORD PARAMETERS:
/WARNNELEMENTS -> If this flag is set, the program will print out
a warning if the number of elements in the new variable does
not match the number of elements in the last variable of the
old structure.
OUTPUTS:
NEWSTRU -> A structure that combines the information from
OLDSTRU and NEWVAR.
SUBROUTINES:
External Subroutines Required:
==============================
CHKSTRU (function)
REQUIREMENTS:
None
NOTES:
(1) NEWNAME (or the tag names from NEWVAR) will be added to
the __NAMES__ tag if present. __EXTRA__ entries will be
combined only if tags within __EXTRA__ structures are
different. If __EXTRA__ contains a non-structure
variable it will be converted to a structure with tag
name 'EXTRA_N' where N is a number from 1-9, A-Z (the
first tag is just 'EXTRA').
EXAMPLES:
(1)
NSTRU = STRUADDVAR( STRU, FINDGEN(100), 'DUMMY' )
; Adds a 100 element floating-point array
; to structure STRU under the tag name "DUMMY"
; and returns the result as NSTRU.
(2)
X = { A :0L, B:STRARR(10), $
C : FINDGEN(100), __EXTRA__:'TEST' }
OSTRU = STRUADDVAR( NSTRU, X )
; Adds the structure X (with tag names A, B, C, and
; __EXTRA__) to the structure NSTRU and returns
; the result as OSTRU.
MODIFICATION HISTORY:
mgs, 03 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/structures/struaddvar.pro)
NAME:
STRUINFO (function)
PURPOSE:
Return information about structures. This routine is designed
to help handling variable structures of mixed type.
CATEGORY:
Structures
CALLING SEQUENCE:
INFO = STRUINFO( STRU, [, Keywords ] )
INPUTS:
STRU -> a structure
KEYWORD PARAMETERS:
NAMES -> return variable names as spelled in structure tags
ORIGINAL_NAMES -> return variable names as stored in
__NAMES__ tag
EXTRA -> return information stored in __EXTRA__ tag. This
information is always returned as a structure
NVARS -> return number of variables, i.e. tags that do
not begin with '__'
HOMOGENEOUS -> return tag indices of tags with identical '
number of elements (only those can be combined to an
array with Stru2Arr). This keyword honors the RefIndex
keyword.
NUMERIC -> return tag indices of numeric structure tags
TYPE -> return variable type of structure tags. For
non-variable tags (whose name begin with '__') a -1
is returned
REFINDEX -> indicates the tag index to compare the number
of elements to (default is the first variable index).
OUTPUTS:
The desired information (hopefully)
SUBROUTINES:
External Subroutines Required:
================================
CHKSTRU (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, STRUINFO( !p, /names )
BACKGROUND CHARSIZE CHARTHICK CLIP COLOR FONT LINESTYLE
MULTI NOCLIP NOERASE NSUM POSITION PSYM REGION SUBTITLE
SYMSIZE T T3D THICK TITLE TICKLEN CHANNEL
; Print the names from the !P system variable structure
MODIFICATION HISTORY:
mgs, 03 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/structures/struinfo.pro)