List routines by category:
Atmospheric Sciences | 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
Last modified: Thu Jul 17 10:11:00 2008.
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 /san/home/ctm/bmy/IDL/gamap2/structures/chkstru.pro)
NAME:
CHOICE
PURPOSE:
Allows user to choose interactively from several options.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = CHOICE( VALUES [,options] )
INPUTS:
VALUES -> a string array containing the selectable options
KEYWORD PARAMETERS:
TITLE -> title to be displayed on top of the selection menu
DEFAULT -> a default selection (to allow user to simply
press enter)
BY_INDEX -> return selection index rather than value
/NOABORT -> prevents addition of 'ABORT' to selection
OUTPUTS:
CHOICE returns a string containing the selected value or
the index of the selection if keyword /BY_INDEX is set.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
CHOICE automatically adds 'ABORT' to the list of selections.
If keyword BY_INDEX is set then ABORT will return -1
(unless /NOABORT keyword is set)
EXAMPLE:
DIRNAMES = [ '~my/dir/','~your/dir/','~any/dir']
DIR = CHOICE( DIRNAMES, TITLE='Select Directory' )
IF (DIR ne 'ABORT') THEN BEGIN
OPENR, U1, DIR+FILE, /GET_LUN
READF, U1, DATA
CLOSE, U1
FREE_LUN,U1
ENDIF ELSE PRINT,'ABORTED !'
; Allow user to pick a directory and then
; read a file from that directory.
MODIFICATION HISTORY:
mgs, 26 Sep 1997: VERSION 1.00
mgs, 17 Nov 1998: - added DEFAULT and NOABORT keywords
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/general/choice.pro)
NAME:
CINDEX
PURPOSE:
This is a program for viewing the current colors in the
colortable with their index numbers overlayed on each color.
CINDEX Draws a NROW x NCOL set of small rectangles, each of
which displays one of the colors in the color table. It also
writes the color index number on top of each rectangle.
CATEGORY:
Color
CALLING SEQUENCE:
CINDEX
INPUTS:
None
KEYWORD PARAMETERS:
NCOL -> Specify the number of columns in the plot.
Default is 16.
NROW -> Specify the number of columns in the plot. If not
specified, then CINDEX will compute the minimum number
of rows that are needed to display all of the colors,
given the setting of NCOL.
TITLE -> Specify the title for the plot window.
/ALL -> Set this switch to plot all 256 colors on a 16x16 grid.
Colors that are not defined will be rendered as white.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
MYCT, /WhGrYlRd
CINDEX
; Displays the colors of the MYCT color table
; WHITE-GREEN-YELLOW-RED (spectral). The drawing
; colors and all 20 colors of this table are shown.
(2)
MYCT, /WhGrYlRd
CINDEX, /ALL
; Same as above, but plots the colors on a
; 16 x 16 grid.
MODIFICATION HISTORY:
INITIAL REVISION: David Fanning, RSI, May 1995
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Added NCOL, ROW, TITLE, ALL keywords to
allow the user to specify these settings
instead of having these be hardwired.
bmy, 21 Apr 2008: GAMAP VERSION 2.12
- Now use NAME and INDEX tags from !MYCT
to define the default title string.
(See /san/home/ctm/bmy/IDL/gamap2/color/cindex.pro)
NAME:
CLOSE_DEVICE
PURPOSE:
CLOSE_DEVICE closes the PostScript device and spawns
a print job to the printer specified by the user or
it can be used to close a graphics window.
CATEGORY:
Graphics
CALLING SEQUENCE:
CLOSE_DEVICE [,OLD_DEVICE] [, Keywords ]
INPUTS:
OLD_DEVICE -> Name of device that shall become the active
plotting device. If omitted, "X", "WIN" or "MAC" will
be set depending on !VERSION.OS_FAMILY. Hence,
specification of OLD_DEVICE is only rarely needed.
This parameter works together with the OLD_DEVICE
parameter of OPEN_DEVICE which returns the device name
before the postscript device (or a graphics device) is
opened. The OLD_DEVICE parameter can be misused to set
the output device to anything! Therefore, it's probably
safest to not use it and stick with the operating system
dependent default.
KEYWORD PARAMETERS:
LABEL -> a string that contains an annotation for a postscript
plot (usually a user name and/or filename). The current
data and time will be appended if TIMESTAMP is set.
NOTE: TIMESTAMP will produce an annotation even if LABEL
is not provided. The annotation is only added to
postscript plots and only if the ps file is actually
open.
/TIMESTAMP -> add date and time to the LABEL on the plot.
If no LABEL is provided, the username and filename
(value of FILENAME will be used or the filename of the
current postscript file will be added). The timestamp
is only added to postscript plots and only on the last
page.
PRINTER -> Name of the printer queue to send output to.
Default is 'none', i.e. the postscript file will only
be closed and can then be manually printed e.g. using
the Unix lpr command. Direct printing only works in
Unix environments.
WINDOW -> window number to be closed (or -1 if current)
_EXTRA=e -> any additional keywords to CLOSE_DEVICE will
be passed on to STRDATE which is used to format the
date and time string. Possible values are: /SHORT,
/SORTABLE, /EUROPEAN.
LCOLOR -> the color value for the LABEL (default 1).
LPOSITION -> the position of the LABEL in normalized
coordinates (a two-element vector with default
[0.98,0.007]).
LSIZE -> the charcter size of the LABEL (default 0.7).
LALIGN -> the alignment of the LABEL (default 1).
FILENAME -> name of the PostScript file. This is actaully
obsolete now because the PostScript filename is
determined at the time the file is opened (e.g. in
routine OPEN_DEVICE)
OUTPUTS:
If postscript device is active, a *.ps file will be closed
and optionally sent to the printer.
SUBROUTINES:
External Subroutines Required:
================================
STRDATE (function)
REQUIREMENTS:
Requires routines in the
NOTES:
The WINDOW keyword is only evaluated if the current device
supports windows [!D.FLAGS AND 256) GT 0]. If you only want
to close a postscript file and don't fuss around with your
screen windows then simply don't set this keyword.
EXAMPLES:
(1)
CLOSE_DEVICE
; Closes a postscript file (if opened) and resets the
; current plotting device to 'X', 'WIN', or 'MAC'
; depending on the OS_FAMILY.
(2)
CLOSE_DEVICE, PRINTER='hplj4', LABEL='mgs', /TIMESTAMP
; If current device name is PS then the postscript
; file will be closed, a user, date and time label will
; be added and the file will be spooled to the printer
; queue 'hplj4'. NOTE: Printing of the file fails if you
; specified FILENAME as a relative path in the OPEN_DEVICE
; command and you changed your working directory while
; the device was opened.
(3)
CLOSE_DEVICE, WIN=-1
; If current device name is PS then the postscript file
; will be closed. If the current device is a screen
; device (that supports windows), then the active window
; will be deleted.
MODIFICATION HISTORY:
bmy, 18 Aug 1997: VERSION 1.00
bmy, 19 Aug 1997: VERSION 1.01
mgs, 20 Aug 1997: VERSION 1.02
mgs, 08 Apr 1998: VERSION 2.00
- automatic filename detection
- default device depending on OS_FAMILY
mgs, 21 May 1998:
- added L.. keywords to control label
and timestamp output
mgs, 18 Nov 1998:
- added output of username as default in timestamp
bmy, 28 Jul 2000: TOOLS VERSION 1.46
- cleaned up a few things
bmy, 24 May 2007: TOOLS VERSION 2.06
- Updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/graphics/close_device.pro)
NAME:
CMSET_OP
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Performs an AND, OR, or XOR operation between two sets
CATEGORY:
Math & Units
CALLING SEQUENCE:
SET = CMSET_OP(A, OP, B)
DESCRIPTION:
SET_OP performs three common operations between two sets. The
three supported functions of OP are:
OP Meaning
'AND' - to find the intersection of A and B;
'OR' - to find the union of A and B;
'XOR' - to find the those elements who are members of A or B
but not both;
Sets as defined here are one dimensional arrays composed of
numeric or string types. Comparisons of equality between elements
are done using the IDL EQ operator.
The complements of either set can be taken as well, by using the
NOT1 and NOT2 keywords. For example, it may be desireable to find
the elements in A but not B, or B but not A (they are different!).
The following IDL expressions achieve each of those effects:
SET = CMSET_OP(A, 'AND', /NOT2, B) ; A but not B
SET = CMSET_OP(/NOT1, A, 'AND', B) ; B but not A
Note the distinction between NOT1 and NOT2. NOT1 refers to the
first set (A) and NOT2 refers to the second (B). Their ordered
placement in the calling sequence is entirely optional, but the
above ordering makes the logical meaning explicit.
NOT1 and NOT2 can only be set for the 'AND' operator, and never
simultaneously. This is because the results of an operation with
'OR' or 'XOR' and any combination of NOTs -- or with 'AND' and
both NOTs -- formally cannot produce a defined result.
The implementation depends on the type of operands. For integer
types, a fast technique using HISTOGRAM is used. However, this
algorithm becomes inefficient when the dynamic range in the data
is large. For those cases, and for other data types, a technique
based on SORT() is used. Thus the compute time should scale
roughly as (A+B)*ALOG(A+B) or better, rather than (A*B) for the
brute force approach. For large arrays this is a significant
benefit.
INPUTS:
A, B - the two sets to be operated on. A one dimensional array of
either numeric or string type. A and B must be of the same
type. Empty sets are permitted, and are either represented
as an undefined variable, or by setting EMPTY1 or EMPTY2.
OP - a string, the operation to be performed. Must be one of
'AND', 'OR' or 'XOR' (lower or mixed case is permitted).
Other operations will cause an error message to be produced.
KEYWORDS
NOT1, NOT2 - if set and OP is 'AND', then the complement of A (for
NOT1) or B (for NOT2) will be used in the operation.
NOT1 and NOT2 cannot be set simultaneously.
EMPTY1, EMPTY2 - if set, then A (for EMPTY1) or B (for EMPTY2) are
assumed to be the empty set. The actual values
passed as A or B are then ignored.
INDEX - if set, then return a list of indices instead of the array
values themselves. The "slower" set operations are always
performed in this case.
The indices refer to the *combined* array [A,B]. To
clarify, in the following call: I = CMSET_OP(..., /INDEX);
returned values from 0 to NA-1 refer to A[I], and values
from NA to NA+NB-1 refer to B[I-NA].
COUNT - upon return, the number of elements in the result set.
This is only important when the result set is the empty
set, in which case COUNT is set to zero.
RETURNS
The resulting set as a one-dimensional array. The set may be
represented by either an array of data values (default), or an
array of indices (if INDEX is set). Duplicate elements, if any,
are removed, and element order may not be preserved.
The empty set is represented as a return value of -1L, and COUNT
is set to zero. Note that the only way to recognize the empty set
is to examine COUNT.
SEE ALSO:
SET_UTILS.PRO by RSI
MODIFICATION HISTORY:
Written, CM, 23 Feb 2000
Added empty set capability, CM, 25 Feb 2000
Documentation clarification, CM 02 Mar 2000
Incompatible but more consistent reworking of EMPTY keywords, CM,
04 Mar 2000
Minor documentation clarifications, CM, 26 Mar 2000
Corrected bug in empty_arg special case, CM 06 Apr 2000
Add INDEX keyword, CM 31 Jul 2000
Clarify INDEX keyword documentation, CM 06 Sep 2000
Made INDEX keyword always force SLOW_SET_OP, CM 06 Sep 2000
Added CMSET_OP_UNIQ, and ability to select FIRST_UNIQUE or
LAST_UNIQUE values, CM, 18 Sep 2000
Removed FIRST_UNIQUE and LAST_UNIQUE, and streamlined
CMSET_OP_UNIQ until problems with SORT can be understood, CM, 20
Sep 2000 (thanks to Ben Tupper)
Still trying to get documentation of INDEX and NOT right, CM, 28
Sep 2000 (no code changes)
Correct bug for AND case, when input sets A and B each only have
one unique value, and the values are equal. CM, 04 Mar 2004
(thanks to James B. jbattat at cfa dot harvard dot edu)
Add support for the cases where the input data types are mixed,
but still compatible; also, attempt to return the same data
type that was passed in; CM, 05 Feb 2005
Fix bug in type checking (thanks to "marit"), CM, 10 Dec 2005
Work around a stupidity in the built-in IDL HISTOGRAM routine,
which tries to "help" you by restricting the MIN/MAX to the
range of the input variable (thanks to Will Maddox), CM, 16 Jan 2006
$Id: cmset_op.pro,v 1.4 2007/11/20 21:55:32 bmy Exp $
(See /san/home/ctm/bmy/IDL/gamap2/math_units/cmset_op.pro)
NAME:
CODE_TREE
PURPOSE:
This routine produces a tree structure for Fortran programs.
It will scan a directory for FORTRAN files and gather all
SUBROUTINE names and CALL statements. FUNCTIONS are not
parsed.
CATEGORY:
General
CALLING SEQUENCE:
CODE_TREE [, DEFAULT_PATH, DEFAULT_MAIN ] [ , /FILENAMES ]
INPUTS:
DEFAULT_PATH -> the default search path to look for FORTRAN files
DEFAULT_MAIN -> the default name of the main program file. Note
that code_tree will not work properly if the main file
contains subroutine definitions.
KEYWORD PARAMETERS:
/FILENAMES -> display the filename where each routine can be
found together with the routine name.
OUTPUTS:
A calling tree is generated on the screen or dumped into a file.
SUBROUTINES:
Several
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
CODE_TREE
MODIFICATION HISTORY:
99/5/18 Philip Cameron-Smith, Harvard
Initial code.
99/5/21 Philip Cameron-Smith, Harvard
Have included some of my utilities to allow easy distribution.
Added '1' to names to ensure no future conflicts.
99/5/24 Philip Cameron-Smith, Harvard
Now removes tabs and strings.
Various other improvements.
99/5/25 Philip Cameron-Smith, Harvard
Reversed order of path and filename arguments
Converted a "print" to a "printf,lun" to stop lines running
on when printing to a file.
Improved check for ENTRY before SUBROUTINE.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/general/code_tree.pro)
NAME:
COLORBAR
PURPOSE:
Draw a colorbar (legend) with labels
CATEGORY:
Color
CALLING SEQUENCE:
COLORBAR [ , Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
ANNOTATION -> Array with string label values. If specified,
ANNOTATION will override the default label values, and
will also override the LABEL keyword.
BOTOUTOFRANGE, TOPOUTOFRANGE -> a color index value for data
that falls below (or above) the normal plot range. If
given, an extra box will be drawn to the left (or right)
of the colorbar, and the colorbar will shrink in size.
A default label '<' (or '>') will be placed below.
NOTE: these options are only available for horizontal
colorbars.
BOR_LABEL, TOR_LABEL -> label values for BOTOUTOFRANGE and
TOPOUTOFRANGE that replace the defaults.
BOTTOM -> First color index to use. Default is !MYCT.BOTTOM.
NOTE: In practice you shouldn't have to specify BOTTOM,
as the value from !MYCT.BOTTOM will reflect the settings
of the current colortable.
C_COLORS -> Array of color indices for "discrete" color bars
e.g. in filled contour plots. You must also use the
C_LEVELS keyword, otherwise there will most likely be
a mismatch between your plot colors and your colorbar
colors. COLORBAR normally limits the number of labels
it prints to 10. Use the SKIP keyword to force a different
behaviour. If C_COLORS is not undefined it overrides the
settings from NCOLORS, and BOTTOM.
C_LEVELS -> Array with label values for "discrete" colorbars.
Use the LABEL or ANNOTATION keyword for continuous
colorbars. C_LEVELS must have the same number of elements
as C_COLORS and assigns one label to each color change
(LABEL distributes the labels evenly). Use the SKIP
keyword to skip labels. As default, COLORBAR limits the
number of labels printed to 10.
CHARSIZE -> Specifies the character size for colorbar labels.
Default is !P.CHARSIZE.
COLOR -> The drawing color for boxes and labels.
Default is !MYCT.BLACK.
DIVISIONS -> Number of labels to put on the colorbar.
Note that this keyword is overwritten by LABEL.
The labels will be equally spaced and the /LOG option
will be honored.
FLAGVAL -> If set, will place a tick mark with label at a
user-defined value. You can use this to denote where
0 or 1 falls w/in a color range, for example.
FORMAT -> Output format of the labels. Default is determined
according to the range given in min and max. Label
strings will be trimmed, so you can safely specify
'(f14.2)' for example.
LABEL -> Array containing label values (must be numeric).
Normally, it is easier to generate labels with the
DIVISIONS options, but this allows tighter control
(e.g. 1,2,5,10,20 labels on logarithmic scales).
Default (if no DIVISIONS are given): MIN and MAX.
NOTE: ANNOTATION will
/LOG -> Set this switch to invoke logarithmic spacing of
labels. The colors are *always* linearily distributed.
MAX -> Maximum value to plot. Default is NCOLORS.
MIN -> Minimum value to plot. Default is BOTTOM.
/NOGAP -> if 0 then there is a gap b/w the triangle or
rectangle OutOfRange boxes and the bar, else no
gap. Defalut is to have a gap. If /TRIANGLE and no
OutOfRange boxes are set then default is No Gap.
NCOLORS -> Number of colors to use in the colorbar. Default
is !MYCT.NCOLORS. NOTE: In practice you shouldn't have
to specify NCOLORS, as the value from !MYCT.NCOLORS will
reflect the settings of the current colortable.
ORIENTATION -> Specifies the orientation of the colorbar
labels. This keyword has the same behavior as the
ORIENTATION option in XYOUTS (i.e. ORIENTATION=0 means
normal "left-right" text, ORIENTATION=-90 means "top-
bottom" text, etc.)
POSITION -> A position value or 4-element vector. If POSITION
contains only one element, it will be centered at the
bottom or right side of the page and extend over 60% of
the total plotting area.
SCIENTIFIC -> If set, will call STRSCI to put the colorbar
labels in scientific notation format (e.g. in the form
A x 10^B). STRSCI will use the format string specified
in the FORMAT keyword.
SKIP -> Print only every Nth discrete label. The default is
computed such that COLORBAR will print no more than 10
labels.
TITLE -> A title string for the colorbar. (This works similarly
to the XTITLE or YTITLE options to the PLOT command.)
TICKLEN -> A number between 0 and 1 which defines the length
of the tick marks as a fraction of the size of the plot
box. Default is 0.25.
/TRIANGLE -> to plot triangles at the end of the color bar. If
OutOfRange boxes are requested, then the triangles
replace the rectangle.
UNIT -> A unit string that will be added to the right of the
labels. If /VERTICAL is set, then the unit string will
be placed at the top of the labels.
/VERTICAL -> Set this keyword to produce a vertical colorbar
(default is horizontal). Note that out-of-range boxes are
only implemented for horizontal color bars.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
====================================
STRSCI (function) TRIANGLE
REQUIREMENTS:
Assumes that we are using a MYCT-defined colortable.
NOTES:
(1) This routine was designed after David Fanning's colorbar
routine and adapted to our needs. Some of the postscript
handling of DF was removed, positioning is a little easier
but maybe a little less flexible; out-of-range boxes have
been added.
(2) The !MYCT system variable contains the properties of the
current MYCT-defined colortable. You normally should not
have to explicity pass BOTTOM or NCOLORS, as these
keywords will be initialized from the values from !MYCT.
EXAMPLES:
COLORBAR, MIN=MIN( DATA, MAX=M ), MAX=M
; Draw a horizontal colorbar with all available colors
; Default placement is at the bottom of the page.
; will be placed at the bottom of the page
COLORBAR, MIN=0.1, MAX=10, /LOG, UNIT='[ppt]', $
LABELS=[0.1, 0.5, 1, 5, 10 ],
POSITION=[0.3. 0.3, 0.3, 0.3]
; Draw another colorbar above the first one,
; use logarithmic scale
COLORBAR, MIN=0.1, MAX=10, /LOG, UNIT='[ppt]', $
LABELS=[0.1, 0.5, 1, 5, 10 ],
POSITION=[0.1, 0.1, 0.1, 0.1], /VERTICAL
; Draw vertical colorbar closer to the left edge of
; the plot. Otherwise options are the same as in the
; previous example.
COLORBAR, MIN=0, MAX=100, $
DIVISIONS=5, TOPOUTOFRANGE=!MYCT.WHITE
; Draw horizontal colorbar with out-of-range box
; (colored white) to the right of the max value.
COLORBAR, MIN=0, MAX=100, $
DIVISIONS=5, TOPOUTOFRANGE=!MYCT.WHITE, $
ANNOTATION=[ '0', '2,500', '5,000', '7,500', '10,000' ]
; Same example as above, but this time we use the
; ANNOTATION keyword to override the default labels
; with string labels.
MODIFICATION HISTORY:
mgs, 02 Jun 1998: VERSION 1.00
mgs, 14 Nov 1998: - changed default format to f14.2 from f6.2
mgs, 19 Nov 1998: - added cbdefaultformat function to better handle
default labeling format.
mgs, 28 Nov 1998: - default labelling format now exponential for
values gt 1.e6
mgs, 19 May 1999: - unit string placed a little further right
in horizontal colorbars.
mgs, 27 May 1999: - added functionality for discrete colorbars
(C_COLORS, C_LEVELS, and SKIP keywords)
bmy, 02 Jun 1999: - added /SCIENTIFIC keyword
- updated comments
mgs, 03 Jun 1999: - fixed discrete labeling x positions
bmy, 27 Jul 2000: TOOLS VERSION 1.46
- added ORIENTATION keyword so that the user
can control the vertical colorbar labels
bmy, 27 Sep 2002: TOOLS VERSION 1.51
- Now use 2 decimal places for exponential
default format instead of 3
bmy, 18 Oct 2002: TOOLS VERSION 1.52
- now use _EXTRA=e to pass commands to
XYOUTS (i.e. to set label thickness)
bmy, 26 Nov 2002: - Added ANNOTATION keyword to print
string labels instead of numeric labels
bmy, 26 Nov 2003: TOOLS VERSION 2.01
- make sure MINV, MAXV, and DIVISIONS
are scalars so as not to generate the
color bar labels incorrectly.
bmy, 21 May 2004: TOOLS VERSION 2.02
- If SKIP is passed, make sure that it is
never less than 1.
- added TICKLEN and FLAGVAL keywords
- now add ticks where labels are printed
- Cosmetic changes, updated comments
bmy, 07 Mar 2007: TOOLS VERSION 2.06
- Updated documentation and examples
dbm & bmy, 13 Jun 2007: - Now define default colors for contour plots
if C_LEVELS is passed but C_COLORS isn't
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
cdh & phs, 19 Nov 2007: GAMAP VERSION 2.11
- Added out of range boxes options for
vertical bar
- Added TRIANGLE and NoGAP keyword
- Set default for case of /TRIANGLE, but no
OutOfRange boxes.
phs, 21 Apr 2008: GAMAP VERSION 2.12
- Bug fix default MAXV should be NCOLORS+BOTTOM
(See /san/home/ctm/bmy/IDL/gamap2/color/colorbar.pro)
NAME:
COLORBAR_NDIV
PURPOSE:
Returns the maximum number of colorbar divisions possible
(up to a user-defined limit) such that tickmarks are placed
in between colors.
CATEGORY:
Color
CALLING SEQUENCE:
Result = COLORBAR_NDIV( NCOLORS [, Keywords ] )
INPUTS:
NCOLORS -> (OPTIONAL) Specifies the number of colors
in the color table. Default is !MYCT.NCOLORS.
KEYWORD PARAMETERS:
MAXDIV -> Specifies the maximum number of divisions
for the colorbar. Default is 6.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
DIV = COLORBAR_NDIV( 20, MAXDIV=8 )
TVMAP, ..., DIVISONS=DIV, ...
; Computes the number of color bar divisions for
; a colortable with 20 colors. DIV will not exceed
; the value of MAXDIV (in this case =8). The value
; of DIV is then passed to the TVMAP routine (which
; in turn passes it to the COLORBAR routine).
MODIFICATION HISTORY:
phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/color/colorbar_ndiv.pro)
NAME:
COMPARE_FLIGHT
PURPOSE:
Compare observations from aircraft campaigns to
high time-resolution CTM output (bpch files).
This routine reads aircraft data in binary (bdt) format
and produces an unlabeld plot and returns all the data
you might ask for. If an aircraft mission extends beyond
midnight GMT, the program will ask for a second model file
which should be from the following day.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
COMPARE_FLIGHT, keywords
INPUTS:
None
KEYWORD PARAMETERS:
DATAFILE -> Name of the aircraft data file or file mask
MODELFILE -> Name of the (first) model output file or file mask
TRACER -> tracer number in model output (default=71)
PSURF -> surface pressure for model grid (default=1013, because most
aircraft data was sampled over oceans)
FLIGHTDATA -> returns the observational data array as read
with gte_readbin. Can also be used to pass flight data if you
set the USE_DATA flag.
FLIGHTVARS -> returns the variable names of the observational data.
Must accompany FLIGHTDATA if you use USE_DATA.
SPECIES -> the name of the observed species to plot (default CH3I).
MODELDATA -> returns a time series of model data along the flight
track and a couple of min/max values:
MODELDATA[*,0] = model value in corresponding grid box
[*,1] = min of neighbouring grid boxes at same level
[*,2] = max ...
[*,3] = min of neighbouring grid boxes at level below
[*,4] = max ...
[*,5] = min of neighbouring grid boxes at level above
[*,6] = max ...
Note that the min/max arrays may contain values from the same
grid boxes at the edges (i.e. there is no level below the first
one, hence 3,4 will be identical to 1,2).
TIME -> returns the time vector of the observations and modeldata
/USE_DATA -> set this flag if you provide the aircraft data in the
FLIGHTDATA array and the variable names in FLIGHTVARS. The data
must contain variables named 'LON', 'LAT', 'ALTP' and SPECIES
(for SPECIES see above). You must also provide a TIME vector
which specifies UTC seconds.
OUTPUTS:
The extracted data is returned in MODELDATA, several other keywords
return things read or computed in the process.
SUBROUTINES:
EXTRACT__FLIGHT : actual workhorse that does the extraction
REQUIREMENTS:
chkstru, ctm_get_data (GAMAP), gte_readbin (GTE)
NOTES:
Some hardwiring of default directories.
EXAMPLE:
simply COMPARE_FLIGHT,tracer=1 if all you want is a plot
CONVERT_FLIGHT,tracer=1,modeldata=md,time=time
plot,time,md[*,0],color=1
MODIFICATION HISTORY:
mgs, 21 Apr 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/gamap_util/compare_flight.pro)
NAME:
COMPRESS_DIV_CT
PURPOSE:
Compresses a diverging color table with even number of colors
into NCOLORS. If the /MIDCOLORPRESENT keyword is specified,
COMPRESS_DIV_CT will also place white or yellow spaces in
the middle of the color table.
CATEGORY:
Color
CALLING SEQUENCE:
COMPRESS_DIV_CT, R, G, B [, Keywords ]
INPUTS:
R, G, B -> The vectors containing the red, blue, and
green color values that define the color table.
KEYWORD PARAMETERS:
NCOLORS -> Requested number of colors to be returned.
If NCOLORS is omitted, then COMPRESS_DIV_CT will
return without doing anything.
/MIDCOLORPRESENT -> Set this switch to add 1 or 2 extra
white or yellow color spaces in the color table.
/WHITE -> If /MIDCOLORPRESENT is set, this switch will
cause 1 (if NCOLORS is odd) or 2 (if NCOLORS is even)
extra white color spaces to be placed
at the center of the color table.
/YELLOW -> If /MIDCOLORPRESENT is set, this switch will
cause 1 (if NCOLORS is odd) or 2 (if NCOLORS is even)
extra white color spaces to be placed
at the center of the color table. ;
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
Designed for use with MYCT. You shouldn't normally
have to call COMPRESS_DIV_CT directly.
NOTES:
None
EXAMPLE:
LOADCT, 63, FILE=FILE_WHICH( 'gamap_colors.tbl' )
TVLCT, R, G, B, /Get
; Load the ColorBrewer "RdBu" table
; and return the color vectors
COMPRESS_DIV_CT, R, G, B, $
NCOLORS=20, /MIDCOLORPRESENT, /WHITE
; Compress the color table down to 20 colors and
; insert 2 white spaces at the middle of the table.
MODIFICATION HISTORY:
phs, 21 Apr 2008: GAMAP VERSION 2.12
(See /san/home/ctm/bmy/IDL/gamap2/color/compress_div_ct.pro)
NAME:
CONVERT_INDEX
PURPOSE:
Converts a 1-D array index (such as is returned from
WHERE, UNIQ, etc) to the appropriate 1-D, 2-D, or 3-D
array indices
CATEGORY:
General
CALLING SEQUENCE:
RESULT = CONVERT_INDEX( Index, Dim )
INPUTS:
INDEX -> The 1-D array index to be converted to
multi-dimensional indices. INDEX is returned
to the calling program unchanged.
DIM -> A vector containing the dimensions of the array
for which multi-dimensional indices are required.
KEYWORD PARAMETERS:
FORTRAN -> Interpret array indices as FORTRAN indices, i.e.
starting from 1 instead of 0. This applies to INPUT
and OUTPUT indices!
OUTPUTS:
RESULT -> Returns either a vector index or a vector of
multi-dimensional array indices as the value of the
function. If INDEX is a 1-dimensional parameter, the
result will have n_elements(dim) dimensions. If INDEX
is a multidimensional parameter, the result will be
a scalar.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
Right now only works for 3-D arrays and smaller. Will
eventually do the general case...
EXAMPLES:
(1)
PRINT, CONVERT_INDEX( [1,1], [2,2] )
3
(2)
PRINT, CONVERT_INDEX( [2,2], [2,2] )
% CONVERT_INDEX: Index[0] greater than Dim[0]
% CONVERT_INDEX: Index[1] greater than Dim[1]
6
(3)
PRINT, CONVERT_INDEX( [2,2], [2,2], /FORTRAN )
4 ; <<<-- shifted by 1 !
(4)
PRINT, CONVERT_INDEX( 72, [72,46,20] )
0 1 0
(5)
PRINT, CONVERT_INDEX( 72, [72,46,20], /FORTRAN )
72 1 1
MODIFICATION HISTORY:
bmy, 07 Oct 1998: VERSION 1.00
mgs, 07 Oct 1998: VERSION 1.20
- made result etc LONG arrays
- allow sany dimensions now
- added reverse operation if index is multidimensional
- added FORTRAN keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/general/convert_index.pro)
NAME:
CONVERT_KG_MOLCM2
PURPOSE:
Converts the units of a 2-D array from kg to molecules/cm2
(or kg/s to molecules/cm2/s).
CATEGORY:
Math & Units
CALLING SEQUENCE:
CONVERT_KG_MOLCM2, DATA, AREACM2, KGPERMOLE
INPUTS:
DATA -> 2-D array of data values in units of
kg or kg s^-1.
AREACM2 -> 2-D array containing the surface area of each
gridbox in cm^2
KGPERMOLE -> The molecular weight of the tracer or
molecule, in units of kg mole^-1.
OUTPUTS:
DATA -> The converted array in molecules cm^-2 s^-1
is returned in DATA.
KEYWORD PARAMETERS:
None
SUBROUTINES:
None
REQUIREMENTS:
CTM_SURFACE_AREA must be called to compute the AREACM2 array.
TRACER_KG_PER_MOLE (or a similar subroutine) must be called
to compute the KGPERMOLE array.
NOTES:
None
EXAMPLE:
AreaCm2 = CTM_SURFACE_AREA( GridInfo, /cm2, /GEOS )
KgPerMole = TRACER_KG_PER_MOLE( /FULLCHEM )
TracerNumber = 1 ; for NOx
CONVERT_KG_MOLCM2, Data, AreaCm2, KgPerMole(TracerNumber)
; Will convert the Data array for the GEOS-1 model (using
; the molecular weight for NOx) from kg/s to molecules/cm2/s.
MODIFICATION HISTORY:
bmy, 07 Apr 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/math_units/convert_kg_molcm2.pro)
NAME:
CONVERT_LON
PURPOSE:
Convert longitudes from -180..180 to 0..360
or vice versa.
CATEGORY:
General
CALLING SEQUENCE:
CONVERT_LON, DATA, NAMES, [, KEywords ]
INPUTS:
DATA -> A data array (lines,vars) or vector containing
longitude data. If DATA is a 2D array, the NAMES
parameter must be given to identify the LONgitude variable.
NAMES -> A string list of variable names. The longitude data
must be labeled 'LON', unless specified with the LONNAME
keyword. The NAMES parameter is not needed, if a data
vector is passed.
KEYWORD PARAMETERS:
PACIFIC -> Convert longitudes from -180..180 to 0..360
ATLANTIC -> Convert from 0..360 to -180..180
LONNAME -> Name of the longitude variable if a name other
than 'LON' is used.
OUTPUTS:
The longitude column in the data array will be changed.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
LONDAT = [ -180.,-179.,-0.1,0.1,179.,180.,270.,359.]
CONVERT_LON, LONDAT, /PACIFIC
PRINT, LONDAT
180.000 181.000 359.900 0.100000
179.000 180.000 270.000 359.000
; Convert longitudes to 0..360
(2)
CONVERT_LON,londat,/Atlantic
PRINT, LONDAT
180.000 -179.000 -0.100006 0.100000
179.000 180.000 -90.0000 -1.00000
; Convert back to -180..180
MODIFICATION HISTORY:
mgs, 25 Aug 1998: VERSION 1.00
mgs, 19 May 1999: - now makes sure that longitude range does
not exceed -180..180 or 0..360
mgs, 24 Jun 1999: - bug fix: choked at missing values
bmy, 24 May 2007: TOOLS VERSION 2.06
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
phs, 19 Nov 2007: GAMAP VERSION 2.11
- now accept scalar
(See /san/home/ctm/bmy/IDL/gamap2/general/convert_lon.pro)
NAME:
CONVERT_MOLCM2_KG
PURPOSE:
Converts the units of a 2-D or 3-D array from molecules/cm2
to kg (or, equivalently, from molecules/cm2/s to kg/s).
CATEGORY:
Math & Units
CALLING SEQUENCE:
CONVERT_MOLCM2_KG, DATA, AREACM2, KGPERMOLE
INPUTS:
DATA -> 2-D or 3-D array of data values in units of
molecules cm^-2 or molecules cm^-2 s^-1.
AREACM2 -> 2-D array containing the surface area of each
gridbox in cm^2
KGPERMOLE -> The molecular weight of the tracer or
molecule, in units of kg/mole.
OUTPUTS:
DATA -> The converted array in kg/s is returned in DATA.
DATA is returned with the same dimensions as
it had when it was passed to CONVERT_MOLCM2_KG.
KEYWORD PARAMETERS:
None
SUBROUTINES:
None
REQUIREMENTS:
CTM_SURFACE_AREA must be called to compute the AREACM2 array.
TRACER_KG_PER_MOLE (or a similar subroutine) must be called
to compute the KGPERMOLE array.
NOTES:
EXAMPLE:
AreaCm2 = CTM_SURFACE_AREA( GridInfo, /cm2, /GEOS )
KgPerMole = TRACER_KG_PER_MOLE( /FULLCHEM )
TracerNumber = 1 ; for NOx
CONVERT_MOLCM2_KG, Data, AreaCm2, KgPerMole
Will convert the Data array for the GEOS-1 model (using
the molecular weight for NOx) from molecules/cm2/s to kg/s.
MODIFICATION HISTORY:
bmy, 07 Apr 1998: VERSION 1.00
bmy, 09 Apr 1998: VERSION 1.01
- DATA can now be a 2-D or 3-D array.
- KgPerMole can now be an array of the same
dimension as the 3rd dimension of Data.
bmy, 07 Oct 1998: VERSION 1.02
- now uses MESSAGE statement
- also uses [] instead of () for array
indices
bmy 23 Nov 1998: VERSION 2.00
- now uses double precision array NEWDATA
to avoid overflow/underflow errors
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/math_units/convert_molcm2_kg.pro)
NAME:
CONVERT_O3PL
PURPOSE:
Converts single-tracer Ox rate files from their native
binary format to binary punch format
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
CONVERT_O3PL [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INMODELNAME -> A string containing the name of the model
grid on which the input data resides. Default is GEOS_STRAT.
INRESOLUTION -> Specifies the resolution of the model grid
on which the input data resides. RESOLUTION can be
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 is 2.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
CTM_TYPE (function)
CTM_GRID (function)
CTM_MAKE_DATAINFO (function)
REQUIREMENTS:
None
NOTES:
Input file names are hardwired for now.
EXAMPLE:
CONVERT_O3PL, INMODELNAME ='GEOS1', $
INRESOLUTION = 4, $
; Regrids P(O3) and L(O3) data from
; GEOS-1 4 x 5 grid to GISS-II-PRIME 4 x 5 grid.
MODIFICATION HISTORY:
bmy, 16 Jul 2002: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read input file as big-endian
(See /san/home/ctm/bmy/IDL/gamap2/file_io/convert_o3pl.pro)
NAME:
CONVERT_UNIT
PURPOSE:
Convert data to a different unit. You can either
replace a unit by the corresponding standard SI unit or
replace a specific unit with another one.
CATEGORY:
Math & Units
CALLING SEQUENCE:
CONVERT_UNIT,DATA,UNIT,TOPARAM [,keywords]
INPUTS:
DATA -> A data vector, array, or a single value that shall
be converted to a new unit.
UNIT -> A string variable containing the (current) unit of
DATA. This will be replaced by the new unit afterwards.
If omitted, you must give the FROM_UNIT keyword to indicate
the current unit of DATA.
TOPARAM -> The unit to convert DATA to. This is equivalent to
the keyword TO_UNIT and overwrites it.
KEYWORD PARAMETERS:
FROM_UNIT -> An individual unit to search and replace. If not
given, any unit will be converted to TO_UNIT, as long as
the current unit belongs to the same category.
TO_UNIT -> An individual unit to convert to. If not given, all
unit that are converted (see FROM_UNIT) will be replaced
by the standard SI unit of their category.
For the individual unit and categories see FIND_UNIT
RESULT -> returns 1 if conversion was successful, 0 otherwise
This keyword is mostly for consistency witholder routines.
It is more convenient to test !ERROR_STATE.CODE for being
0.
MINVAL -> minimum valid data value. Only data above this
value will be converted (default: -1.E30)
QUIET -> In case of an error, an error message is displayed,
and the !ERROR_STATUS system variable is set to reflect the
error condition (program execution continues). Set the
QUIET keyword to suppress the error message.
OUTPUTS:
DATA will be converted and unit will contain new names.
SUBROUTINES:
Uses FIND_UNIT
REQUIREMENTS:
None
NOTES:
CONVERT_UNIT wil return the value and unit unchanged if
the unit was not found in the standard list (see FIND_UNIT)
or the category of the target unit does not match the
category of the source unit. In these cases, !ERROR_STATE.CODE
will be set to signal an error condition.
EXAMPLE:
; create some data
data = findgen(100)
unit = 'cm'
; convert all data to SI unit of same category (m)
convert_unit,data,unit
; test success
if (!ERROR_STATE.CODE ne 0) then stop
; convert temperature in Fahrenheit to 'deg C'
; (multiple calls to capture all different spellings)
; Data will only be changed if unit is indeed Fahrenheit
convert_unit,data,unit,from='F',to='deg C'
convert_unit,data,unit,from='degF',to='deg C'
convert_unit,data,unit,from='deg F',to='deg C'
; (easier way) convert any temperature to 'C'
; This will also convert 'K' !
; Don't display error message
convert_unit,data,unit,to='C',/QUIET
; convert 'mph' data to SI ('m/s')
convert_unit,data,unit,from='mph'
; explicitely convert 'cm' to 'm'
convert_unit,data,'cm','m'
; equivalent to
convert_unit,data,from='cm',to='m'
MODIFICATION HISTORY:
mgs, 26 Aug 1998: VERSION 1.00
mgs, 27 Aug 1998:
- added RESULT and QUIET keywords
- improved error handling
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/math_units/convert_unit.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 /san/home/ctm/bmy/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
(See /san/home/ctm/bmy/IDL/gamap2/internals/create3dhstru.pro)
NAME:
CREATE_NESTED
PURPOSE:
Reads data from a file and trims it down horizontally to a
"nested" CTM grid size. Vertical resolution is not affected.
CATEGORY:
Regridding
CALLING SEQUENCE:
CREATE_NESTED [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the input file containing data to be
trimmed down to "nested" model grid resolution. If
omitted, a dialog box will prompt the user to supply
a filename.
OUTFILENAME -> Name of the file that will contain trimmed
data on the "nested" model grid. OUTFILENAME will be
in binary punch resolution. If omitted, a dialog box
will prompt the user to supply a filename.
XRANGE -> A 2-element vector containing the minimum and
maximum box center longitudes which define the nested
model grid. Default is [-180,180].
YRANGE -> A 2-element vector containing the minimum and
maximum box center latitudes which define the nested
model grid. Default is [-180,180].
/CHINA -> Set this switch to create nested-grid met data
files for the CHINA region. Setting this switch will
override the XRANGE and YRANGE keywords.
/NAMER -> Set this switch to create nested-grid met data
files for the NORTH AMERICA region. Setting this switch
will override the XRANGE and YRANGE keywords.
/EUROPE -> Set this switch to create nested-grid met data
files for the EUROPE region. Setting this switch will
override the XRANGE and YRANGE keywords.
### NOTE: Need to define the region as of 10/4/07 ###
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
================================================
CN_GETRANGES
External Subroutines Required:
================================================
CTM_CLEANUP CTM_GET_DATA
CTM_WRITEBPCH CTM_MAKE_DATAINFO (function)
GETMODELANDGRIDINFO
REQUIREMENTS:
None
NOTES:
(1) Works for the following types of data blocks:
(a) 2-D "zonal-mean" (latitude-altitude)
(b) 2-D "horizontal" (longitude-latitude)
(c) 3-D "global" (longitude-latitude-altitude)
EXAMPLE:
(1)
CREATE_NESTED, INFILENAME='global_grid.bpch', $
OUTFILENAME='nested_grid.bpch, $
XRANGE=[ -150, -30 ], $
YRANGE=[ 10, 70 ]
; Trims data from "global_grid.bpch" to a nested grid
; from 150W to 30W and 10N to 70N (in this example,
; this covers the US and parts of Canada and Mexico).
(2)
CREATE_NESTED, INFILENAME='global_grid.bpch', $
OUTFILENAME='nested_grid.bpch, /CHINA
; Trims data from "global_grid.bpch" to a nested grid
; for the default China nested grid (70-150E and 11S
; to 55 N). The /CHINA keyword is a convenience to the
; user. It will set XRANGE and YRANGE automatically for
; the China nested grid.
MODIFICATION HISTORY:
bmy, 10 Jan 2003: VERSION 1.00
bmy, 25 Sep 2003: VERSION 1.01
- now call PTR_FREE to free pointer heap memory
bmy, 16 Dec 2003: - now add THISFILEINFO in call to CTM_WRITEBPCH
bmy & phs, 04 Oct 2007: GAMAP VERSION 2.10
- Added /CHINA, /NAMER, /EUROPE keywords
which may be specified instead of XRANGE
and YRANGE. This is a user convenience.
phs, 28 Jan 2008: - Bug fix if model name is 'GEOS3_30L'
- Free pointers not referenced at exist.
(See /san/home/ctm/bmy/IDL/gamap2/regridding/create_nested.pro)
NAME:
CREATE_NESTED_ASCII
PURPOSE:
Reads data from an ASCII file and trims it to nested-grid
resolution. Also renumbers I and J from "global" to "window"
coordinates. Vertical and temporal resolution are not affected.
CATEGORY:
Regridding
CALLING SEQUENCE:
CREATE_NESTED_ASCII [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INMODELNAME -> A string containing the name of the model
grid on which the input data resides. Default is 'GEOS3'.
INRESOLUTION -> Specifies the resolution of the model grid
on which the input data resides. INRESOLUTION
can be 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 is 1.
INFILENAME -> Name of the input file containing data to be
trimmed down to "nested" model grid resolution. If
omitted, a dialog box will prompt the user to supply
a filename.
OUTFILENAME -> Name of the file that will contain trimmed
data on the "nested" model grid. OUTFILENAME will be
in binary punch resolution. If omitted, a dialog box
will prompt the user to supply a filename.
XRANGE -> A 2-element vector containing the minimum and
maximum box center longitudes which define the nested
model grid. Default is [-180,180].
YRANGE -> A 2-element vector containing the minimum and
maximum box center latitudes which define the nested
model grid. Default is [-180,180].
HEADER -> Number of header lines to skip over.
FORMAT -> String describing the input file format.
Default is '(2i3,a)', i.e., two 3-digit integers
and then an unspecified length character line.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================================
CTM_TYPE (function) CTM_GRID (function)
OPEN_FILE
REQUIREMENTS:
None
NOTES:
(1) Assumes I and J (the lon & lat grid box indices)
are the first two items on each line.
(2) Assumes that the nested-grid does not wrap around
the date line.
EXAMPLE:
CREATE_NESTED_ASCII, INFILENAME='fert_scale.dat.1x1', $
OUTFILENAME='fert_scale.dat, $
XRANGE=[ -140, -40 ], $
YRANGE=[ 10, 60 ], $
FORMAT='(2i6,a)
; Trims data from "fert_scale.dat.1x1" to a GEOS-3
; 1x1 (default values) nested grid from 14OW to 4OW
; and 10N to 60N (in this example, this covers the US
; and parts of Canada and Mexico).
MODIFICATION HISTORY:
bmy, 10 Apr 2003: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/regridding/create_nested_ascii.pro)
NAME:
CREATE_NESTED_MET
PURPOSE:
Reads GEOS-Chem binary met data files at global resolution
and creates new files that have been "cut down" to a
particular nested-grid region (e.g. China, North America,
Europe). Vertical resolution is not affected.
CATEGORY:
Regridding
CALLING SEQUENCE:
CREATE_NESTED_MET [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the input file containing data to be
trimmed down to "nested" model grid resolution. If
omitted, a dialog box will prompt the user to supply
a filename.
OUTFILENAME -> Name of the file that will contain trimmed
data on the "nested" model grid. OUTFILENAME will be
in binary punch resolution. If omitted, a dialog box
will prompt the user to supply a filename.
/CHINA -> Set this switch to create nested-grid met data
files for the CHINA region.
/NAMER -> Set this switch to create nested-grid met data
files for the NORTH AMERICA region.
/EUROPE -> Set this switch to create nested-grid met data
files for the EUROPE region.
### NOTE: Need to define the region as of 10/4/07 ###
/VERBOSE -> Set this switch to print extra informational
messages to the screen.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
================================================
CNM_GETGRID CNM_GETCORNERS
External Subroutines Required:
================================================
CTM_INDEX
CTM_TYPE (function) CTM_GRID (function)
REQUIREMENTS:
None
NOTES:
(1) Works for the following types of data blocks:
(a) 2-D "horizontal" (longitude-latitude)
(b) 3-D "global" (longitude-latitude-altitude)
EXAMPLE:
CREATE_NESTED_MET, INFILENAME='20021031.i6.1x1', $
OUTFILENAME='20021031.i6.1x1.USA', $
/NAMER
; Trims DAO met data from "20021031.i6.1x1" to a nested
; grid from 150W to 30W and 10N to 70N (in this example,
; this covers the US and parts of Canada and Mexico).
MODIFICATION HISTORY:
bmy, 18 Jan 2003: VERSION 1.00
- adapted from "create_nested.pro"
bmy, 25 Sep 2003: VERSION 1.01
- also added GEOS-4 met fields
bmy & phs, 24 Sep 2007: GAMAP VERSION 2.10
- Rewritten for compatibility with
GAMAP internal routine CTM_READ_GMAO
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Make sure we create big-endian binary files
(See /san/home/ctm/bmy/IDL/gamap2/regridding/create_nested_met.pro)
NAME:
CREATE_TAGOX_RESTART
PURPOSE:
Creates an initial tagged-Ox restart file w/ 13 tracers
(i.e. corresponding to Arlene Fiore's original runs)
CATEGORY:
File & I/O
CALLING SEQUENCE:
CREATE_TAGOX_RESTART
INPUTS:
None
KEYWORD PARAMETERS:
FILENAME -> Name of full-chemistry restart file containing Ox
data (stored under tracer #2) to be used in creating a
Tagged Ox restart file.
OUTFILENAME -> Name of the Tagged Ox restart file that will
be created. Default is "restart.Ox".
/ZERO_STRAT -> Set this
OUTPUTS:
None
SUBROUTINES:
External subroutines required:
==============================
CTM_GRID (function)
CTM_MAKE_DATAINFO (function)
CTM_WRITEBPCH
REQUIREMENTS:
None
NOTES:
Assumes Ox tracers have an offset of 40.
EXAMPLE:
CREATE_TAGOX_RESTART, FILENAME='gctm.trc.20010701', $
OUTFILENAME="gctm.trc.20010701.Ox'
; Reads Ox from a full chemistry restart file and
; creates a tagged-Ox restart file for initial spinup.
MODIFICATION HISTORY:
bmy, 18 Aug 2003: VERSION 1.01
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/file_io/create_tagox_restart.pro)
NAME:
CREATE_USA_MASK
PURPOSE:
This program defines a mask over the USA. All grid boxes
that are totally contained w/ in the continental US are
set equal to 1, with zeroes everywhere else. Boxes that
the USA shares w/ another country are set to zero.
CATEGORY:
Regridding
CALLING SEQUENCE:
CREATE_USA_MASK [, Keywords ]
INPUTS:
KEYWORD PARAMETERS:
OUTMODELNAME -> Name of the CTM model grid on which the
mask is to be created. Default is "GEOS_4". NOTE:
since the mask is only a 2-D quantity, all vertical
layer information will be ignored.
OUTRESOLUTION -> Resolution of the CTM model grid on
which the mask is to be created. Default is 2.
OUTFILENAME -> Name of the output file (BPCH format) which
will contain the USA mask data. Default is
"usa_mask.geos.{RESOLUTION}"
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=====================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_MAKE_DATAINFO (function) CTM_RESEXT (function)
CTM_WRITEBPCH
REQUIREMENTS:
None
NOTES:
May not yet work for 4x5.
EXAMPLE:
CREATE_USA_MASK, OUTMODELNAME="GEOS4", $
OUTRESOLUTION=4, $
OUTFILENAME='usa_mask.geos.4x5'
; Creates a USA mask for the GEOS-4 4x5 grid and
; saves it to a bpch file named "us_mask.geos.4x5"
MODIFICATION HISTORY:
rch & bmy, 22 Jun 2004: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/regridding/create_usa_mask.pro)
NAME:
CTM_BOXSIZE (function)
PURPOSE:
Computes the size of CTM grid boxes.
CATEGORY
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
result = CTM_BOXSIZE( GRIDINFO [,RADIUS [,KEYWORDS] ] )
INPUTS:
GRIDINFO -> the structure returned by function CTM_GRID,
which contains the following necessary fields:
IMX (int ) -> Maximum I (longitude) dimension
JMX (int ) -> Maximum J (latitude ) dimension
YMID (fltarr) -> Array of latitude centers
RADIUS -> The radius of the earth in km. This may be
passed as an input parameter, or can be specified via
the GEOS_RADIUS, GISS_RADIUS, or FSU_RADIUS keywords.
As default, the GEOS value of 6375.0 km is used.
OUTPUT:
CTM_BOXSIZE returns a 2-D (or 1D) array of CTM surface areas,
or a 3-D array for CTM grid box volumes. The default unit
is square kilometers or cubic kilometers.
KEYWORD PARAMETERS:
/CM2 -> Return ctm surface areas in square centimeters.
[default: km^2].
/M2 -> Return ctm_surface areas in square meters.
[default: km^2].
/CM3 -> Return grid box volumes in cubic centimeters.
[default: km^3].
/M3 -> Return grid box volumes in cubic meters.
[default: km^3].
/VOLUME -> Will cause CTM_BOXSIZE to return grid box volumes
instead of grid box surface areas.
GEOS_RADIUS -> selects GEOS value for earth radius (6375.0 km)
[default]
GISS_RADIUS -> selects GISS value for earth radius (6371.4 km)
FSU_RADIUS -> selects FSU value for earth radius (6371.4 km)
IJ, IL, JL -> determine which area shall be computed [default: IJ]
NOTE: IL computes area of southern boundary
XLEN, YLEN, ZLEN -> Returns length of linear segments
(lat, lon, alt) to calling program. If /CM2 or /CM3 is
specified, then XLEN, YLEN, ZLEN will be in centimeters.
If /M2 or /M3 are specified, then XLEN, YLEN, ZLEN will
be in meters. (Default unit is km).
NO_2D -> return 1D vector instead of 2D array
LATIND -> for IL and JL: return result for given latitude index
[default is equator]. This implies NO_2D. The index must
be provided as FORTRAN index (e.g. 1..72).
SUBROUTINES:
External Subroutines Required:
===============================
CHKSTRU (function) USAGE
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
; (1) Compute surface grid box areas for GISS II model in
; standard resolution (4x5):
Areakm2 = CTM_BOXSIZE( CTM_GRID( CTM_TYPE( 'GISS_II' ), /GISS )
; (2) Compute ctm surface areas in cm2 for GEOS 4x5 grid, return
; a vector with 1 value per latitude :
ModelInfo = CTM_TYPE( 'GEOS1', res=4 )
GridInfo = CTM_GRID( ModelInfo )
AreaCm2 = CTM_BOXSIZE( GridInfo, /GEOS, /cm, /NO_2D )
; (3) Compute ctm grid box volumes in cm3 for GEOS 4x5 grid,
; and return a 3-D array
ModelInfo = CTM_TYPE( 'GEOS1', res=4 )
GridInfo = CTM_GRID( ModelInfo )
VolumeCm3 = CTM_BOXSIZE( GridInfo, /GEOS, /Volume, /cm3 )
MODIFICATION HISTORY:
bmy, 27 Mar 1998: VERSION 1.00 (algorithm from mgs)
mgs, 27 Mar 1998: - added NO_2D keyword
mgs, 07 May 1998: VERSION 1.10
- added IJ, IL, JL, LATIND, XLEN,
YLEN, and ZLEN keywords
- corrected polar box sizes
(now uses gridinfo information)
mgs, 08 May 1998: - corrected latindex, now uses FORTRAN convention
mgs, 24 May 1998: - changed IL so it computes area of
southern boundary
mgs, 17 Nov 1998: - changed keywords GISS and GEOS to .._RADIUS
bmy, 27 Jul 1999: VERSION 1.42
- updated comments
bmy, 27 Jan 2000: VERSION 1.45
- added /CM and /M keywords,
deprecated /CM2 and /M2 keywords.
- now return a 3-D array for grid box volumes
- updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now call USAGE to display doc header
if wrong # of arguments are passed.
- Deleted internal routine USE_CTM_BOXSIZE
(See /san/home/ctm/bmy/IDL/gamap2/gamap_util/ctm_boxsize.pro)
NAME:
CTM_CLEANUP
PURPOSE:
Free memory blocked by excessive use of the GAMAP package.
With the /DATA_ONLY option, only the data blocks themselves
are freed, all header information remains accessible.
This speeds up any further analysis. Also calls HEAP_GC
to do garbage collection on unused heap variables.
CATEGORY:
GAMAP Utilities
CALLING SEQUENCE:
CTM_CLEANUP [, /DATA_ONLY, /NO_GC, /NO_FILE_CLOSE ]
INPUTS:
none
KEYWORD PARAMETERS:
/DATA_ONLY -> Only free heap variables that point to the
actual data records. Leave all 'info' intact. Default
is to remove everything includign the global DATAINFO
and FILEINFO structure arrays. NOTE: Setting this switch
will not perform garbage collection via routine HEAP_GC.
/NO_GC -> Set this switch to suppress garbage collection of
heap variables with HEAP_GC.
/NO_FILE_CLOSE -> Set this switch to suppress closing of
all open files.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
CTM_CLEANUP
MODIFICATION HISTORY:
mgs, 05 Oct 1998: VERSION 1.00
mgs, 08 Oct 1998: - fixed DATA_ONLY part so that status is
reset to zero and derived data records
are removed
bmy, 21 Nov 2000: - Updated comments
bmy, 04 Oct 2004: GAMAP VERSION 2.03
- added /NO_GC keyword
- now call HEAP_GC to do garbage collection
of heap variables & pointers
bmy, 23 Mar 2007: GAMAP VERSION 2.06
- Now add /NO_FILE_CLOSE keyword so as not
to close open files
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- close only files opened with GAMAP
(See /san/home/ctm/bmy/IDL/gamap2/gamap_util/ctm_cleanup.pro)
NAME:
CTM_COLUMN_DU
PURPOSE:
Calculates columns in Dobson Units for a given tracer.
CATEGORY:
GAMAP Utilities
CALLING SEQUENCE:
RESULT = CTM_COLUMN_DU( DiagN, [ Keywords ] )
INPUTS:
DIAGN -> Diagnostic category name (or number) containing the
tracer data for which columns will be computed. The
default is 'IJ-AVG-$' (i.e. v/v mixing ratios).
KEYWORD PARAMETERS:
FILENAME -> (OPTIONAL) File containing CTM data for which
to compute columns. If omitted, then the user will
be prompted to select a file via a dialog box.
TAU0 -> Starting TAU value of the desired data block (will
be passed to CTM_GET_DATABLOCK). If omitted, then
CTM_COLUMN_DU will read data for the first time in
the data file.
TRACER -> Number of tracer for which to compute columns.
PFILENAME -> Name of the file containing surface pressure
data (this is necessary in order to compute column
sums). If PFILENAME is omitted, then CTM_COLUMN_DU
will look for surface pressure data in FILENAME.
PTAU0 -> TAU0 value by which surface pressure data in
PFILENAME is indexed. If PTAU0 is omitted, then
CTM_COLUMN_DU will use TAU0.
PTRACER -> Tracer number for the surface pressure data.
Default is 1. (For some GISS-CTM punch files, surface
pressure is saved as tracer #0).
TROPFILENAME -> Name of the file containing the annual mean
tropopause data for the GEOS-Chem model. If TROPFILENAME
is supplied, then columns will be computed from the
surface up to the annual mean tropopause height.
Otherwise, columns will be computed for the full
vertical extent of the data.
/DOUBLE -> If set, will return column sums as double
precision. Otherwise, will return column sums as
single precision.
MODELINFO -> Returns to the calling program the MODELINFO
structure (i.e. output from CTM_TYPE) corresponding to
the data.
GRIDINFO -> Returns to the calling program the GRIDINFO
structure (i.e. output from CTM_GRID) corresponding
to the data.
XMID -> Returns to the calling program the longitude centers
in degrees for the extracted data block.
YMID -> Returns to the calling program the latitude centers
in degrees for the extracted data block.
ZMID -> Returns to the calling program the altitude centers
in # of levels for the extracted data block.
_EXTRA=e -> Picks up any extra keywords.
OUTPUTS:
RESULT -> a 2-D array containing the columns for TRACER
in Dobson Units (DU). 1 DU = 2.69e16 molec/cm2.
SUBROUTINES:
Internal Subroutines:
=============================================================
CCD_GetAirMass (function) CCD_Consistency_Check (function)
External Subroutines Required:
=============================================================
CHKSTRU (function) CTM_BOXSIZE (function)
CTM_EXTRACT (function) CTM_GET_DATABLOCK (function)
EXTRACT_FILENAME (function)
REQUIREMENTS:
References routines in both GAMAP and TOOLS packages.
NOTES:
(1) An internal consistency check is now done to make sure
the tracer data block is of the same model and resolution
as the surface pressure and annual mean tropopause data blocks.
EXAMPLE:
Result = CTM_COLUMN_DU( 'IJ-AVG-$', $
FileName='ctm.bpch' $
Tracer=20, $
Tau0=80304.0 )
; Returns O3 columns in DU from the file "ctm.bpch",
; for March 1994 (TAU0 = 80304 for GEOS date 3/1/1994).
MODIFICATION HISTORY:
bmy, 26 Jul 1999: VERSION 1.00
bmy, 20 Apr 2000: GAMAP VERSION 1.45
- renamed from "rvm_o3col"
- removed hardwiring, added comments
- added internal subroutine "CCD_Consistency_Check
- now can sum up to the annual mean tropopause
for GEOS model data blocks
bmy, 30 Jul 2001: GAMAP VERSION 1.48
- bug fix: make sure to extract the same
lat/lon region for PS, tropopause heights
as we do for tracers
- added XMID, YMID, ZMID keywords to return
XMID, YMID, ZMID arrays from CTM_GET_DATABLOCK
to the calling program
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Rewritten for hybrid grids, and to compute
DU for a data block of less than global size
(See /san/home/ctm/bmy/IDL/gamap2/gamap_util/ctm_column_du.pro)
NAME:
CTM_CONVERT_UNIT
PURPOSE:
Wrapper program for CONVERT_UNIT.PRO
CATEGORY:
GAMAP Utilities
CALLING SEQUENCE:
CTM_CONVERT_UNIT, Data [,Keywords]
INPUTS:
DATA -> The data array (or value) on which to perform
the unit conversion. DATA will be converted.
KEYWORD PARAMETERS:
CNUM -> For hydrocarbons, CNUM is the following
ratio: ( moles C / moles hydrocarbon ).
CNUM is needed to convert from ppbC to ppbv.
Keyword Parameters Passed to CONVERT_UNIT:
==========================================
FROM_UNIT -> An individual unit to search and replace.
If not given, any unit will be converted to TO_UNIT,
as long as the current unit belongs to
the same category.
TO_UNIT -> An individual unit to convert to. If not given,
all units that are converted (see FROM_UNIT) will be
replaced by the standard SI unit of their category.
For the individual unit and categories see FIND_UNIT
_EXTRA=e -> Picks up any extra keywords for CTM_CONVERT_UNIT.
OUTPUTS:
RESULT -> Returns 1 if conversion was successful, 0 otherwise.
SUBROUTINES:
External Subroutines Required:
===============================
CONVERT_UNIT
CONVERT_MOLCM2_KG (function)
CONVERT_KG_MOLCM2 (function)
REQUIREMENTS:
None
NOTES:
Will first convert ppbC to ppbv
EXAMPLE:
CTM_CONVERT_UNIT, Data, From='ppbC', To='ppbv', $
CNum=5, Result=Result
; converts Isoprene (5 mole C / 1 mole ISOP ) from
; parts per billion of Carbon (ppbC) to parts per
; parts per billion by volume of ISOP (ppbv).
; RESULT = 1 if unit conversion was successful.
MODIFICATION HISTORY:
bmy, 29 Sep 1998: VERSION 1.00
bmy, 07 Oct 1998: VERSION 1.01
- Added unit conversion for mol/cm2 -> kg etc..
mgs, 11 Nov 1998: - bug fix if seconds not passed
bmy, 21 Jun 2002: GAMAP VERSION 1.51
- now recognize string "molec/cm2/s"
- updated comments, cosmetic changes
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/gamap_util/ctm_convert_unit.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 /san/home/ctm/bmy/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 /san/home/ctm/bmy/IDL/gamap2/gamap_util/ctm_diaginfo.pro)
NAME:
CTM_DIFF
PURPOSE:
Computes absolute or relative differences between two CTM
data blocks, and creates a new entry in the global DATAINFO
structure.
CATEGORY:
GAMAP Utilities
CALLING SEQUENCE:
CTM_DIFF, DIAGN, [, Keywords ]
INPUTS:
DIAGN -> A diagnostic number or category name (see
(CTM_DIAGINFO). A value of 0 (or an empty string)
prompts processing of all available diagnostics.
DIAGN can also be an array of diagnostic numbers or
category names.
KEYWORD PARAMETERS:
FILE -> File name or list of file names containing the data
blocks to be differenced.
ILUN -> Logical unit number, or list of logical unit numbers
of the files that contain the data blocks to be differenced.
TAU0 -> A time value or list of values to restrict the search.
Default handling as with ILUN or TRACER. TAU0 superseeds
/FIRST, /LAST or TAURANGE.
TRACER -> Tracer ID number, or list of tracer ID numbers.
CTM_DIFF will difference the data blocks for diagnostic
DIAGN and tracer TRACER.
/PERCENT -> If set, will compute the percent difference
between two data blocks as 100 * ( DATA2 - DATA1 ) / DATA1.
Default is to compute the absolute difference DATA2 - DATA1.
NEWTRACER -> Returns to the calling program the tracer values
for the data blocks, as read in from disk.
NEWTAU -> Returns to the calling program the TAU0 values for
the data blocks, as read in from disk.
RANGE -> Returns the min & max difference values to the
calling program.
OUTPUTS:
CTM_DIFF will append an entry to the global DATAINFO array of
structures pertaining to the difference between the data blocks.
SUBROUTINES:
External Subroutines Requrired:
=========================================================
CTM_GET_DATA CTM_MAKE_DATAINFO (function)
CTM_GRID (function) GAMAP_CMN (include file)
INV_INDEX (function) YESNO (function)
CTM_DIAGINFO
REQUIREMENTS:
References routines from GAMAP and TOOLS packages.
Also, currently will only look at data blocks with the same
tracer, since differencing two different tracers is not
always that productive.
NOTES:
(1) If DATA1 corresponds to the "old" data, and DATA2
corresponds to the "new" data, then CTM_DIFF will
compute the following:
Abs. Diff = ( new - old )
% Diff = ( new - old ) / old
(2) The DATAINFO entries created by CTM_DIFF can be read into
GAMAP with the /NOFILE option. The ILUN values of these
data blocks will be negative, indicating derived data.
(3) The call to CTM_REGRID probably does not work yet.
Will get around to fixing that later...
EXAMPLE:
(1) Call CTM_DIFF to compute an absolute difference between
two data blocks from two different punch files, at the
same TAU0 value, for OH (DIAGN='CHEM-L=$', TRACER=1).
FILE = [ 'ctm.bpch.v4-30', 'ctm.bpch.v4-31' ]
CTM_DIFF, 'CHEM-L=$', FILE=FILE, TRACER=1
(2) Call CTM_DIFF to compute a relative difference between
two data blocks from the same punch file, at two
different TAU0 values, for tracer 1 (Radon).
ILUN = 20
TAU0 = [ 74472L, 74640L ]
CTM_DIFF, 'IJ-AVG-$', ILUN=ILUN, TAU0=TAU0, $
TRACER=1, /Percent
MODIFICATION HISTORY:
bmy, 23 Apr 1999: VERSION 1.00
mgs, 18 May 1999: - some bug fixes in error checks.
- regridding still not tested !!
mgs, 10 Jun 1999: - bug fix for percent diference (indexing)
bmy, 15 Sep 1999: GAMAP VERSION 1.43
- now use the GRIDINFO structure from the
global FILEINFO structure, if it exists.
- bug fix in call to CTM_GET_DATABLOCK
- updated comments
bmy, 14 Jan 2000: GAMAP VERSION 1.44
- now allow comparision of two different
tracer numbers (e.g. for comparing two
simulations w/ different tracer indices)
- added error checking for size of the
FILE, ILUN, TAU0, TRACER keywords
- deleted obsolete code
bmy, 26 Jan 2000: GAMAP VERSION 1.45
- now allow TAU0, FILE, ILUN, TRACER to have
0 elements w/o generating an error message
bmy, 15 Nov 2001: GAMAP VERSION 1.49
- Now make sure that NEWTRACER is not a
multiple of 100, so that the tracer #
will be saved correctly to the global
DATAINFO structure
bmy, 22 Apr 2002: GAMAP VERSION 1.50
- updated comments
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- Now get spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 29 Jan 2004: - Added LEV keyword so that you can
select just a single level
- If we are just comparing a single level,
then do not test altitude dimensions
of the two data blocks.
bmy, 16 Feb 2005: GAMAP VERSION 2.03
- now pass _EXTRA=e to CTM_GET_DATA
phs, 24 Oct 2006: GAMAP VERSION 2.05
- replace CTM_REGRID with CTM_REGRIDH
- pass _EXTRA=e to CTM_REGRIDH
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- added RANGE keyword for sending min/max
difference values to the calling program
(See /san/home/ctm/bmy/IDL/gamap2/gamap_util/ctm_diff.pro)
NAME:
CTM_DOSELECT_DATA (function)
PURPOSE:
Return indices for data blocks that match specific
criteria. This is an internal routine which is called
by CTM_GET_DATA.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
INDEX = CTM_DOSELECT_DATA( DIAGN, USE_DATAINFO [, keywords ] )
INPUTS:
CATEGORY -> A string or string array with category names
to search for. Multilevel categories can be expanded to
a string array with the EXPAND_CATEGORY function.
Usually, CTM_DOSELECT_DATA should be called with only
one "logical" category at the time, i.e. only for
multilevel diagnostics should it contain more than one
element. Otherwise, the tracer offset may be wrong.
USE_DATAINFO -> A valid DataInfo structure. No error checking
is performed.
Both parameters are mandatory.
KEYWORD PARAMETERS:
ILUN -> A logical unit value or an array of logical unit
values. Only records from corresponding files will be
returned. If ILUN is an undefined variable, information
about all previously opened files will be returned,
and ILUN will contain all logical unit numbers that
match the selection criteria.
TRACER -> A tracer number or an array of tracer numbers to
restrict the selection of data records. Default is to
return information about all tracers.
Tracer numbers less than 100 are automatically expanded
to include the offset of certain diagnostics (see
keyword TRCOFFSET and routine CTM_DIAGINFO). If TRACER is
an undefined variable, all tracers that match the selection
criteria are returned.
TRCOFFSET -> A tracer offset (multiple of 100) that will be
added to TRACER. The search is performed for both,
TRACER and TRACER+TRCOFFSET. (for tracer offsets see
routine CTM_DIAGINFO and file diaginfo.dat)
TAU -> A time value (tau0 !) or an array of time values
to restrict the selection of data records. Default is to
return information about all time steps. If TAU is an
undefined variable, it will return all time steps that
match the selection criteria.
STATUS -> Restricts the data selection to
Data that has not been read (STATUS = 0)
Data that has been read (STATUS = 1)
All data blocks (STATUS = 2, default)
If STATUS is 1, all pointers returned in DATA are tested
for validity. Status will automatically be restricted
to range 0..1
COUNT -> A named variable that will return the number of
data blocks found with the given selection criteria
MISSING -> If no records were found that match the selection
criteria, MISSING will return a string array with the
items that could not be matched (e.g. ['TRACER','ILUN']).
If records were found, MISSING returns an empty string.
SPACING -> Passes to CTM_DOSELECT_DATA the spacing between
diagnostic offsets listed in "diaginfo.dat".
OUTPUTS:
The function returns an (long) integer array that contains
index values to all the data blocks that match the selection
criteria. If no data is found, -1L is returned.
SUBROUTINES:
Uses IS_SELECTED function
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
See CTM_SELECT_DATA and CTM_READ_DATA source codes.
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 07 Oct 1998: - added DEBUG keyword
mgs, 22 Oct 1998: - now filters ilun, tracer, and tau
after finding matching records. This
was necessary to find the correct first
or last time step in CTM_GET_DATA.
Needs some more testing whether there are
side effects when TAU0 and ILUN or TRACER
are specified.
mgs, 09 Nov 1998: - improved documentation
- default status now 2
- uses status field in use_datainfo instead of
ptr_valid function
- ILUN, TRACER and TAU only overwritten
if they are undefined variables
- added MISSING keyword
mgs, 10 Nov 1998: - minor bug fix for status=1
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- added SPACING keyword to pass the
diagnostic spacing from CTM_DIAGINFO
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/internals/ctm_doselect_data.pro)
NAME:
CTM_EXAMPLES
PURPOSE:
Quick and dirty demonstration of various CTM_* routines
CATEGORY:
GAMAP Examples, GAMAP Utilities
CALLING SEQUENCE:
CTM_EXAMPLES
INPUTS:
None
KEYWORD PARAMETERS:
/PNG -> Set this switch to create PNG files from screen
shots of examples generated by this program.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================================
OPEN_DEVICE MULTIPANEL
CTM_GET_DATA GETMODELANDGRIDINFO
TVMAP PAUSE
CTM_PLOT SCREEN2PNG
NYMD2TAU (function) CTM_OVERLAY
REQUIREMENTS:
None
NOTES:
Updated with the most recent GAMAP routines.
EXAMPLE:
CTM_EXAMPLES, /PNG
; Show example plots and create screenshot output
; as PNG files.
MODIFICATION HISTORY:
mgs, 20 Aug 1998: INITIAL VERSION
mgs, 22 Oct 1998: - adapted for new use of CTM_GET_DATA
some more comments
mgs, 26 Oct 1998: - attached a few more comments about extended
use of ctm_get_data at end
mgs, 18 Nov 1998: - added call to CTM_MAKE_DATAINFO
bmy, 06 Oct 2006: GAMAP VERSION 2.05
- Updated examples w/ newest GAMAP routines
- Added examples w/ CTM_OVERLAY and
FIND_CELLS_BY_COUNTRY
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now uses FILE_WHICH to find ctm.bpch.examples
(See /san/home/ctm/bmy/IDL/gamap2/examples/ctm_examples.pro)
NAME:
CTM_EXTRACT (function)
PURPOSE:
Extracts a block of data from a 3-D CTM data cube.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_EXTRACT, DATA, MODELINFO, GRIDINFO [,Keywords]
INPUTS:
DATA -> The data cube from which to extract a region.
DATA must be 3-dimensional (e.g. lon-lat-alt, or
lon-lat-tracer, etc).
KEYWORD PARAMETERS:
MODELINFO -> The MODELINFO structure returned from function
CTM_TYPE.
GRIDINFO -> The GRIDINFO structure returned from function
CTM_GRID.
AVERAGE -> Bit flag indicating the dimensions over which to
average the data:
1 : longitudinal
2 : latitudinal
4 : vertical
These values can be combined. E.g., to average over
longitude and latitude use 3. A bit set in AVERAGE
superseeds the corresponding bit in TOTAL (see below).
TOTAL -> Bit flag indicating the dimensions over which
to sum the data:
1 : longitudinal
2 : latitudinal
4 : vertical
These values can be combined. E.g., to integrate over
longitude and latitude use 3. A bit set in AVERAGE
superseeds the corresponding bit in TOTAL (see above).
/INDEX -> If set, will interpret LAT, LEV, and LON as index
arrays. If not set, will interpret LAT, LEV, and LON as
ranges (i.e. two-element vectors containing min and max values).
LAT -> An index array of latitudes *OR* a two-element vector
specifying the min and max latitudes to be included in
the extracted data block. Default is [ -90, 90 ].
LEV -> An index array of sigma levels *OR* a two-element vector
specifying the min and max sigma levels to be included
in the extracted data block. Default is [ 1, GRIDINFO.LMX ].
LON -> An index array of longitudes *OR* a two-element vector
specifying the min and max longitudes to be included in
the extracted data block. Default is [ -180, 180 ].
ALTRANGE -> A vector specifying the min and max altitude
values (or a scalar specifying a single altitude) to
be included in the extracted data block.
PRANGE -> A vector specifying the min and max pressure levels
(or a scalar specifying a single pressure level) to be
included in the extracted data block.
WE -> Returns to the calling program the index array of longitudes
for the extracted data region, ordered from west to east.
SN -> Returns to the calling program the index array of latitudes
for the extracted data region, ordered from South to North.
UP -> Returns to the calling program the index array of vertical
levels for the extracted data region, ordered from surface
to top.
DIM -> A named variable will return the new dimension information
of the data block after averaging or totaling.
_EXTRA=e -> Picks up extra keywords for CTM_INDEX.
OUTPUTS:
X, Y, Z -> Arrays of latitude, longitude, or altitude values
corresponding to the the 1st, 2nd, and 3rd dimensions of
the DATA array, respectively.
SUBROUTINES:
CTM_INDEX
DEFAULT_RANGE (function)
REQUIREMENTS:
Uses GAMAP package subroutines.
NOTES:
(1) CTM_EXTRACT returns the extracted data region as
the function value.
(2) Assumes a 3-D data cube as input, of dimensions (lon, lat,
alt), or for some diagnostics (lon, lat, "tracer" number).
(3) In the calling program, CTM_TYPE and CTM_GRID must be
called to compute the MODELINFO and GRIDINFO structures,
which can then be passed to CTM_EXTRACT.
(4) If any of the LAT, LON, LEV, ALTRANGE, PRANGE keywords are
explicity specified, then CTM_EXTRACT will return to the
calling program their original, unmodified values. If any
of these are not explicitly specified , then CTM_EXTRACT
will return to the calling program default values.
EXAMPLE:
(1)
MODELINFO = CTM_TYPE( 'GEOS4', RES=4 )
GRIDINFO = CTM_GRID( MODELINFO )
DATAREGION = CTM_EXTRACT( DATACUBE, $
MODELINFO=MODELINFO, $
GRIDINFO=GRIDINFO $
LON=[-180,0], LAT=[-30,30], $
LEV=[1,10] )
; Extracts from a GEOS-4 4x5 data cube a region
; delimited by longitude = [-180, 0],
; latitude = [-30, 30], for levels 1 to 10.
(2)
LON = INDGEN( 36 )
LAT = INDGEN( 16 ) + 15
LEV = INDGEN( 10 )
MODELINFO = CTM_TYPE( 'GEOS4' )
GRIDINFO = CTM_GRID( MODELINFO )
DATAREGION = CTM_EXTRACT( DATACUBE, $
MODELINFO=MODELINFO, $
GRIDINFO=GRIDINFO, $
/INDEX, LON=LON, $
LAT=LAT, LEV=LEV )
; Extracts same data region as in Example (1) but
; here passes explicit index arrays instead of ranges.
MODIFICATION HISTORY:
bmy, 16 Sep 1998: VERSION 1.00
bmy, 17 Sep 1998: - now extracts data from data cube one
dimension at a time to avoid errors
bmy, 18 Sep 1998: VERSION 1.01
- INDEX, SN, WE, UP keywords added
- LATRANGE, LONRANGE, LEVRANGE renamed
to LAT, LON, LEV (since they may now
contain arrays and not just ranges).
mgs, 21 Sep 1998: - some more error checking
- removed MinData and MaxData
bmy and mgs, 22 Sep 1998: VERSION 1.02
- added AVERAGE and TOTAL keywords
bmy, 24 Sep 1998: VERSION 1.03
- Now returns original values of LAT, LON,
LEV, ALTRANGE, and PRANGE if those keywords
are specified. Otherwise returns
defaults.
MGS, 29 SEP 1998: - Introduced new DEFAULT_RANGE function.
bmy, 06 Oct 1998: - fixed bug: now S = size( NEWDATA )
bmy, 08 Oct 1998: VERSION 1.04
- MODELINFO and GRIDINFO are now keywords
- added X, Y, and Z as parameters
bmy, 11 Feb 1999: - updated comments
bmy, 19 Feb 1999: VERSION 1.05
- added FIRST keyword so that the values of
THISDATAINFO.FIRST can be passed from the
calling routine.
- now call ADJ_INDEX to adjust the WE,
SN, and UP index arrays for data blocks
that are less than global size.
- added DEBUG keyword
mgs, 16 Mar 1999: - cosmetic changes
mgs, 02 Apr 1999: - bug fixes that prevented use with 2D fields
(e.g. EPTOMS data)
mgs, 21 May 1999: - now catches error in multitracer diagnostics
when user requests a level beyond LMX.
qli, 26 May 1999: - "max(newlev) ge" corrected to "gt"
bmy, 15 Sep 1999: VERSION 1.43
- removed bugs that caused data blocks to
always have MODELINFO.NTROP vertical
layers
bmy, 04 Dec 2000: GAMAP VERSION 1.47
- add code for future bug fix
bmy, 24 Apr 2001: - bug fix: now can handle longitudes
greater than 180 degrees
bmy, 06 Jun 2001: - bug fix: Test if LON exists before
assigning it to NEWLON.
bmy, 30 Jul 2001: GAMAP VERSION 1.48
- bug fix: now extract proper latitude range
for data blocks smaller than global size
bmy, 26 Jun 2002: GAMAP VERSION 1.51
- Default value of FIRST is now [1,1,1],
since this has to be in Fortran notation.
- also do error checking on FIRST near
the beginning of the program.
bmy, 15 Nov 2002: GAMAP VERSION 1.52
- now can handle total/average for MOPITT grid
bmy, 23 Aug 2004: GAMAP VERSION 2.03
- now can handle single-point data blocks
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 19 Nov 2007: GAMAP VERSION 2.11
- Updated comments
bmy, 10 Dec 2007: GAMAP VERSION 2.12
- Now pad ALTRANGE and PRANGE to 2 elements
if they are passed w/ one element
(See /san/home/ctm/bmy/IDL/gamap2/gamap_util/ctm_extract.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 /san/home/ctm/bmy/IDL/gamap2/internals/ctm_getdefaultstructures.pro)
NAME:
CTM_GETWEIGHT
PURPOSE:
Computes the "mapping weights" for regridding data from
a "fine" CTM grid to a CTM grid of equal or coarser
horizontal resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
CTM_GETWEIGHT, OLDGRID, NEWGRID, WEIGHT, XX_IND, YY_IND [, Keywords ]
INPUTS:
OLDGRID -> GRIDINFO structure (use ctm_grid to create one)
which defines the old ("fine") grid.
NEWGRID -> GRIDINFO structure (use ctm_grid to create one)
which defines the new ("coarse") grid.
KEYWORD PARAMETERS:
WEIGHTFILE (optional) -> Name of the file to which WEIGHT,
XX_IND, and YY_IND will be written. If WEIGHTFILE is
not given, then
OUTPUTS:
WEIGHT -> Array of mapping weights which defines the fraction
of each "fine" grid box that fits into each "coarse"
grid box.
XX_IND -> Array of "longitude" grid box indices of the "fine"
grid boxes that fit into each "coarse" grid box.
YY_IND -> Array of "latitude" grid box indices of the "fine"
grid boxes that fit into each "coarse" grid box.
SUBROUTINES:
External Subroutines Required:
================================
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) This routine was adapted from CTM_REGRID. It is
sometimes computationally expedient to compute the
mapping weights once for the entire horizontal grid
and save them to a file for future use.
(2) Right now this only works in regridding from a "fine"
grid to a grid of equal horiziontal resolution (i.e. with
shifted grid boxes) or coarser horizontal resolution.
EXAMPLE:
OLDTYPE = CTM_TYPE( 'GENERIC', RES=1, HALFPOLAR=0, CENTER180=0 )
OLDGRID = CTM_GRID( OLDTYPE, /NO_VERTICAL )
NEWTYPE = CTM_TYPE( 'GEOS4', RES=4 )
NEWGRID = CTM_GRID( NEWTYPE, /NO_VERTICAL )
CTM_GETWEIGHT, OLDGRID, NEWGRID, WEIGHT, XX_IND, YY_IND, $
WEIGHTFILE = 'weights.1x1.to.geos1.4x5']
; Precomputes the mapping weights for regridding a
; 1 x 1 grid to the GEOS-1 4 x 5 grid, and saves them
; to an ASCII file named "weights.1x1.to.geos1.4x5"
MODIFICATION HISTORY:
bmy, 11 Aug 2000: VERSION 1.01
- adapted from CTM_REGRID
bmy, 21 Jan 2003: VERSION 1.02
- Added fix for GEOS 1 x 1.25 grid
bmy, 04 May 2006: GAMAP VERSION 2.05