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:
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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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.
AUTOSCALELEVELS -> Set this switch to automatically scale
labels (specified by C_LEVELS, LABEL, MAX, or MIN)
by powers of 10. This reduces the length of each tick label
and helps prevent overlapping numbers in the colorbar.
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.
UPOS -> Specifies the position (relative to the size of the
colorbar) where the unit string will be placed. The
default is 1.15. To print the unit string closer to the
end of the colorbar, reduce this value until the desired
appearance is obtained.
/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
cdh, 16 Apr 2013: Fill MinV and MaxV values from C_Levels
(See /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /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:
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
fil}es 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.
lhu, 12 Jan 2012: GAMAP VERSION 2.16
- Better test for small number equality
- Add SEA4CRS nested grid range
mps, 06 Nov 2013: - Remove SEAC4RS nested grid
- Add NAMER grid for GEOS-FP
mps, 28 Oct 2015: - Add NAMER and CHINA grids for MERRA2
(See /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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
bmy, 16 May 2011: GAMAP VERSION 2.16
- Now make all loop indices long integers
(See /n/home09/ryantosca/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.
/DU -> If set, will return column sums in Dobsun units.
Otherwise, will return column sums in molec/cm2. (jaf, 8/19/08)
_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, $
/DU )
; 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
jaf & phs, 18 Aug 2008: GAMAP VERSION 2.13
- added capability to read surface pressure in
GEOS, which stores surface pressure as a 3-D
array called PEDGE-$
- added DU keyword so that default unit is
molec/cm2, and renamed "DU" output to "Column"
(See /n/home09/ryantosca/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 /n/home09/ryantosca/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 /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_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.
/MASK -> If set, the absolute % difference is return, with
data below either thresholds (see pc_thr and diff_thr)
set to a negative value, -99 .They are "masked", and can
be set to a specific color in a plot (see ctm_plotdiff
usage of the same keyword) or set to NaN for future
analysis.
PC_THR, DIFF_THR : the %-Diff and Diff THResholds to mask data if
/MASK is set. Default values are 1% and 1e4.
OUTPUTS:
CTM_DIFF will append an entry to the global DATAINFO array of
structures pertaining to the difference between the data
blocks.
OUTPUT KEYWORD:
OUTLUN -> set this keyword to a variable name that will hold
the LUN associated with the newly computed difference
data.
SUCCESS -> 0 by default, becomes 1 if MASK is set and all
data are below the thresholds that define the MASK.
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
phs, 25 Sep 2009: GAMAP VERSION 2.13
- OUTLUN kwrd returns LUN associated with
computed difference
- /MASK is available to deals with absolute
%-age data and masked data below PC_THR
and/or DIFF_THR
(See /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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
bmy, 13 Aug 2009: GAMAP VERSION 2.13
- Bug fix: now compute DEF_X_RANGE from the
grid edges for computing NEWLON. Now
also works for nested grids.
phs & bmy, 13 Oct 2009: - Bug fix: now account for ranges that
straddle the date line when computing
DEF_X_RANGE
ccc, 21 Oct 2009: - Bug fix when PRange is passed.
bmy, 20 Mar 2017: GAMAP VERSION 2.19
- Now make sure that WE, SN, UP are converted
from Fortran to IDL notation properly
when /INDEX is specified.
(See /n/home09/ryantosca/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 /n/home09/ryantosca/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
WEIGHTFORMAT (optional) -> Specify the format string used to
save the mapping weights to WEIGHTFILE. For high-res grids,
you may need to specify more than the default 2 decimal
precision. Default value is '(3x,12f6.2)'.
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
- Added fix for GENERIC 2.5 x 2.5 grid
bmy, 29 Jun 2006: - Added fix for GEOS 1x1 -> GENERIC 1x1
bmy & phs, 04 Oct 2007: GAMAP VERSION 2.10
- added fix for GENERIC 0.5 x 0.5 grid
- general fix for over-the-dateline cases
bmy, 26 Sep 2008: GAMAP VERSION 2.13
- Add WEIGHTFORMAT keyword to specify more
decimal places of precision if need be
(See /n/home09/ryantosca/IDL/gamap2/regridding/ctm_getweight.pro)
NAME:
CTM_GET_DATA
PURPOSE:
Retrieve specific data records from CTM output files.
Opening files, parsing header information, and loading
of data are handled transparently and can be
controlled by various keywords. The routine returns a
subset of the global DATAINFO structure that matches the
requested category and (optional) tracer and time step(s).
This routine should be called *whenever* you want to
access data and you are not sure that it has been
loaded previously. It provides the general user-interface
for GAMAP (the Global Atmospheric Model output Analysis
Package).
For the future, a widget interface to this routine is
planned.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_GET_DATA, DATAINFO [,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:
FILENAME -> (optional) If FILENAME is a fully qualified file path
the specified file is opened without user interaction.
If filename is empty or contains wildchards (*,?), a
pickfile dialog will be displayed.
If FILENAME is a named variable it will contain the full
file path upon return so that a subsequent call to
CTM_GET_DATA with the same FILENAME argument will not prompt
another file selection dialog.
If the FILENAME keyword is present, CTM_GET_DATA
will restrict it's scope to records from the selected
is file (even if FILENAME contains an empty string, it will
restrict the scope of the search!).
If the file is found in the global FILEINFO structure or
the USE_FILEINFO structure (i.e. it has been opened
previously), then it will not be parsed again; instead the
data records are returned from memory.
The data itself is loaded transparently via
CTM_RETRIEVE_DATA.
ILUN -> An optional value or array of logical unit numbers. If
given, the search is restricted to data from the specified
files. Default is to use all files (unless the FILENAME
keyword is present). If an undefined variable
is passed into ILUN, information about all accessible files
in the global FILEINFO structure (or USE_FILEINFO) is returned.
TRACER -> A tracer ID number or a list of those. If given, the
search is restricted to those tracers. Default is to use all
tracers. If an undefined variable is passed into TRACER,
and one specific diagnostics is requested with DIAGN,
information about all accessible tracers in the global
DATAINFO structure or USE_DATAINFO structure or the
DATAINFO structure associated with a specific file is returned.
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.
TAURANGE -> A 2-element vector containing the first and last tau0
value to look for.
/FIRST, /LAST -> extract first or last time step that is stored for
the selected diagnostics, ilun, and tracer. Only one can be
be active at a time. /LAST superseeds /FIRST.
INDEX -> A named variable that will contain the indices of the
records in USE_DATAINFO that match the selection criteria.
You can test INDEX[0] ge 0 in order to see if CTM_GET_DATA has
been successful although it is now recommended to test for
n_elements(DATAINFO) eq 0.
The INDEX keyword is useful if you want to change the
information contained in the selected DATAINFO structures
globally.
USE_FILEINFO -> (optional) If provided, CTM_GET_DATA will
restrict its search to only the files that are
contained in USE_FILEINFO which must be a FILEINFO
structure array. Default is to use the global information
(see gamap_cmn.pro).
If an undefined named variable is provided in USE_FILEINFO,
it will either contain the global FILEINFO structure array
or the FILEINFO record of the specified file.
USE_FILEINFO must contain entries for all logical unit numbers
that are used in USE_DATAINFO.
USE_DATAINFO -> (optional) Restrict search to records contained
in USE_DATAINFO which must be a DATAINFO structure array.
If an undefined named variable is provided in USE_DATAINFO,
it will either contain the global DATAINFO structure array
or all DATAINFO records of the specified file.
See also USE_FILEINFO.
/INTERNAL_USE -> Set this keyword if you want to prevent a call
to CTM_OPEN_FILE, but instead abort in case of undefined
(global) FILEINFO or DATAINFO structures.
OUTPUTS:
DATAINFO -> An array of DATAINFO records that match the selected
criteria. You can then simply loop over
0..n_elements(DATAINFO)-1 to access all data records and
extract the data as *(DATAINFO[i].data).
DATAINFO will be undefined if no records are found!!
Always test for IF (n_elements(DATAINFO) eq 0) ... !
NOTE: Alternatively you can return the INDEX to the selected
data records in the global (or USE_) datainfo structure array
with the INDEX keyword. This may in some cases eliminate the
need to make a local copy of the selected DATAINFO records.
SUBROUTINES:
pro reopen_all_files,fileinfo
(needed in order to get free unit numbers)
pro make_compound_datainfo,DataInfo,category,ilun,tracer,tau0,tau1
(make compound structure for multilevel or multitracer diagnostics)
pro update_tracer_datainfo,datainfo,traceroffset
(enter tracer information into global datainfo structure)
REQUIREMENTS:
Several ctm_* routines are used
Also uses UNDEFINE (by D. Fanning)
NOTES:
Please test rigorously. In case of read errors, try using CTM_OPEN_FILE
with the /PRINT keyword.
If your model output (ASCII punch file) does not contain the
dimensional information about each data block, it may cause problems
for diagnostics that do not contain 72x46 elements.
It's defintively a good idea to implement this little change *NOW* !
Outline of this procedure:
- get all data records that match selection criteria
- create "compound" datainfo structures for multilevel and
multitracer diagnostics (those hold 3D data blocks)
- read data for all selected compound structures unless only
status information requested
EXAMPLE:
See CTM_EXAMPLES
MODIFICATION HISTORY:
mgs, 20 Aug 1998: VERSION 1.00
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 22 Sep 1998: - changed to accomodate usage of
tracer information
mgs, 22 Oct 1998: - old FILEINFO and DATAINFO parameters now
keywords USE_..., new DATAINFO parameter
returns selected subset of records.
- print statements replaced with message
- DEBUG messages improved
- catch cancelled file open dialog
mgs, 26 Oct 1998: - datainfo now undefined at start
- allows for multiple categories
- ilun, tracer, tau0 keyword variables renamed
as sel_... in order to preserve them
mgs, 04 Nov 1998: - sel_tracer now expanded to include offsets
mgs, 10 Nov 1998: VERSION 3.0
- major update! Program structure much more
straightforward!
mgs, 12 Nov 1998: - bug fixes for simple diagnostics (line 732)
and finding offset tracers (in update_...)
replaced tracer by (tracer mod 100) in 3 places
mgs, 19 Nov 1998: - bug fix with scale factor. Didn't get globally
updated because it was linked to unit. Need a
more generic global update procedure !
mgs, 03 Dec 1998: - yet another bug fix in reopen files: needed
to test for negative ilun before fstat
bmy, 21 Jan 1999: - added outer parentheses to the FORMAT
descriptor (255(I4,1x)) to avoid errors
mgs, 17 Feb 1999: - bug fix for simple diagnostics: needed
to add dummy value to compound array.
mgs, 16 Mar 1999: - catch error in tracerinfo.dat (more than one
tracer with same number)
- error in update_tracer... should have been
fixed. Some more debug output added for
testing.
mgs, 23 mar 1999: - set vertical dimension to -1 for new compound
datainfo records
mgs, 24 May 1999: - updated filetype info
mgs, 02 Jun 1999: - added retall statement after error
message
bmy, 23 Nov 1999: - added /SMALLCHEM keyword for CTM_TRACERINFO
bmy, 27 Sep 2001: GAMAP VERSION 1.49
- Set F77=1 for filetype 4 (DAO met fields)
- Now reference function LITTLE_ENDIAN
- Swap endian in OPEN_FILE if reading data
on a little-endian machine (e.g. PC)
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- now test valid diagnostics using
DIAGSTRU[*].CATEGORY and not DIAGSTRU[*].INDEX
- removed /SMALLCHEM keyword, it's obsolete
- Now recognizes binary files as having
FILETYPE values between 100 and 200
- Removed /SMALLCHEM flag, it's obsolete
- Now uses diagnostic spacing from CTM_DIAGINFO
and pass this to UPDATE_TRACER_DIAGINFO
bmy, 11 Feb 2004: GAMAP VERSION 2.01a
- Internal routine MAKE_COMPOUND_DATAINFO
now passes SPACING from CTM_DIAGINFO
to routine CTM_DOSELECT_DATA
bmy, 27 Oct 2004: GAMAP VERSION 2.03
- added QUIET keyword to suppress printing
information about retrieved tracers
bmy, 06 Feb 2006: GAMAP VERSION 2.04
- Bug fix: use DIALOG_PICKFILE to get file name
before calling CTM_OPEN_FILE. This is necessary
because the tests for certain file types requires
the file name to be known ahead of time.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now passes _EXTRA keyword to
CTM_OPEN_FILE. This allows to read nested
met (GMAO) files by using /NA or /CHINA
bmy & phs, 20 Nov 2007: GAMAP VERSION 2.11
- If FILENAME is not defined, then the value
of the filename selected via dialog box
will be passed back to the calling program.
KNOWN BUGS OR WEAKNESSES:
- handling of USE_DATAINFO and USE_FILEINFO is not carried
through all lower level subroutines, i.e. they may be replaced
by *pGlobal... in some occasions. Since USE_... should always
be a subset of *pGlobal..., no serious errors are expected
from this weakness.
- known bug in update_tracer_datainfo, see comment in routine.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_get_data.pro)
NAME:
CTM_GET_DATABLOCK
PURPOSE:
Extracts a data block from a CTM punch file.
(Wrapper program for CTM_GET_DATA and CTM_EXTRACT.)
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
SUCCESS = CTM_GET_DATABLOCK(DATA [,DIAGN] [,Keywords])
INPUTS:
DIAGN -> A diagnostic number or category name (see
(CTM_DIAGINFO). This must uniquely identify a
specific data type. DIAGN is passed to CTM_GET_DATA
KEYWORD PARAMETERS:
Keywords that are passed to CTM_GET_DATA:
=========================================
FILENAME -> Name of the file to open. FILENAME is passed
to CTM_GET_DATA. CTM_GET_DATA will return
the full path name, which is then returned
to the calling program.
USE_FILEINFO -> (optional) If provided, CTM_GET_DATA will
restrict its search to only the files that are
contained in USE_FILEINFO which must be a FILEINFO
structure array. Default is to use the global information
(see gamap_cmn.pro).
If an undefined named variable is provided in USE_FILEINFO,
it will either contain the global FILEINFO structure array
or the FILEINFO record of the specified file.
USE_FILEINFO and USE_DATAINFO must be consistent, and should
either both be used or omitted. However, it is
possible to provide the global FILEINFO structure
(or nothing) with a local subset of DATAINFO.
USE_DATAINFO -> (optional) Restrict search to records contained
in USE_DATAINFO which must be a DATAINFO structure array.
If an undefined named variable is provided in USE_DATAINFO,
it will either contain the global DATAINFO structure array
or all DATAINFO records of the specified file.
See also USE_FILEINFO.
Keywords that are passed to CTM_EXTRACT:
========================================
AVERAGE -> Bit flag to average over certain dimensions
(see CTM_EXTRACT)
TOTAL -> Bit flag to sum over certain dimensions
(see CTM_EXTRACT)
/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 to be included in the extracted data block.
PRANGE -> A vector specifying the min and max pressure levels
to be included in the extracted data block.
Other keywords:
===============
XMID, YMID, ZMID -> Arrays of values (e.g. latitude,
longitude, or altitude) for the 1st, 2nd, and 3rd
dimensions of the DATA array, respectively.
NOTE: These are *NOT* index arrays.
THISDATAINFO -> Returns the DATAINFO structure for the
selected data block.
MODELINFO -> Returns to the calling program the model information
structure created by CTM_TYPE.
GRIDINFO -> Returns to the calling program the grid information
structure created by CTM_GRID.
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.
PSURF -> Surface pressure to be used for the conversion from
sigma layers to pressure and altitude. For defaults
see function CTM_TYPE.
_EXTRA=e -> Picks up any extra keywords for CTM_GET_DATA
and CTM_EXTRACT.
OUTPUTS:
SUCCESS -> Returns 1 if successful or 0 otherwise.
DATA -> A 2D or 3D data array
SUBROUTINES:
External Subroutines Required:
==============================
CTM_GET_DATA
CTM_GRID (function)
CTM_EXTRACT (function)
REQUIREMENTS:
None
NOTES:
(1) CTM_GET_DATABLOCK returns the extracted data block as the
function value.
(2) CTM_GET_DATABLOCK is meant to be called whenever you need
to extract data from a punch file. If the punch file needs
to be opened, CTM_GET_DATABLOCK will do that automatically
(via CTM_GET_DATA).
EXAMPLE:
FILENAME = '~/amalthea/CTM4/run/ctm.pch'
LAT = [ -90, 90 ]
LON = [ -180, 180 ]
LEV = 1
SUCCESS = CTM_GET_DATABLOCK( DATA, 'IJ-AVG-$', $
XIND=XMID, YIND=YMID, ZIND=ZMID, $
THISDATAINFO=THISDATAINFO, $
TRACER=1, FILENAME=FILENAME, $
GRIDINFO=GRIDINFO, MODELINFO=MODELINFO, $
LEV=LEV, LAT=LAT, $
LON=LON, WE=WE, $
SN=SN, UP=UP )
IF ( NOT SUCCESS ) THEN RETURN, 0
; gets a data block for the IJ-AVG-$ (ND45) diagnostic,
; for the first tracer, at the first timestep, with the
; given latitude, longitude, and sigma level ranges.
; Returns FILEINFO, DATAINFO, THISDATAINFO, WE, SN, UP,
; XMID, YMID, and ZMID to the calling program.
MODIFICATION HISTORY:
bmy, 16 Sep 1998: VERSION 1.00
bmy, 17 Sep 1998: - added FILENAME keyword, so that the file
name can be passed back to the calling
program.
bmy, 18 Sep 1998: VERSION 1.01
- now compatible with CTM_EXTRACT v. 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: VERSION 1.02
- more error checking
- added PSurf keywords
- frees gridinfo pointer before re-assignment
- removed MinData and MaxData
bmy, 22 Sep 1998: - Now pass AVERAGE and TOTAL keywords to
CTM_EXTRACT
mgs, 22 Sep 1998: - added THISDATAINFO keyword
bmy, 24 Sep 1998: - added FORWARD_FUNCTION for CTM_GRID
and CTM_EXTRACT
bmy, 08 Oct 1998: VERSION 1.03
- FILEINFO and DATAINFO are now keywords
- now returns X, Y, and Z as parameters
bmy, 03 Nov 1998: VERSION 1.04
- compatible with new CTM_GET_DATA routine
- now pass FILEINFO and DATAINFO structures
via USE_FILEINFO and USE_DATAINFO keywords
mgs, 10 Nov 1998: - once more adapted to changes in CTM_GET_DATA
- now extracts locally used FILEINFO structure
bmy, 11 Feb 1999: VERSION 1.05
- updated comments
bmy, 19 Feb 1999: - Renamed XIND, YIND, ZIND to XMID, YMID,
and ZMID, since these are not index
arrays, but the actual longitude,
latitude, or altitude values for each
dimension of the DATA array.
- added DEBUG keyword
- eliminate obsolete XARR, YARR, ZARR keywords
- added NOPRINT keyword to suppress
call to CTM_PRINT_DATAINFO
mgs, 02 Apr 1999: - replace gridinfo in fileinfo only if new
surface pressure is requested. Necessary
for 2D fields (e.g. EPTOMS)
- deactivated SMALLCHEM flag
- added error checking for FILEINFO
bmy, 28 Apr 1999: - return THISFILEINFO as a keyword
mgs, 30 Jun 1999: - Specification of PSURF finally works.
bmy, 13 Dec 1999: - now use CHKSTRU instead of N_ELEMENTS
to diagnose undefined GRIDINFO structure
bmy, 04 Dec 2000: GAMAP VERSION 1.47
- eliminated obsolete code from 12/31/99
bmy, 03 Jun 2001: GAMAP VERSION 1.48
- bug fix: also create GRIDINFO structure
for grids with no vertical layers
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_get_datablock.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_INDEX
PURPOSE:
Return index of CTM grid boxes for given coordinates
(or vice versa) and allow user to interactively select
a grid box
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
CTM_INDEX, [,i,j] [,keywords]
INPUTS:
MINFO --> Model type strucure as returned by CTM_TYPE.PRO
or GINFO --> Model grid structure as returned by CTM_GRID.PRO
If neither is given, the user will be prompted for a model
type and the grid will be computed.
I, J --> index pair for which lon, lat coordinates shall
be found if keyword /GET_COORDINATES is set. Also used
to return index values for given lon, lat pairs (this is
the default operation). NOTE: I and J will be in "FORTRAN"
notation (e.g. the starting from 1 and not zero). To index
IDL arrays, be sure to use I-1 and J-1.
KEYWORD PARAMETERS:
CENTER --> a two element vector with (LAT, LON) coordinates
for which the gridbox index shall be returned. Also used
to return center coordinates for a given index pair if
keyword /GET_COORDINATES is set.
EDGE --> a four element vector in the MAP_SET LIMIT format
(LAT0, LON0, LAT1, LON1). If keyword GET_COORDINATES is
not set and no CENTER coordinates are given, I and J will
return two element vectors with I(0) corresponding to LON0
and I(1) corresponding to LON1 etc. In this case, it may
be useful to retrieve WE_INDEX and SN_INDEX for indexing
of CTM data arrays (note that these indices follow the IDL
convention, i.e. starting from 0. To convert them into "true"
CTM indices, add 1).
If CENTER coordinates are provided or /GET_COORDINATES is set
then EDGE returns the grid box edges for the given or calculated
index pair.
WE_INDEX --> integer array for indexing of CTM data arrays. This
keyword is only used when EDGE is a valid 4 element vector,
keyword GET_COORDINATES is not set and no coordinates are
passed in the CENTER keyword. This array is always arranged
in west-east order (e.g. for EDGE=[0.,175.,0.,-175.] it will
return [70, 71, 0] (GEOS1 grid)).
SN_INDEX --> like WE_INDEX but for latitude indexing. Note that
latitude values in EDGE must be arranged in ascending order.
/GET_COORDINATES --> return coordinates to given index rather
than an index pair for given coordinates
/NON_INTERACTIVE --> default action is interactive box picking per
mouse (only need to supply MINFO in this case, but index and
coordinates of last click will be returned in I, J, CENTER
and EDGES repectively). Set this keyword if you want to convert
values to and fro without drawing a map etc.
XSIZE, YSIZE --> window size (default 900x600)
MAPCENTER --> center coordinates for map projection [p0lat, polon ]
COUNTRIES -> draw country boundaries
_EXTRA --> keywords are passed to MAP_SET
(e.g. LIMIT=[lat0,lon0,lat1,lon1])
Careful if you display data!
WINDOW -> window number to plot into. Normally a new window
is opened with the /free option. Use a specific window number
to overlay the map onto existing data plotted with tvimage
(see example).
DATA -> a data array with dimensions matching your model grid
(no error checking on this!) If DATA contains data, the value
at the selected grid box, and a statistic for neighbouring
grid boxes will be displayed together with the corrdinates.
OUTPUTS:
Index of grid box in I, J, coordinates in named variables supplied
with CENTER and EDGE keywords
SUBROUTINES:
REQUIREMENTS:
needs CTM_TYPE for input of MINFO parameter and
CTM_DEFINE_GRID
NOTES:
This routine makes substantial use of recursive calls. Be careful
when changing.
EXAMPLES:
(1)
CTM_INDEX, CTM_TYPE('GEOS1')
; Display world map and have fun.
(2)
CTM_INDEX, CTM_TYPE( 'GEOS1',RESOLUTION=2 ), $
I, J, LIMIT=[ 0.,-180., 90., -30. ]
; Display map of North America and select grid
; boxes for GEOS 2x2.5 grid.
; Indices of last point are returned in I and J.
(3)
CTM_INDEX, CTM_TYPE('GISS_II_PRIME'),$
I, J, CENTER=[ 42., -72.], /NON_INTERACTIVE
print,I,J
; returns grid box index for Harvard Forest in
; GISS CTM II' (21,33) without displaying a map
(4)
CTM_INDEX, CTM_TYPE('GISS_II'), $
I, J, EDGE=[-25.,170.,0.,-100.], $
WE_INDEX=WE, SN_INDEX=SN, /NON_INTERACTIVE
; returns [ 69, 70, 71, 0, 1, ... , 15 ] in WE and
; [ 15, 16, ..., 21 ] in SN. I is [ 70, 16 ], and J
; is [ 16, 22 ]. Note that I, J refer to CTM (= FORTRAN)
; indices, whereas WS and SN are IDL array indices.
(5)
IM = BYTSCL( DATA,MAX=MAX(DATA))
MINFO = CTM_TYPE( 'GENERIC', RES=[360./XDIM,180./YDIM] )
GINFO = CTM_GRID(MINFO)
TVIMAGE, IM, POSITION=P, /KEEP_ASPECT
CTM_INDEX, GINFO, I, J, WINDOW=0, DATA=DATA
; Overlay interactive map onto data displayed with
; TVIMAGE. You should create a generic MODELINFO
; structure in this case. NOTE: replace xdim, ydim
; with the dimensions of your data array!
; This example also demonstrates the use of ginfo vs. minfo.
MODIFICATION HISTORY:
mgs, 04 May 1998: VERSION 1.00
mgs, 07 May 1998: - added MAPCENTER and _EXTRA keywords,
fixed bug with lon index
- actually substantially rewritten
mgs, 08 May 1998: VERSION 1.10
- CENTER and EDGE keywords now MAP_SET compatible
- added WE_INDEX and SN_INDEX keywords
- improved documentation
- bug fix for display of polar grid boxes
mgs, 09 Jun 1998: - added COUNTRIES keyword
mgs, 15 Jun 1998: - bug fix for WE
mgs, 07 Oct 1998: - added interactive selection of model
mgs, 22 Feb 1999: - added DATA, SHELLS and WINDOW keywords
mgs, 23 Feb 1999: - can now use either minfo or ginfo as parameter
bmy, 24 Jan 2001: GAMAP VERSION 1.47
- commented out annoying & useless warning msg
- updated comments
bmy, 12 Mar 2003: GAMAP VERSION 2.02
- updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now pass DEFAULTMODEL from @GAMAP_CMN
common block to SELECT_MODEL
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_index.pro)
NAME:
CTM_LABEL (function)
PURPOSE:
Returns strings for several CTM quantities.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
RESULT = CTM_LABEL( DATAINFO, MODELINFO [, Keywords ] )
INPUTS:
DATAINFO -> Structure returned from CTM_GET_DATA, which
contains information about one data block
MODELINFO -> Structure returned from CTM_TYPE, which
contains information about the particular model
KEYWORD PARAMETERS:
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
supersedes the corresponding bit in TOTAL (see below).
LAT -> Scalar value or array of latitudes used in the plot.
LON -> Scalar value or array of longitudes used in the plot.
LEV -> Scalar value or array of latitudes used in the plot.
ALT -> Scalar value or array of altitudes used in the plot.
PRS -> Scalar value or array of pressures used in the plot.
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
supersedes the corresponding bit in TOTAL (see above).
FORMAT -> Specifies format for converting numeric values into
string values, for selected fields (such as LAT and LON).
Default is I14 (strings are trimmed).
/NO_SPECIAL -> If set, will not place any special superscript
or subscript characters into the strings returned in
LABELSTRU.
OUTPUTS:
LABELSTRU -> Structure containing the following label fields:
LAT: String for latitude(s)
LON: String for longitude(s)
LEV: String for vertical level(s)
ALT: String for altitude level(s)
PRS: String for pressure level(s)
LATLON: String that has format "(Lat,Lon)"
TRACERNAME: String for the tracer name
SCALE: String for the tracer's scale factor
UNIT: String for the tracer's unit
TAU0: String representation of TAU0
TAU1: String representation of TAU1
YMD0: String representation of (YY)YYMMDD
corresponding to TAU0
YMD1: String representation of (YY)YYMMDD
corresponding to TAU1
HMS0: String representation of HHMMSS
corresponding to TAU0
HMS1: String representation of HHMMSS
corresponding to TAU1
YEAR0: String for the starting year (e.g. 1994)
YEAR1: String for the ending year
MONTH0: String for the starting month name
(e.g. "Jan", "Feb", "Mar", etc..)
MONTH1: String for the ending month name
DAY0: String for the starting day number (1-31)
DAY1: String for the ending day number (1-31)
DATE: String for the date (see below)
MODEL: String for the model name
FAMILY String for the model's family
RES: String for the resolution of the model
SUBROUTINES:
External Subroutines Required:
==============================================
CHKSTRU (function) STRCHEM (function)
STRSCI (function) TAU2YYMMDD (function)
REQUIREMENTS:
DATAINFO and MODELINFO must be passed to CTM_LABEL. These
structures are computed by the GAMAP package subroutines.
NOTES:
DATAINFO is created e.g. by CTM_GET_DATA (or CTM_GET_DATABLOCK)
MODELINFO is created by CTM_TYPE
EXAMPLE:
CTM_LABEL, DataInfo, ModelInfo, LabelStru, Lat=10, Lon=48
print, LabelStru.LAT
'Lat=10!UN!N'
MODIFICATION HISTORY:
bmy, 23 Sep 1998: VERSION 1.00
bmy, 24 Sep 1998: - now ensure that RES is a scalar string
- place TAU2YYMMDD in FORWARD_FUNCTION call
bmy, 28 Sep 1998: VERSION 1.01
- formats for LatStr, LonStr, LevStr
changed to be more consistent.
mgs, 29 Sep 1998: - changed a few comments and fixed bug in
MinLon/MaxLon
bmy, 03 Nov 1998: - changed NAME to TRACERNAME for
the sake of consistency
bmy, 12 Nov 1998: - added LABELSTRU structure tags: YEAR0,
YEAR1, MONTH0, MONTH1, DAY0, DAY1, and DATE
- now reports lats as S/N instead of -/+
and reports lons as W/E instead of -/+
bmy, 17 Nov 1998: - now use function N_UNIQ to test for
the number of unique elements in
LAT, LON, LEV, ALT, PRS
- Added FORMAT keyword to specify
format for LAT and LON strings
- updated comments
bmy, 15 Jan 1999: - added NO_SPECIAL keyword
bmy, 17 Feb 1999: - Now add GMT to date string for timeseries
animation plots (interval < 1 day)
- make sure that HMS0STR and HMS1STR have
string lengths of 6 characters
bmy, 18 Feb 1999: - fix default DATE string for February
mgs, 16 Mar 1999: - cosmetic changes
- removed SUBTRACT_ONE keyword and improved
choice of date format
bmy, 13 Jul 2001: GAMAP VERSION 1.48
- Use updated version of STRREPL.PRO from mgs
bmy, 07 Nov 2001: GAMAP VERSION 1.49
- now use 8-digit YYYYMMDD format for
date variables YMD0, YMD1
bmy, 02 Oct 2002: GAMAP VERSION 1.53
- now write GEOS3 instead of GEOS3_30L
bmy, 05 Nov 2003: GAMAP VERSION 2.01
- now write GEOS4 instead of GEOS3_30L
- now use the proper time epoch for each
model family in call to TAU2YYMMDD
- updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_label.pro)
NAME:
CTM_LOCATEDIFF
PURPOSE:
Locates data blocks which differ in two binary
punch files or GMAO met field files.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_LOCATEDIFF, FILE1, FILE2 [, Keywords ]
INPUTS:
FILE1 -> Name of the first file to be tested. FILE1 may be
a binary punch file, and ASCII file, or a GMAO met field
file.
FILE2 -> Name of the second file to be tested. FILE2 may be
a binary punch file, and ASCII file, or a GMAO met field
file.
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name to restrict the selection
of data records.
OUTFILENAME -> Name of the output file which will contain
the location of differences found between data blocks
in FILE1 and FILE2. If OUTFILENAME is not specified,
then CTM_LOCATEDIFF will print this information to
the screen.
/HEADERS_ONLY -> Set this switch to just print the category
names and tracer numbers where differences occur instead
of printing all of the data points.
_EXTRA=e -> Picks up any extra keywords for CTM_GET_DATA.
OUTPUTS:
None
SUBROUTINES:
External subroutines required:
==============================
CTM_GET_DATA UNDEFINE
CTM_DIAGINFO
REQUIREMENTS:
References routines from both GAMAP and TOOLS directories.
NOTES:
(1) Both FILE1 and FILE2 must contain the same diagnostic
categories, listed in the same order.
EXAMPLE:
CTM_LOCATEDIFF, 'ctm.bpch.old', 'ctm.bpch.new'
; Locates data blocks which differ between ctm.bpch.old
; and ctm.bpch.new. You can investigate these further
; with routines CTM_PRINTDIFF and CTM_PLOTDIFF.
MODIFICATION HISTORY:
bmy, 24 Feb 2003: VERSION 1.00
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- Now get spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 27 Feb 2004: GAMAP VERSION 2.02
- Rewritten to also print out locations in
FORTRAN notation where differences occur
- added DIAGN keyword to specify category name
- added OUTFILENAME to specify output file
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 01 May 2013: GAMAP VERSION 2.17
- Corrected error in EXAMPLE section above
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_locatediff.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_MAPGRID
PURPOSE:
Plots CTM grid boxes superposed atop a world map.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
CTM_MAPGRID, GRIDINFO [, Keywords ]
INPUTS:
GRIDINFO -> Output structure returned from CTM_GRID
containing information about the particular
grid being used.
KEYWORD PARAMETERS:
COLOR -> Color index for the map outline, continents, and
title. Default is BLACK (assuming MYCT color table).
G_COLOR -> Color index for the grid lines.
Default is BLACK (assuming MYCT color table).
LIMIT -> Vector containing [ LatMin, LonMin, LatMax, LonMax ].
These define the latitude and longitude ranges for
the map projection. If LIMIT is not supplied,
CTM_MAPGRID will construct LIMIT from the information
supplied in GRIDINFO.
/PS -> If set, will send output to a PostScript file.
_EXTRA=e -> Picks up any extra keywords for OPEN_DEVICE,
MAP_SET, MAP_CONTINENTS, PLOTS, and CLOSE_DEVICE.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=========================================
CHKSTRU (function) CONVERT_LON
OPEN_DEVICE CLOSE_DEVICE
MYCT_DEFAULTS (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
GRIDINFO = CTM_GRID( CTM_TYPE( 'GEOS1', RES=2 ) )
CTM_MAPGRID, GRIDINFO, LIMIT=[ -90, 130, 90, -130 ], /ISOTROPIC
; Plots a world map (pacific region, spanning
; the date line) for the GEOS-1 2 x 2.5 grid
(2)
CTM_MAPGRID, GRIDINFO, LIMIT=[ -90, -182.5, 90, 177.5 ], /ISOTROPIC
; For the same grid as above, plots the entire world
; centered on 0 degrees lat and 0 degrees longitude.
MODIFICATION HISTORY:
bmy, 03 Nov 1999: VERSION 1.00
bmy, 24 Mar 2000: VERSION 1.45
- now prints map labels
- added /NOBORDER to MAP_SET call
bmy, 27 May 2003: GAMAP VERSION 1.53
- now plots continent lines after grid lines
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_mapgrid.pro)
NAME:
CTM_MASS_CHECK
PURPOSE:
Plots the time evolution of % difference of tracer mass and
air mass from a CTM simulation. Used to assess mass
conservation in CTM transport codes.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_MASS_CHECK [, Keywords ]
INPUTS:
FILENAME -> Name of the CTM output file containing air mass
and tracer concentrations. FILENAME can be either an
ASCII punch file or a BINARY punch file. If omitted,
the user will be prompted to supply FILENAME via a
dialog box.
KEYWORD PARAMETERS:
TRACER -> Number of the tracer that you wish to check for
mass conservation.
/PS -> Set this switch to create PostScript plot output.
OUTFILENAME -> If /PS is set, OUTFILENAME will be the name of
the PostScript plot output file. Default is "mass_check.ps".
_EXTRA=e -> Catches extra keywords for routines OPEN_DEVICE
and CLOSE_DEVICE.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
CLOSE_DEVICE CTM_GET_DATA
MULTIPANEL OPEN_DEVICE
UNDEFINE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Assumes that the tracer concentration has been saved
under the IJ-AVG-$ diagnostic category. Also assumes
that the airmass has been saved under the BXHGHT-$
diagnostic category.
EXAMPLE:
CTM_MASS_CHECK, 'ctm.bpch.geos4', TRACER=4
; Plots the evolution of % difference of both
; tracer and air mass for CO from a GEOS-4 simulation.
MODIFICATION HISTORY:
bdf & bmy, 26 Jun 2003: GAMAP VERSION 2.03
bmy, 06 Mar 2007: GAMAP VERSION 2.06
- make FILENAME an input rather than
a keyword argument.
- now pass _EXTRA=e to the PLOT command
- Added WINPARAM keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_mass_check.pro)
NAME:
CTM_NAMEXT
PURPOSE:
Returns the proper filename extension for CTM model names.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
RESULT = CTM_NAMEXT( MODELINFO )
INPUTS:
MODELINFO -> a MODELINFO structure (output from function
CTM_TYPE) desribing the desired CTM model.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Returns a string containing the model name
(e.g. 'geos3', 'geos4', 'geos5', 'gcap', 'giss2p',
'generic', etc.).
SUBROUTINES:
External Subroutines Required:
==============================
CHKSTRU (function)
REQUIREMENTS:
None
NOTES:
(1) Add more model names as is necessary.
EXAMPLE:
MODELINFO = CTM_TYPE( 'GEOS_STRAT', RESOLUTION=4 )
PRINT, CTM_NAMEXT( MODELINFO )
geoss
; Returns filename extension for the GEOS-STRAT model
MODIFICATION HISTORY:
bmy, 30 Jun 2000: GAMAP VERSION 1.46
bmy, 02 Jul 2001: GAMAP VERSION 1.48
- added GENERIC as a return option
bmy, 02 Oct 2003: GAMAP VERSION 1.53
- now add GEOS3_30L to the CASE statement
bmy, 16 Oct 2003: - now add GEOS4 to the CASE statement
bmy, 12 Feb 2004: GAMAP VERSION 2.01a
- added GEOS4_30L to the CASE statement
bmy, 05 Aug 2004: GAMAP VERSION 2.02
- added GCAP to the CASE statement
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- added GEOS5, GEOS5_47L to the CASE statement
bmy, 04 Jan 2010: GAMAP VERSION 2.15
- added MERRA, MERRA_47L to the CASE statement
bmy, 09 Feb 2012: GAMAP VERSION 2.16
- added GEOS57, GEOS57_47L to the CASE statement
mps, 06 Nov 2013: - added GEOSFP, GEOSFP_47L to the CASE statement
mps, 28 Oct 2015: - added MERRA2, MERRA2_47L to the CASE statement
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_namext.pro)
NAME:
CTM_NOYBUDGET
PURPOSE:
Computes the NOy budget within a given 3-D region.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_NOYBUDGET [, BATCHFILE [, Keywords ] ]
INPUTS:
BATCHFILE (optional) -> Name of the batch file which
contains inputs that defines the 3-D region and NOy
constituents. If BATCHFILE is omitted, then the user
will be prompted to supply a file name via a dialog box.
KEYWORD PARAMETERS:
LOGFILENAME (optional) -> Name of the log file where output
will be sent. Default is "noy_budget.log".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
--------------------------------------------------------------
ErrorNOy (function)
TruncateAndWrapForNOy (function)
GetNoxEmissionsForNOy (function)
GetHNO3WetDepForNOy (function)
GetDryDepositionForNOy (function)
GetNetExportForNOy (function)
GetNetChemicalProductionForNOy (function)
ReadBatchFileForNOy (procedure)
External Subroutines:
--------------------------------------------------------------
CTM_Get_Datablock (function) CTM_BoxSize (function)
REQUIREMENTS:
None
NOTES:
(1) CTM_NOYBUDGET was developed for use with the GEOS-CTM,
there might be some adaptation required for use with
other models.
(2) Only 5 "families" are considered:
Dry Deposition, NOx, PAN, HNO3, R4N2.
(3) Wrapping around the date line seems to work but you
should always double-check.
EXAMPLE:
CTM_NOYBUDGET, 'box1.dat', LogFileName='box1.log'
; Computes NOy budgets for the region specified in
; the file "box1.dat" and sends output to the
; "box1.log" log file.
MODIFICATION HISTORY:
bmy, 28 Jan 2000: VERSION 1.00
- adapted original code from Isabelle Bey
bmy, 25 May 2000: VERSION 1.45
- now allow the user to specify diagnostic
category names in the batch file
- added internal function "TruncateAndWrapForNOy"
to wrap arrays around the date line
- added internal procedure "ErrorNOy"
to do error checking for CTM_GET_DATABLOCK
- now can create budgets for more than one
diagnostic interval
- now allow user not to compute chemical
production data for given families
acs, 26 May 2000: - bug fixes: now do not stop the run if
data blocks are not found
bmy, 01 Aug 2000: VERSION 1.46
- use abs( Total( X ) ) > 0 when testing if
transport fluxes are all nonzero
bmy, 24 Jan 2001: GAMAP VERSION 1.47
- now no longer require all types of emissions
to be nonzero in order to sum them
- now no longer require both HNO3 LS and
convective wetdep to be zero in order to
sum them
bmy, 17 Jan 2002: GAMAP VERSION 1.50
- now call STRBREAK wrapper routine from
the TOOLS subdirectory for backwards
compatiblity for string-splitting
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_noybudget.pro)
NAME:
CTM_OPEN_FILE
PURPOSE:
Open a CTM output (punch) file and reads the complete
header information from that file. The file may be either
ASCII or binary type, and is only opened if not already
parsed. It is re-opened if it was parsed but closed in the
meantime. CTM_OPEN_FILE can also be used to read GEOS-CTM
restart files. However, since it is not possible to
point randomly at these data, the complete set of tracers
in a restart file will be read at once.
While in general files are opened automatically when
CTM_GET_DATA is used, there are several circumstances where
direct use of CTM_OPEN_FILE advantageous:
* if a read error occurs, use CTM_OPEN_FILE with the /PRINT
keyword to diagnose the error
* to compare two model runs, it is simpler to first open
the two files, then call CTM_GET_DATA without the filename
keyword. All operations will then be done on both files
in parallel.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_OPEN_FILE, FILENAME, THISFILEINFO, THISDATAINFO
INPUTS:
FILENAME -> The name of the file to be opened or a
file mask. If the file was not found or the file
mask contains wild cards, a pickfile dialog is
opened for interactive selection. The default
search mask can be set in gamap.defaults (see
GAMAP_INIT).
KEYWORD PARAMETERS:
CANCELLED -> Returns 1 if the CANCEL button was pressed
during DIALOG PICKFILE filename selection.
_EXTRA keywords are passed to the various routines which
read the file headers.
OUTPUTS:
THISFILEINFO -> A named variable that will contain a
fileinfo structure (see CREATE3DFSTRU).
THISDATAINFO -> A named variable that will contain an
array of datainfo structures (see CREATE3DHSTRU)
associated with this file.
THISFILEINFO and THISDATAINFO are also appended to the
global pointer variables pGlobalFileInfo and pGlobalDataInfo
(see gamap_cmn.pro and GAMAP_INIT).
SUBROUTINES:
Internal Subroutines:
============================================================
Get_Free_Lun (function) Test_For_NCDF (function)
Test_For_HDF (function) Test_For_HDFEOS (function)
Test_For_GMAO (function) Test_For_Binary (function)
File_Parse (function) File_Opened_Previously (function)
Handle_Prev_Opened_File
External Subroutines Required:
==============================================================
GAMAP_CMN (incl file) OPEN_FILE
CTM_READ3DB_HEADER (function ) CTM_READ3DB_HEADER (function)
CTM_READ_GMAO (function ) CTM_READ_NCDF (function)
CTM_READ_GMI (function ) LITTLE_ENDIAN (function)
STRRIGHT (function )
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) In internal function "test_for_dao", add additional met
field names as is necessary to the FIELDNAMES array. The
first met field name in a file is tested against FIELDNAMES.
If there is a match, then the file is declared to be a DAO
met field file, and it is assigned a file type of 4.
(2) You must also add additional met field names to routine
"ctm_read_dao" as is necessary. The DAO met field files do
not carry tracer numbers, so the name of each met field must
be checked in "ctm_read_dao" before a corresponding DATAINFO
structure can be assigned.
(3) If a binary file is the wrong endian, we will get a
"Corrupted F77 file error" when we try to read data from it.
We now test for this error in routines TEST_FOR_BINARY and
TEST_FOR_DAO. If this error condition occurs, the file is
re-opened with the /SWAP_ENDIAN command.
EXAMPLE:
CTM_OPEN_FILE
; queries the user for a filename and stores the analyzed
; header information in the global common block
; If an ASCII punch file is read, the user is prompted for
; a model name
CTM_OPEN_FILE,'',fileinfo,datainfo
; opens a CTM punch file after selection from a pickfile
; dialog
CTM_OPEN_FILE,'~/amalthea/CTM4/run/ctm.pch',fileinfo,datainfo
; opens the specified punch file
MODIFICATION HISTORY:
mgs, 14 Aug 1998: VERSION 1.00
mgs, 17 Sep 1998: - file units now starting from 20, so
they do not interfere with GET_LUN
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 05 Oct 1998: - added function file_parse
- can now handle GEOS restart files as well.
mgs, 10 Nov 1998: - no message after Cancel on Pickfile dialog
bmy, 20 Jan 1999: - explicitly set binary type to 2 for
GEOS-CTM restart files
- accept bey's personal GEOS CTM timeseries label
mgs, 19 May 1999: - added SWAP_ENDIAN keyword to open_file if
binary files are read on PC
mgs, 24 May 1999: - added support for 'CTM bin 02' files
(involved changing filetype numbers)
bmy, 12 Apr 2000: GAMAP VERSION 1.45
- added test for DAO binary met field files
bmy, 12 Jun 2000: - added CLDFRC to list of recognized DAO fields
bmy, 28 Jul 2000: GAMAP VERSION 1.46
- added GEOS-3 names to list of recognized fields
- deleted a couple of field names woe don't use
bmy, 25 Sep 2000: - added new field: SLP (sea level pressure)
bmy, 05 Dec 2000: GAMAP VERSION 1.47
- added new fields: TKE, RH, KH
bmy, 07 Mar 2001: - added new fields: CLDTMP, TPW
bmy, 25 Apr 2001: - added new fields: TAULOW, TAUMID, TAUHI
bmy, 26 Jul 2001: GAMAP VERSION 1.48
- added new field: T2M
bmy, 15 Aug 2001: - added new field: OPTDEPTH
bmy, 27 Sep 2001: GAMAP VERSION 1.49
- reference LITTLE_ENDIAN in internal
subroutine "handle_prev_opened_file"
- swap endian if LITTLE_ENDIAN() returns true
in internal subroutine "handle_prev_opened_file"
bmy, 29 Jan 2002: GAMAP VERSION 1.50
- added new field: GWET
bmy, 03 Mar 2003: GAMAP VERSION 1.52:
- added new fvDAS fields: CMFDTR, CMFETR,
ZMDU, ZMED, ZMEU, ZMMD, ZMMU, HKETA, HKBETA
bmy, 18 Jun 2003: GAMAP VERSION 1.53
- added new fields: EVAP, LAI, PARDF, PARDR
bmy, 30 Jul 2003: - added new field: TSKIN
lyj & tdf, 22 Oct 2003: - added SWAP_BINARY keyword to TEST_FOR_BINARY
- Call TEST_FOR_BINARY with /SWAP_BINARY
as a last-ditch effort if the file type
cannot be classified. This will open the
file and swap the endian.
bmy, 12 Dec 2003: GAMAP VERSION 2.01
- Now also test for netCDF file format
- Added internal routines TEST_FOR_NETCDF,
TEST_FOR_HDF (stub), TEST_FOR_HDFEOS
- FILETYPE for ASCII files range from 0-99
- FILETYPE for BINARY files range from 100-199
- FILETYPE for netCDF files range from 200-299
- FILETYPE for HDF-EOS files range from 300-399
- Routine TEST_FOR_GMAO now looks for met
field tracer names from "tracerinfo.dat",
instead of using a hardwired string array
- rewritten for clarity; updated comments
- Now looks for the GEOS-4 met field ident string
bmy, 11 Feb 2004: GAMAP VERSION 2.01a
- Now prevents infinite loops when testing
for file type
bmy, 24 Aug 2004: GAMAP VERSION 2.03
- now recognizes GEOS-CHEM station timeseries
file in bpch file format by the FTI string
bmy, 21 Mar 2005: - Added COARDS-compliant netCDF as FILETYPE=203
bmy, 24 May 2005: GAMAP VERSION 2.04
- Now test properly for GCAP met fields
bmy, 06 Feb 2006: - Activate file type tests for HDF-EOS4
swath and point file types
- Add new function TEST_FOR_HDF5 to test if
the file is in HDF5 format
- Use the absolute path name internally when
testing for HDF5 or HDF-EOS files
bmy, 31 May 2006: GAMAP VERSION 2.05
- Now expand the filename when calling NCDF_OPEN
- Skip test for HDF5 for IDL versions
earlier than 6.0
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now modified for GEOS-5
- Added FILETYPE=106 for files that
contain 4-D data blocks
- Use FILETYPE=202 for netCDF files
created by BPCH2GMI
phs, 30 Jun 2008: GAMAP VERSION 2.12
- warning if too many files are opened
- completly rewrite handling of endian swapping
bmy, 23 Jan 2017: GAMAP VERSION 2.19
- Add a better test for netCDF files. This
removes the restriction of the file having
to end with *.nc or *.nc4.
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_open_file.pro)
NAME:
CTM_OVERLAY
PURPOSE:
Calls TVMAP to plot a pixel or contour map and then overplots
either an aircraft flight track or individual station data
atop it.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_OVERLAY, DATA, XMID, YMID, $
TRACKD, TRACKX, TRACKY [, Keywords ]
INPUTS:
DATA -> Data array (e.g. from CTM_GET_DATA or CTM_GET_DATABLOCK)
from which a pixel plot or contour plot will be generated.
XMID -> Vector of longitudes corresponding to DATA.
YMID -> Vector of latitudes corresponding to DATA
TRACKD -> Vector of data values corresponding to the aircraft
flight track or station data points.
TRACKX -> Vector of longitudes corresponding to the aircraft
flight track or station data points. Should be in the
range [-180,180].
TRACKY -> Vector of longitudes corresponding to the aircraft
flight track or station data points. Should be in the
range [-90,90].
KEYWORD PARAMETERS:
C_COLORS -> Vector to specify the color levels for filled
contour plots. If not passed, then C_COLORS will return
to the calling program the default color level values
generated internally by TVMAP.
C_LEVELS -> Vector containing contour levels for filled
contour plots. Used in conjunction with /FCONTOUR.
COLOR -> Color of the map outline. Passed to TVMAP.
/FCONTOUR -> Set this switch to generate a filled-contour
plot instead of a pixel plot.
/LOG -> Set this switch to use a logarithmic color table.
MINDATA -> Minimum value of DATA. If omitted, then MINDATA
will be automatically set to the minimum value of DATA.
MAXDATA -> Minimum value of DATA. If omitted, then MINDATA
will be automatically set to the minimum value of DATA.
/OVERPLOT -> Set this keyword to overplot a flight track
atop a map previously drawn by TVMAP.
T_COLOR -> (1) If plotting aircraft flight track data, then
T_COLOR will be used to define the color of the line.
(2) If plotting symbol data, then T_COLOR will be used to
describe the color of the border around the symbol.
To suppress printing a border around the symbol, use
any negative value for T_COLOR (e.g. T_COLOR = -1).
T_LINESTYLE -> IDL linestyle for the aircraft flight track.
Takes same values as the LINESTYLE graphic keyword
(see help pages).
T_SYMBOL -> Argument to the SYM keyword, which will be used
to define the individual data points if you are plotting
station data. Recommended value: 1 (filled circle).
T_THICK -> Thickness of the aircraft flight track, in pixels.
_EXTRA=e -> Passes extra keywords to TVMAP and OPLOT.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
==========================================
SCALETRACK (function)
External Subroutines Required:
=========================================
MULTIPANEL MYCT_DEFAULTS (function)
TVMAP RECTANGLE
SYM (function)
REQUIREMENTS:
None
NOTES:
You can pass all of the same keywords to CTM_OVERLAY_FLIGHT
as you do to TVMAP.
EXAMPLE:
(1) Plot flight tracks atop a pixel or contour map
--------------------------------------------------
; Read the data -- in this case, CO concentrations
SUCCESS = CTM_Get_DataBlock( Data, 'IJ-AVG-$', $
File='ctm.bpch.1995', $
Tra=4, $
/First, $
Lon=[-180, 180], $
Lat=[-88, 88], $
Lev=1, $
XMid=XXmid, Ymid=YYMid )
; Make a "fake" aircraft track
; Here we'll use MAP_2POINTS to create a "fake" flight
; track of constant longitude (30 deg E meridian)
nPts = 101
a = MAP_2POINTS( 30, -90, 30, 90, NPATH=NPTS )
TrackX = A[0,*]
TrackY = A[1,*]
TrackD = FltArr( nPts )
; Plot a pixel map w/ countries, continents, grid lines,
; and overlay a red, dashed-line flight track atop it.
CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
/Sample, /Countries, /Coasts, /CBar, $
Div=4, Min_Val=1e-20, /Isotropic, /Grid, $
Title='Pixel map overlaid /w contour map', $
T_Color=!MYCT.RED, T_Thick=2, T_LineStyle=2
; Make a second "fake" aircraft track
; (of course, if you have a real flight track, use it...)
TrackX = Replicate( 72, 100 )
TrackY = Findgen( 100 ) - 50
TrackD = Fltarr( 100 )
; Call CTM_OVERLAY again with /OVERPLOT to
; overplot the second flight track
CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
T_Color=!MYCT.BLUE, T_Thick=2, T_LineStyle=2, /OVERPLOT
(2) Draw Boxes for Tagged Tracer regions
----------------------------------------
; Define (X,Y) coordinates of first tagged tracer region
TrackX = [ 0, 60, 60, 0, 0 ]
TrackY = [ 0, 0, 30, 30, 0 ]
TrackD = [ 0, 0, 0, 0, 0 ]
; Call CTM_OVERLAY with all TVMAP keywords to
; plot the map and to initialize the map dataspace
CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
/Sample, /Countries, /Coasts, /CBar, $
Div=4, Min_Val=1e-20, /Isotropic, /Grid, $
Title='Test pixel map w/ overlay boxes', $
T_Thick=3, T_Color=!MYCT.BLACK, T_LineStyle=0
; Define second tagged tracer region
TrackX = [ 0, 120, 120, 0, 0 ]
TrackY = [ 0, 0, -30, -30, 0 ]
; Call CTM_OVERLAY with /OVERPLOT to overplot
; atop the previously defined map
CTM_OverLay, Data, XXMid, YYMid, TrackX, TrackY, $
/OVERPLOT, T_Thick=3, T_Color=!MYCT.RED, T_LineStyle=0
(3) Plot individual station data points
----------------------------------------
; Define "fake" station data for demo
; (along the equator between 60W and 60E)
Ind = Where( XMid ge -60 AND XMid le 60, N )
TrackD = Findgen(N) + 20
TrackY = Fltarr(N) + 0
TrackX = Xmid[Ind]
; Call CTM_OVERLAY with all TVMAP keywords to
; plot the map and to initialize the map dataspace
CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
/Sample, /Countries, /Coasts, /CBar, $
Div=4, Min_Val=1e-20, /Isotropic, /Grid, $
T_Symbol=1, SymSize=2, $
Title='Test pixel map w/ station data',
MODIFICATION HISTORY:
bmy, 05 Oct 2006: GAMAP VERSION 2.05
- Modified from CTM_OVERLAY_FLIGHT and
renamed to CTM_OVERLAY
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
dbm & bmy, 06 Nov 2007: - Modified to allow filled contour plots
cdh & bmy, 18 Feb 2009: GAMAP VERSION 2.13
- Now pass LOG=LOG to TVMAP call to ensure
that TVMAP gets the /LOG keyword OK
bmy & cph, 14 Jan 2010: GAMAP VERSION 2.14
- Remove the call to the PLOT command after
TVMAP. This does set up the approropriate
coordinates for map projections other
than /CYLINDRICAL.
- Now use PLOTS to plot symbols or lines
rather than OPLOT.
- Updated comments
cdh, 24 Feb 2010: - Added /NOADVANCE keyword
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Now set default values for C_COLORS
for filled contour plots if not specified
bf & bmy, 18 Oct 2010: - Bug fix submitted by Bonne Ford to allow
more than one overlay on the same plot
bmy, 10 Feb 2016: GAMAP VERSION 2.19
- If plotting symbols, suppress symbol borders
if T_COLOR is negative (e.g. T_COLOR=-1).
- Now require adding /NOADVANCE before each
successive call to CTM_OVERLAY with /OVERPLOT
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_overlay.pro)
NAME:
CTM_OVERLAY_WIND
PURPOSE:
Calls TVMAP to plot a pixel or contour map and then overplots
wind data atop it.
%%%% NOTE: Still in BETA testing! %%%%
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_OVERLAY, DATA, XMID, YMID, U, V, [, Keywords ]
INPUTS:
DATA -> Data array (e.g. from CTM_GET_DATA or CTM_GET_DATABLOCK)
from which a pixel plot or contour plot will be generated.
XMID -> Vector of longitudes corresponding to DATA.
YMID -> Vector of latitudes corresponding to DATA
U -> Array of U-wind values
V -> Array of V-wind values
KEYWORD PARAMETERS:
COLOR -> Color of the map outline. Passed to TVMAP.
/LOG -> Set this switch to use a logarithmic color table.
MINDATA -> Minimum value of DATA. If omitted, then MINDATA
will be automatically set to the minimum value of DATA.
MAXDATA -> Minimum value of DATA. If omitted, then MINDATA
will be automatically set to the minimum value of DATA.
/OVERPLOT -> Set this keyword to overplot the wind
atop a map previously drawn by TVMAP.
_EXTRA=e -> Passes extra keywords to TVMAP and VELOCITY_FIELD.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
==========================================
SCALETRACK (function)
External Subroutines Required
=========================================
MULTIPANEL MYCT_DEFAULTS (function)
TVMAP RECTANGLE
SYM (function)
REQUIREMENTS:
Uses routines from both GAMAP and TOOLS packages.
NOTES:
You can pass all of the same keywords to CTM_OVERLAY_FLIGHT
as you do to TVMAP.
EXAMPLE:
(1) Plot flight tracks atop a pixel or contour map
--------------------------------------------------
; Read the data -- in this case, CO concentrations
SUCCESS = CTM_Get_DataBlock( Data, 'IJ-AVG-$', $
File='ctm.bpch.1995', $
Tra=4, $
/First, $
Lon=[-180, 180], $
Lat=[-88, 88], $
Lev=1, $
XMid=XXmid, Ymid=YYMid )
; Make a "fake" wind [TO DOCUMENT]
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 20 Mar 2008: GAMAP VERSION 2.12
- cleanup, updated for new TVMAP
- now pass Map Position to velocity_field
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_overlay_wind.pro)
NAME:
CTM_OXBUDGET
PURPOSE:
Computes the Ox budget within a given 3-D region.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_OXBUDGET [, BATCHFILE [, Keywords ] ]
INPUTS:
BATCHFILE (optional) -> Name of the batch file which
contains inputs that defines the 3-D region and NOy
constituents. If BATCHFILE is omitted, then the user
will be prompted to supply a file name via a dialog box.
KEYWORD PARAMETERS:
LOGFILENAME (optional) -> Name of the log file where output
will be sent. Default is "ox_budget.log".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
--------------------------------------------------------------
ErrorOx (function)
TruncateAndWrapForOx (function)
GetHNO3WetDepForOx (function)
GetDryDepositionForOx (function)
GetNetChemicalProductionForOx (function)
GetNetExportForOx (function)
ReadBatchFileForOx (procedure)
External Subroutines Required:
--------------------------------------------------------------
CTM_Get_Datablock (function) CTM_BoxSize (function)
REQUIREMENTS:
NOTES:
(1) CTM_OXBUDGET was developed for use with the GEOS-CTM,
there might be some adaptation required for use with
other models.
(2) Only 2 "families" are considered: Dry Deposition and Ox.
(3) Wrapping around the date line seems to work but you
should always double-check.
(4) Currently, the box of consideration must be less than
global size in order to m
EXAMPLE:
CTM_OXBUDGET, 'box1.ox', LogFileName='box1.log'
; Computes Ox budgets for the region specified in
; the file "box1.ox" and sends output to the
; "box1.log" log file.
MODIFICATION HISTORY:
bmy, 28 Jan 2000: VERSION 1.00
- adapted original code from Isabelle Bey
bmy, 25 May 2000: GAMAP VERSION 1.45
- now allow the user to specify diagnostic
category names in the batch file
- added internal function "TruncateAndWrapForOx"
to wrap arrays around the date line
- added internal procedure "ErrorOx"
to do error checking for CTM_GET_DATABLOCK
- now can create budgets for more than one
diagnostic interval
- now allow user not to compute chemical
production data for given families
acs, 26 May 2000: - bug fixes: now do not stop the run if
data blocks are not found.
bmy, 01 Aug 2000: GAMAP VERSION 1.46
- use abs( Total( X ) ) > 0 when testing if
transport fluxes are all nonzero
bmy, 13 Dec 2001: GAMAP VERSION 1.49
- Now do not require all transport fluxes
to be nonzero in order to compute budgets
- now truncate data blocks correctly for
E/W and N/S transport fluxes
- Now compute the total number of seconds
over the entire diagnostic interval
- Now divide fluxes by the number of diagnostic
time intervals in order to get average fluxes
bmy, 17 Jan 2002: GAMAP VERSION 1.50
- now call STRBREAK wrapper routine from
the TOOLS subdirectory for backwards
compatiblity for string-splitting;
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 23 Mar 2008: GAMAP VERSION 2.12
phs, 20 Aug 2008: GAMAP VERSION 2.13
- now 3D region can be as small as one box.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_oxbudget.pro)
NAME:
CTM_PLOT
PURPOSE:
General plotting tool for CTM data that is stored in the
GAMAP datainfo and fileinfo structures. CTM_PLOT can
handle everything from 0-D to 3-D and has many different
plot options, especially for 2-D plots for which it was
originally designed. E.g. full map support.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_PLOT, [ Diagn [ [ ,Keywords ] ]
INPUTS:
DIAGN -> The diagnostic number (e.g. ND22, ND45, etc or
category name (e.g. "JV-MAP", "IJ-AVG") for which to
read data from the punch file.
KEYWORD PARAMETERS:
Keyword parameters passed to CTM_GET_DATABLOCK:
===============================================
FILENAME -> Name of the punch file to read data from.
FILENAME is passed to CTM_GET_DATABLOCK. You can also
use a file mask, in which case FILENAME will return the
full filename if it is a named variable. If an empty
filename is provided, the default search mask from
gamap.defaults (see gamap.cmn) will be used. If no
filename is given, ctm_plot will try
to find the records from data already loaded.
TRACER -> Number of tracer to read from the punch file.
TAU0, /FIRST, /LAST -> time step to be plotted
LON -> If /INDEX is set, LON denotes the CTM longitude index
of the box to plot. Otherwise, LON denotes the actual
longitude value of that box. (that is at box CENTER, phs
4/2/08)
LAT -> If /INDEX is set, LAT denotes the CTM latitude index
of the box to plot. Otherwise, LAT denotes the actual
latitude value of that box. (that is at box CENTER, phs
4/2/08)
LEV -> An index array of sigma levels *OR* a two-element
vector specifying the min and max sigma levels to be
included in the plot. Default is [ 1, GRIDINFO.LMX ].
ALTRANGE -> A vector specifying the min and max altitude
values to be included in the extracted data block.
PRANGE -> A vector specifying the min and max pressure
levels to be included in the extracted data block.
/INDEX -> If set, will interpret LAT, LEV, and LON as CTM
indices. If not set, will interpret LAT, LEV, and LON
as the actual values of latitude, level, and longitude.
NOTE: If /INDEX is set, then GAMAP cannot create plots
for longitude ranges that span the date line!!!
AVERAGE -> If = 0, will not average the data
= 1, will average data longitudinally
= 2, will average data latitudinally
= 4, will average data vertically
These are cumulative (e.g. AVERAGE=3 will average over
both lat and lon, and AVERAGE=7 will average over lat,
lon, and vertical levels to produce 1 data point).
TOTAL -> If = 0, will not total data
= 1, will total data longitudinally
= 2, will total data latitudinally
= 4, will total data vertically
These are cumulative (e.g. TOTAL=3 will total over both
lat and lon, and TOTAL=7 will total over lat, lon, and
vertical levels to produce 1 data point).
USE_FILEINFO -> (optional) If provided, CTM_GET_DATABLOCK will
restrict its search to only the files that are
contained in USE_FILEINFO which must be a FILEINFO
structure array. Default is to use the global information
(see gamap_cmn.pro).
If an undefined named variable is provided in USE_FILEINFO,
it will either contain the global FILEINFO structure array
or the FILEINFO record of the specified file.
USE_FILEINFO and USE_DATAINFO must be consistent, and should
either both be used or omitted. However, it is
possible to provide the global FILEINFO structure
(or nothing) with a local subset of DATAINFO.
USE_DATAINFO -> (optional) Restrict search to records contained
in USE_DATAINFO which must be a DATAINFO structure array.
If an undefined named variable is provided in USE_DATAINFO,
it will either contain the global DATAINFO structure array
or all DATAINFO records of the specified file.
See also USE_FILEINFO.
Keywords passed to CTM_CONVERT_UNIT:
====================================
UNIT -> Name of the unit that the DATA array will be converted
to. If not specified, then no unit conversion will be done.
Keywords passed to TVMAP or TVPLOT:
===================================
NOERASE -> Do not erase previous plot.
POSITION -> A four-element array of normalized coordinates
that specifies the location of map on the plot. POSITION
has the same form as the POSITION keyword on a plot.
Default is [0.1, 0.05, 0.9, 0.08]. (Passed to TVMAP).
NCOLORS -> This is the maximum color index that will be used.
BOTTOM -> The lowest color index of the colors to be loaded
used in the color map and color bar.
/NOCBAR -> If set, will not plot the colorbar below the map
in the position specified by CBPOSITION. Default is to
plot a colorbar.
CBCOLOR -> Color index of the colorbar outline and
characters. Defaults to BLACK (from colors_default.pro).
CBPOSITION -> A four-element array of normalized coordinates
that specifies the location of the colorbar. BARPOSITION
has the same form as the POSITION keyword on a plot.
Default is [0.1, 0.05, 0.9, 0.08].
CBUNIT -> Passes the Unit string to COLORBAR, which will be
plotted to the right of the color bar. NOTE: For black
& white contour plots, the string specified by CBUNIT
will be plotted below the X-axis.
CBFORMAT -> format to use in call to colorbar. Default is I12
if abs(max(data)) < 1e4, else e12.2 (strings get trimmed)
COLOR -> Color index of the map outline and title characters.
Defaults to BLACK (from colors_default.pro). Also used as
plot color for 1-D (line) plots.
MPARAM -> A 3 element vector containing values for
[ P0Lat, P0Lon, Rot ]. Default is [ 0, 0, 0 ].
POSITION -> A four-element array of normalized coordinates
that specifies the location of the map. POSITION has
the same form as the POSITION keyword on a plot.
Default is [0.1, 0.1, 0.9, 0.9].
TITLE -> The title string that is to be placed atop the
map window.
/NOCONTINENTS -> If set, will suppress adding continent lines
to the map. Default is to call MAP_CONTINENTS to plot
continent outlines or filled boundaries.
CCOLOR -> The color index of the continent outline or fill
region. Default is BLACK (from colors_default.pro).
CFILL -> Value passed to FILL_CONTINENTS keyword of
MAP_CONTINENTS. If CFILL=1 then will fill continents
with a solid color (as specified in CCOLOR above).
If CFILL=2 then will fill continents with hatching.
/NOGRID -> If set, will suppress printing of grid lines.
Default is to call MAP_GRID to overlay grid lines.
GCOLOR -> The color index of the grid lines.
Default is BLACK (from colors_default.pro)
/NOGLABELS -> Will suppres printing of labels for each grid
line in TVMAP.PRO. Default is to print grid labels
for each grid line.
/NOISOTROPIC -> Will suppress plotting of an isotropic map
(i.e. one with the same X and Y scale). Default is to
print an isotropic map.
/CONTOUR -> Will produce a line-contour map instead of the
default color-pixel image map.
/FCONTOUR -> Will produce a filled contour map instead
of the default color-pixel image map. If you find
that one or more color bands are not filled properly,
try the /CELL_FILL keyword. This is a known IDL precularity.
C_LEVELS -> Vector containing the contour levels. If not
specified, TVMAP will use quasi-logarithmic levels.
C_COLORS -> Index array of color levels for each line (or
each fill section) of the contour map. If not
specified, TVMAP will select default colors from the
colortable.
C_ANNOTATION -> Vector containing the contour labels.
Default is to use string representations of C_LEVELS.
C_FORMAT -> Format string used in converting C_LEVELS to
the default C_ANNOTATION values. Default is '(f8.1)'.
C_LABELS -> Specifies which contour levels should be labeled.
By default, every other contour level is labeled. C_LABELS
allows you to override this default and explicitly
specify the levels to label. This parameter is a vector,
converted to integer type if necessary. If the LEVELS
keyword is specified, the elements of C_LABELS
correspond directly to the levels specified, otherwise,
they correspond to the default levels chosen by the
CONTOUR procedure. Setting an element of the vector to
zero causes that contour label to not be labeled. A
nonzero value forces labeling.
NOTE: If C_LABELS is given as a scalar, then it will be
expanded to a vector with all elements having the same value.
/C_LINES -> Will overplot a filled-contour map with contour lines
and labels instead of plotting a colorbar. This was the old
default behaviour but has been changed with the advent of
"discrete" colorbars. The old NOLINES keyword is kept
for compatibility reasons but doesn't do anything.
/NOLABELS -> Will suppress printing contour labels on both
line-contour and filled-contour maps.
OVERLAYCOLOR -> Color of the solid lines that will be
overlaid atop a filled contour map. Default is BLACK.
/OVERPLOT -> Add an additional line plot to an existing one.
You should specify LINE=n and/or COLOR=n to distinguish
between curves in this case. You can manually add a legend
with legend.pro after the plot(s) are produced.
Note that the title string will contain information on
your first selection only. Use an explicit TITLE for
best results.
/SAMPLE -> Will cause REBIN (in TVMAP) to use nearest-
neighbor sampling rather than bilinear interpolation.
/LOG -> Will create a color-pixel plot with logarithmic
scaling. /LOG has no effect on line-contour or
filled-contour plots, since the default contour levels
are quasi-logarithmic.
/POLAR -> Create a polar plot. Note that the longitude range must
be -180..180 and the latitude range must extend to one pole
but not straddle the equator.
Keywords passed to ISOPLETH_MAP:
================================
ISOPLETH -> Value for which a 3-D isosurface will be computed.
ISOPLETH_MAP assigns a default value of 35.0.
Other Keywords:
===============
USTR -> Unit string to be plotted to the right of the colorbar.
If not specified, then CTM_PLOT will construct a unit
string based on the value of TRACERINFO.UNIT.
NOTE: USTR is a synonym for the keyword CBUNIT, which
specifies the color bar unit string.
THISDATAINFO -> Returns to the calling program the THISDATAINFO
structure obtained by CTM_GET_DATABLOCK.
LABELSTRU -> Returns to the calling program the structure
of label information obtained by CTM_LABEL.
YRANGE -> range of y values for color scaling (default:
scale each plot seperately with data min and max)
X_FORMAT, Y_FORMAT (optional) -> Specifies the format string
(e.g. '(f10.3)', '(e14.2)' ) for the X and Y axes, when
making line plots. If omitted, CTM_PLOT will call
GET_DEFAULTFORMAT to compute default format strings.
RESULT -> A named variable will contain the data subset that was
plotted together with the X and/or Y coordinates in a structure.
For 1D plots, either X or Y are -1. 3D visualization returns
a structure including the Z coordinate.
_EXTRA=e -> Picks up extra keywords for CTM_GET_DATABLOCK,
CTM_LABEL, TVMAP, and TVPLOT.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===========================================================
CTM_DRAW_CUBE CONVERT_LON
CTM_TRACERINFO CTM_CONVERT_UNIT
TVMAP TVPLOT
CHKSTRU (function) MYCT_DEFAULTS (function)
CTM_GET_DATABLOCK (function) CTM_LABEL (function)
REPLACE_TOKEN (function) CTM_BOXSIZE (function)
GET_DEFAULTFORMAT (function) GAMAP_CMN (include file)
REQUIREMENTS:
Also assumes colortable has been loaded with "myct.pro".
NOTES:
(1) Some keywords are saved in local variables with
slightly different names (e.g. MCONTOUR for /CONTOUR)
to prevent confusion with routine names and/or keywords
that are picked up by the _EXTRA=e facility.
(2) Not every possible combination of keywords has been thoroghly
tested. *PLEASE* report reproducible errors to mgs@io.harvard.edu!!
(3) As of 11/17/98, CTM_PLOT can only produce X-Y plots with
either PRESSURE or ALTITUDE along the left Y-Axis. The right
Y-Axis is left disabled (but will fix that later on...)
(4) Now define X-axis labels for longitude. The labels are
defined correctly for data blocks that span the date line.
EXAMPLE:
(0)
CTM_PLOT
; To plot an ozone surface map (default) of a
; user-selected file
(1)
FileName = '~/terra/CTM4/run_code/ctm.pch.sep1'
CTM_PLOT, 22, 1, FileName=FileName, Lev=[1,14], $
Total=4, /NoErase
; Plots vertically-summed map for tracer 1 of ND22
; (J-Values map). Will erase screen before plotting map.
(2)
CTM_PLOT, 'JV-MAP-$', 1, FileName=FileName, Lev=[1,14], $
Total=4, /NoErase
; Same as above, but uses category name instead of
; diagnostic number.
MODIFICATION HISTORY:
bmy, 21 Sep 1998: VERSION 1.00
bmy, 22 Sep 1998: VERSION 1.01
- added AVERAGE and TOTAL keywords
bmy, 22 Sep 1998: VERSION 1.10
- Modified for use with new versions of
CTM_GET_DATABLOCK, CTM_EXTRACT,
CTM_LABEL, REPLACE_TOKEN, and TVMAP
bmy, 25 Sep 1998: VERSION 1.11
- modified for TVMAP v. 2.0
bmy, 28 Sep 1998: VERSION 2.00
- modified for TVMAP v. 2.01
- renamed LONSHIFT to LSHIFT
bmy, 29 Sep 1998: - added ALTRANGE and PRANGE keywords
(which had been previously omitted)
bmy, 30 Sep 1998: VERSION 2.01
- added call to CTM_CONVERT_UNIT
- added LABELSTRU keyword
bmy, 07 Oct 1998 VERSION 2.02
- now works with TVMAP 3.0
- added /CONTOUR, /FCONTOUR, and
/COLORBAR keywords
- removed I/O error handling (that
is already done in CTM_GET_DATABLOCK)
bmy, 08 Oct 1998: VERSION 2.03
- now works with CTM_GET_DATABLOCK v. 1.03
and CTM_EXTRACT v. 1.04
- added DATA and THISDATAINFO keywords so
that an external data block can be
passed.
- another bug fix for UNITSTR
bmy, 03 Nov 1998: VERSION 2.04
- works with new CTM_GET_DATA,
CTM_GET_DATABLOCK and CTM_LABEL routines
- Now pass the FILEINFO and DATAINFO
structures via USE_FILEINFO and
USE_DATAINFO keywords
- removed DATA keyword
- changed %NAME% token to %TRACERNAME%
- Now can pass an explicit unit string
via the USTR keyword
mgs, 10 Nov 1998: - adapted for use with new CTM_GET_DATABLOCK
- changed keyword Erase to NoErase
- defaults set to produce an OX surface map
from IJ-AVG-$ diagnostics
- allow for vertical cross section plots
(interface to TVPLOT) : ** still needs work! **
- changed CBAR to NOCBAR
bmy, 12 Nov 1998: - TRACER is now a keyword instead of
an argument
- Changed keyword CONTINENTS to
NOCONTINENTS and GRID to NOGRID
- added NOISOTROPIC, SAMPLE and
keywords
bmy, 13 Nov 1998: - VERSION 3.00
- ***** RENAMED to CTM_PLOT *****
- updated documentation header
- renamed C_LABELS to C_ANNOTATION to
prevent keyword name confusion
- added NOLINES, NOLABELS, C_LABELS,
and OVERLAYCOLOR keywords for tvmap
- now gets default colors from
DEFAULT_COLORS.PRO
- Error checking for LIMIT keyword
(OK for now...fix this later on...)
bmy, 16 Nov 1998: - Now use %DATE% instead of %YMD1% for
all default plot titles
- now enhanced for TVPLOT v. 2.0
- now only convert units for a tracer
if the default unit is different from
the desired unit!!
bmy, 17 Nov 1998: - added /PRESSURE keyword to plot pressure
instead of altitude on the left Y-axis
mgs, 17 Nov 1998: - messed around quite a bit, because of
(unfortunate) changes in default_range !@#$!@
- added CBFormat keyword
bmy, 23 Nov 1998: - eliminated %SCALE% token from UNITSTR,
to be consistent with the latest
upgrade to COLORBAR.PRO.
- now pass SECONDS to CTM_CONVERT_UNIT
bmy, 13 Jan 1999: - add support for line plots. Also, if
the DATA array is averaged down to a
single point, will print the value of
that point and exit.
- use NEWXTITLE and NEWYTITLE as token-replaced
strings for XTITLE and YTITLE
bmy, 15 Jan 1999: - add support for 3-D visualization plots
- added unit string for contour plots
- now place CTM_LABEL call after the case
statement for PLOTTYPE, so that we can
suppress printing of special characters
in plot titles.
bmy, 19 Jan 1999: - improve 0-D output
- fixed [XY]Titles for line plots
- "unitless" is now a unit string option
- now use new default color names from
DEFAULT_COLORS.PRO
bmy, 20 Jan 1999: - Updated comments
mgs, 22 Jan 1999: - couple bug fixes, some code cleaning
- added OverPlot keyword to allow multiple
line plots
bmy, 19 Feb 1999: - now pass DEBUG (from GAMAP_CMN) to
CTM_GET_DATABLOCK via DEBUG keyword
- Rename XIND, YIND, ZIND keywords to
XMID, YMID, ZMID, in call to CTM_GET_DATABLOCK
bmy, 23 Feb 1999: - Add XTICKNAME, XTICKS, XTICKV in call to
TVPLOT...fix for map regions smaller than
the globe
- bug fix.../NOGRID was listed as GRID!!!
- added keyword /NOGLABELS, which
suppresses grid line labels in MAP_SET
- updated comments
bmy, 26 Feb 1999: - now calls MAP_LABELS to get latitude labels
for X, XZ, Y, YZ plot types.
- updated comments
bmy, 04 Mar 1999: - now pass DEBUG keyword to TVMAP
- now use GRIDINFO.XEDGE, GRIDINFO.YEDGE
to compute the LIMIT keyword for MAP_SET
mgs, 18 Mar 1999: - minor cleaning
mgs, 23 Mar 1999: - added ILun to keyword list to prevent retrieval
of two otherwise identical records from two
different files
bmy, 25 Mar 1999: - now line plots use MULTIPANEL
- if NPANELS >=2 then place the plot title
higher above the window, to allow for
carriage-returned lines
for X, Y, Z, XY, XZ, YZ plots
mgs, 25 Mar 1999: - no unit conversion if not necessary
- small fix to allow for 2D fields (e.g. EPTOMS)
bmy, 14 Apr 1999: - now prints unit string at lower right of
XZ or YZ plots, if the colorbar is not
plotted
bmy, 26 Apr 1999: - rename YRANGE to YYRANGE internally, so as
to avoid confusion with YRANGE plot keywords
mgs, 19 May 1999: - removed a few too explicit keyword settings
for 1D plots and fixed OverPlot option.
Now stores !X, !Y, and !P from last 1D plot
in a local common block.
mgs, 21 May 1999: - restore !X, !Y, and !P at the end of each
1-D plot to allow overplotting of data.
mgs, 25 May 1999: - needed to mess around with lonrange to get
it right.
mgs & bmy, 26 May 1999: - added POLAR keyword
bmy, 27 May 1999: - bug fix: CBUnit keyword wasn't honored
- neither was NoIsotropic
mgs, 27 May 1999: - changed default behaviour for filled contours:
now plots no lines and colorbar. Keyword
NoLines changed to C_Lines.
mgs, 28 May 1999: - added RESULT keyword to return data as plotted
- bug fix with wrapping round data: shouldn't be
done for vertical cross sections.
mgs, 02 Jun 1999: - small bug fix for 0D results.
mgs, bmy 03 Jun 1999: - removed "Unit:" from output
bmy, 07 Jul 1999: - added PLOTCSFAC scale factor for multipanel
plots
- small fixes for line plots
bmy, 02 Nov 1999: GAMAP VERSION 1.44
- return if THISDATAINFO contains
information for more than one data block
bmy, 24 Nov 1999: - now pass _EXTRA=e to CTM_TRACERINFO
so that /SMALLCHEM will be passed
bmy, 13 Dec 1999: - if GRIDINFO is undefined after returning from
CTM_GET_DATABLOCK, rebuild it w/ CTM_TYPE
bmy, 03 Feb 2000: GAMAP VERSION 1.45
- NOTE: /INDEX does not work with lon range
shifting anymore. Will fix later.
- also make sure LON, LAT have two elements
- added X_FORMAT, Y_FORMAT keywords for line plots
- updated comments
bmy, 06 Apr 2000: - bug fix: restrict X or Y axis range for line
plots using the value passed from YYRANGE.
- cosmetic changes, updated comments
bmy, 23 Jan 2001: GAMAP VERSION 1.47
- now call "isopleth_map.pro" to plot a 3-D
isosurface. 3-D visualization via
routine "ctm_draw_cube.pro" is obsolete.
- added ISOPLETH keyword as pass-thru to
ISOPLETH_MAP
bmy, 23 Jul 2001: GAMAP VERSION 1.48
- replaced call to DEFAULT_COLORS with
call to MYCT_DEFAULTS() to specify
MYCT color table information
- deleted obsolete code from 1998 and 1999
bmy, 09 Aug 2001: - bug fix: remove reference to BLACK from
the old "default_colors.pro"
bmy, 24 May 2002: GAMAP VERSION 1.50
- Now use SI unit hPa instead of mb in axis titles
- delete obsolete, commented-out code
bmy, 28 Sep 2002: GAMAP VERSION 1.51
- now get default NCOLORS, BOTTOM, BLACK values
from !MYCT system variable instead of from
the MYCT_DEFAULTS function
bmy, 16 Apr 2004: GAMAP VERSION 2.02
- Also need to convert the units of YYRANGE
accordingly so that /AUTORANGE will work
bmy, 16 Jun 2004: - Bug fix: if we do unit conversion, do not
let the converted value of YRANGE get
passed back to the main program
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Modified for GEOS-5 fields that are
defined on level edges
phs, 19 Mar 2008: GAMAP VERSION 2.12
- Bug fix for working with new map_labels
phs, 02 Apr 2008: - Bug fix for XZ and YZ pixel plots
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plot.pro)
NAME:
CTM_PLOTDIFF
PURPOSE:
Prints a lat-lon map of 2 CTM fields, their absolute difference,
and their percent difference. This is a quick way of ensuring
that two model versions are producing identical results.
The page will contain the following plot panels:
Panel #1 Panel #2
Data Block D1 Data Block D2
Panel #3 Panel #4
Abs Diff (D2 - D1) % Diff (D2 - D1)
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_PLOTDIFF, DIAGN, FILE1, FILE2 [, Keywords ]
INPUTS:
DIAGN -> A diagnostic number or category to restrict
the record selection (default is: "IJ-AVG-$").
FILE1 -> Name of the first CTM output file. If FILE1
is not given, or if it contains wildcard characters
(e.g. "*"), then the user will be prompted to supply
a file name via a pickfile dialog box.
FILE2 -> Name of the second CTM output file. If FILE2
is not given, or if it contains wildcard characters
(e.g. "*"), then the user will be prompted to supply
a file name via a pickfile dialog box.
KEYWORD PARAMETERS:
LON -> A 2-element vector specifying the longitude range that
will be used to make the plot. Default is [-180,180].
LAT -> A 2-element vector specifying the latitude range that
will be used to make the plot. Default is [-88,88].
LEV -> A scalar or 2-element vector which specifies the
level(s) that will be used to make the plot. Default
is [ 1, 1 ].
/PS -> Set this switch to print to a PostScript file.
OUTFILENAME -> Name of the PostScript file if the /PS option
is set. Default is "idl.ps".
TRACER -> Tracer number(s) for which differences will be plotted.
TAU0 -> TAU value(s) (hours since 0 GMT 1 Jan 1985) at the start
of the diagnostic data block to plot.
DIVISIONS -> Specifies the number of colorbar divisions for
the quantity plot (Panels #1 and #2). Default is 5.
NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.
DATARANGE -> Allows you to manually specify the min and max
values of the data that will appear on the plot (Panels
# 1 and #2). The default is to automatically compute
the overall min and max of both data blocks.
MIN_VALID -> Specifies the minimum valid data for the plot.
Data lower than MIN_VALID will be rendered with color
!MYCT.WHITE. For example, MIN_VALID is useful for
plotting emissions which only occur on land.
DIFFDIV -> Specifies the number of colorbar divisions for
the difference plots (Panels #3 and #4). Default is 8.
NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.
DIFFNCOLORS -> Sets the # of colors used to create the
difference plots (Panels #3 and #4). Default is 13.
DIFFRANGE -> Allows you to manually specify the min and max
values that will appear on the absolute difference
plot (Panel #3). Default is to use the dynamic range of
the absolute difference data (symmetric around zero).
/NODEVICE -> set to not call open_device, so you can do it
from outside
/NOMULTIPANEL -> set to not call multipanel, so you can do it
from outside
PCRANGE -> Allows you to manually specify the min and max
values that will appear on the percentage difference
plot (Panel #4). Default is to use the dynamic range of
the percentage difference data (symmetric around zero).
PCDIV -> number of ticks in the %-Diff colorbar
PCNCOLORS -> number of colors for the %-Diff plot
T1, T2, DIFFTITLE -> allows you to overwrite the default
title for the 1st, 2nd and DIff plots.
_EXTRA=e -> Picks up extra keywords for CTM_DIFF,
OPEN_DEVICE, and MYCT
Keywords for the MASK feature:
------------------------------
/MASK -> set to mask with a green color boxes where %-diff
and/or diff are below some threshold. The absolute value
of the % is plot.
PC_THR, DIFF_THR : the %-Diff and Diff THResholds to mask data in the
4th plot if /MASK is set. Boxes with %-Diff or/and Diff
below the THResholds are masked. Default values are 1%
and 1e4.
/ZAP -> set to skip all plots if /MASK is set and all boxes
are masked.
OUTPUTS:
none
SUBROUTINES:
External Subroutines Required:
=======================================================
CHKSTRU (function) CLOSE_DEVICE
CTM_CLEANUP COLORBAR_NDIV (function)
CTM_DIFF CTM_GET_DATABLOCK (function)
IS_DEFINED (function) EXTRACT_FILENAME (function)
MULTIPANEL OPEN_DEVICE
REQUIREMENTS:
None
NOTES:
(1) CTM_PLOTDIFF calls CTM_CLEANUP each time to remove
previously read datablock info from the GAMAP common
block.
(2) The default TAU0 value is 0, and is not suitable if your
run has no output for 0 GMT 1 Jan 1985! You may have to
gather tau0 before running and crashing CTM_PLOTDIFF.
EXAMPLE:
FILE1 = 'ctm.bpch.v4-30'
FILE2 = 'ctm.bpch.v4-31'
CTM_PLOTDIFF, 'IJ-AVG-$', FILE1, FILE2, TRACER=1
; Creates 4-panel plot w/ old data, new data,
; new - old (abs diff), and new - old (% diff).
MODIFICATION HISTORY:
bmy, 17 Apr 2002: GAMAP VERSION 1.50
bmy, 17 Jul 2002: GAMAP VERSION 1.51
- added TAU0 keyword
bmy, 16 Dec 2002: GAMAP VERSION 1.52
- now can handle 2 different tracer numbers
- now can handle 2 different TAU0 values
bmy, 29 Jan 2004: GAMAP VERSION 2.01
- Now pass LEV keyword to CTM_DIFF
- Now plot both DATA1 and DATA2 on
the same scale for easier comparison
bmy, 16 Feb 2005: GAMAP VERSION 2.03
- Now use /QUIET and /NOPRINT keywords in
CTM_GET_DATA and CTM_GET_DATABLOCK to
suppress screen output
phs, 24 Oct 2006: GAMAP VERSION 2.05
- Now use YRANGE if it is passed.
- Also use DIFFRANGE (for range of the
abs difference plot) if it is passed.
- Now use PCRANGE (for range of the
%age difference plot) if it is passed.
bmy, 15 Nov 2006: GAMAP VERSION 2.06
- Now use blue-white-red color table
for abs diff and % diff plots
bmy & phs, 04 Oct 2007: GAMAP VERSION 2.10
- Added DIVISIONS keyword (default=5)
- Now make the default DIFFRANGE and
PCRANGE symmetric around zero
- Added DIFFDIV, DIFFNCOLORS keywords
- Also restore original !MYCT structure
- restore initial Color Table and !MyCt,
and return, when crashes.
- Now skip plotting % difference if
DATA1 is zero everywhere
- Add error trapping with CATCH
bmy, 16 Jan 2008: GAMAP VERSION 2.12
- add _EXTRA=e to calls to CTM_PLOT, in order
to pass extra variables to that routine
phs, 31 Jan 2008: - Add NODEVICE keyword, so device (like PS
file) can be open outside this routine,
allowing for multiple pages in a PS file
for example.
- Clipping of percentage difference range
is indicated with triangle.
phs, 25 Feb 2008: - Improved error catcher
bmy, 05 Nov 2008: GAMAP VERSION 2.13
- Renamed YRANGE keyword to DATARANGE in
order to avoid confusion with nested grids
phs, 22 Sep 2009: - more flexible call to MYCT for diff
plots, so it can be overwriten from
caller
- Can select number of colors and divisions
for %-diff plot
- Can overwrite titles
- Can set Multipanel from outside in caller
- Can MASK data according to both Diff and
%-Diff values, in the 4th plot
bmy, 29 Jan 2010: GAMAP VERSION 2.14
- Minor fix in IF statement to prevent code
from dying after call to CTM_DIFF.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plotdiff.pro)
NAME:
CTM_PLOTDIFF4
PURPOSE:
Prints a lat-lon map of 2 CTM fields, their absolute difference,
and their percent difference. This is a quick way of ensuring
that two model versions are producing identical results.
The page will contain the following plot panels:
Panel #1 Panel #2
Data Block D1 Data Block D2
Panel #3 Panel #4
Abs Diff (D2 - D1) % Diff (D2 - D1) / D1
CTM_PLOTDIFF4 is a lighter version of CTM_PLOTDIFF, and does
not use CTM_DIFF as an intermediary routine.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_PLOTDIFF4, DIAGN, FILE2, FILE2 [, Keywords ]
INPUTS:
DIAGN -> A diagnostic number or category to restrict
the record selection (default is: "IJ-AVG-$").
FILE1 -> Name of the first CTM output file. If FILE1
is not given, or if it contains wildcard characters
(e.g. "*"), then the user will be prompted to supply
a file name via a pickfile dialog box.
FILE2 -> Name of the second CTM output file. If FILE2
is not given, or if it contains wildcard characters
(e.g. "*"), then the user will be prompted to supply
a file name via a pickfile dialog box.
KEYWORD PARAMETERS:
LON -> A 2-element vector specifying the longitude range that
will be used to make the plot. Default is [-180,180].
LAT -> A 2-element vector specifying the latitude range that
will be used to make the plot. Default is [-88,88].
LEV -> A scalar or 2-element vector which specifies the
level(s) that will be used to make the plot. Default
is [ 1, 1 ].
/PS -> Set this switch to print to a PostScript file.
OUTFILENAME -> Name of the PostScript file if the /PS option
is set. Default is "idl.ps".
TRACER -> A scalar or 2-element vector which specifies the
tracer number(s) for each data block.
TAU0 -> A scalar or 2-element vector which specifies the
TAU value(s) (hours since 0 GMT 1 Jan 1985) by which
each data block is timestamped.
DIVISIONS -> Specifies the number of colorbar divisions for
the quantity plot (Panels #1 and #2). Default is 5.
NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.
DATARANGE -> Allows you to manually specify the min and max
values of the data that will appear on the plot (Panels
# 1 and #2). The default is to automatically compute
the overall min and max of both data blocks.
MIN_VALID -> Specifies the minimum valid data for the plot.
Data lower than MIN_VALID will be rendered with color
!MYCT.WHITE. For example, MIN_VALID is useful for
plotting emissions which only occur on land.
DIFFDIV -> Specifies the number of colorbar divisions for
the difference plots (Panels #3 and #4). Default is 8.
NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.
DIFFNCOLORS -> Sets the # of colors used to create the
difference plots (Panels #3 and #4). Default is 13.
DIFFRANGE -> Allows you to manually specify the min and max
values that will appear on the absolute difference
plot (Panel #3). Default is to use the dynamic range of
the absolute difference data (symmetric around zero).
/NODEVICE -> set to not call open_device, so you can do it
from outside
/NOMULTIPANEL -> set to not call multipanel, so you can do it
from outside
PCRANGE -> Allows you to manually specify the min and max
values that will appear on the percentage difference
plot (Panel #4). Default is to use the dynamic range of
the percentage difference data (symmetric around zero).
PCDIV -> number of ticks in the %-Diff colorbar
PCNCOLORS -> number of colors for the %-Diff plot
TITLE_1 -> Allows you to override the default plot title for
the first data block (1st plot panel).
TITLE_1 -> Allows you to override the default plot title for
the 2nd data block (2nd plot panel).
DIFFTITLE -> Allows you to override the default plot title for
the absolute difference plot (3rd plot panel).
PCTITLE -> Allows you to override the default plot title for
the percent difference plot (4th plot panel).
_EXTRA=e -> Picks up extra keywords for CTM_DIFF,
OPEN_DEVICE, and MYCT
Keywords for the MASK feature:
------------------------------
/MASK -> set to mask with a green color boxes where %-diff
and/or diff are below some threshold. The absolute value
of the % is plot.
PC_THR, DIFF_THR : the %-Diff and Diff THResholds to mask
data in the 4th plot (percent difference) if /MASK is
set. Boxes with %-Diff or/and Diff below the THResholds
are masked. Default values are 1% and 1e4.
/ZAP -> set to skip all plots if /MASK is set and all boxes
are masked.;
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==========================================================
CHKSTRU (function) CLOSE_DEVICE
COLORBAR_NDIV (function) CTM_GET_DATABLOCK (function)
EXTRACT_FILENAME (function) MULTIPANEL
MYCT OPEN_DEVICE
TVMAP UNDEFINE
REQUIREMENTS:
Requires routines from the GAMAP package.
NOTES:
(1) When plotting a subset of the globe, CTM_PLOTDIFF4
properly sets the colorbar ranges for the abs diff
and percent diff plots. This was an issue in the
older CTM_PLOTDIFF.
(2) Longitude and latitude ranges specified by LON and LAT
will be applied to both data blocks.
EXAMPLE:
CTM_PLOTDIFF4, 'IJ-AVG-$', $
'v8-03-02.bpch', 'v9-01-01.bpch, $
TRACER=6, LEVEL=1, $
LON=[-90,-30], LAT=[30,15]
; Creates a 4-panel difference plot for ISOPRENE
; (IJ-AVG-$, tracer #6) at the surface for the Amazon
; basin region from data in 2 different model versions.
MODIFICATION HISTORY:
bmy, 16 May 2011: VERSION 1.00
bmy, 13 Jan 2014: GAMAP VERSION 2.17
- Bug fix: For 2-D data blocks that lack the
GRIDINFO.ZMID tag name, display the altitude
of the data as 0.0 km.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plotdiff4.pro)
NAME:
CTM_PLOTRATIO
PURPOSE:
Plots the ratio of two CTM data fields. This is one way
to see if two model versions produce identical results.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_PLOTRATIO, DIAGN [, Keywords ]
INPUTS:
DIAGN -> A diagnostic number or category to restrict
the record selection. Default is "IJ-AVG-$".
KEYWORD PARAMETERS:
FILE1 -> Name of the first CTM output file (containing the
"old" data). If FILE1 is not given, or if it contains
wildcard characters (e.g. "*"), then the user will be
prompted to supply a file name via a pickfile dialog box.
FILE2 -> Name of the second CTM output file. If FILE2
is not given, or if it contains wildcard characters
(e.g. "*"), then the user will be prompted to supply
a file name via a pickfile dialog box.
LON -> A 2-element vector specifying the longitude range that
will be used to make the plot. Default is [-180,180].
LAT -> A 2-element vector specifying the latitude range that
will be used to make the plot. Default is [-88,88].
LEV -> Vertical level for which to plot data. Default is 1.
TITLE -> Title string for the plot. If not specified, a
generic title string will be generated.
TRACER -> Number of the tracer for which differences
will be plotted. Default is 1.
_EXTRA=e -> Picks up extra keywords for CTM_DIFF.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==========================================
CTM_CLEANUP CTM_GET_DATABLOCK (function)
CTM_DIFF EXTRACT_FILENAME (function)
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL
REQUIREMENTS:
None
NOTES:
(1) The ratio plotted will be DATA2 / DATA1, where DATA2
is contained in FILE2, and DATA1 is contained in FILE1.
(2) For places where DATA1 = 0, DATA2 will also be set to 0.
This avoids division by zero errors.
(3) CTM_PLOTRATIO calls CTM_CLEANUP each time to remove
previously read datablock info from the GAMAP common
block.
EXAMPLE:
FILE1 = 'ctm.bpch.v4-30'
FILE2 = 'ctm.bpch.v4-31'
CTM_PLOTRATIO, 'IJ-AVG-$', $
FILE1=FILE1, FILE2=FILE2, TRACER=1, LEV=1
; Plots the ratio of NOx data at the surface:
; ctm.bpch.v4-31 / ctm.bpch.v4-30
MODIFICATION HISTORY:
bmy, 24 Apr 2002: GAMAP VERSION 1.50
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plotratio.pro)
NAME:
CTM_PLOT_TIMESERIES
PURPOSE:
Plots station timeseries data (e.g. from the GEOS-CHEM
ND48 diagnostic) contained in binary punch file format.
%%%% MAY NEED UPDATING %%%%%
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_PLOT_TIMESERIES, CATEGORY [ , Keywords ]
INPUTS:
CATEGORY -> The diagnostic number (e.g. ND22, ND45, etc or
category name (e.g. "JV-MAP-$", "IJ-AVG-$") for which to
read data from the punch file.
KEYWORD PARAMETERS:
BOTTOM -> The lowest color index of the colors to be loaded
used in the color map and color bar. The default is
to use the value in system variable !MYCT.BOTTOM.
COLOR -> Color of the plot window and/or data. The default
is to use the system variable !MYCT.BLACK.
LABELSTRU -> Returns to the calling program the structure
of label information obtained by CTM_LABEL.
LEV -> An index array of sigma levels *OR* a two-element
vector specifying the min and max sigma levels to be
included in the plot. Default is [ 1, GRIDINFO.LMX ].
OVERPLOT -> Plot data atop the previous plot window, instead
of erasing the screen and plotting in a new window.
RESULT -> A named variable will contain the data subset that
was plotted together with the X and/or Y coordinates in
a structure.
TITLE -> Top title string for the plot. If not passed,
then a default title string will be printed.
UNIT -> Name of the unit that the DATA array will be converted
to. If not specified, then no unit conversion will be done.
XTITLE -> X-Axis title string for the plot. If not passed,
then a default title string will be printed.
YTITLE -> Y-Axis title string for the plot. If not passed,
then a default title string will be printed.
YRANGE -> range of y values for color scaling (default:
scale each plot seperately with data min and max)
_EXTRA=e -> Picks up extra keywords for routines called
by CTM_PLOT_TIMESERIES.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===========================================================
CTM_GET_DATA CTM_INDEX (function)
CTM_LABEL (function) GETMODELANDGRIDINFO (function)
UNDEFINE REPLACE_TOKEN (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
MODIFICATION HISTORY:
bmy, 16 Apr 2004: GAMAP VERSION 2.03
- Initial version
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plot_timeseries.pro)
NAME:
CTM_PRINTDIFF
PURPOSE:
Prints the sum of the differences between two CTM
output files. This is a quick way of ensuring that
two model versions are producing identical results.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_PRINTDIFF, DIAGN [, Keywords ]
INPUTS:
DIAGN -> A diagnostic number or category to restrict
the record selection (default is: "IJ-AVG-$").
KEYWORD PARAMETERS:
FILE1 -> Name of the first CTM output file (the "old" file).
If FILE1 is not given, or if it contains wildcard
characters (e.g. "*"), then the user will be prompted
to supply a file name via a pickfile dialog box.
FILE2 -> Name of the second CTM output file (the "new" file).
If FILE2 is not given, or if it contains wildcard
characters (e.g. "*"), then the user will be prompted
to supply a file name via a pickfile dialog box.
TRACER -> Number of the tracer for which differences
will be plotted.
_EXTRA=e -> Picks up other keywords for CTM_GET_DATABLOCK.
OUTPUTS:
Prints the quantity:
DIFF[L] = TOTAL( DATA2[*,*,L] - DATA1[*,*,L] )
for each level L. If DIFF[L] = 0 for all levels L, then
FILE1 and FILE2 contain identical data.
SUBROUTINES:
External Subroutines Required:
==============================
CTM_CLEANUP
CTM_GET_DATABLOCK (function)
REQUIREMENTS:
None
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 )
(2) CTM_PRINTDIFF calls CTM_CLEANUP each time to remove
previously read datablock info from the GAMAP common
block.
EXAMPLE:
FILE1 = 'ctm.bpch.v4-30' ; the "old" file
FILE2 = 'ctm.bpch.v4-31' ; the "new" file
CTM_PRINTDIFF, 'IJ-AVG-$', $
FILE1=FILE1, FILE2=FILE2, TRACER=1
IDL prints:
Level: 26 Difference: -2.3841858e-07
Level: 25 Difference: 0.0000000e+00
Level: 24 Difference: 0.0000000e+00
Level: 23 Difference: 0.0000000e+00
Level: 22 Difference: -1.4901161e-08
Level: 21 Difference: 0.0000000e+00
Level: 20 Difference: 0.0000000e+00
Level: 19 Difference: 0.0000000e+00
Level: 18 Difference: 0.0000000e+00
Level: 17 Difference: 0.0000000e+00
Level: 16 Difference: 0.0000000e+00
Level: 15 Difference: 0.0000000e+00
Level: 14 Difference: -7.4505806e-09
Level: 13 Difference: 0.0000000e+00
Level: 12 Difference: 0.0000000e+00
Level: 11 Difference: 0.0000000e+00
Level: 10 Difference: 0.0000000e+00
Level: 9 Difference: 0.0000000e+00
Level: 8 Difference: 0.0000000e+00
Level: 7 Difference: 0.0000000e+00
Level: 6 Difference: 0.0000000e+00
Level: 5 Difference: 0.0000000e+00
Level: 4 Difference: 0.0000000e+00
Level: 3 Difference: 0.0000000e+00
Level: 2 Difference: 0.0000000e+00
Level: 1 Difference: 0.0000000e+00
; Prints the sum of differences at each level
; betweeen two GEOS-STRAT binary punch files
; for NOx (tracer=1).
MODIFICATION HISTORY:
bmy, 04 Apr 2002: GAMAP VERSION 1.50
bmy, 22 Apr 2002: - now takes diff of DATA2 - DATA1, in order
to be consistent with CTM_PLOTDIFF.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_printdiff.pro)
NAME:
CTM_PRINT_DATAINFO
PURPOSE:
Create and print a formatted list of DATAINFO records.
This procedure can be used for direct printing, but it
can also return a string array of the formatted output
e.g. for use in a widget list.
CATEGORY:
GAMAP Internals, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_PRINT_DATAINFO,DATAINFO [,keywords]
INPUTS:
DATAINFO -> One or more DATAINFO records, e.g. the result
from CTM_GET_DATA.
KEYWORD PARAMETERS:
FIELDS -> (*** not yet implemented ***) A list of fields
(structure tag names) to be printed. Default is
CATEGORY, ILUN, TRACERNAME, TRACERNUMBER,
UNIT, TAU0, STATUS, DIMENSIONS
FIELDS can also include tags from the (global) FILEINFO
structure (e.g. FILENAME).
OUTPUT -> A named variable that will contain a string array
with the formatted output including the title line but
without the seperating lines. The title is not included
if keyword /NOTITLE is set.
/NOPRINT -> Don't print, only return formatted strings
/NOTITLE -> Do not generate title line (will neither be printed
nor included in OUTPUT.
OUTPUTS:
None
SUBROUTINES:
External subroutines required:
------------------------------
GAMAP_CMN (include file)
TAU2YYMMDD (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
For GISS, FSU family of models, TAU0 = 0 occurs on date 1/1/1980.
For GEOS family of models, TAU0 = 0 occurs on date 1/1/1985.
Therefore, the model family must be obtained from the global
FILEINFO structure in order to display the YYMMDD
corresponding to TAU0.
EXAMPLE:
CTM_GET_DATA,DataInfo,File='',tracer=2
CTM_PRINT_DATAINFO,DataInfo
; *or*
CTM_PRINT_DATAINFO,DataInfo,Output=r,/NOPRINT
MODIFICATION HISTORY:
mgs, 10 Nov 1998: VERSION 1.00
bmy, 11 Feb 1999: VERSION 1.01
- adjust format for double-precision TAU0
mgs, 16 Mar 1999: - added tracer number and removed STATUS
- made cosmetic changes
mgs, 23 Mar 1999: - print dimension as NA if not yet available
bmy, 27 Apr 1999: - widen tracer number field to 6 chars
mgs, 22 Jun 1999: - widen unit field to 12 chars and add DATE field
bmy, 27 Jul 1999: VERSION 1.42
- GISS/FSU YYMMDD values are now correct
- cosmetic changes
bmy, 10 Aug 1999: - change I6 format for date to I6.6
so that leading zeroes are printed
bmy, 03 Jan 2000: VERSION 1.44
- change I6.6 format to I8.8 and print the
date in YYYYMMDD format for Y2K compliance
- declare TAU2YYMMDD as external with the
FORWARD_FUNCTION command
bmy, 14 Feb 2001: GAMAP VERSION 1.47
- decrease tracer name from 10 to 7 chars
- Now use 10-digit date string YYYYMMDDHH
bmy, 02 Jul 2001: GAMAP VERSION 1.48
- now assume that GENERIC grids use GEOS
time epoch for NYMD2TAU
bmy, 21 Oct 2002: GAMAP VERSION 1.52
- now assume MOPITT grid uses GEOS epoch
- deleted obsolete code
bmy, 03 May 2005: GAMAP VERSION 2.04
- wrap tracer number into 5 digits
- GCAP uses the same TAU values as GEOS models
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy 24 Jan 2014: GAMAP VERSION 2.17
- Adjust output format string to allow for
a few extra spaces in UNIT and TRACER #.
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_print_datainfo.pro)
NAME:
CTM_READ3DB_HEADER
PURPOSE:
retrieve header information and file positions of data
blocks from binary global 3D model output. This is a
twin of CTM_READ3DP_HEADER which digests the header
information from ASCII punch files.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
test = CTM_READ3DB_HEADER(LUN,FILEINFO,DATAINFO [,keywords])
INPUTS:
LUN --> logical file unit of the binary punch file. The file
must be open (see CTM_OPEN_FILE or OPEN_FILE)
FILEINFO --> a (single) fileinfo structure containing information
about the (open) file (see CREATE3DFSTRU). FILEINFO also
contains information about the model which generated
the output (see CTM_TYPE)
DATAINFO --> a named variable that will contain an array of
structures describing the file content (see
CREATE3DHSTRU)
KEYWORD PARAMETERS:
PRINT -> if activated, print all headers found in the file
OUTPUTS:
The function returns 1 if successful, and 0 otherwise.
FILEINFO --> toptitle and modelinfo tags will be set
DATAINFO --> contains an array of named structures
(see CREATE3DHSTRU) with all relevant information
from the punch file header and what is needed to find
and load the data.
SUBROUTINES:
REQUIREMENTS:
uses CREATE3DHSTRU function to create header structure
uses CHKSTRU to test FILEINFO structure
uses CTM_TYPE to create modelinfo structure
needs gamap_cmn.pro to access global common block
NOTES:
This routine uses the new binary file format introduced
first to the GEOS/Harvard CTM.
EXAMPLE:
fileinfo = create3dfstru() ; not required !
fname = '~bmy/terra/CTM4/results/ctm.bpch'
open_file,fname,ilun,/F77_UNFORMATTED ; <=== !!
if (ilun gt 0) then $
result = CTM_READ3DB_HEADER(ilun,fileinfo,datainfo)
print,result
To get e.g. all scaling factors, type
print,datainfo[*].scale
To retrieve the header structure for one data block, type
blocki = datainfo[i]
MODIFICATION HISTORY:
mgs, 15 Aug 1998: VERSION 1.00
- derived from CTM_READ3DP_HEADER
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 14 Jan 1999: - now expects diag category name instead
of number
bmy, 11 Feb 1999: - change TAU0, TAU1 to double-precision,
in accordance w/ new binary file format
- clean up some POINT_LUN calls
bmy, 22 Feb 1999: VERSION 1.01
- now store I0, J0, L0 from binary file
in new FIRST field from CREATE3DHSTRU
- comment out assignment statement for
SKIP; now use value from binary file
mgs, 16 Mar 1999: - cosmetic changes
mgs, 24 May 1999: - now supports 'CTM bin 02' files
- added a filetype check
- now defaults to 512 records (former 4096)
mgs, 27 May 1999: - fixed bug with new record default: new
records were never added as they were
supposed to.
bmy, 26 Jul 1999: - also print out SKIP field in debug output
bmy, 10 Jul 2003: GAMAP VERSION 1.53
- added kludge so that GEOS-3 reduced grid
w/ 30 layers will be added to FILEINFO
correctly
bmy, 21 Nov 2003: GAMAP VERSION 2.01
- BPCH file v1 now has FILETYPE=101
- BPCH file v2 now has FILETYPE=102
- Now define separate DATAINFO.FORMAT values
for BPCH v1 and BPCH v2 type files
- removed kludge for GEOS3_30L, since the
bug in CTM_TYPE has now been fixed
bmy, 24 Aug 2004: GAMAP VERSION 2.03
- now assign FORMAT string for Filetype 105
which is BPCH file for GEOS-CHEM station
timeseries (e.g. ND48 diagnostic)
phs & bmy, 13 Jul 2007: GAMAP VERSION 2.10
- Now account for FILETYPE=106, which
denotes CTM bpch files w/ 4-D data.
bmy, 23 Feb 2012: GAMAP VERSION 2.16
- Now make FILEPOS and NEWPOS LONG64
variables, in order to read bpch files
larger than 2.4 GB.
bmy, 20 Jan 2016: GAMAP VERSION 2.19
- Bug fix: cast SKIP variable to LONG64
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read3db_header.pro)
NAME:
CTM_READ3DP_HEADER
PURPOSE:
retrieve header information and file positions of data
blocks from global 3D model punch file output.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
test = CTM_READ3DP_HEADER(LUN,FILEINFO,DATAINFO [,keywords])
INPUTS:
LUN --> logical file unit of the punch file. The file
must be open (see CTM_OPEN_FILE or OPEN_FILE)
FILEINFO --> a (single) fileinfo structure containing information
about the (open) file (see CREATE3DFSTRU). FILEINFO also
contains information about the model that generated the
data, which is queried interactively.
DATAINFO --> a named variable that will contain an array of
structures describing the file content (see
CREATE3DHSTRU)
KEYWORD PARAMETERS:
/NO_TOPTITLE --> do not interprete first line of file as
header line. Only one header line will be skipped
(as normally only one header line is read in).
/EXTRA_SPACE -> digests output from GISS_II_PRIME model with
extra spaces in the punch file. This keyword is optional
in the following sense: If CTM_READ3DP_HEADER detects
an error reading a header line, it is called again
automatically with this option set.
PRINT -> if activated, print all headers found in the file
OUTPUTS:
The function returns 1 if successful, and 0 otherwise.
FILEINFO --> toptitle and modelinfo tags will be set
DATAINFO --> contains an array of named structures
(see CREATE3DHSTRU) with all relevant information
from the punch file header and what is needed to find
and load the data.
SUBROUTINES:
REQUIREMENTS:
uses CREATE3DHSTRU function to create header structure
uses CHKSTRU to test FILEINFO structure
uses CTM_TYPE to set modelinfo
needs gamap_cmn.pro to set default in query for model type
NOTES:
This routine does rely on the output format from the global GCM
as specified first for the GEOS/Harvard CTM. However, it is
designed to digest the output from all models currently used
in DJJ's group.
It uses the NL parameter to skip blocks between headers.
The window offsets (I0, J0, L0) are set to
zero, since the ASCII punch file is not set up to save
a sub-region of the globe (bmy, 2/11/99)
EXAMPLE:
fileinfo = create3dfstru() ; not required !
fname = '~bmy/terra/CTM4/results/ctm.pch.m2'
open_file,fname,ilun
if (ilun gt 0) then $
result = ctm_read3dp_header(ilun,fileinfo,datainfo)
print,result
To get e.g. all scaling factors, type
print,datainfo[*].scale
To retrieve the header structure for one data block, type
blocki = datainfo[i]
MODIFICATION HISTORY:
mgs, 21 Aug 1997: VERSION 1.00
mgs, 02 Mar 1998: VERSION 1.10
- can handle GEOS output now
- reads in file header
- returns structure instead of string array
- always returns all entries, filtering must be done later
mgs, 03 Mar 1998: - now returns a structure and is a function
mgs, 04 Mar 1998: - toptitle is now default, changed keyword to
NO_TOPTITLE ; eliminated search for '!' or '%'
mgs, 10 Mar 1998: - rewritten again, now with named structure
returned as DATAINFO. Skipping of data blocks
drastically improved by setting the file pointer
instead of reading the lines.
mgs, 16 May 1998: - removed DATATYPE3DP function, set type tag to -1
- added EXTRA_SPACE option for GISS_II_PRIME output and
LINELENGTH keyword for full flexibility
- now ignores time series ('TS...') data
mgs, 13 Aug 1998: - format string now composed here, not in
read3dp_data
mgs, 14 Aug 1998: VERSION 2.00 - major changes!
- now requires open file and uses ILUN parameter
- automatic EXTRA_SPACE detection
- fileinfo structure not created any more, and only
extended if present (chkstru)
- error messages as dialog box
- LINELENGTH keyword removed
mgs, 15 Aug 1998: - now calls select_model and inserts model
information in fileinfo structure
- gamap_cmn.pro included for default model name
- had to change DEBUG keyword into PRINT
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 26 Oct 1998: - now resets error state in no_dim
mgs, 14 Jan 1998: - new lcount for line counting in error report
- linelength adjusted for working in Windows (CR/LF)
bmy, 11 Feb 1999: VERSION 2.01
- Add window offsets (I0,J0,L0) to DATAINFO
- save DATAINFO.TAU0 and DATAINFO.TAU1 as double precision
bmy, 17 Feb 1999: VERSION 2.02
- changed to accommodate the FIRST field (instead of OFFSET)
of the DATAINFO structure, which contains
the I, J, L indices of the first grid box
bmy, 01 Mar 1999:
- bug fix! NL needs to be a longword, so that
we can read 2 x 2.5 punch files correctly!!
mgs, 23 Mar 1999:
- cleaned up reading of dimensions from label a little
mgs, 27 May 1999:
- new default number of records is 512 instead of 4096.
- bug fix: new records were never appended.
mgs, 22 Jun 1999:
- bug fix: "title" needed to be trimmed.
bmy, 20 Jan 2000: FOR GAMAP VERSION 1.44
- !ERR is now replaced by !ERROR_STATE.CODE
- !ERR_STRING is now replaced by !ERROR_STATE.MSG
- I/O error trapping is now done by testing error
messages instead of testing for error numbers
- cosmetic changes, updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read3dp_header.pro)
NAME:
CTM_READ_COARDS
PURPOSE:
Reads data blocks from a COARDS-compliant netCDF file (such
as created by routine BPCH2COARDS) into GAMAP. CTM_READ_COARDS
is is an internal routine which is called by CTM_OPEN_FILE.
NOTE: COARDS is a formatting standard for netCDF files which
is widely used in both the atmospheric & climate communities.
COARDS-compliant netCDF files can be read by GAMAP, GrADS and
other plotting packages.
See http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html
for more information about the COARDS standard.
CATEGORY:
GAMAP Internals, Scientific Data Formats
CALLING SEQUENCE:
CTM_READ_COARDS, [, Keywords ]
INPUTS:
ILUN -> GAMAP file unit which will denote the netCDF file.
FILENAME -> Name of the netCDF grid file to be read.
FILEINFO -> Array of FILEINFO structures which will be
returned to CTM_OPEN_FILE. CTM_OPEN_FILE will
append FILEINFO to the GAMAP global common block.
DATAINFO -> Array of DATAINFO structures (each element
specifies a GAMAP data block) which will be returned
to CTM_OPEN_FILE. CTM_OPEN_FILE will append FILEINFO
to the GAMAP global common block.
KEYWORD PARAMETERS:
_EXTRA=e -> Picks up extra keywords
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
====================================================
CRC_Get_DimInfo CRC_Get_IndexVars
CRC_Read_Global_Atts CRC_Get_Tracer
CRC_Get_Data CRC_Save_Data
External Subroutines Required:
====================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_MAKE_DATAINFO (function) STRRIGHT (function)
STRREPL (function)
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) Assumes that data blocks have the following dimensions:
(a) longitude, latitude, time
(b) longitude, latitude, levels, time
(2) Assumes that times are given in GMT.
(3) If information about each tracer in the COARDS-compliant
netCDF file is stored in the GAMAP "tracerinfo.dat" file,
then CTM_READ_COARDS will be able to read the file without
having to ask the user to supply a GAMAP category and
tracer name.
EXAMPLE:
ILUN = 21
FILENAME = 'coards.20010101.nc'
CTM_READ_COARDS, ILUN, FILENAME, FILEINFO, DATAINFO
; Reads data from the COARDS-compliant netCDF file
; coards.20010101.nc and stores it the FILEINFO and
; DATAINFO arrays of structures. If you are calling
; CTM_READ_COARDS from CTM_OPEN_FILE, then CTM_OPEN_FILE
; will append FILEINFO and DATAINFO to the GAMAP global
; common block.
MODIFICATION HISTORY:
bmy, 21 Mar 2005: GAMAP VERSION 2.03
bmy, 21 Jul 2005: GAMAP VERSION 2.04
- bug fix in CRC_SAVE_DATA
bmy, 06 Mar 2006: GAMAP VERSION 2.05
- minor bug fix in CRC_READ_GLOBAL_ATTS
- bug fix in CRC_SAVE_DATA: add a fake 4th
dim to DATA array if needed
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 16 Sep 2008: GAMAP VERSION 2.13
- Convert some global attributes to number
types in case attributes were initially
saved to the netCDF file as strings
phs, 15 Sep 2009: - Added check on reading tracerinfo.dat
- Convert some tracer names created by
BPCH2COARDS to their original value.
bmy, 14 Dec 2011: GAMAP VERSION 2.16
- Updated to read the GAMAP category value
from a netCDF variable attribute (if present)
bmy, 19 Dec 2011: - Generalized to handle several different
vertical levels
bmy, 21 Dec 2011: - Now will interpret netCDF attributes
"begin_date" and "begin_time" in the same
way as "start_date" and "start_time"
bmy, 22 Dec 2011: - Now compute FIRST (nested datablock offsets)
properly for nested grids. For now assume
that the data will always start on the first
vertical level.
- Bug fix: test for Latrev gt 0 to avoid
INADVERTENTLY reversing latitudes
bmy, 03 Jan 2012: - Skip over Ap and Bp index arrays
- Now use better error checks for
the time and vertical level dimensions
for each tracer in the netCDF file.
bmy, 05 Jan 2012: - Now interpret DELTA_TIME attribute
correctly when specified in hhmmss format.
bmy, 10 Jan 2012: - Fix to interpret data blocks with multiple
vertical dimensions in the same file
bmy, 13 Jan 2012: - When the time dimension in the netCDF
file is 1 (esp. when time is an UNLIMITED
variable, we need to add a fake dimension
of 1 back onto the data block to avoid
crashes. This is a quirk in how the IDL
NCDF_VARGET function works.
bmy, 23 Jan 2017: GAMAP VERSION 2.19
- Add modifications to read netCDF restart files
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_coards.pro)
NAME:
CTM_READ_DATA
PURPOSE:
read in one data block from a global model punch file output
(ASCII or binary)
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_READ_DATA,data,datainfo
or:
CTM_READ_DATA,data,ilun,filepos,xsize,ysize[,zsize,keywords]
INPUTS:
DATAINFO -> a datainfo structure as retrieved from
CTM_OPEN_FILE. This is the easiest way to read 3D
model output. Alternatively, the individual parameters
can be specified as follows.
ILUN -> logical file unit of input file (must be opened before)
FILEPOS -> a long word containing the start position of the data
block to be read (normally retrieved by CTM_OPEN_FILE)
XSIZE -> 1st dimension of the data array
YSIZE -> 2nd dimension of the data array
ZSIZE -> optional 3rd dimension of the data array
KEYWORD PARAMETERS:
Note: These keywords are ineffective when parameters are passed
via the DATAINFO structure!
SCALE -> apply scaling factor to data (default = 1.0)
FORMAT -> string with format identifier for data block
Default is '(12f6.2)'. Use '(8e10.3)' for BUDGETS output and
'(12(f6.2,1x))' for "extra_space" output. Format='BINARY'
indicates a binary file with REAL*4 data. (As long as the
dimensions are specified correctly ANY binary file can
be read this way, i.e. there is no need for additional
routines to read in e.g. gridded emission data files)
RESULT -> will return 1 if successful, 0 otherwise
OUTPUTS:
DATA -> a float array containing the block of data which is
either a 2D or a 3D array.
SUBROUTINES:
REQUIREMENTS:
file must have been opened and file positions of the data block
must be known (see CTM_OPEN_FILE)
NOTES:
The data array is *not* added to the datainfo structure!
EXAMPLE:
; Open a punch file interactively
CTM_OPEN_FILE,'',fileinfo,datainfo
; Test if successful
IF (not chkstru(datainfo)) then return
; Read in data of first data block
CTM_READ_DATA,data,datainfo[0]
; This is equivalent to:
CTM_READ_DATA,data,fileinfo.ilun,datainfo[0].filepos, $
datainfo[0].dim[0],datainfo[0].dim[1],datainfo[0].dim[2], $
scale=datainfo[0].scale,format=datainfo[0].format
MODIFICATION HISTORY:
mgs, 13 Aug 1998: VERSION 1.00 (from CTM_READ3DP_DATA)
- replaced EFORMAT keyword by more flexible
FORMAT keyword (involves changes in
CTM_READ3DP_HEADER and CREATE_3DHSTRU)
mgs, 17 Aug 1998: VERSION 2.00
- now possible to pass DATAINFO structure
- made it necessary to place DATA argument
as first parameter
mgs, 19 Aug 1998: - added RESULT keyword
mgs, 26 Oct 1998: - changed print statements to message
- user is now prompted when dimensions
are not given
bmy, 07 Apr 2000: - Added DAO keyword for reading in DAO met fields
bmy, 11 Apr 2001: - now uses DATA = TEMPORARY( DATA ) * SCALE[0]
in order to prevent excess memory usage
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- Removed GMAO keyword, we now use the
FORMAT string to test for GMAO data files
phs & bmy, 13 Jul 2007: GAMAP VERSION 2.10
- Modified for 4-D data blocks
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_data.pro)
NAME:
CTM_READ_EOSGR
PURPOSE:
Reads data blocks from a HDF-EOS Grid file into GAMAP.
(This is an internal routine which is called by CTM_OPEN_FILE.)
CATEGORY:
GAMAP Internals, Scientific Data Formats
CALLING SEQUENCE:
CTM_READ_EOSGR, ILUN, FILENAME, FILEINFO, DATAINFO, [, Keywords ]
INPUTS:
ILUN -> GAMAP file unit which will denote the HDF-EOS file.
FILENAME -> Name of the HDF-EOS grid file to be read.
FILEINFO -> Array of FILEINFO structures which will be
returned to CTM_OPEN_FILE. CTM_OPEN_FILE will
append FILEINFO to the GAMAP global common block.
DATAINFO -> Array of DATAINFO structures (each element
specifies a GAMAP data block) which will be returned
to CTM_OPEN_FILE. CTM_OPEN_FILE will append FILEINFO
to the GAMAP global common block.
KEYWORD PARAMETERS:
_EXTRA=e -> Picks up any extra keywords
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
=====================================================
CRE_Get_DimInfo CRE_Get_TracerInfo CRE_Save_Data
External Subroutines Required:
=====================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_MAKE_DATAINFO (function) STRRIGHT (function)
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) Currently is set up to read HDF-EOS files containing
GMAO met data files. You must have all possible met
field names listed in your "tracerinfo.dat" file or
else you will get an "Invalid Selection" error.
EXAMPLE:
ILUN = 21
FILENAME = 'a_llk_03.tsyn2d_mis_x.t20030801'
CTM_READ_EOSGR, ILUN, FILENAME, FILEINFO, DATAINFO
; Reads data from HDF-EOS file a_llk_03.tsyn2d_mis_x.t20030801
; and stores it the FILEINFO and DATAINFO arrays of
; structures. If calling CTM_READ_GMI from CTM_OPEN_FILE,
; then CTM_OPEN_FILE will append FILEINFO and DATAINFO
; to the GAMAP common block.
MODIFICATION HISTORY:
bmy, 12 Nov 2003: GAMAP VERSION 2.01
- initial version
bmy, 19 Feb 2004: GAMAP VERSION 2.01a
- added c402_rp_02 to the assim list
- bug fix: use DEFAULT keyword for SELECT_MODEL
bmy, 09 Mar 2004: GAMAP VERSION 2.02
- now test for "GEOS3", "GEOS4" strings in
the file name to determine model type
- now undefine variables after use
- now make sure that data block begins at the
date line and has longitude values in the
range [-180,180] degrees.
- always ensure that L=1 is the surface level
bmy, 25 Aug 2004: GAMAP VERSION 2.03
- Added c402_cer to the assim list
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Remove reference to unused SORT_STRU
bmy, 05 Dec 2007: GAMAP VERSION 2.12
- Modified for DAS.llk.asm files
bmy, 01 Oct 2008: GAMAP VERSION 2.13
- Increase DI, DJ in CRE_GET_DIMINFO for
the 0.5 x 0.667 grid
- Also now test for GEOS-5 in the filename
in CRE_GET_DIMINFO
- Bug fix in CRE_SAVE_DATA: If there is
only one data time in the HDF-EOS file,
then add an extra dimension to THISDATA
so that the CASE statement will be
interpreted properly.
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_eosgr.pro)
NAME:
CTM_READ_GMAO
PURPOSE:
Reads GMAO I-6,(instantaneous 6h), A-6 (average 6h),
or A-3 (average 3-h) met field files, and constructs
a DATAINFO structure for each met field.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
Result = CTM_READ_GMAO( Ilun, FileInfo, DataInfo [, Keywords ] )
INPUTS:
ILUN --> The name of the input file (or a file mask).
FILENAME is passed to OPEN_FILE. If FILENAME is a null
string or a file mask, then OPEN_FILE will open a
pickfile dialog box.
FILEINFO --> a (single) fileinfo structure containing information
about the (open) file (see CREATE3DFSTRU). FILEINFO also
contains information about the model which generated
the output (see CTM_TYPE)
DATAINFO --> a named variable that will contain an array of
structures describing the file content (see
CREATE3DHSTRU)
KEYWORD PARAMETERS:
PRINT -> if activated, print all headers found in the file
OUTPUTS:
The function returns 1 if successful, and 0 otherwise.
FILEINFO --> toptitle and modelinfo tags will be set
DATAINFO --> contains an array of named structures
(see CREATE3DHSTRU) with all relevant information
from the punch file header and what is needed to find
and load the data.
SUBROUTINES:
Internal Subroutines:
================================================
CRG_GET_MODELINFO
External Subroutines Required:
================================================
CHKSTRU (function) CTM_GRID (function)
CTM_TYPE (function) CREATE3DHSTRU (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) You must also add additional met field names to your
"tracerinfo.dat" file as is neccesary. CTM_READ_GMAO looks
up met fields stored under the GAMAP categories "GMAO-2D"
and "GMAO-3D$".
(2) GEOS-4 met field files have an 8-char ident string
of the format "G4 45 19", where:
(a) "G4" means that it is a GEOS-4 met field file/
(b) "45" is the resolution code (in this case 4x5).
(c) "19" is the number of met fields stored w/in the file.
CTM_READ_GMAO will now set the modeltype and resolution from
the information in this ident string. For older met field
types (e.g. GEOS-3) which do not have this ident string,
CTM_READ_GMAO will determine the modeltype and resolution
from the filename and date.
EXAMPLES:
FileInfo = CREATE3DFSTRU() ; not required !
FName = '/r/amalthea/N/scratch/bmy/960101.a3.4x5'
OPEN_FILE, FName, Ilun, /F77_Unformatted
if ( Ilun gt 0 ) $
then Result = CTM_READ_GMAO( Ilun, FileInfo, DataInfo )
print,result
MODIFICATION HISTORY:
bmy, 16 May 2000: GAMAP VERSION 1.45
- adapted from original program "read_gmao"
bmy, 12 Jun 2000: - declare XYMD and XHMS as integers for
GEOS-2 and GEOS-3 data
bmy, 28 Jul 2000: GAMAP VERSION 1.46
- added GEOS-3 names to list of recognized fields
- deleted a couple of field names we don't use
bmy, 25 Sep 2000: - added new field: SLP (sea level pressure)
bmy, 08 Dec 2000: GAMAP VERSION 1.47
- added new fields: TKE, RH, KH
bmy, 07 Mar 2001: - added new fields: CLDTMP, TPW
bmy, 25 Apr 2001: - added new fields: TAULOW, TAUMID, TAUHI
bmy, 26 Jul 2001: GAMAP VERSION 1.48
- added new field: T2M
bmy, 15 Aug 2001: - added new field: OPTDEPTH
bmy, 06 Nov 2001: GAMAP VERSION 1.49
- added new field: DELP
- changed units from "mb" to "hPa"
bmy, 29 Jan 2002: GAMAP VERSION 1.50
- added new field: GWET
- removed obsolete code from 11/6/01
bmy, 01 May 2002: - added GWETTOP as synonym for GWET
- now assign correct units for fvDAS/GEOS-4
CLDMAS and DTRAIN fields: kg/m2/s
- now assign correct units for fvDAS/GEOS-4
PBL field: m (instead of hPa)
bmy, 17 Jul 2002: GAMAP VERSION 1.51
- added PBLH, Z0M, Z0H fields for fvDAS/GEOS-4
bmy, 16 Dec 2002: GAMAP VERSION 1.52:
- added new fvDAS fields: CMFDTR, CMFETR,
ZMDU, ZMED, ZMEU, ZMMD, ZMMU, HKETA, HKBETA
bmy, 21 May 2003: GAMAP VERSION 1.53:
- added T, U, V as synonyms of TMPU, UWND, VWND
- added Q as a synonym of SPHU
- removed CMFDTR, CMFETR fields
- HKBETA is now #18; HKETA is now #19
- updated comments
- added EVAP field as tracer #28
- TGROUND and T2M are now tracers #29, #30
- LAI is now tracer #31
- PARDF, PARDR are now tracers #32, 33
bmy, 30 Jul 2003: - added TSKIN as a synonym for TGROUND
bmy, 12 Dec 2003: GAMAP VERSION 2.01
- renamed to CTM_READ_GMAO to reflect the
change of name from "DAO" to "GMAO".
- GMAO binary files now have FILETYPE=104
- Rewrote so that we don't have to hardwire
met field names...it now gets the met
field names from "tracerinfo.dat"
- Now gets modeltype and resolution info
from GEOS-4 ident string
- Added internal function CRG_GET_MODELINFO
to generate the MODELINFO structure based
on the filename and date.
- Improved error output if we can't find
the tracer name
bmy & phs, 03 Aug 2007: GAMAP VERSION 2.10
- Ident string value "56" now will specify
a grid with 0.5 x 0.666 degree resolution
- Ident string value "10" now will specify
a grid with 1.0 x 1.0 degree resolution
- Now don't reset ILUN for GEOS-5 files
- Now call EXTRACT_FILENAME in CRG_GET_MODELINFO
to get just the filename instead of the full
path name.
- Adjusted for GEOS-5 fields with LMX+1 levels
- Bug fix: set null strings if GMAO-2D and/or
GMAO-3D$ categories aren't found
- Bug fix: change "gt" to "ge" in IF statements
where NAME2D, NAME3D, etc. are defined.
- Now use IS_EDGED
- Added routine CRG_GET_HORZDIM to return NI,
NJ, NL, FIRST for global or nested grids.
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Now check for MERRA grid. This is
identical to GEOS-5, but retains the
"MERRA" name for clarity.
bmy, 11 Aug 2010: - Bug fix: define STRUC array of structures
with 1024 entries. 512 is not enough for
the hourly MERRA data.
bmy, 17 Aug 2010: - Bug fix: define STRUC array of structures
with 2048 entries. 1024 may not be
enough for the hourly MERRA data.
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_gmao.pro)
NAME:
CTM_READ_GMI
PURPOSE:
Reads data blocks from a GMI netCDF file into GAMAP.
(This is an internal routine called from CTM_OPEN_FILE.)
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_READ_GMI, ILUN, FILENAME, FILEINFO, DATAINFO, [, Keywords ]
INPUTS:
ILUN -> GAMAP file unit which will denote the GMI netCDF file.
FILENAME -> Name of the GMI netCDF grid file to be read.
FILEINFO -> Array of FILEINFO structures which will be
returned to CTM_OPEN_FILE. CTM_OPEN_FILE will
append FILEINFO to the GAMAP global common block.
DATAINFO -> Array of DATAINFO structures (each element
specifies a GAMAP data block) which will be returned
to CTM_OPEN_FILE. CTM_OPEN_FILE will append FILEINFO
to the GAMAP global common block.
KEYWORD PARAMETERS:
_EXTRA=e -> Picks up extra keywords
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
===============================================
CRG_Debug_Print CRG_Get_Name CRG_Get_Tau0
CRG_Get_Tracer CRG_Get_Data CRG_Save_Data
External Subroutines Required:
===============================================
CTM_GRID (function) CTM_TYPE (function)
NCDF_GET (function) TVMAP
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) Currently is hardwired to reading in data blocks
from netCDF files created for the GMI comparison
study. It is difficult to create a general netCDF
reader since there are many different ways to store
data w/ in a netCDF file.
EXAMPLE:
ILUN = 21
FILENAME = 'gmit4_maccm3_year_CO.nc'
CTM_READ_GMI, ILUN, FILENAME, FILEINFO, DATAINFO
; Reads data from the netCDF file gmit4_maccm3_year_CO.nc
; and stores it the FILEINFO and DATAINFO arrays of
; structures. If calling CTM_READ_GMI from CTM_OPEN_FILE,
; then CTM_OPEN_FILE will append FILEINFO and DATAINFO
; to the GAMAP common block.
MODIFICATION HISTORY:
bmy, 05 Nov 2003: GAMAP VERSION 2.01
- initial version
bmy, 13 Feb 2004: GAMAP VERSION 2.01a
- bug fix: now should get multiple months
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_gmi.pro)
NAME:
CTM_READ_MULTILEVEL
PURPOSE:
Read all levels of a multilevel diagnostic (e.g. IJ-AVG-$)
and return a 3D data block. The associated datainfo structure
must be created before and passed into this routine.
This is an internal procedure which should not be used
directly.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_READ_MULTILEVEL,data,datainfo, $
Use_DataInfo=Use_DataInfo, $
Use_FileInfo=Use_FileInfo, $
result=result
INPUTS:
DATAINFO -> The datainfo structure that is to hold the new
3D data block.
KEYWORD PARAMETERS:
USE_DATAINFO, USE_FILEINFO -> The array of Datainfo and Fileinfo
stuctures to select from. Unlike the higher level routines,
CTM_READ_MULTILEVEL does not provide default values for
these!
RESULT -> A named variable that will be 1 if successful,
0 otherwise.
OUTPUTS:
DATA -> The 3D data block composed of the individual levels
from the ASCII punch file.
SUBROUTINES:
External Subroutines Required:
===========================================
EXPAND_CATEGORY CTM_DIAGINFO
CTM_DOSELECT_DATA CTM_READ_DATA
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
The dimensional information of the DATAINFO parameter is
adapted to the number of levels actually read from disk.
EXAMPLE:
See source code of CTM_RETRIEVE_DATA
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 26 Oct 1998: - made more error tolerant:
= if file ends within record, now returns
what's there
= if no dimensions were read,
assumes 72x46 and prints warning
= added status keyword
mgs, 10 Nov 1998: VERSION 3.00
- major design change
mgs, 28 Nov 1998: - hopefully fixed scaling bug now
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- Now get diagnostic spacing from CTM_DIAGINFO
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_multilevel.pro)
NAME:
CTM_READ_MULTITRACER
PURPOSE:
Read all entries of a 'multitracer' diagnostic (i.e.
source type diagnostic) and return a 3D data block.
The associated datainfo structure must be created before
and passed into this routine. This routien is meant for
internal use in the CTM_GET_DATA routines.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_READ_MULTITRACER,data,datainfo, $
Use_DataInfo=Use_DataInfo, $
Use_FileInfo=Use_FileInfo, $
result=result,debug=debug
INPUTS:
DATAINFO -> The datainfo structure that is to hold the new
3D data block.
KEYWORD PARAMETERS:
USE_DATAINFO, USE_FILEINFO -> The array of Datainfo and Fileinfo
stuctures to select from. Unlike the higher level routines,
CTM_READ_MULTILEVEL does not provide default values for
these!
RESULT -> A named variable that will be 1 if successful,
0 otherwise.
OUTPUTS:
DATA -> The 3D data block composed of the individual levels
from the ASCII punch file.
SUBROUTINES:
REQUIREMENTS:
Uses CTM_DOSELECT_DATA, CTM_READ_DATA
NOTES:
The dimensional information of the DATAINFO parameter is
adapted to the number of levels actually read from disk.
EXAMPLE:
See source code of CTM_***
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 26 Oct 1998: made more error tolerant:
- if file ends within record, now returns what's there
- if no dimensions were read, assumes 72x46 and prints warning
mgs, 10 Nov 1998: VERSION 3.00
- major design change
mgs, 28 Nov 1998:
- hopefully fixed scaling bug now
bmy & phs: 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_multitracer.pro)
NAME:
CTM_READ_NCDF
PURPOSE:
Reads data blocks from a netCDF file created by routine
BPCH2NC or BPCH2GMI into GAMAP. (This is an internal routine
which is called by CTM_OPEN_FILE.)
CATEGORY:
GAMAP Internals, Scientific Data Formats
CALLING SEQUENCE:
CTM_READ_NCDF, [, Keywords ]
INPUTS:
ILUN -> GAMAP file unit which will denote the netCDF file.
FILENAME -> Name of the netCDF grid file to be read.
FILEINFO -> Array of FILEINFO structures which will be
returned to CTM_OPEN_FILE. CTM_OPEN_FILE will
append FILEINFO to the GAMAP global common block.
DATAINFO -> Array of DATAINFO structures (each element
specifies a GAMAP data block) which will be returned
to CTM_OPEN_FILE. CTM_OPEN_FILE will append FILEINFO
to the GAMAP global common block.
KEYWORD PARAMETERS:
_EXTRA=e -> Picks up extra keywords
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
====================================================
CRN_Get_DimInfo CRN_Get_Time CRN_Get_Tracer
CRN_Read_Global_Atts CRN_Get_Data CRN_Save_Data
External Subroutines Required:
====================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_MAKE_DATAINFO (function) STRRIGHT (function)
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) Currently assumes that the netCDF file was written
by GAMAP routine BPCH2NC.
EXAMPLE:
ILUN = 21
FILENAME = 'geos.20010101.nc'
CTM_READ_NCDF, ILUN, FILENAME, FILEINFO, DATAINFO
; Reads data from the netCDF file geos.20010101.nc
; and stores it the FILEINFO and DATAINFO arrays of
; structures. If calling CTM_READ_GMI from CTM_OPEN_FILE,
; then CTM_OPEN_FILE will append FILEINFO and DATAINFO
; to the GAMAP common block.
MODIFICATION HISTORY:
bmy, 05 Nov 2003: GAMAP VERSION 2.01
- initial version
bmy, 26 Mar 2004: GAMAP VERSION 2.02
- bug fix: now correctly separates "__"
in netCDF tracer names with STRPOS
bmy, 28 Feb 2005: GAMAP VERSION 2.03
- bug fix: now also exclude ETAC from
being passed to CRN_GET_TRACER
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Modified to read files from BPCH2GMI
bmy, 19 Dec 2007: GAMAP VERSION 2.12
- Now also skip ETAE, SIGE arrays
- Also don't add any vertical info to
the GRIDINFO structure if NLAYERS=1
bmy, 24 Jan 2011: GAMAP VERSION 2.15
- Now skip over Ap and Bp index fields
in the netCDF file
bmy, 14 Dec 2011: GAMAP VERSION 2.16
- Now also check to see if the GAMAP
category string is passed via the netCDF
"gamap_category" attribute
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_ncdf.pro)
NAME:
CTM_READ_PLANEFLIGHT
PURPOSE:
Reads GEOS-CHEM plane flight diagnostic (ND40) data.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
RESULT = CTM_READ_PLANEFLIGHT( FILENAME )
INPUTS:
FILENAME -> Name of the file containing data from the GEOS-CHEM
plane following diagnostic ND40. If FILENAME is omitted,
then a dialog box will prompt the user to supply a file name.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Array of structures containing data from read from
the input file. Each different plane type will have
a structure in RESULT containing the following tags:
NPOINTS : Number of points read from the file
NVARS : Number of variables read from the file
PLATFORM : Name of plane type (e.g. DC8, P3B, FALCON)
DATE : Array w/ YYYYMMDD at each flight point [GMT date]
TIME : Array w HHMM at each flight point [GMT time]
LAT : Array w/ latitude at each flight point [degrees ]
LON : Array w/ longitude at each flight point [degrees ]
PRESS : Array w/ pressure at each flight point [hPa ]
VARNAMES : Array w/ names of each variable
DATA : Array w/ data for each variable
SUBROUTINES:
External Subroutines Required:
==========================================
OPEN_FILE STRBREAK (function) UNDEFINE
REQUIREMENTS:
None
NOTES:
We read the data into arrays first, and then save the arrays
into an IDL structure. If you read the data into an array of
structures, this executes much more slowly. Also arrays of
structures seem to suck up an inordinate amount of memory.
EXAMPLES:
PLANEINFO = CTM_READ_PLANEFLIGHT( 'plane.log.20040601' )
; Reads data from file into the PLANEINFO structure
DC8 = WHERE( PLANEINFO[*].PLATFORM eq 'DC801' )
; Look for DC8 data
PRINT, PLANEINFO[DC8].LAT[*]
PRINT, PLANEINFO[DC8].LON[*]
; Prints latitudes and longitudes of DC8 to the screen
IND = WHERE( PLANEINFO[DC8].VARNAMES eq 'TRA_004' )
CO = PLANEINFO[DC8].DATA[ *, IND ]
; Extracts CO (tracer #4 in a GEOS-CHEM fullchem
; simulation) to an array
IND = WHERE( PLANEINFO[DC8].VARNAMES eq 'GMAO_UWND' )
UWND = PLANEINFO[DC8].DATA[ *, IND ]
; Extracts U-wind information to an array
MODIFICATION HISTORY:
bmy, 23 Mar 2005: GAMAP VERSION 2.03
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_read_planeflight.pro)
NAME:
CTM_REGRIDH
PURPOSE:
Regrids data horizontally from one CTM grid to another,
for both cases:
(1) fine grid --> coarse grid OR
(2) coarse grid --> fine grid
CATEGORY:
Regridding
CALLING SEQUENCE:
NEWDATA = CTM_REGRIDH( DATA, OLDGRID, NEWGRID [ , Keywords ] )
INPUTS:
DATA -> a 2-D or 3-D data field to be regridded. DATA can be
either in single-precision or double-precision.
OLDGRID, NEWGRID -> GRIDINFO structures (use "ctm_grid.pro"
to create one) defining the old and new grids.
KEYWORD PARAMETERS:
/DOUBLE -> If set, will return NEWDATA as a double-precision
array. Default is to return NEWDATA as a floating-point
single-precision array.
/PER_UNIT_AREA -> Set this switch if the quantity you want to
regrid is per unit area or per unit volume (i.e. molec/cm2,
molec/cm3, kg/m2, etc.). CTM_REGRIDH will multiply by
the input grid's surface areas, so as to convert it to
an area-independent quantity for regridding. After the
regridding, CTM_REGRIDH will then divide the quantity
by the surface areas on the new grid.
/USE_SAVED_WEIGHTS -> If set, will use the mapping weights
saved by a prior call to CTM_REGRIDH. This is useful
if you are regridding 3-D data, thus CTM_REGRIDH can be
told only to compute the mapping weights for the first
level, thus saving processing time.
/VERBOSE -> If set, will echo informational messages to the
screen during the regridding process. Totals on both
old and new grids will also be printed.
WFILE -> Name of the file with pre-saved mapping weights from
the old grid to the new grid (created by CTM_GETWEIGHT).
If WFILE is not specified, then CTM_REGRIDH will compute
the mapping weights on the fly. These weights will be
returned to the calling program via the WEIGHT keyword
for use on subsequent calls to CTM_REGRIDH.
OUTPUTS:
NEWDATA -> a 2-D or 3-D array containing the regridded data.
SUBROUTINES:
Internal Subroutines Included:
=================================================
CRH_GETWEIGHT
External Subroutines Required:
=================================================
CHKSTRU (function) CTM_BOXSIZE (function)
CTM_GETWEIGHT UNDEFINE
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
(1) CTM_REGRIDH now supersedes CTM_REGRID. The old
CTM_REGRID program worked fine, but could only
go from fine grids to coarse grids.
(2) Assumes that you are passing globally-sized arrays.
If you have less than global-sized data, then you
must add that data to a globally sized array, and
then call CTM_REGRIDH.
EXAMPLE:
(1)
; Define old grid
OLDTYPE = CTM_TYPE( 'GENERIC', RES=[1,1], $
HALFPOLAR=0, CENTER180=0 )
OLDGRID = CTM_GRID( OLDTYPE )
; Define new grid
NEWTYPE = CTM_TYPE( 'GEOS_STRAT', RES=4 )
NEWGRID = CTM_GRID( NEWTYPE )
; Regrid data
NEWDATA = CTM_REGRIDH( DATA, OLDGRID, NEWGRID, $
/PER_UNIT_AREA, /VERBOSE )
; Regrids a quantity such as fossil fuel emissions
; in [molec/cm2/s] from the generic 1 x 1 emissions
; grid to GEOS-STRAT 4 x 5 resolution. Message info
; will be echoed to the screen during the regridding.
; The mapping weights from OLDGRID to NEWGRID will
; be computed by CTM_REGRIDH and stored internally
; for possible future use.
(2)
; Define old grid
OLDTYPE = CTM_TYPE( 'GEOS_STRAT', RES=2 )
OLDGRID = CTM_GRID( OLDTYPE )
; Define new grid
NEWTYPE = CTM_TYPE( 'GEOS_STRAT', RES=4 )
NEWGRID = CTM_GRID( NEWTYPE )
; Regrid first data array, read mapping weights from disk
NEWDATA1 = CTM_REGRIDH( DATA1, OLDGRID, NEWGRID, $
WFILE='weights_generic1x1_geos4x5.dat' )
; Regrid second data array, use weights from prior call
NEWDATA2 = CTM_REGRIDH( DATA2, OLDGRID, NEWGRID, $
/USE_SAVED_WEIGHTS )
; Regrids quantities such as air mass in [kg] from
; 2 x 2.5 resolution to 4 x 5 resolution for the
; GEOS-STRAT grid. Since WFILE is specified,
; will read the mapping weights between OLDGRID and
; from a file on disk instead of having to compute
; them online. These mapping weights will then be
; saved internally for possible future use.
;
; Note that you can specify that you want to use the
; pre-saved with the /USE_SAVED_WEIGHTS flag. This
; prevents CTM_REGRIDH from having to re-read the
; mapping weights all over again -- a real timesaver.
MODIFICATION HISTORY:
bmy, 13 Feb 2002: GAMAP VERSION 1.50
- adapted from CTM_REGRID plus
other various existing codes
bmy, 16 Jan 2003: GAMAP VERSION 1.52
- fixed a small bug which prevented flagging
coarse --> fine regridding when going from
1 x 1.25 to 1 x 1
phs, 24 Oct 2005: GAMAP VERSION 2.05
- Fix the Coarse-to-Fine case. Works as
expected for both PER_UNIT_AREA=1 and =0.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
jintai, 14 Apr 2010: GAMAP VERSION 2.14
- Added fix for NaN's
(See /n/home09/ryantosca/IDL/gamap2/regridding/ctm_regridh.pro)
NAME:
CTM_RESEXT
PURPOSE:
Returns the proper filename extension for CTM resolution.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
RESULT = CTM_RESEXT( MODELINFO )
INPUTS:
MODELINFO -> a MODELINFO structure (output from function
CTM_TYPE) desribing the desired CTM model.
KEYWORD PARAMETERS:
None
OUTPUTS:
Returns a string containing the model resolution.
(e.g. '05x05', '1x1', '2x25', '4x5', '8x10' etc.)
SUBROUTINES:
External Subroutines Required:
==============================
CHKSTRU (function)
REQUIREMENTS:
None
NOTES:
(1) Add more grid resolutions as is necessary.
EXAMPLE:
MODELINFO = CTM_TYPE( 'GEOS4' )
PRINT, CTM_NAMEXT( MODELINFO )
4x5
; Returns filename extension for the
; 4x5 GEOS-4 model grid
MODIFICATION HISTORY:
bmy, 30 Jun 2000: GAMAP VERSION 1.46
bmy, 08 Aug 2000: - Added string for 0.5 x 0.5
bmy, 08 Feb 2006: GAMAP VERSION 2.04
- Added strings for 1.0 x 1.25 and
0.5 x 0.625
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- added string for 0.5 x 0.667
bmy, 09 Feb 2012: GAMAP VERSION 2.10
- Added string for 0.25 x 0.3125
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_resext.pro)
NAME:
CTM_RESTART_O3
PURPOSE:
Merges single-tracer Ox data into a full-chemistry
CTM restart file.
CATEGORY:
GAMAP Utilities
CALLING SEQUENCE:
CTM_RESTART_O3 [, BATCHFILE [, Keywords ] ]
INPUTS:
BATCHFILE (optional) -> Name of the input file containing
the names of the full chemistry restart file, the
single tracer O3 file, the annual mean tropopause file,
and the output file. If BATCHFILE is omitted, then the
user will be prompted to make a selection via a dialog box.
KEYWORD PARAMETERS:
/STRAT_ONLY -> Set this keyword to only merge the stratospheric
Ox into the full chemistry restart file. Stratospheric
levels are determined by reading in the annual mean
tropopause file (as specified in BATCHFILE). Default is
to merge all levels into the full chemistry restart file.
OUTPUTS:
Will write merged data to an output file whose name is
specified in BATCHFILE.
SUBROUTINES:
External subroutines required:
------------------------------------------------------
CTM_GRID (function) CTM_GET_DATABLOCK (function)
CTM_GET_DATA OPEN_FILE
STR2BYTE (function)
REQUIREMENTS:
None
NOTES:
CTM_RESTART_O3 is currently only applicable to the GEOS-CTM,
since this is the only model that can run single tracer Ox.
A Sample BATCHFILE is given below. There must be 3 header
lines before the first file name:
CTM_RESTART_O3.DAT -- defines filenames to read in for merging single
tracer Ox data into a full chem restart file
=============================================================================
Full Chem File : /r/amalthea/N/scratch/bmy/run_3.2/gctm.trc.941001
Ox Run File : /r/amalthea/N/scratch/bmy/run_o3_3.2/gctm.trc.941001
T-Pause File : /r/amalthea/Li/data/ctm/GEOS_4x5/ann_mean_trop.geos1.4x5
Output File : /scratch/bmy/gctm.trc.941001.new
=============================================================================
EXAMPLE:
CTM_RESTART_O3, 'filenames.dat', /STRAT_ONLY
; Will merge stratospheric single tracer Ox into the
; full chemistry restart file. Input and output file
; names are given in "filenames.dat".
MODIFICATION HISTORY:
bmy, 17 Feb 2000: VERSION 1.45
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_restart_o3.pro)
NAME:
CTM_RETRIEVE_DATA
PURPOSE:
Read one "compound" data block from disk. The datainfo
parameter must contain only one entry, and it must have
status=0. The data pointer is assumed to be NULL.
If requested data block is a multilevel or multitracer
diagnostics, the routine will search all individual data
records that belong to that block and loop over them
(this is actually done in ctm_read_multilevel and
ctm_read_multitracer).
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_RETRIEVE_DATA,DataInfo,DiagStru, $
Use_DataInfo=Use_DataInfo, $
Use_FileInfo=Use_FileInfo, $
result=result
INPUTS:
DataInfo -> DataInfo structure that is to hold the data.
Normally, this is either created in CTM_GET_DATA for
multilevel or multitracer diagnostics, or it is created
upon parsing the header information (ctm_read3d?_header).
DIAGSTRU -> A (single) diagnostic structure containing
information what to load (see CTM_DIAGINFO)
KEYWORD PARAMETERS:
USE_DATAINFO, USE_FILEINFO -> The array of Datainfo and Fileinfo
stuctures to select from. Unlike the higher level routines,
CTM_READ_MULTILEVEL does not provide default values for
these!
RESULT -> A named variable that will be 1 if successful,
0 otherwise.
OUTPUTS:
The DATAINFO structure will contain the correct dimensional
information, the status will be set to 1, and the data pointer
points to a 2D or 3D data array. (if reading was successful)
SUBROUTINES:
REQUIREMENTS:
Uses CTM_DOSELECT_DATA, CTM_READ_MULTILEVEL,
CTM_READ_MULTITRACER, CTM_READ_DATA,
gamap_cmn.pro
NOTES:
This routine is meant for internal use from CTM_GET_DATA.
EXAMPLE:
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 22 Oct 1998: - scale factor set to 1 after unit scaling
is applied for multi...
- tracername and unit setting now also done
for non-multi fields
mgs, 26 Oct 1998: - added status keyword. If used (0,1,or 2)
no data will be read but datainfo record
will be prepared as usual.
mgs, 04 Nov 1998: - bug fix for reading of 2D arrays. Now return
correct (offset) tracer number
mgs, 10 Nov 1998: VERSION 3.00
- major design change
mgs, 28 Nov 1998: - hopefully fixed scaling bug now!
bmy, 07 Apr 2000: - now can read DAO met field files
bmy, 21 Nov 2003: GAMAP VERSION 2.01
- Removed GMAO keyword in call to
CTM_READ_DATA
bmy, 23 Aug 2004: GAMAP VERSION 2.03
- Now account for single-point data blocks
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_retrieve_data.pro)
NAME:
CTM_SELECT_DATA (function)
PURPOSE:
Provide a user-friendly function to extract data
from a DATAINFO structure. The function returns an
index to the given DATAINFO structure which points
to all recored that fulfill the specified conditions.
CATEGORY:
GAMAP Internals, GAMAP Data Manipulation
CALLING SEQUENCE:
index = CTM_SELECT_DATA(DIAGN[,DATAINFO,keywords])
INPUTS:
DIAGN -> A diagnostic number or category name. Only one
diagnostic can be extracted at the same time. Complete
information about the requested diagnostic is returned
via the DIAGSTRU keyword. (see also CTM_DIAGINFO)
DATAINFO -> An [optional] subset of the global DataInfo
structure. As default, CTM_SELECT_DATA operates on
the global DATAINFO structure (see gamap_cmn.pro) scanning
all files that have been opened.
KEYWORD PARAMETERS:
ILUN -> A logical unit value or an array of logical unit
values. Only recored from these files will be returned.
Default is to use all files.
A link between logical unit numbers and filenames can be
made through the (global) FileInfo structure (see gamap_cmn.pro)
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
CTM_DIAGINFO and CTM_DOSELECT_DATA).
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. (see also example)
LEVELRANGE -> A 1 or 2 element vector with a level index or
a range of level indices for multilevel diagnostics
(e.g. 'IJ-AVG$'). As default, information is returned
about full 3D data blocks only. See also
EXPAND keyword.
/EXPAND -> If set, multilevel diagnostic fields are
expanded to return the individual layers in addition to
the complete 3D cube.
DATA -> A named variable that will contain an array with
pointers to the indexed data blocks. Note that some may
be NIL pointers if the STATUS value is 0 or 2.
COUNT -> A named variable that will return the number of
data blocks found with the given selection criteria
DIAGSTRU -> A named variable that will contain complete
information about the requested diagnostics (see
CTM_DIAGINFO)
STATUS -> Restricts the data selection to
Data that has not been read (STATUS = 0)
Data that has been read (STATUS = 1, default)
All data blocks (STATUS = 2)
If STATUS is 1, all pointers returned in DATA are valid.
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, -1 is returned.
SUBROUTINES:
REQUIREMENTS:
Uses CTM_DOSELECT_DATA, EXPAND_CATEGORY, gamap_cmn.pro,
GAMAP_INIT, CTM_DIAGINFO
NOTES:
This function acts for the most part as a convenient user
interface to CTM_DOSELECT_DATA which performs the actual
selection process and contains only minimal error checking.
For programming purposes, use CTM_DOSELECT_DATA when possible.
EXAMPLE:
; open a CTM punch file
CTM_OPEN_FILE
; Read diagnostic number 45 for all tracers and time steps
CTM_READ_DATA,45
; Select data for tracer 1 and diagnostics 45
index = CTM_SELECT_DATA(45,tracer=1,data=pdata)
; De-reference the data pointer for the first record
; (usually the first timestep)
if (index[0] ge 0) then data = (*pdata)[0]
; find data for a specific time range
DataInfo = (*pGlobalDataInfo)[index]
taus = where(DataInfo.tau0 ge 77666L AND DataInfo.tau1 le 78888L)
taus = DataInfo.tau0[taus]
index = CTM_SELECT_DATA(45,DataInfo,tracer=1,tau=taus,data=pdata)
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 07 Oct 1998: - removed obsolete FILEINFO parameter
- changed NO_EXPAND to EXPAND
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- Now get spacing between diagnostic offsets
from CTM_DIAGINFO and pass to CTM_DOSELECT_DATA
- Now use the /NO_DELETE keyword in the
call to routine EXPAND_CATEGORY
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_select_data.pro)
NAME:
CTM_SUM
PURPOSE:
Calculate the sum of several CTM output data blocks
and store them in a new datainfo structure as "derived
data". The user can select data blocks by diagnostics,
tracer, tau0, or logical unit of the source file. With
the AVERAGE keyword averages will be computed instead of
totals.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_SUM [, DIAGN ] [, Keywords ]
INPUTS:
DIAGN -> The diagnostic category name. Default is 'IJ-AVG-$'
KEYWORD PARAMETERS:
TRACER -> Tracer number(s) to look for.
TAU0 -> beginning of time step to look for. You can
specify a date using function nymd2tau(YYMMDD,HHMMSS)
ILUN -> If you want to restrict summation to datablocks from
one particular file, set the ILUN keyword to the
respective logical unit number. ILUN and FILENAME are
mutually exclusive. If you select FILENAME then ILUN
will be ignored.
FILENAME -> Instead of ILUN you may pass the name of a
CTM data file containing data blocks to be summed.
FILENAME and ILUN are mutually exclusive. If you
select FILENAME then ILUN will be ignored.
NEWTRACER -> Tracer number for the new tracer. Default is
to use the same number as the tracer in the first
selected data block.
NEWTAU0 -> A new pair of values for the time stamp. Default
is to use the minimum tau0 and maximum tau1 from the
selected data blocks. If only one value is passed (tau0),
then tau1 will be set to tau0+1.
/AVERAGE -> set this keyword to compute a (simple) average
instead of the total.
OUTPUTS:
This routne produces no output but stores a new datainfo
and fileinfo structure into the global arrays.
SUBROUTINES:
uses gamap_cmn, ctm_get_data, ctm_grid, and ctm_make_datainfo
REQUIREMENTS:
None
NOTES:
All data blocks must originate from compatible models.
No test can be made whether an identical addition had been
performed earlier. Hence, it is a good idea to test the
existence of the "target" record before in order to avoid
duplicates.
EXAMPLE:
(1)
CTM_GET_DATA, DATAINFO, 'IJ-AVG-$', $
TRACER=1, TAU0=NYMD2TAU( 940301L )
IF (N_ELEMENTS(DATAINFO) EQ 0) THEN $
CTM_SUM, 'IJ-AVG-$', TRACER=[1,2,3,4,5], $
TAU0=NYMD2TAU(940301L), NEWTRACER=1
; Add individual CH3I tracers for 03/01/1994 and
; store them as total CH3I concentration.
; But first: test!
(2)
CTM_SUM,'IJ-AVG-$',$
TRACER=2, FILENAME='ctm.bpch.ox', /AVERAGE
; Compute annual averages from monthly means for Ox
MODIFICATION HISTORY:
mgs, 18 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Added FILENAME keyword as an
alternative to ILUN
- Updated comments, cosmetic changes
phs, 18 Aug 2008: GAMAP VERSION 2.13
- Added experimental keyword DIMAVER to
average along any dimension of the
datablocks.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_sum.pro)
NAME:
CTM_SUM_EMISSIONS
PURPOSE:
Computes totals of emissions in Tg [or Tg C] for the
following diagnostics: ND28, ND29, ND32, ND36, ND46, ND13, etc.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_SUM_EMISSIONS, DIAGN [, Keywords ]
INPUTS:
DIAGN -> A diagnostic category name to restrict
the record selection (default is "ANTHSRCE").
KEYWORD PARAMETERS:
FILENAME -> Punch file (ASCII or Binary) from which to
read CTM emissions data. If omitted, the user
will be prompted to select a file via a dialog box.
FORMAT -> To overwrite the default format to output the
sum.
TRACER -> The tracer number (or a 1-D array of tracer
numbers) to compute emission totals for.
/CUM_ONLY -> If this switch is set, SUM_EMISSIONS will
only print out cumuluative totals (and skip individual
totals for each data block).
RESULT -> An array of structures (tag names: NAME, SUM, UNIT)
that returns, the name of each tracer, its cumulative
total, and its unit to the calling program.
/NO_SECONDS -> Set this switch if the data to be summed is
independent of seconds (e.g. molec/cm2). CTM_SUM_EMISSIONS
will not multiply the data by the number of seconds in the
interval when converting to Tg.
/KG -> Set this switch if the data to be summed is in kg
instead of molec/cm2 or molec/cm2/s. CTM_SUM_EMISSIONS
will not multiply the data by the surface area of each
grid box when converting to Tg.
/TO_Mg -> Set this switch if you wish to display emissions
totals in Mg instead of Tg.
/TO_Gg -> Set this switch if you wish to display emissions
totals in Gg instead of Tg.
/SHORT -> Use a shorter output format to print totals.
Default is to print out w/ the long output format.
_EXTRA=e -> Picks up any extra keywords for CTM_GET_DATA
or CTM_TRACERINFO.
OUTPUTS:
Prints totals in Tg or Tg C for each tracer to the screen
SUBROUTINES:
Internal Subroutines:
==================================================
CSE_GetUnit (function) CSE_GetAreaCm2 (function)
CSE_GetInfo
External Subroutines Required:
==================================================
CTM_DIAGINFO CTM_TRACERINFO
CTM_GETDATA CTM_BOXSIZE (function)
CTM_GRID (function) GAMAP_CMN
TAU2YYMMDD (function) UNDEFINE
REQUIREMENTS:
None
NOTES:
(1) Most of the time there will be 1 data block per month,
and the cumulative total will be a yearly total.
(2) For NOx, a molecular weight of 14e-3 kg/mole will report
results in Tg N. A molecular weight of 46e-3 will report
results in Tg NOx. This can be changed in the file
"tracerinfo.dat".
(3) Should now be compatible with any model type and grid
resolution. As of 6/19/01, has only been tested using
GEOS-CHEM diagnostic output.
EXAMPLE:
CTM_SUM_EMISSIONS, 'ANTHSRCE', $
FILENAME='ctm.bpch', TRACER=1, $
MODELNAME='GEOS1', RESOLUTION=4
; Will print emission totals for tracer #1 (NOx)
; for the ANTHSRCE (ND36) diagnostic, using data
; in file "ctm.bpch". The data is from a GEOS-1
; simulation on a 4x5 grid.
MODIFICATION HISTORY:
bmy, 26 Apr 2001: GAMAP VERSION 1.47
bmy, 08 Jun 2001: - now uses correct tracer name, unit,
and molecular weight for CO--SRCE
bmy, 19 Jun 2001: GAMAP VERSION 1.48
- added internal function CSE_GETUNIT
to return the proper unit string
("Tg N", "Tg C", or "Tg").
- added internal function CSE_GETAREACM2
which gets the proper surface area
for each data block
- removed MODELNAME, RESOLUTION keywords
bmy, 03 Jul 2001: - now can sum emissions from GENERIC grids
bmy, 16 Aug 2001: - added /NO_SECONDS and /KG keywords
bmy, 26 Sep 2001: GAMAP VERSION 1.49
- set XNUMOL = 1d-3 if /KG is set; this
will convert from g/cm2 to Tg correctly
bmy, 21 Nov 2001: - added internal routine CSE_GETINFO
- now call CTM_EXTRACT to restrict the
totaling to any arbitrary lat/lon rectangle
bmy, 10 Jan 2002: GAMAP VERSION 1.50
- Bug fix: Don't call CTM_EXTRACT if /KG is,
set, since AREACM2 will be 1 in that case
bmy, 31 Jan 2002: - change output format from f10.4 to f12.4
bmy, 10 Jun 2002: GAMAP VERSION 1.51
- added "kludge" for biomass burning files
if /NO_SECONDS is set; will use proper
mol wts & units for ACET, C3H8, C2H6
bmy, 14 Jan 2003: GAMAP VERSION 1.52
- added another quick fix to get the unit strings
correct for sulfate and nitrogen tracers for ND13
bmy, 19 Sep 2003: GAMAP VERSION 1.53
- now call PTR_FREE to free the pointer memory
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- now get the spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 26 Mar 2004: GAMAP VERSION 2.02
- added FORMAT keyword
bmy, 03 Dec 2004: GAMAP VERSION 2.03
- now pass /QUIET to CTM_GET DATA which
reduces a lot of printing to the screen
bmy, 15 Mar 2005: - Added /TO_Gg and TO_Mg keywords, which
will print totals in either Gg or Mg
instead of the default unit of Tg
- Now pass _EXTRA=e to CTM_GET_DATA so that
we can restrict to a given time
bmy, 07 Apr 2006: GAMAP VERSION 2.05
- Added /SHORT keyword
bmy, 29 Sep 2006: - Bug fix: now test for molec wt in kg/mole
in internal function CSE_GETUNIT
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 20 Mar 2008: GAMAP VERSION 2.12
- updated to work with nested grid
mps, 23 Jan 2014: - Added case for NO to CSE_GetUnit for output from
GEOS-Chem v9-02 and higher versions
- Now report NO emissions in Tg N
- Now print unit 'Tg C' for BC/OC tracers
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_sum_emissions.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:
CTM_WRITEBPCH
PURPOSE:
Save GAMAP datainfo records to disk
(in binary punch file format).
CATEGORY:
GAMAP Utilities, BPCH Format
CALLING SEQUENCE:
CTM_WRITEBPCH, DATAINFO, [, Keywords ]
INPUTS:
DATAINFO -> a datainfo record or an array of datainfo records
FILEINFO -> a fileinfo record or an array of fileinfo records
KEYWORD PARAMETERS:
FILENAME -> Filename of output file. Should end in '.bpch'.
SCALE -> An optional scaling factor. This factor will be applied
to _all_ data record upon saving. The globally stored records
are not affected.
NEWUNIT -> With this keyword you can change the unit _name_ for
the saved data. This will _not_ perform a unit conversion!
For a true unit conversion you must also use the SCALE
keyword. NEWUNIT will be applied to _all_ records!
/APPEND -> If set, then will append to an existing binary
punch file rather than writing to a new file.
OUTPUTS:
A binary punch file with the selected data records will be
created.
SUBROUTINES:
External Subroutines Required:
====================================================
CHKSTRU (function) CTM_DIAGINFO
CTM_GET_DATA (function) DATATYPE (function)
OPEN_FILE
REQUIREMENTS:
None
NOTES:
This routine forces reading of all selected data records via
CTM_GET_DATA. This may take a while for huge ASCII punch files.
EXAMPLE:
gamap [,options] ; call gamap to read records from a file
@gamap_cmn ; get global datainfo structure
d = *pglobalDataInfo
ind = where(d.tracer eq 2) ; select all Ox records
ctm_writebpch,d[ind],filename='oxconc.bpch'
MODIFICATION HISTORY:
mgs, 20 May 1999: VERSION 1.00
- stores binary files version 1
mgs, 24 May 1999: VERSION 2.00
- stores binary files version 2
bmy, 26 Jul 1999: VERSION 2.01
- now call function DATATYPE
- make sure only floating point data gets
written to binary punch file v. 2.0
bmy, 19 Jan 2000: - updated commetns
bmy, 07 Jun 2000: GAMAP VERSION 1.45
- Save TRACER mod 100L to the punch file
- updated comments
bmy, 02 Mar 2001: GAMAP VERSION 1.47
- added FILEINFO as an argument; will use
PGLOBALFILEINFO structure if not passed
- removed obsolete comments
bmy, 13 Mar 2001: - now supports Windows, MacOS, and Unix/Linux
bmy, 07 Jun 2001: - removed obsolete code from 7/26/99
mje & bmy, 17 Dec 2001: GAMAP VERSION 1.49
- added /APPEND keyword in order to
append to an existing binary punch file
- updated comments
bmy, 15 Oct 2002: GAMAP VERSION 1.52
- added LEVELSAVE keyword to define certain
levels which to save to disk
- Updated comments, cosmetic changes
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- now get diagnostic spacing from CTM_DIAGINFO
and write TRACER mod SPACING to the BPCH file.
bmy, 27 May 2004: GAMAP VERSION 2.02
- Bug fix: Don't call CTM_GET_DATA to initialize
data pointers if this has been done already
- removed LEVELSAVE keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now save 4D datablock if the tag
of FILEINFO[0].FILETYPE = 106;
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_writebpch.pro)
NAME:
CTM_WRITENC
PURPOSE:
Save GAMAP datainfo records to disk (in netCDF format)
CATEGORY:
GAMAP Utilities, Scientific Data Formats
CALLING SEQUENCE:
CTM_WRITENC, DATAINFO, FILENAME=FILENAME
INPUTS:
DATAINFO -> a datainfo record or an array of datainfo records
KEYWORD PARAMETERS:
FILENAME -> Filename of output file. Should end in '.bpch'.
SCALE -> An optional scaling factor. This factor will be applied
to _all_ data record upon saving. The globally stored records
are not affected.
NEWUNIT -> With this keyword you can change the unit _name_ for
the saved data. This will _not_ perform a unit conversion!
For a true unit conversion you must also use the SCALE
keyword. NEWUNIT will be applied to _all_ records!
OUTPUTS:
A binary punch file with the selected data records will be
created.
SUBROUTINES:
External Subroutines Required:
====================================
CTM_GET_DATA
OPEN_FILE
DATATYPE
REQUIREMENTS:
Must have a version of IDL w/ the netCDF library installed.
NOTES:
This routine forces reading of all selected data records via
ctm_get_data. This may take a while for huge ASCII punch files.
EXAMPLE:
gamap [,options] ; call gamap to read records from a file
@gamap_cmn ; get global datainfo structure
d = *pglobalDataInfo
ind = where(d.tracer eq 2) ; select all Ox records
ctm_writebpch,d[ind],filename='oxconc.bpch'
MODIFICATION HISTORY:
mgs, 20 May 1999: GAMAP VERSION 1.47
- adapted from "ctm_writebpch.pro"
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_writenc.pro)
NAME:
CUM_TOTAL (function)
PURPOSE:
Compute cumulative total of a data vector.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = CUM_TOTAL(Y)
INPUTS:
Y -> The data vector
KEYWORD PARAMETERS:
None
OUTPUTS:
A data vector with the same number of elements
and the cumulative totals.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
See also function RUN_AV.
EXAMPLE:
Y = FINDGEN(10)
PRINT, CUM_TOTAL(Y)
; IDL prints: 0 1 3 6 10 15 21 28 36 45
MODIFICATION HISTORY:
mgs, 21 Oct 1998: VERSION 1.00
bmy, 23 May 2007: TOOLS VERSION 2.06
- Now use longword for loop counter
- Updated comments, cosmetic changes
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/cum_total.pro)
NAME:
CUSTOM_COLORTABLE
PURPOSE:
Defines various customized color tables for use with MYCT.
Color tables may be stretched to more than the original #
of colors, or compressed to less than the original # of
colors. You may add more color tables as necessary.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% AS OF GAMAP v2-12, CUSTOM_COLORTABLE IS DEPRECATED. %%
%% MYCT NOW LOADS IDL AND ColorBrewer COLORTABLES FROM %%
%% THE "gamap_colors.tbl" FILE. (phs, bmy, 4/21/08) %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
CATEGORY:
Color
CALLING SEQUENCE:
CUSTOM_COLORTABLE, R, G, B [ , Keywords ]
INPUTS:
None
KEYWORD PARAMETERS
/BuWhRd -> Set this switch to load the BLUE-WHITE-RED
(diverging) color table from Harvard University. This
color table is a concatenation of the WHITE-BLUE and
WHITE-RED ColorBrewer colortables. The center color
is white. (Original # of colors = 19)
/BuWhWhRd -> Set this switch to load the BLUE-WHITE-WHITE-RED
(diverging) color table. This is a concatenation of
the WhBu and WhRd colortables from ColorBrewer. The two
center colors in this colortable are white, which makes
it easier to align colorbar tickmarks at the divisions
between colors. (Original # of colors = 20)
/BuYlRd -> Set this switch to load the BLUE-YELLOW-RED
(diverging) color table from ColorBrewer. (Original
# of colors = 12)
/BuYlYlRd -> Set this switch to load the BLUE-YELLOW-YELLOW-RED
(diverging) color table from ColorBrewer. The two center
colors in this colortable are light yellow, which makes
it easier to align colorbar tickmarks at the divisions
between colors. Use this colortable instead of /BuWhWhRd
if you need to denote "missing data" values by white.
(Original # of colors = 12)
/DIAL -> Set this switch to load the DIAL/LIDAR (diverging)
color table from Ed Browell. (Original # of colors = 27)
/DIFF -> Synonym for /BuWhRd. Kept for backwards compatibility.
/ModSpec -> Set this switch to load the MODIFIED SPECTRUM
(diverging) color table from ColorBrewer. (Original #
of colors = 11)
NAME -> Returns to the calling program the name of the color
table that we have selected.
NCOLORS -> The number of colors that you would like to be
included in the colortable. If NCOLORS is greater than
the native number of colors for the given colortable,
the colortable will be stretched to produce a finer
gradation of colors. Conversely, if NCOLORS is less
than the native number of colors, then the colortable
will be compressed to produce a coarser gradation of
colors.
/NOLOAD -> If set, then CUSTOM_COLORTABLE will just return R,
G, B to the calling program without loading the colortable.
/TRUNCATE -> When NCOLORS is less than the number of colors
in the given color table, setting /TRUNCATE will cause
CUSTOM_COLORTABLE to truncate the color table to NCOLORS
rather than trying to compress it via interpolation.
/UserDef -> Set this switch to load a user-defined colortable.
In order to use this option, you must first add the R, G,
B color vectors into internal routine DEFINE_UserDef.
/WhBu -> Set this switch to load the WHITE-BLUE (spectral)
color table from ColorBrewer. (original # of colors = 10)
/WhGrYlRd -> Set this switch to load the WHITE-GREEN-YELLOW-RED
(spectral) color table from A. van Donkelaar. (Original
# of colors = 20)
/WhGyBk -> Set this switch to load the WHITE-GRAY-BLACK
(spectral) color table from ColorBrewer. (Original #
of colors = 10)
/WhRd -> Set this switch to load the WHITE-RED (spectral) color
table from ColorBrewer. (original # of colors = 10)
OUTPUTS:
R -> Returns to the calling program the red color
vector that defines the customized colortable.
G -> Returns to the calling program the green color
vector that defines the customized colortable.
B -> Returns to the calling program the blue color
vector that defines the customized colortable.
SUBROUTINES:
Internal Subroutines Included:
================================================
DEFINE_BuWhRd DEFINE_BuWhWhRd DEFINE_BuYlRd
DEFINE_BuYlYlRd DEFINE_DIAL DEFINE_MODSPEC
DEFINE_WhBu DEFINE_WhGrYlRd DEFINE_WhRd
DEFINE_WhGyBk
REQUIREMENTS:
None
NOTES:
(1) For contour plots, the native resolution of the
custom colortables should be sufficient.
(2) For smoothed pixel plots, NCOLORS=100 or higher will
eliminate the streaking caused by TVIMAGE's smoothing
algorithm.
(3) Some color tables were adapted from the ColorBrewer
package (see license info below).
(4) We will use the ColorBrewer color abbreviations:
Bk = Black Br = Brown Bu = Blue
Gr = Green Gy = Gray Or = Orange
Pi = Pink Pu = Purple Rd = Red
Wh = White Yl = Yellow
(5) An MS Excel spreadsheet with all ColorBrewer color tables
is available for download from:
www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_RGB.html
EXAMPLES:
CUSTOM_COLORTABLE, R, G, B, /NOLOAD, /DIAL
; Returns the red, green, blue color vectors for the
; DIAL colortable at native resolution (26 colors)
CUSTOM_COLORTABLE, NCOLORS=120, /DIAL
; Loads the DIAL colortable and stretches it
; from 26 to 120 colors.
CUSTOM_COLORTABLE, /WhGrYlRd
; Loads the WHITE-GREEN-YELLOW-RED (spectral)
; color table with 20 colors.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Adapted from "dial_ct.pro"
- Now can compress the colortable if
NCOLORS is less than N_ORIG
- Added /BuWhWhRd keyword for selecting
the BLUE-WHITE-WHITE-RED colortable
- Added /BuYlYlRd keyword for selecting
the BLUE-YELLOW-YELLOW-RED colortable
- /DIFF is now a synonym for /BuWhWhRd
- Added /UserDef keyword and internal
routine DEFINE_UserDef for selecting
a user-defined color table.
phs, 12 Feb 2008: GAMAP VERSION 2.12
- Now create /BuWhRd as a concatenation of
the /WhBu and /WhRd colortables.
- Updated the interpolation for case of
NCOLORS lt NORIG. It works fine with all
the 4 diverging colortables, and keeps the
doubling of the middle range color if NCOLORS
is even and BuWhWhRd or BuYlYlRd is used.
bmy, 18 Apr 2008: - Bug fix: don't overwrite colortable name
for BuWhRd colortable
(See /n/home09/ryantosca/IDL/gamap2/color/custom_colortable.pro)