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:
ADD_DATA
PURPOSE:
Add a variable to a data array and its header, units,
cfact, and mcode fields. For use with CHEM1D.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
ADD_DATA,data,header,units,cfact,mcode, $
newdat,newhead,newunit,newfact,newcode [,keywords]
INPUTS:
DATA --> the array containing all the data
HEADER --> string vector of variable names
UNITS --> string vector of variable units (maybe undefined)
CFACT --> float vector of conversion factors (maybe undefined)
MCODE --> float vector of missing value codes (maybe undefined)
NEWDATA --> data vector containing new variable
NEWHEADER --> name of new variable
NEWUNIT --> physical unit of new variable (may be omitted)
NEWFACT --> conversion factor of new variable (may be omitted)
NEWCODE --> missing value code for new variable (may be omitted)
KEYWORD PARAMETERS:
/INFO --> prints number of variables (elements of HEADER)
after merging the new column with the old array
/TRANSPOSE --> NEWDAT is being transposed before merging it
with DATA
/FIRST --> add variable at first position rather than last
OUTPUTS:
DATA, HEADER, UNITS, CFACT, MCODE will contain the extra data
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
suppose DATA is a 3x10 array, and HEADER contains
the names A, B, and C. Then
ADD_DATA,DATA,HEADER,DUMMY,DUMMY,DUMMY,findgen(10),'COUNT'
will add the variable COUNT to the dataset and the name to HEADER.
A more realistic example:
ADD_DATA,DATA,HEADER,UNITS,CFACT,MCODE, $
NEWDAT,'SATURATION_PRESSURE','mbar',1.0,-999.99
MODIFICATION HISTORY:
mgs, 05 Nov 1997: VERSION 1.00
extracted from CREATE_MASTER.PRO, added flexibility for
optional parameters
mgs, 06 Nov 1997: - added FIRST keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/add_data.pro)
NAME:
ADD_DATE
PURPOSE:
Computes the YYYY/MM/DD date after a number of days in the
future (or past) have elapsed.
CATEGORY:
Date & Time
CALLING SEQUENCE:
RESULT = ADD_DATE( YYYYMMDD, NDAYS )
INPUTS:
YYYYMMDD -> Today's date in YYYY/MM/DD format
NDAYS -> The number of days (either positive or negative)
to add to YYYYMMDD. Default is 1.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
DATE2YMD YMD2DATE (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
PRINT, ADD_DATE( 20060101, 100 )
20060411
; Computes the date 100 days after 2006/01/01
PRINT, ADD_DATE( 20060101, -100 )
20050923
; Computes the date 100 days before 2006/01/01
MODIFICATION HISTORY:
bmy, 06 Jun 2006: TOOLS VERSION 2.05
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/date_time/add_date.pro)
NAME:
ADD_SEPARATOR
PURPOSE:
Adds a pathname separator to the last character of
a file name or path name.
CATEGORY:
General
CALLING SEQUENCE:
NEWPATH = ADD_SEPARATOR( PATH )
INPUTS:
PATH -> Path name to append the separator character
to. If Unix, will append a "/" character. If
Windows, will append a "/" character. If
Macintosh, will append a ":" character.
KEYWORD PARAMETERS:
None
OUTPUTS:
NEWPATH -> Path name with separator appended to
the last character.
SUBROUTINES:
None
REQUIREMENTS:
Supports Unix, Windows, and Macintosh platforms.
NOTES:
None
EXAMPLE:
(1)
PATH = '/scratch/bmy'
NEWPATH = ADD_SEPARATOR( PATH )
/scratch/bmy/
; Adds a separator to the path "/scratch/bmy".
(2)
SEP = ADD_SEPARATOR()
PRINT, SEP
/
; Returns the default separator string
; (here we have assumed a Unix environment).
MODIFICATION HISTORY:
bmy, 03 May 2002: TOOLS VERSION 1.50
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/add_separator.pro)
NAME:
ADD_TEMPLATE
PURPOSE:
Add a near standard IDL template to a given IDL routine file.
CATEGORY:
Documentation
CALLING SEQUENCE:
ADD_TEMPLATE, FILE
INPUTS:
FILE -> Input IDL routine file name.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
COMMON BLOCKS:
None
NOTES:
(1) Existing front end, up to the pro or function
statement, are replaced by the new template.
(2) Also see routine IDL2HTML, which converts the IDL
doc header text to HTML format.
MODIFICATION HISTORY:
written by:
R. Sterner, about Sep 1989 at Sac Peak. The exact date was
probably lost by this routine itself.
modified:
R. Sterner, 13 Dec, 1993 --- dropped spawn to copy files.
R. Sterner, 11 Mar, 1993 --- handled no help text case.
M. Schultz, 01 Aug, 1997 --- simplified version without
analyzing help text
Also, original file is left intact
(i.e. modification date etc.)
and renamed file.backup if operation successfully.
OF COURSE the copyright note is changed as well
mgs, 09 Oct 1998 : - added Id tag for RCS
bmy, 19 Jul 1999 : - changed name & email from mgs to bmy
for convenience! :-)
bmy, 27 Jul 1999 : - put RCS tag as the first line of
the standard header
bmy, 06 Jul 2000 : - extended separator lines a bit
bmy, 11 Oct 2006 : TOOLS VERSION 2.05
- Cosmetic chanes
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now include 2 email addresses
- Updated comments, cosmetic changes.
- Same conditions apply
bmy, 22 Apr 2008: GAMAP VERSION 2.12
- Updated email addresses
(See /n/home09/ryantosca/IDL/gamap2/doc/add_template.pro)
NAME:
ADJ_INDEX
PURPOSE:
Adjusts CTM global index arrays for a particular
data-block dimension from global size to window size.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
NEWINDEX = ADJ_INDEX( OLDINDEX, N_SUBTRACT, MAXINDEX )
INPUTS:
OLDINDEX -> The globally sized CTM index array to be adjusted.
N_SUBTRACT -> The number to subtract from each element
of OLDINDEX.
MAXINDEX -> The maximum number of elements that OLDINDEX
can have.
KEYWORD PARAMETERS:
None
OUTPUTS:
ADJ_INDEX returns the window-sized index array as
the value of the function.
SUBROUTINES:
None
REQUIREMENTS:
None.
NOTES:
Designed for use with GAMAP, but can be used for more
general purpose applications as well.
EXAMPLE:
WE = [ 69, 70, 71, 0, 1, 2 ] ; WE straddles the date line
WE_ADJ = ADJ_INDEX( WE, 69, 72 )
print, WE_ADJ
0 1 2 3 4 5
NEWDATA = DATA[ WE_ADJ, *, * ]
; WE has a possible maximum of 72 elements. Convert WE
; from global size to window size by subtracting 69
; from each element of WE. Use WE_ADJ to reference
; elements of the DATA array.
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/adj_index.pro)
NAME:
AIRDENS (function)
PURPOSE:
Compute air mass density for a given pressure and
temperature. If the temperature is not provided, a
temperature is estimated using the US Standard atmosphere.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
idens = AIRDENS(p [,T])
INPUTS:
P -> pressure in hPa (mbar)
T -> temperature in K
KEYWORD PARAMETERS:
HELP -> print help information
OUTPUTS:
The air mass density in molec/cm^3. The result type will
match the type and array dimensions of p unless p is a
scalar and T an array.
SUBROUTINES:
External Subroutines Required:
===========================================
USSA_ALT (function) USSA_TEMP (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, AIRDENS( 1013.25, 273.15 )
2.69000e+19
; Prints air density at std temperature & pressure
(2)
P = FINDGEN(5)*100+500
PRINT,AIRDENS(P,T) ; T undefined !
1.44840e+19 1.67414e+19 1.89029e+19 2.10104e+19 2.30998e+19
PRINT, T
250.334 259.894 268.538 276.117 282.534
; Prints air density w/ undefined temperature
; Temperature profile from the US Std atmosphere
; will be returned.
(3)
PRINT,AIRDENS(800.,T) ; T from previous calculation
2.31744e+19 2.23218e+19 2.16033e+19 2.10104e+19 2.05332e+19
; Use T from previous example and print
; air density at 800 hPa
MODIFICATION HISTORY:
mgs, 12 Nov 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/airdens.pro)
NAME:
ARREX (function)
PURPOSE:
This function extracts a multi-dimensional subset
of an array. For each dimension the start index,
end index, and stride can be specified - default values
are 0 (i.e. first start index), "all" (i.e. last end
index), and 1 (i.e. every element). A negative stride
causes reversion of the respective array dimension.
CATEGORY:
Math & Units
CALLING SEQUENCE:
Result = ARREX(Array [, Starti [,Endi [, Stride ]]] [,/Reform])
INPUTS:
ARRAY -> The parent array from which the extraction shall be made.
Currently up to 4 dimensions are supported.
STARTI -> An array with starting indices. Each element of STARTI
corresponds to one dimension of ARRAY. If STARTI has less
elements than ARRAY dimensions, the remainder is assumed 0.
ENDI -> An array with ending indices. Each element of ENDI
corresponds to one dimension of ARRAY. If ENDI has less
elements than ARRAY dimensions, the remainder is set to the
maximum possible value for that dimension.
STRIDE -> An array with stride values. A stride of 1 (default)
signifies extraction of every element, 2 returns every
second element for that dimension, etc. Negative values
cause the respective dimension to be reversed.
Each value of STRIDE corresponds to one dimension of ARRAY.
If STRIDE has less elements than ARRAY dimensions, the
remainder is assumed 1.
KEYWORD PARAMETERS:
/REFORM -> Set this keyword to eliminate unnecessary dimensions
in the result.
OUTPUTS:
A subset of the original array. This will have the same
dimensionality as ARRAY unless the REFORM keyword is set.
SUBROUTINES:
Function arrex_ComputeInd
REQUIREMENTS:
None
NOTES:
Created after discussion in newsgroup idl-pvwave.
This version contains some debug output.
EXAMPLE:
A = indgen(10,10)
print,arrex(A,[2,1],-1,[2,4])
; yields 12 14 16 18
; 52 54 56 58
; 92 94 96 98
print,arrex(A,[10,1],[1,10],[5,5])
; yields 19 15
; 69 65
; note that stride for dimension 1 is adjusted automatically.
MODIFICATION HISTORY:
mgs, 20 May 1999: VERSION 1.00
- with a lot of input from
L. Gumley, S. Vidar, and others
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/arrex.pro)
NAME:
ARROWMAP
PURPOSE:
Plots a vector field atop a world map.
CATEGORY:
Plotting
CALLING SEQUENCE:
ARROWMAP, U, V, X, Y [, Keywords ]
INPUTS:
U, V -> The X and Y components of the two-dimensional vector
field. U and V must be two-dimensional arrays.
The vector at point (i,j) has a magnitude of:
( U(i,j)^2 + V(i,j)^2 )^0.5
and a direction of:
ATAN2( V(i,j), U(i,j) ).
X, Y -> Longitude (X) and latitude (Y) values corresponding to
the U and V arrays. X must be a vector with a length equal
to the 1st dimension of U and V. Y must be a vector
with length equal to the 2nd dimension of U and V.
KEYWORD PARAMETERS:
UNIT -> String containing the units for the plot legend.
Default is '' (the null string).
FORMAT -> Format string for the arrow legend. Default
is '(f10.3)'.
TITLE -> Top title for the map panel.
Default is '' (the null string).
CSFAC -> Character size for the map labels and X, Y titles.
Default settings for CSFAC vary according to the number
of plots per page and type of plot device.
TCSFAC -> Character size for the top title. Default
settings for TCSFAC vary according to the number
of plots per page and type of plot device.
_EXTRA=e -> Picks up extra keywords (not listed below) for
ARROW, MAP_SET, MAP_GRID, MAP_CONTINENTS, VELOCITY_FIELD.
Keywords for MAP_SET:
=====================
MPARAM -> A 3 element vector containing values for
[ P0Lat, P0Lon, Rot ]. Default is [ 0, 0, 0 ].
Elements not specified are automatically set to zero.
NOTE: If X contains positive longitudes (i.e. in the
range 0-360), then set MPARAM = [0, 180, 0]. This will
ensure that the map is displayed correctly.
LIMIT -> A four-element vector which specifies the latitude
and longitude extent of the map. The elements of LIMIT
are arranged thus: [ LatMin, LonMin, LatMax, LonMax ].
Default is to set LIMIT = [ -90, -180, 90, 180 ] (i.e.
to include the entire globe). P0Lon will be computed
to fit into the LIMIT range unless it is explicitely
requested in MParam.
If LIMIT is not passed explicitly, then LIMIT will be
computed from the maximum and minimum values of the
X and Y vectors.
COLOR -> Color index of the map outline and flow vectors.
Defaults is 1 (MYCT black color).
/POLAR -> Plot a polar stereographic projection.
NOTE: Polar is not yet supported (bmy, 5/26/00)
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.0, 0.15, 1.0, 1.0].
MARGIN -> specify a margin around the plot in normalized
coordinates. This keyword does not change any IDL
system variables and will thus only become "visible"
if you use the POSITION returned by MULTIPANEL in
subsequent plot commands. MARGIN can either be one value
which will be applied to all four margins, or a 2-element
vector which results in equal values for the left and
right and equal values for the bottom and top margins,
or a 4-element vector with [left,bottom,right,top]. The
default MARGIN setting is [ 0.05, 0.04, 0.03, 0.07 ].
/ISOTROPIC -> If set, will produce a map with the same scale
in the X and Y directions. Default is not to plot an
isotropic-scale map. Note, however, that if TVMAP is
called from CTM_PLOT, the default is to plot a map that
keeps the aspect ratio (which is about the same as
isotropic).
Keywords for MAP_CONTINENTS:
============================
/CONTINENTS -> If set, will call MAP_CONTINENTS to plot
continent outlines or filled boundaries. Default is 0.
CCOLOR -> The color index of the continent outline or fill
region. Default is 1 (MYCT black color).
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.
Keywords for MAP_GRID:
======================
/GRID -> If set, will call MAP_GRID to plot grid lines and
labels. Default is NOT to plot grid lines and labels.
GCOLOR -> The color index of the grid lines. Default is
BLACK (see above).
Keywords for VELOCITY_FIELD:
============================
ACOLOR -> Specifies the color of the arrows. Default is black.
HSIZE -> The length of the lines used to draw the arrowhead.
If HSIZE is positive, then the arrow head will be the
same regardless of the length of each vector. (Default
size is !D.X_SIZE / 100). If HSIZE is negative, then
the arrowhead will be 1/HSIZEth of the total arrow length.
THICK -> Thickness factor for the arrows. Default is 2.0.
MAXMAG -> Returns to the calling program the magnitude of the
longest vector.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=====================================
MULTIPANEL MYCT_DEFAULTS (function)
MAP_LABELS VELOCITY_FIELD
REQUIREMENTS:
None
NOTES:
(1) The U and V arrays may contain either CTM winds or
flux quantities. However, when plotting fluxes, it is
STRONGLY RECOMMENDED that you double-check the units of
U and V before passing them to ARROWMAP. Some unit
conversion may be required in order to display fluxes
properly.
(2) If your map spans the date line, then do the following:
(a) Make sure that your longitudes are in the range
0 - 360 degrees
(b) Call ARROWMAP with MPARAM=[0,180,0] in order to
have MAP_SET accept longitudes in the range 0-360.
EXAMPLE:
ARROWMAP, U, V, X, Y, $
/GRID, /CONTINENTS, THICK=3, CFILL=2, GCOLOR=1, UNIT='m/s'
; Plots a vector flow pattern over a world map. Continents
; are filled to a solid red color (assuming a MYCT colortable).
; Arrows have a thickness factor of 3.
MODIFICATION HISTORY:
bmy, 26 May 2000: GAMAP VERSION 1.45
bmy, 24 Jul 2000: GAMAP VERSION 1.46
- added X_STEP, Y_STEP, and MAXMAG keywords
- now print the longest vector as the arrow
legend below the plot.
- added MARGIN keyword for MULTIPANEL
- added ISOTROPIC keyword for MAP_SET
bmy, 23 Jul 2002: GAMAP VERSION 1.51
- now default HSIZE to a device pixel length
- added LEGENDLEN keyword
- now call VELOCITY_FIELD using new LEGENDLEN,
LEGENDNORM, and LEGENDMAG keywords
- Now use MYCT_DEFAULTS for default BLACK
- added COUNTRIES and COASTS keywords
- removed HANGLE keyword -- it's obsolete!
- renamed ARRLEN to LEGENDNORM
- renamed MAXMAG to LEGENDMAG
bmy, 28 Sep 2002: - Now reference MYCT colors from the !MYCT
system variable
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 12 Mar 2008: GAMAP VERSION 2.12
- add /NOADVANCE keyword to prevent advancing
to the next page (in case you want to overplot)
(See /n/home09/ryantosca/IDL/gamap2/plotting/arrowmap.pro)
NAME:
BARGRAPH
PURPOSE:
Creates a bar graph from a vector of data points.
CATEGORY:
Plotting
CALLING SEQUENCE:
BARGRAPH, DATA, BASELINE [,keywords]
INPUTS
DATA -> Vector of data points to be plotted as a bargraph.
BASELINE -> Vector of points to be used as a baseline for
DATA (i.e., Y(I) = DATA(I) + BASELINE(I) ). If BASELINE
is not specified, its default value will be an array
of zeroes.
KEYWORD PARAMETERS:
/OVERPLOT -> Set this switch to prevent the current plot
window from being erased. This is useful for producing
stacked bar plots with successive calls to BARGRAPH.
BARWIDTH -> The width of the bars. If BARWIDTH is not
specified, its default value will be 1.0.
BARCOLOR -> a value or an array containing the colorindex for
all boxes or each box, respectively. If a single value
is given, *all* boxes will have this color. If an array
is passed that has less elements than there are groups to
plot, the remaining colors will be filled with 15 (grey
in MYCT standard-scheme).
BARLABELS -> A string array of labels to be plotted above each
bar. If BARLABELS may be originally set equal to the
DATA vector, and it will be converted to the string
representation of DATA, using the FORMAT statement
contained in L_FORMAT.
BARCHARSIZE -> Character size for BARLABELS. Default is 1.0.
COLOR -> Color index for the plot axes and labels.
Default is !MYCT.BLACK.
L_FORMAT -> The FORMAT statement used to convert BARLABELS
from a numeric array to a string array.
/NO_LABELS -> Set this switch to suppress printing the labels
contained in the BARLABELS atop each bar. This is useful
for producing stacked bar plots.
XLABELS -> A string array containing the labels that will be
printed underneath each bar on the X-axis.
NOTE: If /HORIZONTAL is set, then these labels will be
printed along the Y-axis instead.
ALSO NOTE: IDL only allows a maximum limit of 60 ticks
along any axis. If XLABELS has more than 58 elements
(also allowing for null labels at the beginning and end
of the plot range), then the labels will not be printed.
YRANGE -> Use this keyword to specify the range of the data
values. If YRANGE is not specified, then YRANGE will be
computed based on the maximum value of the DATA array.
For stacked plots, it is useful to compute YRANGE in the
calling program and pass it to BARGRAPH.
NOTE: If HORIZONTAL is set, then the YRANGE settings
will apply to the X-axis instead.
/HORIZONTAL -> Set this switch to plot the bars in the
horizontal instead of in the vertical. NOTE: In this
case, the YRANGE settings will be applied to the X-axis.
and the XRANGE and XLABELS settings will be applied to
the Y-axis.
YFACTOR -> Use this to add space between the bar and bar label.
This will multiply DATA + BASELINE by a factor that you
specify. Default is 1.01.
_EXTRA=e -> Passes extra keywords to PLOT and other routines.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
(1) This routine has been modified to be more general and
more robust than the original version in the IDL 5.0
User's Guide (p. 170).
(2) IDL 5.x array notation [] is now used.
EXAMPLES:
(1)
BARGRAPH, [1,2,3], BARWIDTH=1.0, BARCOLOR=[10,11,12]
XLABELS=['Bart', 'Lisa', 'Maggie']
; Create a simple bar graph with bars of 3 different
; colors, using a baseline of zero.
(2)
DATA = [2,3.5,6,7,2,1]
DATA2 = 0.0*DATA + 2
BARGRAPH, DATA, XLABELS=['A','B','C','D','E','F'], $
XSTYLE=1, BARWIDTH=0.8
BARGRAPH, DATA2, DATA, BARWIDTH=0.8 ,/OVERPLOT, $
BARCOLOR=2, BARLABELS=DATA+DATA2, L_FORMAT='(F8.2)'
; Use successive calls to BARGRAPH to create a
; "stacked" bar graph with two different data vectors.
; The first vector is used as the baseline for the
; second. The BARLABELS array is created from the actual
; data values.
(3)
BARGRAPH, [1,2,3], BARWIDTH=1.0, BARCOLOR=[10,11,12]
XLABELS=['Bart', 'Lisa', 'Maggie'], /HORIZONTAL
; Same as example (1), but plot bars in the horizontal.
MODIFICATION HISTORY:
bmy, 18 Nov 1997: VERSION 1.00
bmy, 19 Nov 1997: VERSION 1.01
bmy, 29 Apr 1999: VERSION 1.10
- added COLOR keyword
- eliminated help screen
- enhanced readability & updated comments
bmy, 15 Mar 2000: VERSION 1.45
- added BARCHARSIZE keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- added HORIZONTAL keyword to plot
bars in the horizontal
- Now limits XLABELS array to 58 elements
in order to prevent exceeding an IDL
plotting limit
bmy, 15 Dec 2016: GAMAP VERSION 2.19
- Now plot top-of-bar labels in the right
place when using the /HORIZONTAL option
bmy, 20 Dec 2017: - Now compute YOffSet dynamically, for more
consistent spacing between bars & bar labels
(See /n/home09/ryantosca/IDL/gamap2/plotting/bargraph.pro)
NAME:
BENCHMARK_1MON
PURPOSE:
Produces maps of tracers and other quantities from two
GEOS-Chem benchmark simulations (for model validation).
CATEGORY:
Benchmarking
CALLING SEQUENCE:
BENCHMARK_1MON, INPUTFILE, [, Keywords ]
INPUTS:
INPUTFILE -> A file containing default values for version
numbers, directories, model names, resolutions, etc.
Default is "input_bm.1mon"
KEYWORD PARAMETERS:
By default, BENCHMARK_1MON will produce the following types
of output:
(a) Table of Ox and CO budgets, mean OH conc. and CH3CCL3 lifetime
(b) Table of emissions totals
(c) Frequency distribution histogram
(d) Vertical profiles of tracer differences along 15S and 42N
(e) Maps of tracer concentration @ surface and 500 hPa
(f) Maps of tracer differences @ surface and 500 hPa
(g) Maps of J-value differences @ surface and 500 hPa
(h) Maps of tracer ratios @ surface and 500 hPa
Each of these types of output can be turned off individually
with the following keywords:
/NO_AOD_DIFFS -> Do not create difference maps of aerosol optical
depths.
/NO_AOD_MAPS -> Do not create concentration plots for aerosol
optical depths.
/NO_BUDGET -> Do not create the table of Ox and CO budgets,
mean OH concentration and CH3CCl3 lifetime.
/NO_CONC_MAPS -> Do not create the plot the maps of tracer
concentrations @ sfc and 500 hPa altitude.
/NO_DIFFS -> Do not create the maps of tracer differences
at the surface and 500 hPa altitude.
/NO_EMISSIONS -> Do not create the table of emissions totals.
/NO_FREQ_DIST -> Do not create the the frequency distribution
histogram plot.
/NO_JVALUES -> Do not create the maps of J-value ratios
at the surface and 500 hPa altitude.
/NO_JVDIFFS -> Do not create the maps of J-value differences
at the surface and 500 hPa altitude.
/NO_JVMAPS -> Do not create the maps of J-values
at the surface and 500 hPa altitude.
/NO_PROFILES -> Do not create the plot of vertical profiles
of tracer differences along 15S and 42N.
/NO_RATIOS -> Do not create the maps of tracer ratios at
the surface and 500 hPa altitude.
/NO_STRATDIFF -> Do not create the maps of zonal mean differences
in the stratosphere (100hPa-0.01hPa)
/NO_STRATCONC -> Do not create the maps of zonal mean concentrations
in the stratosphere (100hPa-0.01hPa)
/NO_ZONALDIFF -> Do not create the maps of zonal mean differences
/NO_ZONALCONC -> Do not create the maps of zonal tracer concentrations
/NO_CLOUDDIFF -> Do not create difference plots of cloud optical depth
/NO_2D_MET -> Do not create difference plots for 2-D met fields
/NO_3D_MET -> Do not create difference plots for 3-D met fields
Additional keywords:
--------------------
/DEBUG -> Set this switch to print the values of the various
input variables. Use this to make sure that all values
have been created corectly.
/DYNRANGE -> Set this switch to create additional difference
plots, ratio plots, and profile plots using the whole
dynamic range of the data.
/NO_FULLCHEM -> Set this switch to only plot the advected
tracers and omit full-chemistry quantities such as OH
and aerosol optical depths. This is useful if you wish
to compare output from offline GEOS-Chem simulations
(e.g. Rn-Pb-Be, CH4).
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
====================================================
DynOutFile (function) GetSfc500Levels (function)
External Subroutines Required:
====================================================
CTM_NAMEXT (function) CTM_TYPE (function)
DIFFERENCES FREQ_DIST
FULLCHEM_BUDGET FULLCHEM_EMISSIONS
JV_RATIO PROFILES
MAPS NYMD2TAU (function)
RATIOS REPLACE_TOKEN
STRUADDVAR (function) MCF_LIFETIME (function)
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
BENCHMARK_1MON assumes that the following GEOS-Chem
diagnostic quantities have been archived for the
"old" and "new" model versions:
(a) ND22 ("JV-MAP-$") (h) ND44 ("DRYD-FLX")
(b) ND24 ("EW-FLX-$") (i) ND45 ("IJ-AVG-$")
(c) ND25 ("NS-FLX-$") (j) ND65 ("PORL-L=$")
(d) ND26 ("UP-FLX-$") (k) ND66 ("DAO-3D-$")
(e) ND31 ("PEDGE-$" ) (l) ND67 ("DAO-FLDS")
(f) ND43 ("CHEM-L=$") (m) ND69 ("DXYP" )
(g) ND32 (""NOX-AC-$", "NOX-AN-$", "NOX-BIOB",
"NOX-FERT", "NOX-LI-$", "NOX-SOIL")
EXAMPLES:
BENCHMARK_1MON, 'input.1mon'
; Produces the full suite of benchmark output plots.
BENCHMARK_1MON, 'input.1mon', /DYNRANGE
; Produces the full suite of benchmark output plots.
; Will also produce an additional set of difference and
; ratio maps using the full dynamic range of the data.
BENCHMARK_1MON, 'input.1mon', /DEBUG, /NO_FREQ_DIST
; Will produce the standard plots except for the
; frequency distribution histogram. Also will cause
; extra information to be echoed to the screen.
MODIFICATION HISTORY:
bmy, 09 Nov 2007: VERSION 1.01
- based on "benchmark.pro"
bmy, 10 Jan 2011: VERSION 1.02
- Now set proper symbolic links to
diaginfo.dat and tracerinfo.dat
- Set 500hPa level for MERRA
- Added /NO_PROFILES keyword to suppress
printing of vertical profiles
bmy, 08 Jun 2011: VERSION 1.03
- Updated comments
- Added /NO_BUDGET, /NO_EMISSIONS,
/NO_PROFILES, /NO_CONC_MAPS, /NO_DIFFS,
/NO_JVALUES, /NO_RATIOS, /NO_FULLCHEM
keywords.
- Now pass _EXTRA=e to all routines
- Now use FILE_WHICH to locate the
diff_range.1mon file
- Now look for diaginfo.dat and
tracerinfo.dat in RUNDIR_2. Do not
use symbolic links anymore.
bmy, 10 Jun 2011: - Now call EMISSION_RATIOS
bmy, 23 Jun 2011 - Now call ZONAL_DIFF
bmy, 18 Jul 2011 - Now pass /PRESSURE keyword to ZONAL_DIFF
to create plots w/ pressure on Y-axis
bmy, 11 May 2012: GAMAP VERSION 2.16
- Now do not stop the run if the two model
grids are equivalent. This allows
comparisons between GEOS-5, MERRA,
GEOS-5.7 data.
- Return 500hPa level for GEOS-5.7 met
cdh, 18 Mar 2013: GAMAP VERSION 2.17
- Added Zonal concentration plots for !
1-month benchmarks
mps, 16 Sep 2013: - Now create AOD difference plots
- Now create AOD map plots
mps, 18 Nov 2013: - Read in Model_1 and Model_2 as printed in input
file. Previously, model names were converted to
filename extensions using CTM_NamExt.
- Update GetSfc500Levels to accept model names
- Rename all instances of GEOS57_47L to GEOSFP_47L
mps, 02 Dec 2013: - Now create difference plots for 2-D and 3-D
met fields
mps, 03 Dec 2013: - Now create absolute difference plots for J-values
mps, 21 Apr 2015: - Now create emission maps and emission difference
plots
mps, 11 Sep 2015: - Now create stratospheric benchmark plots showing
zonal mean differences and concentrations for
100-0.01 hPa
mps, 04 Mar 2016: - Include MERRA2 in the check for equivalent
vertical grids
mps, 29 Mar 2016: - Add plots for cloud optical depth
(See /n/home09/ryantosca/IDL/gamap2/benchmark/benchmark_1mon.pro)
NAME:
BINARY (function)
PURPOSE:
This function returns the binary representation of a number.
Numbers are converted to LONG integers if necessary.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = BINARY( NUMBER )
INPUTS:
NUMBER -> Number for which its binary representation
will be returned. Number may be any of the numeric
types (BYTE, INT, LONG, FLOAT, DOUBLE, COMPLEX, etc).
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, BINARY( 11B )
0 0 0 0 1 0 1 1
; Binary representation of 11B
(2)
PRINT, FORMAT='(Z9.8,5X,4(1X,8A1))', LONG(!PI,0), BINARY(!PI)
40490fdb 01000000 01001001 00001111 11011011
; If data extraction is used instead of conversion
; Binary representation of pi (little endian IEEE
; representation)
AUTHOR:
Kevin Ivory Tel: +49 5556 979 434
Max-Planck-Institut fuer Aeronomie Fax: +49 5556 979 240
Max-Planck-Str. 2 mailto:Kevin.Ivory@linmpi.mpg.de
D-37191 Katlenburg-Lindau, GERMANY
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/math_units/binary.pro)
NAME:
BOXPLOT
PURPOSE:
Produce a box and whisker plot of a data vector
CATEGORY:
Plotting
CALLING SEQUENCE:
BOXPLOT,DATA [,keywords]
INPUTS:
DATA --> the data vector
KEYWORD PARAMETERS:
GROUP --> array of the same dimension as DATA which contains
grouping information. One box is plotted for each group.
If MINGROUP or MAXGROUP are given, boxes and whiskers are
only plotted for group values within this range.
GROUP may not contain more than 28 different values.
Group can also be a string array. In this case MINGROUP
and MAXGROUP make no sense of course.
MINGROUP --> the minimum group value for which a box shall be
plotted
MAXGROUP --> the maximum group value for which a box shall be
plotted
LABEL --> string array containing labels for *different* groups.
NOTE: The user must take care that one label is passed for
each group to be plotted. If label is not specified, the
group values will be used as axis labels
COLOR --> plotting color for axis (default : 1, i.e. black in MYCT
color scheme). Will also be used as default for BOXCOLOR.
BOXCOLOR --> color of the boxes (frames). Default is the COLOR
value, i.e. 1 if not specified. This color will also be used as
default for MEDIANCOLOR and MEANCOLOR. If you want boxes that
are only filled but have no frame, you must specify BOXCOLOR=-1.
In this case the default for MEDIANCOLOR and MEANCOLOR will
be the COLOR value.
BOXWIDTH --> relative width of boxes (default: 0.8).
BOXPOSITION --> relative position of box on x axis (default: 0.).
This parameter can be used together with the OVERPLOT keyword
to plot multiple groups of boxes in one graph.
MEDIANCOLOR --> a color value for the median bar
(default: value of BOXCOLOR)
MEANSYMBOL --> symbol to be used for mean values. If no symbol
is given, no mean values will be drawn.
MEANCOLOR --> color for mean symbols (default: value of BOXCOLOR)
FILLCOLOR --> a value or an array containing the colorindex for all
boxes or each box, respectively. If a single value is given,
*all* boxes will be filled with this color. If an array is
passed that has less elements than there are groups to plot,
the remaining colors will be filled with 15 (grey in MYCT
standard-scheme). If no FILLCOLOR is specified, the boxes will
be empty.
MISSING --> a value that represents missing data. If given, any data
with a value of missing will be filtered out before plotting.
PRINTN --> print number of elements on top of each box/whisker
CHARSIZE --> character size of the PRINTN labels (default: 0.8)
/OVERPLOT --> do not draw a new coordinate system but overlay new
data. For 2 sets of data you should use BOXWIDTH=0.4 and
BOXPOSITION=-0.25 and 0.25, respectively.
ORIENTATION -> orientation for axis labels (see XYOUTS procedure)
/IS_PERCENTILE --> data are already processed percentiles. In this
case data must be an array with dimensions 5,N. The GROUP keyword
is ignored, and each set of the N percentiles will be treated as
one group.
PERCVAL --> float array with 5 elements denoting the percentile
values (default: 0.05, 0.25, 0.5, 0.75, 0.95)
Further keywords are passed to the PLOT routine and can be used
to determine the appearance of the plot (e.g. XTITLE,YTITLE,
YSTYLE,YRANGE,/YLOG,COLOR,THICK)
OUTPUTS:
SUBROUTINES:
External Subroutines Required:
===============================
PERCENTILES (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
O3 = DATA( WHERE( HEADER EQ 'O3' ), * )
ALT = DATA( WHERE( HEADER EQ 'ALT' ), * )
IALT = 2.0* FIX( ALT / 2.0 )
BOXPLOT, O3, GROUP=IALT
; Produces a boxplot with ozone percentiles in
; altitude bins of 2 (km). Axis, box frames and
; labels will be black, boxes are not color filled.
(2)
BOXPLOT, O3, GROUP=IALT, FILLC=15, MEANSYM=SYM(1), $
MEANCOL=2, BOXWIDTH=0.6, YTITLE='O3', $
XTITLE='alt. bin', MISSING=-999.99, /PRINTN
; Produces boxes that are filled with light grey and
; have a black frame and median line. A red filled
; circle denotes the mean value, titles are assigned
; to the x and y axis. The number of valid observations
; is printed on top of each box. The boxes are reduced
; in size.
CO = DATA( WHERE( HEADER EQ 'CO' ), * )
BOXPLOT, O3, GROUP=IALT, MISSING=-999.99, BOXCOL=4, $
BOXWIDTH=0.4, BOXPOS=-0.25
BOXPLOT, CO, GROUP=IALT, MISSING=-999.99, BOXCOL=2, $
BOXWIDTH=0.4, BOXPOS=+0.25, /OVERPLOT
; Produces a plot with blue box frames for ozone
; and red frames for CO data.
MODIFICATION HISTORY:
mgs, 30 Jul 1997: VERSION 1.00
mgs, 03 Aug 1997: added template
mgs, 27 Nov 1997: some revisions and suggested changes by T.Brauers:
- better color handling (NOTE: meaning of BOXCOLOR has changed)
- optional overlay of mean value
- box frames
- variable boxwidth
- error fixing lower upper boundaries in log plots
- bug fix with label keyword
- added OVERPLOT and BOXPOSITION keywords
mgs, 22 Jan 1998: added IS_PERCENTILE keyword to allow
plotting of data that has been processed already
mgs, 17 Apr 1998:
- x-axis handling improved (now uses axis command and xyouts)
- orientation and medianthick keywords added
mgs, 21 May 1998:
- added percval keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/plotting/boxplot.pro)
NAME:
BPCH2ASCII
PURPOSE:
Translates data from GAMAP-readable binary punch file v. 2.0
format to a simple ASCII file format
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH2ASCII, INFILE, OUTFILE [ , Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the ASCII file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2ASCII will write a separate
netCDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2nc_output.%DATE%.%TIME%.ascii".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in ASCII format to OUTFILE.
/VERBOSE -> If set, then BPCH2ASCII will also echo the
header lines for each data block to the screen.
FORMAT -> String containing the numeric format for
for the data values. Default is '(7(e13.6,1x))'
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=============================================
CTM_GET_DATA TAU2YYMMDD (function)
GETMODELANDGRIDINFO REPLACE_TOKEN (function)
UNDEFINE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) BPCH2ASCII assumes that all data blocks in the *.bpch file
file adhere to same grid. This will be true for output
files from the GEOS-CHEM model.
(2) BPCH2ASCII will write a separate ASCII file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(3) BPCH2NC will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. The tokens %DATE% and %TIME% tokens
may be either in uppercase or lowercase.
(4) The format of the ASCII file is:
Data block #1 header line
Data block #1 values (format specified by FORMAT keyword)
Data block #2 header line
Data block #2 values (format specified by FORMAT keyword)
...
The header line will contain the units and size of
each data block.
(5) The data is written to the ASCII file in column-major
order (i.e. the same way as in FORTRAN), so you can read
the data into FORTRAN w/ the following code:
READ( IUNIT, '(a)' ) HEADER
READ( IUNIT, '(1p,7(e13.6,1x))' )
& ((DATA(I,J), I=1,IMX), J=1,JMX)
where IMX and JMX are the dimensions of the data block.
EXAMPLE:
BPCH2ASCII, 'myfile.bpch', 'myfile.%DATE%.%TIME%.ascii'
; Read data from binary punch file 'myfile.bpch'
; and writes it to ASCII file 'myfile.bpch.ascii'.
MODIFICATION HISTORY:
bmy, 22 May 2002: GAMAP VERSION 1.50
bmy, 28 May 2002: GAMAP VERSION 1.51
- Added FORMAT keyword
bmy, 03 Jun 2004: GAMAP VERSION 2.02
- now pass extra keywords to CTM_GET_DATA
via _EXTRA=e keyword
bmy, 03 Dec 2004: GAMAP VERSION 2.03
- add CATEGORY keyword (passed to CTM_GET_DATA)
in order to refine data block search
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2ascii.pro)
NAME:
BPCH2COARDS
PURPOSE:
Reads data from a binary punch file and saves it in a
COARDS-compliant netCDF (network Common Data Format) 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:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2COARDS, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If INFILE
is not passed, the user will be prompted to supply a
file name via a dialog box.
OUTFILE -> Name of the netCDF file to be written. It is
recommended to insert the tokens %DATE% (or %date%)
into OUTFILE, since BPCH2COARDS will write a separate
netCDF file for each unique YYYYMMDD value contained
within the *.bpch file. If OUTFILE is not specified,
BPCH2COARDS will use the default file name
"coards.%DATE%.nc".
KEYWORD PARAMETERS:
DIAGN -> Array of diagnostic categories from the bpch file
to save to netCDF format. If omitted, BPCH2COARDS will
save all diagnostic categories.
/VERBOSE -> If set, will print the name of each tracer
as it is being written to the netCDF file. Useful
for debugging purposes.
/NC4 -> Write a netCDF4 file instead of netCDF3. Default is
NetCDF3. NetCDF4 support requires IDL 8.0 or later.
COMPRESS -> Integer 0-9 specifies amount of compression in
netCDF4 files. Default is 2, with very little benefit
for higher compression.
/PCOORD -> Use mean pressure as the vertical coordinate rather
sigma or eta
/ALTCOORD -> Use mean altitude as the vertical coordinate
rather than sigma or eta
/TROPONLY -> Write only tropospheric layers
/ONEFILE -> Write all data to one netCDF output file.
Default is one file per calendar day.
_EXTRA=e -> Picks up additional keywords for NCDF_SET
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
============================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
STRREPL (function) GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the NCDF routines.
NOTES:
(1) BPCH2COARDS assumes that each data block in the *.bpch
file is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2COARDS assumes that the number type of each data
block in the *.bpch file is REAL*4 (a.k.a. FLOAT).
(3) BPCH2COARDS assumes that all data blocks in the *.bpch
file adhere to same horizontal grid. This will always
be true for output files from the GEOS-CHEM model.
(4) BPCH2COARDS will write a separate COARDS-compliant netCDF
file corresponding to each unique YYYYMMDD date. This
prevents the files from becoming too large to be read
with IDL.
(5) BPCH2COARDS will replace the %DATE% (or %date%) token with
the current YYYYMMDD value. Therefore, it is recommended
to insert this token into the string passed via OUTFILE.
(6) BPCH2COARDS will write arrays containing the latitudes,
longitudes to the netCDF file. For 3-D data blocks,
the eta or sigma centers will also be written to the
file. Time will be written as TAU values (i.e. hours
since 00:00 GMT on 01-Jan-1985.
(7) The netCDF library has apparently been updated in
IDL 6.0+. The result is that variable names containing
characters such as '$', '=', and ':' may now cause an
error in NCDF_VARDEF. Therefore, we now pre-screen
tracer names with function NCDF_VALID_NAME.
EXAMPLE:
BPCH2COARDS, 'myfile.bpch', 'myfile.%DATE%.nc'
; Will write the contents of "myfile.bpch" to one
; or more COARDS-compliant netCDF files adhering
; to the filename convention "myfile.YYYYMMDD.nc"
MODIFICATION HISTORY:
rjp & bmy, 17 Mar 2005: GAMAP VERSION 2.03
- Based on bpch2nc.pro
bmy, 21 Jul 2005: GAMAP VERSION 2.04
- Bug fix:
bmy, 13 Jul 2006: GAMAP VERSION 2.05
- Remove call to PTR_FREE
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now count GCAP among the GEOS family
for the purpose of converting the TAU
date to a YYYY/MM/DD date.
phs, 29 Oct 2009: GAMAP VERSION 2.14
- Can process files with 3D data on both
centers and edges of the grid boxes.
bmy, 19 Dec 2011: GAMAP VERSION 2.16
- Now handles multiple vertical dimensions
in the bpch file properly.
- Bug fix: now write vertical levels edges to
the file.
bmy, 27 Sep 2012: - Bug fix: Now handle data blocks that straddle
the date line.
bmy, 05 Nov 2013: GAMAP VERSION 2.17
- Change attributes for better COARDS compliance
bmy, 12 Feb 2014: GAMAP VERSION 2.18
- Add more modifications for 4-D data blocks
from bpch files created w/ GC_COMBINE_ND49
bmy, 03 Mar 2015: - Now define dims in order: time, lev, lon, lat,
which is more COARDS compliant.
cdholmes, 29 Mar 2017 - Add support for NetCDF4 and
compression
- Add support for pressure and altitude
as vertical coordinate
- ONEFILE puts all data into a single
output file
- TROPONLY limits the output to
troposphere layers
- Singleton "altXXX" dimensions are avoided
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2coards.pro)
NAME:
BPCH2GMI
PURPOSE:
Reads data from a binary punch file and saves it in
netCDF (network Common Data Format) format. The data
will be shifted so that the first longitude is 0 degrees
(i.e. the prime meridian) in order to conform with the
GMI (Global Model Initiative) model grid definition.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2GMI, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the netCDF file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2NC will write a separate
netCDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2nc_output.%DATE%.%TIME%.nc".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in netCDF format to OUTFILE.
/VERBOSE -> If set, will print the names of each tracer
as it is being written to the netCDF file.
_EXTRA=e -> Picks up additional keywords for netCDF routines
OUTPUTS:
SUBROUTINES:
Internal Subroutines:
============================================
B2G_Valid_VarName (function)
B2G_SetNcDim (function)
B2G_GetNcDim (function)
External Subroutines Required:
============================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
STRREPL (function) GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the NCDF routines.
NOTES:
(1) BPCH2GMI assumes that each data block in the *.bpch file
is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2GMI assumes that the number type of each data block
in the *.bpch file is REAL*4 (a.k.a. FLOAT).
(3) BPCH2GMI assumes that all data blocks in the *.bpch file
file adhere to same horizontal grid. This will always
be true for output files from the GEOS-CHEM model.
(4) BPCH2GMI will write a separate NC file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(5) BPCH2GMI will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. The tokens %DATE% and %TIME% tokens
may also be passed in lowercase (e.g, %date%, %time% ).
(6) BPCH2GMI will write arrays containing the latitudes,
longitudes to the netCDF file. For 3-D data blocks,
the sigma centers will also be written to the file.
Date and time are stored as global attributes.
(7) The netCDF library has apparently been updated in
IDL 6.0+. The result is that variable names containing
characters such as '$', '=', and ':' may now cause an
error in NCDF_VARDEF. Therefore, we now pre-screen
tracer names with function NCDF_VALID_NAME.
EXAMPLE:
BPCH2GMI, 'myfile.bpch', 'myfile.%DATE%.%TIME%.nc'
; Will write the contents of "myfile.bpch" to one
; or more netCDF files "myfile.YYYYMMDD.HHMMSS.nc"
MODIFICATION HISTORY:
bmy & phs, 20 Aug 2007: GAMAP VERSION 2.10
- Based on BPCH2NC
bmy, 19 Dec 2007: GAMAP VERSION 2.12
- Now save sigma edges & centers or
eta edges & centers to the file.
- Extra error trap, if there is only one
level in the file then set IS_3D=0.
bmy, 20 Dec 2011: GAMAP VERSION 2.16
- Changed default filename to "bpch2
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2gmi.pro)
NAME:
BPCH2HDF
PURPOSE:
Reads data from a binary punch file and saves it in HDF-SD
(Hierarchical Data Format, Scientific Dataset) format.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2HDF, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the HDF file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2HDF will write a separate
HDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2hdf_output.%DATE%.%TIME%.hdf".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in HDF format to OUTFILE.
_EXTRA=e -> Picks up additional keywords for HDF_SETSD
OUTPUTS:
SUBROUTINES:
External Subroutines Required:
=========================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
HDF_SETSD GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the HDF-SD routines.
NOTES:
(1) BPCH2HDF assumes that each data block in the *.bpch file
is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2HDF assumes that all data blocks in the *.bpch file
file adhere to same horizontal grid. This will be true
for output files from the GEOS-CHEM model.
(3) BPCH2HDF will write a separate HDF file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(4) BPCH2HDF will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. These tokens may be in either
uppercase or lowercase.
(4) BPCH2HDF will also write arrays containing the latitudes,
longitudes, sigma coordinates (for 3-D data blocks only!)
to the HDF file.
(5) BPCH2HDF will write arrays containing the latitudes,
longitudes to the netCDF file. For 3-D data blocks,
the sigma centers and sigma edges will also be written
to the file.
EXAMPLE:
BPCH2HDF, 'myfile.bpch', 'myfile.%DATE%.%TIME%.hdf'
; Will write the contents of "myfile.bpch" to
; one or more HDF files "myfile.YYYYMMDD.HHMMSS.hdf"
MODIFICATION HISTORY:
bmy, 22 May 2002: GAMAP VERSION 1.50
bmy, 22 Oct 2002: GAMAP VERSION 1.52
- bug fix: now do not write vertical layer
dim info to HDF file for 2-D grids
bmy, 22 May 2003: GAMAP VERSION 1.53
- Make sure LONGNAME is not a null string
bmy, 18 Sep 2003: - Call PTR_FREE to free the pointer memory
bmy, 03 Jun 2004: GAMAP VERSION 2.02
- now pass extra keywords to CTM_GET_DATA
via _EXTRA=e keyword
bmy, 03 Sep 2004: GAMAP VERSION 2.03
- now defines ETAC and ETAE variables
for hybrid grids
bmy, 03 Dec 2004: GAMAP VERSION 2.03
- add DIAGN keyword (passed to CTM_GET_DATA)
in order to refine data block search
bmy, 19 May 2006: GAMAP VERSION 2.05
- Now do not free the pointer memory
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now count GCAP among the GEOS family
for the purpose of converting the TAU
date to a YYYY/MM/DD date.
bmy, 18 Feb 2009: GAMAP VERSION 2.13
- Bug fix: should be N_ELEMENTS( DiagN )
instead of N_ELEMENTS( Category ) in the
IF statement for CTM_GET_DATA.
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2hdf.pro)
NAME:
BPCH2NC
PURPOSE:
Reads data from a binary punch file and saves it in
netCDF (network Common Data Format) format.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2NC, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the netCDF file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2NC will write a separate
netCDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2nc_output.%DATE%.%TIME%.nc".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in netCDF format to OUTFILE.
/VERBOSE -> If set, will print the names of each tracer
as it is being written to the netCDF file.
_EXTRA=e -> Picks up additional keywords for NCDF_SET
OUTPUTS:
SUBROUTINES:
Internal Subroutines:
============================================
B2N_Valid_VarName (function)
B2N_SetNcDim (function)
B2N_GetNcDim (function)
External Subroutines Required:
============================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
STRREPL (function) GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the NCDF routines.
NOTES:
(1) BPCH2NC assumes that each data block in the *.bpch file
is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2NC assumes that the number type of each data block
in the *.bpch file is REAL*4 (a.k.a. FLOAT).
(3) BPCH2NC assumes that all data blocks in the *.bpch file
file adhere to same horizontal grid. This will always
be true for output files from the GEOS-CHEM model.
(4) BPCH2NC will write a separate NC file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(5) BPCH2NC will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. The tokens %DATE% and %TIME% tokens
may also be passed in lowercase (e.g, %date%, %time% ).
(6) BPCH2NC will write arrays containing the latitudes,
longitudes to the netCDF file.
(7) For pure-sigma grids (e.g. GEOS-1, GEOS-STRAT, GEOS-3),
BPCH2NC will write the following additional variables to
the netCDF file:
(1) SIGE : Sigma coordinate at level edges
(2) SIGC : Sigma coordinate at level centers
The pressure at the bottom edge of level L is given by:
Pe(L) = Ptop + [ SIGE(L) * ( Psurface - Ptop ) ]
and the pressure at the vertical center of level L is:
Pc(L) = Ptop + [ SIGC(L) * ( Psurface - Ptop ) ]
%%%%% NOTE: This is mostly obsolete, as most met fields
%%%%% that are used to drive CTM's are now placed onto
%%%%% hybrid grids.
(8) For hybrid grids (e.g. GEOS-4, GEOS-5, MERRA), the following
dditional variables will be written to the netCDF file:
(1) ETAE : Eta coordinate on level edges
(2) ETAC : Eta coordinate on level centers
(3) Ap : Hybrid grid "A" parameter
(4) Bp : Hybrid grid "B" parameter
The pressure at the bottom edge of level L is given by:
Pe(L) = Ap(L) + ( Bp(L) * Psurface )
and the pressure at the vertical center of level L is:
Pc(L) = ( Pe(L) + Pe(L+1) ) * 0.5
The hybrid ETA coordinates (similar to sigma) at the
level edges and centers are, correspondingly:
ETAE(L) = ( Pe(L) - Ptop ) / ( Psurface - Ptop )
ETAC(L) = ( Pc(L) - Ptop ) / ( Psurface - Ptop )
%%%%% NOTE: The ETAe and ETAc values are only approximate
%%%%% and are computed with a surface pressure of 1013.25
%%%%% hPa. For your scientific analysis, you should compute
%%%%% the pressures at level edges from Ap, Bp, and a
%%%%% spatially-varying surface pressure field (e.g. saved
%%%%% out from GEOS-Chem or another model).
(7) The date and time of the data are stored in the netCDF
file as global attributes.
(8) The netCDF library has apparently been updated in
IDL 6.0+. The result is that variable names containing
characters such as '$', '=', and ':' may now cause an
error in NCDF_VARDEF. Therefore, we now pre-screen
tracer names with function NCDF_VALID_NAME.
EXAMPLE:
BPCH2NC, 'myfile.bpch', 'myfile.%DATE%.%TIME%.nc'
; Will write the contents of "myfile.bpch" to one
; or more netCDF files "myfile.YYYYMMDD.HHMMSS.nc"
MODIFICATION HISTORY:
bmy, 22 May 2002: GAMAP VERSION 1.50
bmy, 22 Oct 2002: GAMAP VERSION 1.52
- bug fix: now do not write vertical layer
dim info to netCDF file for 2-D grids
bmy, 22 May 2003: GAMAP VERSION 1.53
- Bug fix: LONGNAME cannot be a null string
bmy, 22 Sep 2003: - Now declare all variables first, then save
data into them. This is much more efficient!
- Remove reference to NCDF_SET routine
- Call PTR_FREE to free the pointer memory
- Bug fix: now sort TAU0 values for call to UNIQ
- added /VERBOSE keyword
bmy, 09 Oct 2003: - for IDL 6.0+, use '__' to separate category
name from the tracer name
bmy, 21 Oct 2003: - Now uses function NCDF_Valid_Name to screen
out and replace invalid characters for netCDF
variable names
bmy, 06 Nov 2003: GAMAP VERSION 2.01
- added extra global attributes to facilitate
reading netCDF files created by BPCH2NC
into GAMAP
bmy, 29 Mar 2004: GAMAP VERSION 2.02
- Now saves ETA centers for hybrid grid
instead of sigma centers
bmy, 17 Mar 2005: GAMAP VERSION 2.03
- Bug fix: now prints ETAC properly
when the /VERBOSE keyword is set
bmy, 03 Oct 2006: GAMAP VERSION 2.05
- Bug fix: now do not call PTR_FREE
to free the pointer memory
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now count GCAP among the GEOS family
for the purpose of converting the TAU
date to a YYYY/MM/DD date.
bmy, 21 Jan 2008: GAMAP VERSION 2.12
- Now save sigma edges & centers or
eta edges & centers to the file.
- Extra error trap, if there is only one
level in the file then set IS_3D=0.
- Now error check for duplicate variable names
bmy, 28 Nov 2008: GAMAP VERSION 2.15
- Now save out hybrid-grid Ap and Bp
parameters so that users can accurately
compute the pressure at level edges and
centers.
- Updated comments
bmy, 07 Mar 2012: GAMAP VERSION 2.16
- Correct typos in /VERBOSE output
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2nc.pro)
NAME:
BPCH2PCH
PURPOSE:
Translates data from GAMAP-readable binary punch
file v. 2.0 format to the ancient ASCII-punch
file standard.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH2PCH, FILENAME [, OUTFILENAME [, Keywords ] ]
INPUTS:
FILENAME -> Name of the binary punch file from which
to read data. FILENAME may be a file mask, and may
contain wild card characters (e.g. ~/ctm.bpch.*). If
FILENAME is omitted or contains a wild card character,
the user will be prompted to pick a file via a dialog box.
OUTFILENAME (optional) -> Name of the output ASCII punch
file. Default is 'ASCIIfile.pch'
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in ASCII punch format
to OUTFILE.
/EXTRA_SPACE -> If set, will put an extra space between
the numbers in the ASCII punch file. This might
be necessary when using MATLAB or S-PLUS to read
in the ASCII punch file.
OUTPUTS:
Writes data to ASCII punch file format
SUBROUTINES:
CTM_GET_DATA
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
Some limitations:
(1) Works only for global lon-lat diagnostics.
(2) The top header line might be inaccurate (but nobody
really reads that anyway, so forget it for now...)
EXAMPLE:
BPCH2PCH, '~/bmy/ctm.bpch', '~/bmy/ctm.pch'
; Reads data from binary punch file '~/bmy/ctm.bpch'
; and writes it to ASCII punch file '~/bmy/ctm.pch'.
MODIFICATION HISTORY:
bmy, 08 Nov 1999: VERSION 1.00
bmy, 03 Jun 2004: GAMAP VERSION 2.02
- now pass extra keywords to CTM_GET_DATA
via _EXTRA=e keyword;
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2pch.pro)
NAME:
BPCH_LINK
PURPOSE:
Copies data from several binary punch files into a single
binary punch file. Also can trim data down to nested-grid
resolution if necessary
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH_LINK, INFILES, OUTFILE [, Keywords ]
INPUTS:
INFILES -> A path name or file mask (with wildcards)
which indicates the names of the individual files
to be linked together in a single bpch file.
OUTFILE -> Name of the bpch file that will contain data
from the individual bpch files specified by INFILES.
KEYWORD PARAMETERS:
/CREATE_NESTED --> If set, then BPCH_LINK will trim data
to the nested grid resolution as specified by the
XRANGE and YRANGE keywords.
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 [-90,90].
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
OPEN_FILE UNDEFINE
CTM_DIAGINFO
REQUIREMENTS:
Requires routines from the GAMAP and TOOLS packages.
NOTES:
None
EXAMPLE:
BPCH_LINK, 'ctm.bpch.*', 'new.ctm.bpch'
; Consolidates data from the 'ctm.bpch.*' files
; into a single file named 'new.ctm.bpch'
MODIFICATION HISTORY:
bmy, 31 Jan 2003: VERSION 1.00
bmy, 09 Apr 2003: VERSION 1.01
- now can save to nested grid
bmy, 15 May 2003: VERSION 1.02
- now can pass a list of files via INFILES
bmy, 20 Nov 2003: GAMAP VERSION 2.01
- now gets the spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 28 May 2004: GAMAP VERSION 2.02
- Now use MFINDFILE to get INLIST regardless
of the # of elements of INFILES
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read/write bpch as big-endian
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_link.pro)
NAME:
BPCH_MONTHLY_MEAN
PURPOSE:
Creates monthly means from GEOS-Chem output saved at less
than monthly intervals. Ideal for working with output of
high-resolution model output, especially if your queuing
system time limits do not permit a 1-month simulation to be
completed in a single run stage.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH_MONTHLY_MEAN, FILES [, Keywords ]
INPUTS:
FILES -> A vector containing the pathnames of the files from
which you would like to create monthly mean output.
KEYWORD PARAMETERS:
OUTFILENAME -> Name of the file (bpch format) that will
contain the monthly mean output. The default is
"bpch_monthly_mean_output.bpch".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required
================================
REQUIREMENTS:
Requires other routines from the GAMAP package.
NOTES:
Assumes that each of the files passed via the FILES argument
contains an identical sequence of diagnostic data blocks.
This will normally be the case for GEOS-Chem simulations that
have to be separated into several run stages for the queue
system.
Error checking is minimal, we will fix this later. This
routine in intended for use with files that are created from
individual stages of a long GEOS-Chem simulation. As such,
we can usually assume that all files will have the same
sequence of data blocks, and that all data blocks will be on
the same grid.
EXAMPLE:
FILES = [ 'ctm.bpch.2011010100', 'ctm.bpch.2011011500' ]
BPCH_MONTHLY_MEAN, FILES, OUTFILENAME = 'monthly_mean.bpch'
; Creates monthly-mean output from two GEOS-Chem bpch
; files that contain 15-day averaged data.
MODIFICATION HISTORY:
bmy, 21 Dec 2011: GAMAP VERSION 2.16
- Initial version
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_monthly_mean.pro)
NAME:
BPCH_SEP
PURPOSE:
Separates data from one binary punch file into another binary
punch file by time (TAU0), tracer, or location indices. Useful
for making smaller bpch files so that we don't run out of IDL
memory when reading/processing them.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:p
BPCH_SEP, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> A path name or file mask (with wildcards)
which indicates the names of the individual files
to be linked together in a single bpch file.
OUTFILE -> Name of the bpch file that will contain data
from the individual bpch files specified by INFILES.
KEYWORD PARAMETERS:
DIAGN -> Array of diagnostic categories for which to
save out to OUTFILE Default is to save all diagnostic
categories to OUTFILE.
TAU0 -> Time index (hours from 1 Jan 1985) denoting the
data blocks to be saved from INFILE to OUTFILE. You
can use NYMD2TAU to compute this from a YYYYMMDD date.
TRACER -> Tracer number(s) for which to save to OUTFILE.
Default is to save all tracers.
II, JJ, LL -> Longitude, latitude, altitude index arrays used
to cut down the data block to less than global size. Use
IDL notation, meaning first element is 0.
GLOBALCOORDS -> When the data entries in the bpch file
contain only part of the global CTM grid (e.g. ND48,
ND49, ND50, ND51) this indicates
that II, JJ, LL indices should be
interpreted as global CTM indices, rather than relative
to the regional subset grid.
EXCLUDE -> Reverses the selection criteria, so that the
designated DIAGN, TAU0, and TRACER are EXCLUDED from the
output file. Everything else is included. In order to be
excluded, a datablock must match all specified keywords:
DIAGN, TAU0, and TRACER.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================================
CTM_DIAGINFO LITTLE_ENDIAN (function)
OPEN_FILE UNDEFINE
REQUIREMENTS:
None
NOTES:
(1) Assumes that II, JJ, LL contain consecutive indices in
longitude, latitude, and altitude, respectively.
(2) Also assumes that II, JJ, LL are in IDL notation
(i.e. starting from zero). This is so that you can
pass the output from the WHERE command to BPCH_SEP.
EXAMPLES:
(1)
BPCH_SEP, 'ctm.bpch.big', 'ctm.bpch.small', tau0=140256D
; Pulls out data blocks for TAU0=140256 (1/1/2001) from
; "ctm.bpch.big" and saves them in "ctm.bpch.small"
(2)
INTYPE = CTM_TYPE( 'GEOS4', RES=4 )
INGRID = CTM_GRID( INTYPE )
INDX = WHERE( INGRID.XMID ge -60 AND INGRID.XMID le 60 )
INDY = WHERE( INGRID.YMID ge 0 AND INGRID.YMID le 60 )
BPCH_SEP, 'ctm.bpch.big', 'ctm.bpch.small', II=INDX, JJ=INDY
; Pulls out all data blocks for the geographical area
; from 60W - 60E longitude and 0-60N latitude.
MODIFICATION HISTORY:
bmy, 18 Sep 2003: GAMAP VERSION 1.53
bmy, 20 Nov 2003: GAMAP VERSION 2.01
- now gets the spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 07 Jul 2005: GAMAP VERSION 2.04
- minor bug fix; now can save out data
blocks for more than one matching TAU0
phs, 24 Oct 2006: GAMAP VERSION 2.05
- Added the II, JJ, LL keywords for
selecting a smaller geographical area.
These must be index arrays.
- Added the TRACERN keyword
- Added SWAP_ENDIAN=LITTLE_ENDIAN() in
the call to OPEN_FILE
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Cosmetic changes
bmy, 18 Jul 2016: GAMAP VERSION 2.19
- Now use the spacing obtained from
the diaginfo.dat file
cdh, 04 Apr 2017: -Add GlobalCoord keyword so that II,JJ,LL keywords
work with ND48, ND49, ND50 and ND51 output
-Prevent writing data when no matching
II,JJ,LL coordinates
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_sep.pro)
NAME:
BPCH_TEST
PURPOSE:
Reads header and data block information from binary punch
(BPCH for short) files and prints the file pointer locations.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH_TEST [, FILENAME, [ Keywords ] ]
INPUTS:
FILENAME (optional) -> Name of the binary punch file to read.
If omitted, a dialog box will prompt the user to make
a selection.
KEYWORD PARAMETERS:
/NOPAUSE -> If set, will not pause after displaying information
about each data block. Default is to pause to allow the
user to examine each data blocks header information.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
------------------------------
LITTLE_ENDIAN (function)
REQUIREMENTS:
References routines from the TOOLS package.
NOTES:
BPCH_TEST does not return any data values from the binary
punch file. It is meant to be used for debugging purposes.
EXAMPLES:
BPCH_TEST, 'my.bpch'
BPCH_TEST, FILENAME = 'my.bpch'
; will print info about each data block in 'my.bpch'
MODIFICATION HISTORY:
bmy, 10 Dec 1999: VERSION 1.00
bmy, 25 May 2000: GAMAP VERSION 1.45
- allow user to quit after viewing
each data block header
- add FILENAME keyword, so that the filename
can be passed as a parameter or a keyword
bmy, 21 Jul 2000: GAMAP VERSION 1.46
- now print locations of min, max data values
- changed FILETYPE to reflect new definitions
from CTM_OPEN_FILE
bmy, 24 Aug 2004: GAMAP VERSION 2.03
- Now recognizes bpch file containing
GEOS-CHEM station timeseries data
- Updated comments, cosmetic change
bmy, 05 Feb 2013: GAMAP VERSION 2.17
- Now recognize FTI "CTM bin 4D", which is
output from gc_combine_nd49.pro etc.
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_test.pro)
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)
NAME:
DATATYPE
PURPOSE:
Returns the number (or name) of the data type
of an IDL scalar, array, structure, or object.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = DATATYPE( Data [, Keywords ] )
INPUTS:
DATA -> A variable (scalar, array, structure, or object)
whose data type is desired.
KEYWORD PARAMETERS:
/NAME -> If set, will return the name of the data type
instead of the type number.
OUTPUTS:
The IDL data type number or data type name will be
contained in RESULT.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The IDL data type numbers are:
-----------------------------------------
0 : undefined 6 : complex
1 : byte 7 : string
2 : int 8 : structure
3 : long 9 : double complex
4 : float 10 : pointer
5 : double 11 : object reference
EXAMPLES:
PRINT, DATATYPE( 0d0 )
5
; Double precision data is type 5
PRINT, DATATYPE( 0d0, /Name )
DOUBLE
; Returns the name of the data type
MODIFICATION HISTORY:
bmy, 26 Jul 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/datatype.pro)
NAME:
DATE2YMD
PURPOSE:
Given a date in YYYYMMDD format, returns the year, month,
and day in separate variables. Also can be used to separate
time in a HHMMSS format into hours, minutes, seconds.
CATEGORY:
Date & Time
CALLING SEQUENCE:
DATE2YMD, YYYYMMDD, YEAR, MONTH, DAY
INPUTS:
YYYYMMDD -> Today's date as YYYY/MM/DD (or time as HH/MM/SS)
YEAR -> Year (or hour ) value
MONTH -> Month (or minute) value
DAY -> Day (or second) value
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
DATE2YMD, 20060101, Y, M, D
PRINT, Y, M, D
2006 1 1
; Separates the date into Y, M, D variables
DATE2YMD, 123000, H, Mi, S
PRINT, H, Mi, S
12 30 0
; Separates the time into H, Mi, S variables
MODIFICATION HISTORY:
bmy, 06 Jun 2006: TOOLS VERSION 2.05
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/date_time/date2ymd.pro)
NAME:
DAY_OF_YEAR (function)
PURPOSE:
Computes the day number (0-365 or 0-366 if leap year)
of a given date.
CATEGORY:
Date & Time
CALLING SEQUENCE:
RESULT = DAY_OF_YEAR( MONTH, DAY, YEAR ) OR
RESULT = DAY_OF_YEAR( YYYYMMDD )
INPUTS:
With 3 arguments:
MONTH (int or long) -> the input month (1 - 12)
DAY (int or long) -> the input day (0 - 31)
YEAR (int or long) -> the input year (YEAR<0 is BC; YEAR>0 is AD)
With 1 argument:
YYYYMMDD (long) -> the input date in YYYYMMDD format.
KEYWORD PARAMETERS:
OUTPUTS:
RESULT -> Day number of the year
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
(1) You cannot abbreviate YEAR. If you specify 10/14/97
DAY_OF_YEAR will compute the day number for 14 Oct 97 AD
instead of 14 Oct 1997 AD
EXAMPLES:
(1)
PRINT, DAY_OF_YEAR( 10, 14, 1997 )
287
; A typical modern date: 14 Oct 1997 AD
(2)
PRINT, DAY_OF_YEAR( 19971014 )
287
; The same as example #1, but this time we call
; DAY_OF_YEAR with a date in YYYYMMDD format
(3)
PRINT, DAY_OF_YEAR( 1, 1, 1 )
1
; Beginning of the "Anno Domini" era: 1 Jan 1 AD
(4)
PRINT, DAY_OF_YEAR( 3, 15, -44 )
74
; When Julius Caesar was murdered: 15 Mar 44 BC
MODIFICATION HISTORY:
bmy, 14 Oct 1997: VERSION 1.00
bmy, 26 Mar 1998: VERSION 1.01
-- now written as a function with
more elegant error checking.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 03 Apr 2008: GAMAP VERSION 2.12
- Modified to accept either 3 arguments
(month, day, year) or one argument
(date in YYYYMMDD format)
(See /n/home09/ryantosca/IDL/gamap2/date_time/day_of_year.pro)
NAME:
DEFAULT_DIRS
PURPOSE:
Define a couple of system variables to facilitate
file searching across or in multiple platforms.
The settings are made depending on the host name which
is queried with getenv().
This file is meant to be modified for your own computing
environment and directory structure. It's probably a good
idea to include a call to Default_Dirs in your startup file.
A string (or string array) argument allows individual users
to add their own default settings for individual projects
(see INPUTS).
CATEGORY:
General
CALLING SEQUENCE:
DEFAULT_DIRS [,projectlist [,searchpath=searchpath] ]
INPUTS:
PROJECTLIST -> A string or string array containing the names
of projects of individual users for which additional
settings shall be made. For each entry for which a procedure
named default_.pro exists, this procedure
will be called with the host name (lower case) as argument.
If the procedure is not found, a warning message is issued.
KEYWORD PARAMETERS:
SEARCHPATH -> A string that will be inserted at the beginning
of the !PATH variable to look for the default_
procedures. This keyword is only evaluated when a
PROJECTLIST is present. For simplicity, the user must make sure
that SEARCHPATH adheres to the syntax of the curent OS. Since
DEFAULT_DIRS is usually caled from the startup file, this
shouldn't be too much of a problem.
/PRINT -> print all system variables ending in 'DIR' after
the definition.
OUTPUTS:
Various system variables are created. As a minimum, these are
!RootDir = the root of the file system
!HomeDir = the user's home directory
!DataDir = a general data depository
!TmpDir = a temporary directory
!FNSep = filename seperator ('/' for unix and '\' for windows)
Further project-specific directories should also end in 'Dir',
this allows an easy query of all default directories:
help,/system_variables,output=o
print,o[ where(strpos(o,'DIR') gt 0) ]
(see PRINT keyword).
******* NEED TO WORK THAT OUT !! ****** it's not that easy !!! *********
SUBROUTINES:
none.
REQUIREMENTS:
none.
NOTES:
This routine uses a common block (yes!) to remember whether
the user had already been warned about non-exisiting project
procedures. Therefore, when you add projects on the fly,
you can probably call default_dirs safely every time you wish
to compose a search mask.
EXAMPLE:
default_dirs ; set platform dependent default directories
default_dirs,['GTE','CTM'],searchpath='~/myprogs',/PRINT
; as above, but add definitions from default_gte.pro and
; default_ctm.pro which may be in ~/myprogs or the regular
; IDL search !PATH. Print all !...DIR system variables upon
; exit. See attached default_gte procedure for an example.
MODIFICATION HISTORY:
mgs, 12 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/default_dirs.pro)
NAME:
DEFAULT_GTE
PURPOSE:
Define default system variables for GTE data directories
and GTE programs. Specific entries are made for the
PEM-Tropics A and B projects.
This procedure is caled from DEFAULT_DIRS when 'GTE' is
added as an argument.
CATEGORY:
General
CALLING SEQUENCE:
DEFAULT_GTE,host
INPUTS:
HOST -> the name of the host computer which is running IDL.
In our environment these are sol or cyclope or now.
KEYWORD PARAMETERS:
OUTPUTS:
Additional system variables are created:
!GTE_Dir = home of GTE data on current platform
!PEMTA_Dir = PEM-Tropics A data
!PEMTB_Dir = PEM-Tropics B data
!GTE_Filetypes = list of fiel extensions used with GTE data
SUBROUTINES:
REQUIREMENTS:
It is assumed that this routine is called from DEFAULT_DIRS
although it should be working stand-alone as well.
NOTES:
EXAMPLE:
see default_dirs
MODIFICATION HISTORY:
mgs, 12 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/default_gte.pro)
NAME:
DEFAULT_RANGE (function)
PURPOSE:
Make sure a RANGE argument or keyword is a valid vector with
at least two elements. Can also be used to limit RANGE to
two elements. The argument may be a string containing one or
more numeric values delimited by almost any character
combination (including '..' and '-'). A '-' will be treated
as a separator if it is preceeded by a digit or not followed
by a digit. The resulting range will be sorted and spans the
minimum and maximum of the "data" given in the argument.
CATEGORY:
General
CALLING SEQUENCE:
RANGE = DEFAULT_RANGE( ARG, DEFAULT [,/LIMIT2] )
INPUTS:
ARG -> The range argument or keyword as passed into
a procedure or function. This can be an undefined
variable or a variable with 1 or more elements.
If ARG contains 1 element, it will be repeated
to range from and to the same number.
DEFAULT -> A 2-element vector containing the default range
if ARG is undefined. This argument is mandatory
although it is not used if ARG contains at least
1 element.
KEYWORD PARAMETERS:
/LIMIT2 -> Limit the resulting RANGE vector to 2 elements.
Default is to return *at least* 2 elements.
RANGE -> Limit the RANGE vector to minimum and maximum
value given by this keyword.
/NOSORT -> Do not sort the output. This can be useful for
longitude vectors spanning the Pacific ;-)
OUTPUTS:
RANGE -> A two (or more) element vector that can be used in
statements like WHERE(x ge RANGE[0] AND x lt RANGE[1]).
SUBROUTINES:
External Subroutines Required:
============================================
ISALGEBRAIC (function) ISDIGIT (function)
STRBREAK (function) STRREPL (function)
REQUIREMENTS:
None
NOTES:
This function is meant for argument checking in procedures
or functions, hence it will generally not be called from the
command line.
EXAMPLE:
LATRANGE = DEFAULT_RANGE( LATRANGE, [-90.,90.] )
; Suppose a procedure has a keyword parameter named
; LATRANGE. Before we use LATRANGE in any form, we
; should test it (as above). This ensures that we have
; at least 2 elements in LATRANGE and it defaults
; LATRANGE to the whole globe if nothing was passed
; in the LATRANGE keyword.
MODIFICATION HISTORY:
mgs, 29 Sep 1998: VERSION 1.00
mgs, 17 Nov 1998: - added string handling
- added RANGE and NOSORT keywords
bmy, 13 Jul 2001: TOOLS VERSION 1.48
- now uses new STRREPL function from mgs
bmy, 16 Jul 2001: - bug fix: only call STRREPL if there are
non-algebraic characters to be replaced
- eliminate call to obsolete STR_SEP function
bmy, 17 Jan 2002: TOOLS 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/general/default_range.pro)
NAME:
DIFFERENCES
PURPOSE:
Creates absolute difference plots ( New - Old )
for GEOS-Chem tracers and OH.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
DIFFERENCES, FILES, LEVELS, TAUS, TRACERS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
LEVELS -> A 4-element vector containing the level indices
for the GEOS-Chem surface layer and 500 hPa layer.
for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
NOTE: This is in Fortran notation (starting from 1!)
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DO_FULLCHEM -> Set this switch to plot the chemically
produced OH in addition to the advected tracers.
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range to predetermined values as returned
by routine GET_DIFF_RANGE.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
===================================================
PlotDiff
External Subroutines Required:
===================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA GET_DIFF_RANGE
GETMODELANDGRIDINFO EXTRACT_FILENAME (function)
MULTIPANEL MYCT
OPEN_DEVICE TVMAP
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILES = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
LEVELS = [ 1, 1, 13, 13 ]
TAUS = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
TRACERS = INDGEN( 43 ) + 1
VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
DIFFERENCES, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'
; Creates ratio plots of two GEOS-CHEM versions
; (in this case v7-04-11 / v7-04-10) for July 2001.
; Output is sent to PostScript file "myplot.ps".
; The min and max of the data on each plot panel is
; restricted to pre-defined values returned by
; function GET_DIFF_RANGE.
DIFFERENCES, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
/DO_FULLCHEM, /DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Same as the above example, but the min & max of
; each plot panel corresponds to the dynamic range
; of the data.
MODIFICATION HISTORY:
bmy, 14 Nov 2007: VERSION 1.01
- Initial version
bmy, 20 Nov 2007: VERSION 1.02
- Now draw out-of-bounds triangles for
the colorbar when using the "small"
data ranges. New feature of TVMAP.
bmy, 07 May 2008: VERSION 1.03
- Now allow for comparing models on 2
different vertical grids.
bmy, 08 Feb 2011: VERSION 1.04
- Now display in the top-of-plot title
if the dynamic range option is used.
bmy, 08 Jun 2011: VERSION 1.05
- Added /NO_FULLCHEM keyword
- Now call COLORBAR with the UPOS keyword
to place the colorbar unit string properly
- Now use appropriate settings for creating
plots w/ the full dynamic range (/DYNRANGE)
- Now restore !MYCT sysvar to previous
settings upon exiting the program
mps, 29 Mar 2013: - Now plot HO2 differences
(See /n/home09/ryantosca/IDL/gamap2/benchmark/differences.pro)
NAME:
DIFFERENCES_AOD
PURPOSE:
Creates column difference maps of aerosol optical depths from
1-month GEOS-Chem benchmark simulation output.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
DIFFERENCES_AOD, FILES, TAUS, TRACERS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "red", 'green", and "blue" GEOS-Chem model
versions that are to be compared.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$") to be plotted.
VERSIONS -> A 2-element vector containing the model version
names from the "red", 'green", and "blue" simulations.
KEYWORD PARAMETERS:
/DYNRANGE -> Set this switch to create plots using the entire
dynamic range of the data (centered around zero). The
default is to use pre-defined data ranges.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Provided:
=========================================
PLOTDIFF
External Subroutines Required:
=========================================
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL COLORBAR_NDIV (function)
CTM_PLOT CHKSTRU (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLE:
FILES = [ 'ctm.bpch.v9-02p', 'ctm.bpch.v9-02q' ]
TAUS = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
TRACERS = [ 1, 2, 4 ]
VERSIONS = [ 'v9-02p', 'v9-02q' ]
DIFFERENCES_AOD, FILES, TAUS, TRACERS, VERSIONS, $
/PS, OUTFILENAME='myplot.ps'
; Creates difference maps from 2 different model versions
; using output from GEOS-Chem 1-month benchmark simulations.
DIFFERENCES_AOD, FILES, TAUS, TRACERS, VERSIONS, /DYNRANGE, $
/PS, OUTFILENAME='myplot.ps'
; Same as above, but will create difference maps using
; the full dynamic range of the data (centered around zero)
; instead of using pre-defined min & max values.
MODIFICATION HISTORY:
bmy, 09 Nov 2007: VERSION 1.01
- Initial version
bmy, 20 Dec 2007: VERSION 1.02
- Now pass the month as a keyword to
put on the plot panel titles
bmy, 02 Jun 2011: VERSION 1.03
- Make the colorbar a little wider
- Reduce the character size CsFac to 0.75
to better display long plot titles
- Now call COLORBAR with the UPOS keyword
to place the colorbar unit string properly
- Now use appropriate settings for creating
plots w/ the full dynamic range (/DYNRANGE)
- Also restore the !MYCT sysvar to defaults
mps, 16 Sep 2013: - Modified for 1-month benchmark output
bmy, 24 Jan 2014: GAMAP VERSION 2.17
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/benchmark/differences_aod.pro)
NAME:
DIFF_2D_MET
PURPOSE:
Creates absolute difference plots ( New - Old )
for GEOS-Chem 2-D meteorology fields.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
DIFF_2D_MET, FILES, TAUS, TRACERS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range to predetermined values as returned
by routine GET_DIFF_RANGE.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
===================================================
PlotDiff
External Subroutines Required:
===================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA GET_DIFF_RANGE
GETMODELANDGRIDINFO EXTRACT_FILENAME (function)
MULTIPANEL MYCT
OPEN_DEVICE TVMAP
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILES = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
TAUS = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
TRACERS = INDGEN( 43 ) + 1
VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
DIFF_2D_MET, FILES, TAUS, TRACERS, VERSIONS, $
/PS, OUTFILENAME='myplot.ps'
; Creates ratio plots of two GEOS-CHEM versions
; (in this case v7-04-11 / v7-04-10) for July 2001.
; Output is sent to PostScript file "myplot.ps".
; The min and max of the data on each plot panel is
; restricted to pre-defined values returned by
; function GET_DIFF_RANGE.
DIFF_2D_MET, FILES, TAUS, TRACERS, VERSIONS, $
/DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Same as the above example, but the min & max of
; each plot panel corresponds to the dynamic range
; of the data.
MODIFICATION HISTORY:
mps, 02 Dec 2013: - Initial version, based on differences.pro
ewl, 14 Mar 2016: - Fix bug in PlotPctDiff by passing Log=Log to TvMap
(See /n/home09/ryantosca/IDL/gamap2/benchmark/diff_2d_met.pro)
NAME:
DIFF_3D_MET
PURPOSE:
Creates absolute difference plots ( New - Old )
for GEOS-Chem 3-D meteorology fields.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
DIFF_3D_MET, FILES, LEVELS, TAUS, TRACERS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
LEVELS -> A 4-element vector containing the level indices
for the GEOS-Chem surface layer and 500 hPa layer.
for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
NOTE: This is in Fortran notation (starting from 1!)
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range to predetermined values as returned
by routine GET_DIFF_RANGE.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
===================================================
PlotDiff
External Subroutines Required:
===================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA GET_DIFF_RANGE
GETMODELANDGRIDINFO EXTRACT_FILENAME (function)
MULTIPANEL MYCT
OPEN_DEVICE TVMAP
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILES = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
LEVELS = [ 1, 1, 13, 13 ]
TAUS = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
TRACERS = INDGEN( 43 ) + 1
VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
DIFF_3D_MET, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
/PS, OUTFILENAME='myplot.ps'
; Creates ratio plots of two GEOS-CHEM versions
; (in this case v7-04-11 / v7-04-10) for July 2001.
; Output is sent to PostScript file "myplot.ps".
; The min and max of the data on each plot panel is
; restricted to pre-defined values returned by
; function GET_DIFF_RANGE.
DIFF_3D_MET, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
/DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Same as the above example, but the min & max of
; each plot panel corresponds to the dynamic range
; of the data.
MODIFICATION HISTORY:
mps, 02 Dec 2013: - Initial version, based on differences.pro
(See /n/home09/ryantosca/IDL/gamap2/benchmark/diff_3d_met.pro)
NAME:
DIFF_CLOUDS
PURPOSE:
Creates absolute difference plots ( New - Old ) for cloud fraction
(CLDTOT) and cloud optical depth (OPTD) in the surface - 500 hPa
column.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
DIFF_CLOUDS, FILES, TAUS, TRACERS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range to predetermined values as returned
by routine GET_DIFF_RANGE.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
===================================================
PlotAbsDiff
PlotPctDiff
External Subroutines Required:
===================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA GET_DIFF_RANGE
GETMODELANDGRIDINFO EXTRACT_FILENAME (function)
MULTIPANEL MYCT
OPEN_DEVICE TVMAP
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILES = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
TAUS = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
TRACERS = [ 1, 2 ]
VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
DIFF_CLOUDS, FILES, TAUS, TRACERS, VERSIONS, $
/DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Creates ratio plots of two GEOS-CHEM versions
; (in this case v7-04-11 / v7-04-10) for July 2001.
; Output is sent to PostScript file "myplot.ps".
; The min and max of the data on each plot panel
; corresponds to the dynamic range of the data.
MODIFICATION HISTORY:
mps, 23 Mar 2016: - Initial version
(See /n/home09/ryantosca/IDL/gamap2/benchmark/diff_clouds.pro)
NAME:
DISTRIBUTE
PURPOSE:
Collect all the routine names and file names that are
used in a given program.
CATEGORY:
General
CALLING SEQUENCE:
DISTRIBUTE [, ROUTINENAME ]
INPUTS:
ROUTINENAME -> (OPTIONAL) The name of the routine to be
searched. If omitted, then the user will be prompted
to supply a file name via a dialog box.
KEYWORD PARAMETERS:
OUTFILE -> Name of file where output will be sent. If
OUTFILE is omitted then DISTRIBUTE will print the
information to the screen.
/NO_IDL -> Set this switch to exclude IDL library routines
from the search process.
OUTPUTS:
A list of filenames with full pathnames and a list of
routinenames together with the filenames where they can
be found. Sorry, for local files, no pathname is provided.
SUBROUTINES:
External Subroutines Required:
===============================
OPEN_FILE
REQUIREMENTS:
Requires routines from the TOOLS package.
NOTES:
Unfortunately there is no way to figure out which routines
really belong to a given ROUTINENNAME, so DISTRIBUTE will
always return too many routinenames and filenames, including
itself and FILE_EXIST, as well as a couple of IDL standard
library routines (The latter can be left out with the keyword
NO_IDL). In order to get the closest results, run DISTRIBUTE
only at the start of an IDL session.
EXAMPLE:
DISTRIBUTE, 'iterate'
; Get all routines that belong to "iterate.pro".
; A subsequent call with routinename 'create_master'
; will return both, the routines for "create_master.pro"
; and the routines for "iterate.pro".
MODIFICATION HISTORY:
mgs, 16 Nov 1997: VERSION 1.00
mgs, 20 Nov 1997: - added OUTFILE and NO_IDL keywords
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now use IDL routine RESOLVE_ALL
- Now use OPEN_FILE instead of OPENW
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/general/distribute.pro)
NAME:
DOCUMENT_COLOR_TABLE
PURPOSE:
Displays all of the color tables within a standard IDL
*.tbl file. Can display output to the Xwindow device,
or create PostScript and PDF output.
CATEGORY:
Color
CALLING SEQUENCE:
DOCUMENT_COLOR_TABLE [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
FILE -> Name of the the color table (*.tbl) file to read.
Default is "gamap_colors.tbl".
/PS -> Set this switch to print output to a PostScript
document instead of plotting to the screen.
/PDF -> Set this switch to create a PostScript document
and then also create a PDF document.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
The Unix utility "ps2pdf" must be installed on your system
for the /PDF keyword to work. The ps2pdf utility should come
standard with most Unix or Linux builds.
NOTES:
None
EXAMPLES
DOCUMENT_COLOR_TABLE
; Prints out the color tables to the screen.
; Will set a 900x900 pixel window by default.
DOCUMENT_COLOR_TABLE, /PS
; Prints color tables to a PostScript file
; called "table_info.ps".
DOCUMENT_COLOR_TABLE, /PDF
; Prints out the color tables to a PostScript file
; "table_info.ps", then also creates a PDF file
; "table_info.pdf" using "ps2pdf".
MODIFICATION HISTORY:
phs, 21 Apr 2008: VERSION 1.00
phs, 25 Mar 2009: GAMAP VERSION 2.13
- Added FUN keyword
(See /n/home09/ryantosca/IDL/gamap2/color/document_color_table.pro)
NAME:
DRAWDOTONMAP
PURPOSE:
Draws a dot atop a world map, in order to highlight a given
(lat,lon) location. Also prints a label next to the point,
and draws a line from the point to the label.
CATEGORY:
Plotting
CALLING SEQUENCE:
DRAWDOTONMAP, X, Y, R, THETA, NAME, COLOR [, ALIGN=ALIGN ]
INPUTS:
X -> Longitude of the point to be drawn (degrees)
Y -> Latitude of the point to be drawn (degrees)
R -> Radius (in degrees) of the line that will extend from
the point to the the label.
THETA -> Angle (in the trigonometric sense, 0=due east)
which specifies the direction of the line that will
connect the plot label to the point.
NAME -> String for the plot label. Default is ''.
COLOR -> Color of the point to be plotted. Default
is !MYCT.BLACK.
KEYWORD PARAMETERS:
ALIGN -> Specifies the alignment of NAME. Works in the same
way as the ALIGN keyword to XYOUTS (e.g. ALIGN=0 is
left-justified, ALIGN=0.5 is centered, ALIGN=1 is
right-justified).
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
SYM (function)
REQUIREMENTS:
Assumes that we are using a MYCT-defined colortable.
NOTES:
None
EXAMPLE:
MAP_SET, LIMIT=[ 10, -140, 55,-40 ], GRID=0, $
COLOR=!MYCT.BLACK, /CYL, /NOBORDER
MAP_CONTINENTS, /COUNTRIES, /COASTS, $
COLOR=!MYCT.BLACK, /USA
DRAWDOTONMAP, -71, 42, 3, 0, 'Harvard', !MYCT.RED
; Draws a USA map and then plots a dot at the (lat,lon)
; of Harvard University. The label will be plotted 3
; units away along THETA=0 (due east).
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/plotting/drawdotonmap.pro)
NAME:
EMISSION_DIFFERENCES
PURPOSE:
Creates emission difference plots ( New - Old ) for GEOS-Chem.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
EMISSION_DIFFERENCES, FILES, TAUS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/PS -> Set this switch to generate PostScript output.
OUTDIR -> If /PS is set, then EMISSION_DIFFERENCES will
create PostScript files in this directory.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
===========================================
ComputeEmDiff PlotEmDiff
CreatePlots
External Subroutines Required:
============================================
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL COLORBAR_NDIV (function)
TVMAP CHKSTRU (function)
UNDEFINE EXTRACT_FILENAME (function)
CTM_GET_DATA ADD_SEPARATOR (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILES = [ 'ctm.bpch.v9-01-01', 'ctm.bpch.v9-01-02' ]
TAUS = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
VERSIONS = [ 'v9-01-01', 'v9-01-02' ]
EMISSION_DIFFERENCES, FILES, TAUS, VERSIONS, $
/PS, OUTDIR='v9-01-02/output/'
; Creates emission difference plots of two GEOS-CHEM versions
; (in this case v9-01-02 - v9-01-01) for July 2005.
MODIFICATION HISTORY:
mps, 21 Apr 2015: Initial version based on emission_ratios.pro
(See /n/home09/ryantosca/IDL/gamap2/benchmark/emission_differences.pro)
NAME:
EMISSION_MAPS
PURPOSE:
Creates emission plots for GEOS-Chem tracers.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
EMISSION_MAPS, FILE, TAU, VERSION, [, Keywords ]
INPUTS:
FILE -> The name of the file containing data to be plotted.
TAU -> The TAU value (hours GMT from /1/1985) corresponding
to the data to be plotted.
VERSION -> The model version number corresponding to the
data to be plotted.
KEYWORD PARAMETERS:
/PS -> Set this switch to generate PostScript output.
OUTDIR -> If /PS is set, then EMISSION_MAPS will
create PostScript files in this directory.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
===========================================
CreatePlots PlotEmissions
External Subroutines Required:
============================================
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL COLORBAR_NDIV (function)
TVMAP CHKSTRU (function)
UNDEFINE EXTRACT_FILENAME (function)
CTM_GET_DATA ADD_SEPARATOR (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILE = 'ctm.bpch.v10-01i'
TAU = NYMD2TAU( 20130701 )
VERSION = 'v10-01i'
EMISSION_MAPS, FILE, TAU, VERSION, /PS, OUTDIR='v10-01i/output/'
; Creates emission maps of GEOS-CHEM v10-01i for July 2013.
MODIFICATION HISTORY:
mps, 21 Apr 2015: Initial version based on emission_ratios.pro
(See /n/home09/ryantosca/IDL/gamap2/benchmark/emission_maps.pro)
NAME:
EMISSION_RATIOS
PURPOSE:
Creates emission ratio plots ( New / Old ) for GEOS-Chem.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
EMISSION_RATIOS, FILES, LEVELS, TAUS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/PS -> Set this switch to generate PostScript output.
OUTDIR -> If /PS is set, then EMISSION_RATIOS will
create PostScript files in this directory.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
===========================================
ComputeEmRatios PlotEmRatio
CreatePlots
External Subroutines Required:
============================================
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL COLORBAR_NDIV (function)
TVMAP CHKSTRU (function)
UNDEFINE EXTRACT_FILENAME (function)
CTM_GET_DATA ADD_SEPARATOR (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILES = [ 'ctm.bpch.v9-01-01', 'ctm.bpch.v9-01-02' ]
TAUS = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
VERSIONS = [ 'v9-01-01', 'v9-01-02' ]
EMISSION_RATIOS, FILES, TAUS, VERSIONS, $
/PS, OUTDIR='v9-01-02/output/'
; Creates emission ratio plots of two GEOS-CHEM versions
; (in this case v9-01-02 / v9-01-01) for July 2005.
MODIFICATION HISTORY:
bmy, 10 Jun 2011: VERSION 1.00
- Initial version, based on "ratios.pro"
- Make sure directory ends with a path
separator character
bmy, 23 Jun 2011: - Add ratio plot for lightning NOx
bmy, 27 Jun 2011: - Now split top-title into 2 lines
bmy, 11 Aug 2011: VERSION 1.01
- Fix bug by making values less than 0.5
not show up as missing data.
bmy, 16 Dec 2011: GAMAP VERSION 2.16
- Remove ACET from dryleaf and ACET from
grass. These were GEIA diagnostics,
which are now obsoleted.
mps, 02 Apr 2013: Renamed NOx-xxxx emissions diagnostics to
NO-xxxx. NO emissions have now replaced
NOx emissions in GEOS-Chem (v9-02h).
mps, 15 Jul 2013: Fixed bug in MaxLev: Now plot column NO for
anthro, aircraft, and lightning emissions.
mps, 25 Nov 2014: Now plot anthro + biofuel emissions because HEMCO
does not separate them
ewl, 18 Mar 2015: Bug fixes: change NO, SO2, and SO4 anthro level
from 2 to 1; change 'Tracer_bf ge 1' to 'Tracer_bf
ge 0' to add biofuels to anthro in Create_Plots;
change Files index from 0 to 1 for Data2 err msg.
(See /n/home09/ryantosca/IDL/gamap2/benchmark/emission_ratios.pro)
NAME:
EOS_GETGR
PURPOSE:
Convenience routine to read variables from an HDF-EOS
grid data structure.
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
DATA = EOS_GETGR( FID, NAME [, Keywords, _EXTRA=e ] )
INPUTS:
FID -> HDF-EOS File ID, as returned by routine EOS_GD_START.
NAME -> Name of the HDF-EOS grid dataset variable that
you want to extract from the HDF-EOS file.
KEYWORD PARAMETERS:
GRIDNAME -> Name of the HDF-EOS grid under which the data
is stored in the file. You can use the IDL HDF_BROWSER
routine to easily find the grid name.
_EXTRA=e -> Passes extra keywords to routine EOS_SW_READFIELD.
OUTPUTS:
DATA -> Array containing extracted data from the HDF-EOS file.
SUBROUTINES:
None
REQUIREMENTS:
Need to use a version of IDL w/ HDF-EOS routines installed.
NOTES:
None
EXAMPLE:
; Make sure HDF is supported on this platform
IF ( EOS_EXISTS() eq 0 ) then MESSAGE, 'HDF not supported!'
; Open the HDF file and get the file ID # (FID)
FID = EOS_GD_OPEN( 'gridfile.hdf', /READ )
IF ( FID lt 0 ) THEN MESSAGE, 'Error opening file!'
; Read a variable from a grid file
DATA = EOS_GETGR( fId, 'Latitude', GRIDNAME='GRID1' )
; Close the file
STATUS = EOS_GD_CLOSE( FID )
IF ( STATUS lt 0 ) THEN MESSAGE, 'Error closing file!'
MODIFICATION HISTORY:
bmy, 18 Sep 2002: TOOLS VERSION 1.51
bmy, 19 Dec 2002: TOOLS VERSION 1.52
- fixed typos
bmy, 04 Jun 2003: TOOLS VERSION 1.53
- fixed more typos
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/eos_getgr.pro)
NAME:
EOS_GETSW
PURPOSE:
Convenience routine to read variables from an HDF-EOS
satellite swath data structure.
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
DATA = EOS_GETSW( FID, NAME [, Keywords, _EXTRA=e ] )
INPUTS:
FID -> HDF File ID, as returned by routine EOS_SW_START.
NAME -> Name of the satellite swath dataset variable that
you want to extract from the HDF-EOS file.
KEYWORD PARAMETERS:
SWATHNAME -> Name of the HDF-EOS swath under which the data
is stored in the file. You can use the IDL HDF_BROWSER
routine to easily find the swath name.
_EXTRA=e -> Passes extra keywords to routine EOS_SW_READFIELD.
OUTPUTS:
DATA -> Array containing extracted data from the HDF-EOS file.
SUBROUTINES:
None
REQUIREMENTS:
Need to use a version of IDL w/ HDF-EOS routines installed.
NOTES:
None
EXAMPLE:
; Make sure HDF is supported on this platform
IF ( EOS_EXISTS() eq 0 ) then MESSAGE, 'HDF not supported!'
; Open the HDF file and get the file ID # (FID)
FID = EOS_SW_OPEN( 'swathfile.hdf', /READ )
IF ( FID lt 0 ) THEN MESSAGE, 'Error opening file!'
; Read a variable from a swath file
DATA = EOS_GETSW( fId, 'Latitude', SWATHNAME='swath1' )
; Close the file
STATUS = EOS_SW_CLOSE( FID )
IF ( STATUS lt 0 ) THEN MESSAGE, 'Error closing file!'
MODIFICATION HISTORY:
bmy, 18 Sep 2002: TOOLS VERSION 1.51
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/eos_getsw.pro)
NAME:
ERRORBAR
PURPOSE:
Plots error bars atop data points,
along the X or Y dimension.
CATEGORY:
Plotting
CALLING SEQUENCE:
ERRORBAR, XARR, YARR, ERROR [ , Keywords ]
INPUTS:
XARR, YARR -> Arrays of X and Y values correspoinding
to the location of the data points. XARR and YARR
must have the same number of elements.
ERROR -> An array (or scalar) of error values. If ERROR
is a scalar, its value will be used for all data
points. If ERROR is an array, it must be of the
same dimension as XARR and YARR, or else an error
message will be generated.
KEYWORD PARAMETERS:
/X -> If set, will plot error bars along the X-dimension.
Default is to plot error bars along the Y-dimension.
SUBROUTINES:
None
REQUIREMENTS
None
NOTES:
ERRORBAR just plots the error bars, but not the
data points. This is useful if you want to use
different colors for data points and error bars.
MODIFICATION HISTORY:
bmy, 21 Jul 1999: VERSION 1.01
- based on IDL routine OPLOTERR
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/plotting/errorbar.pro)
NAME:
EXAMPLES_MANIP_4D
PURPOSE:
Shows how to manipulate TS data saved as 4D array with
GC_COMBINE_ND49 or GC_COMBINE_ND48.
The routine loops over all available 4D data blocks and print
information for each of them.
CATEGORY:
GAMAP Data Manipulation, GAMAP Examples, Time Series
CALLING SEQUENCE
EXAMPLES_MANIP_4D, File [ , Keywords ]
INPUTS:
FILE -> The name of the file created by GC_COMBINE_ND48/9.
OUTPUT KEYWORD PARAMETERS:
#### ONLY THE LAST DATA SET IF MORE THAN ONE IS AVAILABLE ####
DATA -> Output keyword. Set to a variable name that will
contain the data set on exist.
LON -> Output keyword. Set to a variable name that will
contain the vector of LONGITUDES on exit.
LAT -> Output keyword. Set to a variable name that will
contain the vector of LATITUDES on exit.
TIME -> Output keyword. Set to a variable name that will
contain the vector of TIME STEP on exit. Format is
YYYYMMDD if daily max is asked for (see DMAX keyword),
TAU value else.
LOCALTIME -> to get the output TIME in LOCALTIME. If there
is more than one longitude in the data block, TIME
becomes an array : one vector for each longitude.
KEYWORD PARAMETERS:
MAVG -> The window size (boxcar) of the moving average, if
you want to apply one.
DMAX -> Return daily maximum of the TS.
VERBOSE -> to print some basic information about the data
set.
_EXTRA=e -> Picks up extra keywords for routines
OUTPUTS:
With optional keyword.
SUBROUTINES:
REQUIREMENTS:
References many routines from GAMAP package. Requires GAMAP
v2.10 for handling 4D dataset.
NOTES:
EXAMPLES:
file = dialog_pickfile()
EXAMPLES_MANIP_4D, file, /v, data=ts, lat=lat, lon=lon, time=time
PLOT, time-time[0], ts[0,0,0,*], title='Time series at lon='+ $
strtrim(lon[0],2)+' / lat='+strtrim(lat[0],2)
MODIFICATION HISTORY:
phs, 6 Jun 2007: GAMAP VERSION 2.10
- Initial version
(See /n/home09/ryantosca/IDL/gamap2/examples/examples_manip_4d.pro)
NAME:
EXAMPLE_ANIM_TS
PURPOSE:
Illustrates how to use XINTERANIMATE with GAMAP
timeseries routine GC_COMBINE_ND49.
CATEGORY:
GAMAP Examples, GAMAP Utilities
CALLING SEQUENCE:
EXAMPLE_ANIM_TS [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================================
GC_COMBINE_ND49 MULTIPANEL
MYCT PROGRAM_DIR (function)
TAU2YYMMDD (function) TVMAP
REQUIREMENTS:
Requires routines from the GAMAP package.
NOTES:
None
EXAMPLE:
EXAMPLE_ANIM_TS
; Creates sample animation from timeseries data.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.11
(See /n/home09/ryantosca/IDL/gamap2/examples/example_anim_ts.pro)
NAME:
EXAMPLE_ND48_ND49
PURPOSE:
Creates several example plots to illustrate the use of GAMAP
timeseries routines GC_COMBINE_ND48 and GC_COMBINE_ND49.
CATEGORY:
GAMAP Examples, GAMAP Utilities, Time Series
CALLING SEQUENCE:
EXAMPLE_ND48_ND49 [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
/PNG -> Set this switch to save screen output
Portable Network Graphics (PNG) format.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=========================================
GC_COMBINE_ND48 GC_COMBINE_ND49
MULTIPANEL PROGRAM_DIR (function)
SCREEN2PNG
REQUIREMENTS:
Requires routines from the GAMAP package.
NOTES:
None
EXAMPLE:
EXAMPLE_ND48_ND49, /PNG
; Create example plots and save to PNG file.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.11
(See /n/home09/ryantosca/IDL/gamap2/examples/example_nd48_nd49.pro)
NAME:
EXAMPLE_OVERPLOT
PURPOSE:
Example program for overlay of data with model results.
This program is meant to provide a demonstration example
rather than a ready-to-use program, so please copy it
and adapt it to your needs.
For a try, just call EXAMPLE_OVERPLOT with no options.
Before you rewrite this code, try some of the keyword
options to get a feel how it works.
CATEGORY:
GAMAP Examples, GAMAP Utilities
CALLING SEQUENCE:
EXAMPLE_OVERPLOT [,DATA [,ALTITUDE]] [,keywords]
INPUTS:
DATA -> A vector with your vertical profile data. If nothing
is supplied, a dummy ozone profile is generated.
ALTITUDE -> Altitude vector correspondign to your data. If not
supplied, a vector will be created ranging from 0-12 km.
KEYWORD PARAMETERS:
Keywords to select certain model results:
DIAGN -> Name (or number) of a diagnostic. Default is 'IJ-AVG-$'
TRACER -> A tracer number (default is 2 = 'Ox')
TAU0 -> A time step value. You can specify a date using the
NYMD2TAU function.
Keywords to select the geographical domain:
LONRANGE, LATRANGE -> 2-element vectors specifying the minimum
and maximum longitude and latitude for the model results
to be considered. Not that LONRANGE[1] < LONRANGE[0] is
possible, denoting a region across the Pacific.
Keywords to change the appearance of the plot:
TITLE -> Give your plot a title. Default is 'EXAMPLE PLOT'
with longitude and latitude rang and date.
If you are sure that you select only one data record each
time, you can leave it up to CTM_PLOT to construct a title
(simply remove the TITLE keyword in the call to CTM_PLOT).
Note that you can take advantage of various "variables"
with the '%NAME%' notation (see GAMAP documentation for
details).
_EXTRA -> Look at the documentation of CTM_PLOT and add your
favorite keywords to the call to EXAMPLE_OVERPLOT. You are
likely to use XRANGE or XSTYLE.
OUTPUTS:
just a plot ;-)
SUBROUTINES:
none
REQUIREMENTS:
uses ctm_get_dat and ctm_plot as well as everything that is
needed by these to.
NOTES:
EXAMPLE:
EXAMPLE_OVERPLOT
data = your_fancy_reading_routine(filename)
EXAMPLE_OVERPLOT,data,tau0=nymd2tau(940601L)
MODIFICATION HISTORY:
mgs, 21 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/examples/example_overplot.pro)
NAME:
EXAMPLE_POLAR
PURPOSE:
Quick and dirty examples of polar plots made with CTM_PLOT.
CATEGORY:
GAMAP Examples, GAMAP Utilities
CALLING SEQUENCE:
EXAMPLE_POLAR
INPUTS:
None
KEYWORD PARAMETERS:
/PS -> Set this switch to write output to a PostScript file.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================
MYCT CTM_PLOT MULTIPANEL
REQUIREMENTS:
None
NOTES:
none
EXAMPLE:
EXAMPLE_POLAR, /PS
; Create polar plots and save to PostScript file.
MODIFICATION HISTORY:
mgs, 20 Aug 1998: INITIAL VERSION
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now uses FILE_WHICH to find ctm.bpch.examples
- rewritten for clarity
bmy, 14 Mar 2008: GAMAP VERSION 2.12
- Bug fix: save output from FILE_WHICH to
FILE (instead of FILENAME)
(See /n/home09/ryantosca/IDL/gamap2/examples/example_polar.pro)
NAME:
EXAMPLE_TVMAP
PURPOSE:
Generates several example plots using CTM_PLOT and TVMAP.
CATEGORY:
GAMAP Examples, GAMAP Utilities
CALLING SEQUENCE:
EXAMPLE_TVMAP [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
/PNG -> Set this switch to save screen output
Portable Network Graphics (PNG) format.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
====================================
CTM_PLOT MULTIPANEL
MYCT NYMD2TAU (function)
SCREEN2PNG TVMAP
REQUIREMENTS:
Requires routines from the GAMAP package.
NOTES:
None
EXAMPLE:
EXAMPLE_TVMAP, /SAMPLE
; Create example plots with pixel plots for all plots.
EXAMPLE_TVMAP, /PNG
; Create example plots and save to a PNG file.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.11
(See /n/home09/ryantosca/IDL/gamap2/examples/example_tvmap.pro)
NAME:
EXPAND_CATEGORY (function)
PURPOSE:
Replace wildcards in a multilevel diagnostic category
and return a string array with one entry for each
level.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
xcatgeory = EXPAND_CATEGORY(category)
INPUTS:
CATGEORY -> The original category name containing one
wildcard character (see CTM_DIAGINFO). If category
does not contain a wildcard character, the category
will be returned unchanged.
KEYWORD PARAMETERS:
RANGE -> A level index or range of level indices (2-elements)
to be returned. Default is to return the maximum
possible range (currently 1..24).
WILDCHARD -> a character value that is searched for as
wildchard. Default is '$' which is used in CTM_DIAGINFO
to denote a varying level index.
/NO_DELETE -> if set, will return category with wildcard as
first entry in result list. Default is to delete the
wildcard string.
OUTPUTS:
A string array with category names.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, EXPAND_CATEGORY('IJ-AVG-$')
; prints IJ-AVG-1 IJ-AVG-2 IJ-AVG-3 ...
; ... IJ-AVG-A IJ-AVG-B ...
print, EXPAND_CATEGORY( 'IJ-AVG-$', range=5 )
; prints IJ-AVG-5
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 26 Oct 1998: added no_delete keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- added extra letters for grids w/
more than about 30 layers
(See /n/home09/ryantosca/IDL/gamap2/internals/expand_category.pro)
NAME:
EXTRACT_COMMENTS
PURPOSE:
Split a string returned from READDATA.PRO into
items of a string array.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = EXTRACT_COMMENTS( COMMENTS, INDEX, DELIM=' ' )
INPUTS:
COMMENTS -> String array of comment lines returned from
readdata.pro
INDEX -> line number of comments to be analyzed
KEYWORD PARAMETERS:
DELIM -> delimiter character between items. Default: 1 blank.
OUTPUTS:
RESULT -> A string array containing the single "words"
of 1 comment line.
SUBROUTINES:
External Subroutines Required:
===============================
STRBREAK (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
UNITS = EXTRACT_COMMENTS( comments, 2, delim=' ' )
MODIFICATION HISTORY:
mgs, 10 Nov 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now use version-independent STRBREAK
routine instead of older STR_SEP routine
(See /n/home09/ryantosca/IDL/gamap2/general/extract_comments.pro)
NAME:
EXTRACT_FILENAME
PURPOSE:
Extract the filename from a fully qualified filepath
CATEGORY:
File & I/O
CALLING SEQUENCE:
FILENAME = EXTRACT_FILENAME( FULLNAME [ , Keywords ] )
INPUTS:
FULLNAME --> a fully qualified filename containing path information.
KEYWORD PARAMETERS:
FILEPATH --> a named variable that returns the path of the
file. This can be used if both, the filename and the name
of the file will be used. Otherwise it is recommended to
use EXTRACT_PATH instead.
OUTPUTS:
A string containing the filename to be analyzed.
SUBROUTINES:
External Subroutines Required:
===============================
ADD_SEPARATOR (function)
REQUIREMENTS:
Requires routines from the TOOLS package.
NOTES:
See also EXTRACT_PATH
EXAMPLE:
PRINT, EXTRACT_FILENAME( '~/IDL/tools/extract_filename.pro')
extract_filename.pro
; Prints just the file name part of a longer path.
PRINT,EXTRACT_FILENAME( 'example.dat', filepath=filepath )
example.dat'
; will print 'example.dat', and filepath will contain ''
MODIFICATION HISTORY:
mgs, 18 Nov 1997: VERSION 1.00
mgs, 21 Jan 1999: - added extra check for use of '/' path
specifiers in Windows OS;
bmy, 19 Jan 2000: TOOLS VERSION 1.44
- replaced obsolete RSTRPOS( ) command with
STRPOS( /REVERSE_SEARCH ) for IDL 5.3+
- updated comments, few cosmetic changes
bmy, 13 Mar 2001: TOOLS VERSION 1.47
- Add support for MacOS operating system
bmy, 17 Jan 2002: TOOLS VERSION 1.50
- now call RSEARCH for backwards compatibility
with versions of IDL prior to v. 5.2
- use FORWARD_FUNCTION to declare RSEARCH
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now use ADD_SEPARATOR
- updated comments
(See /n/home09/ryantosca/IDL/gamap2/file_io/extract_filename.pro)
NAME:
EXTRACT_PATH
PURPOSE:
Extract the file path from a full qualified filename
CATEGORY:
File & I/O
CALLING SEQUENCE:
Path = EXTRACT_PATH( FULLNAME [, Keywords] )
INPUTS:
FULLNAME --> a fully qualified filename. If this input is
already a path it must end with the delimiter '/' (Unix),
'\' (Windows), or ':' (MacOS).
KEYWORD PARAMETERS:
FILENAME --> a named variable that returns the name of the
file. This can be used if both, the path and the name
of the file will be used. Otherwise it is recommended to
use EXTRACT_FILENAME instead.
OUTPUTS:
A string containing the path to the file given.
SUBROUTINES:
External Subroutines Required:
===============================
ADD_SEPARATOR (function)
RSEARCH (function)
REQUIREMENTS:
None
NOTES:
See also EXTRACT_FILENAME
EXAMPLE:
print,extract_path('~mgs/IDL/tools/extract_path.pro')
will print '~mgs/IDL/tools/'
print,extract_path('example.dat',filename=filename)
will print '', and filename will contain 'example.dat'
MODIFICATION HISTORY:
mgs, 18 Nov 1997: VERSION 1.00
mgs, 21 Jan 1999: - added extra check for use of '/' path
specifiers in Windows OS
bmy, 19 Jan 2000: TOOLS VERSION 1.44
- replaced obsolete RSTRPOS( ) command with
STRPOS( /REVERSE_SEARCH ) for IDL 5.3+
- updated comments, few cosmetic changes
bmy, 13 Mar 2001: TOOLS VERSION 1.47
- Add support for MacOS operating system
bmy, 17 Jan 2002: TOOLS VERSION 1.50
- now call RSEARCH for backwards compatibility
with versions of IDL prior to v. 5.2
- use FORWARD_FUNCTION to declare RSEARCH
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now use ADD_SEPARATOR
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/file_io/extract_path.pro)
NAME:
E_H2O
PURPOSE:
Calculate water vapour pressure for a given temperature
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = E_H2O( TEMPERATURE [,/WATER,/ICE,minval=minval] )
INPUTS:
TEMPERATURE --> dew or frostpoint reading in K. If you supply
the dry air temperature (or static air temperature),
you will get a value for the water vapor saturation
pressure.
KEYWORD PARAMETERS:
/WATER --> interprete temperature as dewpoint (default)
/ICE --> interpret temperature as frostpoint
MINVAL -> minimum valid data value (default -1.0E30)
OUTPUTS:
RESULT -> The water vapour pressure [hPa]
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The algorithm has been taken from the NASA GTE project data
description.
EXAMPLE:
PH2O = E_H2O(266.)
; Calculate water vapor pressure for a
; dewpoint reading of 266 K
RH = PH2O/E_H2O(283.)
; Compute relative humidity
; (divide ph2o by saturation pressure of DRY temperature)
PRINT,PH2O,RH
3.61742 0.294607
; Prints values
MODIFICATION HISTORY:
mgs, 23 Feb 1997: VERSION 1.00
mgs, 03 Aug 1997: split e_h2o and rh, renamed, added template
mgs, 23 May 1998: changed default behaviour to set reference
temperature to given TD value
mgs, 29 Aug 1998: VERSION 2.00
- much simpler and more logical interface
- no automatic detection of dew- or frostpoint any longer
- can now accomodate arrays
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/e_h2o.pro)
NAME:
FCONVERT_UNIT (function)
PURPOSE:
Wrapper for CONVERT_UNIT. Passes all of the input data to
CONVERT_UNIT and returns the result to the calling program.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = FCONVERT_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:
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.
_EXTRA=e -> Passes extra keywords to CONVERT_UNIT.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
CONVERT_UNIT
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
MODIFICATION HISTORY:
mgs, 26 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Added std documentation header
(See /n/home09/ryantosca/IDL/gamap2/math_units/fconvert_unit.pro)
NAME:
FILE_EXIST
PURPOSE:
FILE_EXIST checks to see whether a specified file
can be found on disk, or if it does not exist.
CATEGORY:
File & I/O
CALLING SEQUENCE:
RESULT = FILE_EXIST( FILE [,OPTIONS])
INPUTS:
FILE (str) --> the name of the file to be checked
KEYWORD PARAMETERS:
PATH -> a path string (e.g. the IDL system variable !PATH)
or a list (string array) of directory names to be
searched for FILE. Under Unix, a trailing '/' is
attached to each entry; under Windows, a trailing
'\'; under MacOS, a trailing ':'. VMS isn't supported.
FULL_PATH -> returns the path of FILE if found. This is
not a true systemwide path but rather a combination
of a PATH element (which may be relative) and FILE.
DIRNAMES -> This keyword is now replaced by PATH, and
should not be used any more.
OUTPUTS:
RESULT -> =1 if the file is found or =0 otherwise
SUBROUTINES:
External Subroutines Required:
================================================
ADD_SEPARATOR (function) MFINDFILE (function)
REQUIREMENTS:
Requires routines from the TOOLS package.
NOTES:
(1) The PATH entries are expanded prior to use, so it is
possible to specify e.g. '~mgs/bla.pro'
(2) FILE_EXIST will always return the first file it
finds that matches your specification.
EXAMPLES:
(1)
IF ( FILE_EXIST( 'file_exist.pro' ) ) THEN PRINT, 'Found it!'
; Search for file_exist.pro
(2)
DIRS = [ '../', '~/DATA/' ]
OK = FILE_EXIST( 'test.dat', path=dirs, full=path )
IF ( OK ) THEN OPENR, U1, PATH
...
; Search for a file given a list of directories.
; If file is found, then open it for reading.
MODIFICATION HISTORY:
mgs, 26 Sep 1997: VERSION 1.00
mgs, 28 Sep 1997: - added expand_path() in order to digest ~-pathnames
- initializes FULL_PATH with a zero string
mgs, 06 Nov 1997: - replaced DIRNAMES by PATH and added
string seperation if PATH is a path
string with multiple entries
mgs, 05 Feb 1998: - bug fix: use expand_path also if only
filename is given
bmy, 13 Mar 2001: TOOLS VERSION 1.47
- now supports Windows, MacOS, and Unix
- cosmetic change, updated comments
bmy, 17 Jan 2002: TOOLS VERSION 1.50
- now call STRBREAK wrapper routine from
the TOOLS subdirectory for backwards
compatiblity for string-splitting;
bmy, 03 Oct 2003: TOOLS VERSION 1.53
- minor bug fix: FILE must be placed w/in
the call to EXPAND_PATH for IDL 6.0+
- deleted obsolete code from Jan 2002
bmy, 28 May 2004: TOOLS VERSION 2.02
- now call MFINDFILE instead of FINDFILE,
since MFINDFILE will call the new
FILE_SEARCH program for IDL 5.5+
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now use ADD_SEPARATOR
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/file_io/file_exist.pro)
NAME:
FIND_CELLS_BY_COUNTRY
PURPOSE:
Returns an index array which can be used to determine
which CTM grid boxes lie within a given country.
CATEGORY:
GAMAP Utilities
CALLING SEQUENCE:
RESULT = FIND_CELLS_BY_COUNTRY( COUNTRYID, GRIDINFO [, Keywords] )
INPUTS:
COUNTRYID -> Name of the country you are interested in, OR
the country ID number ID from "countries.table".
GRIDINFO -> Structure from CTM_GRID which defines the output
CTM model grid in which you wish to find a given country.
KEYWORD PARAMETERS:
/MAXIMIZE -> Set this switch to search for all grid boxes that
contain any portion of the specified country. The
default is to determine the specified country by the
center of the grid box.
/INDEX -> Set this switch to return RESULT as an 1-D index
vector (i.e. similar to output from the WHERE command).
OUTPUTS:
RESULT -> Integer index array for OUTGRID. Grid boxes where
RESULT[I,J] = 1 designate the desired country. If the
/INDEX flag is set then RESULT will be an 1-D index
vector (i.e. similar to output from the WHERE command).
SUBROUTINES:
Internal Subroutines:
============================
GET_COUNTRY_NUMBER (function)
External Subroutines Required:
===========================================
CHKSTRU (function) CTM_GRID (function)
CTM_TYPE (function) DATATYPE (function)
STRBREAK (function)
REQUIREMENTS:
None
NOTES:
(1) Requires the following input files:
(a) countries.table
(b) countries.generic.025x025.gif
(2) The search algorithm is brute-force (i.e. FOR loops
over lat & lon). Maybe in a later version we can
optimize this w/ IDL array notation.
MODIFICATION HISTORY:
tmf & bmy, 01 Jul 2006: GAMAP VERSION 2.05
- Initial version
bmy & phs, 27 Jul 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to find countries.table
- Use FILE_WHICH to find countries.gif
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/find_cells_by_country.pro)
NAME:
FIND_TRACER_INDEX
PURPOSE:
Given the diagnostic category and tracer name, returns the
tracer number as specified in the "tracerinfo.dat" file.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
RESULT = FIND_TRACER_INDEX( DIAGN, NAME )
INPUTS:
DIAGN -> Diagnostic category name as specified in the
"diaginfo.dat" file (e.g. "IJ-AVG-$", "GMAO-2D", etc.).
NAME -> Tracer name as specified in the "tracerinfo.dat"
file (e.g. NOx, Ox, CO, PS, TAUCLI, etc.)
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Tracer number corresponding to NAME and DIAGN.
SUBROUTINES:
External subroutines required:
------------------------------
CTM_DIAGINFO CTM_TRACERINFO
REQUIREMENTS:
Requires routines from the GAMAP package.
NOTES:
Here, "tracer" is used in the wider sense. It can be can be
any quantity saved out from a CTM diagnostic output, as long
as it is specified by "diaginfo.dat" and "tracerinfo.dat".
EXAMPLE:
PRINT, FIND_TRACER_INDEX( 'GMAO-2D', 'PS' )
IDL prints 5931
; Returns the tracer index number for the "PS"
; quantity in the "GMAO-2D" diagnostic category.
MODIFICATION HISTORY:
bmy, 06 Aug 2010: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/find_tracer_index.pro)
NAME:
FIND_UNIT
PURPOSE:
Return classification and conversion information for
physical units. You pass a unit name, and you will
get a standard form of that name as well as a factor
and an offset that convert the unit to SI standard.
To convert one unit to another, use FIND_UNIT twice
(see example below).
CATEGORY:
Math & Units
CALLING SEQUENCE:
FIND_UNIT,NAME,STDNAME,FACTOR,OFFSET,CATEGORY [,keywords]
INPUTS:
NAME -> A string containing the name to search for
KEYWORD PARAMETERS:
/GET_SI -> Return the name of the SI unit of the category of
the given unit. Factor and offset will always be 1.0 and
0.0, CATEGORY will contain the category number.
/NO_STANDARD -> Do not return the standard name of a unit. The
standard spelling is identified as the first occurrence
of a given unit with the same conversion factor and offset
in the same category and normally replaces the input name.
/TEST -> Check standard unit strings for consistency
This keyword is only useful when you add extra units.
OUTPUTS:
STDNAME -> The unit name as saved in the stdunits array
(e.g. 'KG' is returned as 'kg')
FACTOR -> A conversion factor to SI
OFFSET -> A conversion offset
CATEGORY -> The class to which the unit belongs:
-1 : unit not found
0 : distance
1 : area
2 : volume
3 : time
4 : frequency
5 : speed
6 : accelaration
7 : temperature
8 : weight
9 : pressure
10 : force
11 : energy
12 : power
13 : mixing ratio
14 : currency
15 : voltage
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
FIND_UNIT,'kM/H',stdname,factor,offset,category
print,stdname,factor,offset,category
; prints km/h 0.277780 0.00000 5
; conversion from Fahrenheit to Celsius
temp = [ 0., 32., 80., 100. ]
FIND_UNIT,'F',fromname,fromfac,fromoff,fromcat
FIND_UNIT,'C',toname,tofac,tooff,tocat
if (fromcat ne tocat) then print,'bullsh...'
ctemp = ((fromfac*temp+fromoff) - tooff) / tofac
print,ctemp
; prints -17.7778 0.000152588 26.6670 37.7782
; find name of corresponding SI unit
FIND_UNIT,'mph',stdname,/get_si
print,stdname
; prints m/s
; find standard form of any unit
FIND_UNIT,'miles/hour',stdname
print,stdname
; prints mph
MODIFICATION HISTORY:
mgs, 26 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/find_unit.pro)
NAME:
FIX_MANUAL_HTML
PURPOSE:
Removes text from the GAMAP manual pages that is
automatically inserted by IDL's MK_HTML_HELP routine,
and replaces them with better HTML code.
CATEGORY:
Documentation
CALLING SEQUENCE:
FIX_MANUAL_HTML
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
======================================================
EXTRACT_FILENAME (function) EXTRACT_PATH (function)
MFINDFILE (function) OPEN_FILE
REPLACE_TOKEN (function)
REQUIREMENTS:
Requires routines from the GAMAP package
NOTES:
Also see routines GAMAP2_HTML and IDL2HTML.
EXAMPLE:
GAMAP2_HTML, /ALL, OUTDIR='manual/html/all'
GAMAP2_HTML, /BY_CATEGORY, OUTDIR='manual/html/by_category'
GAMAP2_HTML, /BY_ALPHABET, OUTDIR='manual/html/by_alphabet'
FIX_MANUAL_HTML
; Creates GAMAP manual pages (HTML format) and then
; removes unwanted text that is automatically added
; by IDL's MK_HTML_HELP routine.
MODIFICATION HISTORY:
bmy, 23 Apr 2008: GAMAP VERSION 2.12
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Stop w/ error if "gamap_manual_replace.html"
file cannot be found
(See /n/home09/ryantosca/IDL/gamap2/doc/fix_manual_html.pro)
NAME:
FORMAT_INP
PURPOSE:
Display one line of S-type input file for CHEM1D model
formatted so that each line contains name, unit, value and
scaling factor of 1 species (may help to find errors).
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
FORMAT_INP, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> name of the input file
KEYWORD PARAMETERS:
OUTFILE -> filename for ASCII file with formatted output
(default: FILENAME+'.formatted')
SKP1, SKP2, DELIM -> parameters for READDATA routine:
number of lines to skip before variable names and
delimiter for variable names (defaults: 1, 3, and ' ')
LINE -> data line to be displayed (default=1)
SIMPLE -> assume no unit and scale factor line, and print
dummies instead. Will be automatically set if SKP2 is
less than 2.
OUTPUTS:
Screen output and output to file OUTFILE
SUBROUTINES:
External Subroutines Required:
===============================
READDATA
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
FORMAT_inp, 'test.inp', LINE=3
will display the third line of a chem1d input file test.inp in a
format similar to:
NAME UNIT VALUE SCALE
O3_COLUMN DU 227.330 2.687e+16
DECLINATION deg -1.634 1.000e+00
PSMB mb 238.434 1.000e+00
...
MODIFICATION HISTORY:
mgs, 18 Dec 1997: VERSION 1.00
mgs, 11 Jun 1998: - added SIMPLE and SKP2 keyword
mgs, 30 Oct 1998: - bug fix with units and scale
- improved formatting for large numbers
(allows display of chem1d output files)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/format_inp.pro)
NAME:
FORMSTRLEN (function)
PURPOSE:
Return the (approximated) length of a string that
contains Hershey formatting characters. If the string
does not contain any formatting characters, the result
equals that of STRLEN, otherwise it will be shorter.
Hershey characters ('!'+1 char) are ignored, characters in
super or subscript mode are counted as of width 0.6
CATEGORY:
Strings, Plotting
CALLING SEQUENCE:
LEN = FORMSTRLEN( S )
INPUTS:
S -> A string that may contain Hershey formatting characters.
As with STRLEN, S may be a string array.
KEYWORD PARAMETERS:
none
OUTPUTS:
A float(!) value that gives the "true" length of the string
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
PRINT, FORMSTRLEN('C2H6')
4
PRINT, FORMSTRLEN('C!L2!NH!L6!N')
3.2
MODIFICATION HISTORY:
mgs, 27 Oct 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/strings/formstrlen.pro)
NAME:
FREQ_DIST
PURPOSE:
Creates frequency distribution and percentile plots
for GEOS-CHEM tracers from benchmark simulations.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
FREQ_DIST, FILES, TAUS, TRACERS, VERSIONS [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DO_FULLCHEM -> Set this switch to plot the chemically
produced OH and aerosol optical depths in addition
to the advected tracers.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==========================================
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL EXTRACT_FILENAME (function)
CTM_GET_DATA
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(2) Assumes the version # is located at the end of FILENEW.
(3) Assumes the following diagnostics are archived in FILENEW:
(a) ND43 ("CHEM-L=$"): Fullchem benchmark
(b) ND45 ("IJ-AVG-$"): Radon and Fullchem benchmarks
EXAMPLE:
FILES = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
TAUS = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
FREQ_DIST, FILES, LEVELS, TAUS, VERSIONS, $
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'
; Creates a frequency-ratio plot from the data
; files for GEOS-Chem versions v7-04-10 and v7-04-11
MODIFICATION HISTORY:
bmy, 12 Aug 2002: VERSION 1.01
- adapted from Isabelle Bey's "comparison.pro"
bmy, 21 Jan 2003: VERSION 1.02
- increased from 24 to 31 tracers
bmy, 28 Apr 2004: VERSION 1.03
- increased from 31 to 35 tracers
bmy, 03 May 2004: VERSION 1.04
- increased from 35 to 39 tracers
bmy, 21 May 2004: VERSION 1.05
- increased from 39 to 41 tracers
bmy, 02 Nov 2004: VERISION 1.06
- bug fix: now print out top title on each
page (when it is the first panel)
bmy, 06 May 2005: VERSION 1.07
- Now use -9.99e30 to flag strat boxes
bmy, 08 Jul 2005: VERSION 1.08
- Increased from 41 to 43 tracers
bmy, 09 Nov 2007: VERSION 1.09
- Modified argument list and some
internal variable names.
- Removed Radon keyword
bmy, 25 May 2011: VERSION 1.10
- Added /DO_FULLCHEM keyword
bmy, 17 Apr 2012: GAMAP VERSION 2.16
- Omit modelname error check
(See /n/home09/ryantosca/IDL/gamap2/benchmark/freq_dist.pro)
NAME:
FULLCHEM_BUDGET
PURPOSE:
Computes the budgets of Ox and CO from the GEOS-CHEM model.
for full chemistry benchmark simulations.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
FULLCHEM_BUDGET [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
TAU0 -> Time index of the data to plot. Units are hours
since 0 GMT on 1/1/1985. Default is 144600D (July 1, 2001).
FILENEW -> Name of a binary punch file containing model
output from a "New" version of the GEOS-CHEM.
If omitted, a dialog box will prompt the user to
supply a file name.
OUTFILENAME -> Name of the file where budget information
will be written to. Default is "(VERSION).budget.fullchem",
where VERSION is the version number contained w/in
FILENEW.
INITIALFILE -> Name of a binary file containing the mass of
Ox [in kg] at the start of a GEOS-CHEM model run.
FINALFILE -> Name of a binary file containing the mass of
Ox [in kg] at the end of a GEOS-CHEM model run.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
====================================
OPEN_FILE CTM_BOXSIZE (function)
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE GETMODELANDGRIDINFO
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Assumes the version # is located at the end of FILENEW.
(2) Assumes the following GEOS-CHEM diagnostics
have been archived in the input files:
(a) ND24 ("EW-FLX-$") (f) ND65 ("PORL-L=$")
(b) ND25 ("NS-FLX-$") (g) ND66 ("DAO-3D-$")
(c) ND26 ("UP-FLX-$") (h) ND68 ("BXHGHT-$")
(d) ND44 ("DRYD-FLX") (i) ("TCMASS-$")
(e) ND45 ("CHEM-L=$") (j) ("TR-PAUSE")
EXAMPLE:
FULLCHEM_BUDGET, TAU0=144600D,
FILENEW='ctm.bpch.v5-01'
INITIALFILE='fullchem.mass.initial.v5-01', $
FINALFILE='fullchem.mass.final.v5-01', $
OUTFILENAME='v5-01.budget.fullchem'
MODIFICATION HISTORY:
bmy, 15 Aug 2002: VERSION 1.01
- adapted from Isabelle Bey's "budget.pro"
bmy, 14 Jan 2003: VERSION 1.02
- In GEOS-CHEM v5-03+, ND44 saves out tracers
using the CTM tracer number
bmy, 30 Oct 2003: VERSION 1.03
- now call PTR_FREE to free the heap memory
so that we don't run out of memory
- now compute mean mass-weighted OH instead
of methyl chloroform lifetime
ccc & bmy, 11 Aug 2010: VERSION 1.04
- Updated computation of Ox budget
bmy, 10 Jan 2011: VERSION 1.05
- Updated 200hPa level for MERRA
bmy, 08 Jun 2011: - Also print out MCF lifetime
bmy, 11 May 2012: GAMAP VERSION 2.16
- Modified for GEOS-5.7.2 met
mps, 06 Jan 2014: - Fix bug in calculation of WetYear so that wetdep
from convective updrafts is not double counted
(P. Kasibhatla)
mps, 04 Mar 2016: - Modified for MERRA2 met
(See /n/home09/ryantosca/IDL/gamap2/benchmark/fullchem_budget.pro)
NAME:
FULLCHEM_EMISSIONS
PURPOSE:
Prints totals of GEOS-CHEM emission species for two different
model versions. Also prints the difference in emission
totals between the two model versions.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
FULLCHEM_EMISSIONS [ , Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
FILENEW -> Name of a binary punch file containing model
output from a "New" version of the GEOS-Chem
FILEOLD -> Name of a binary punch file containing model
output from a "Old" version of the GEOS-Chem.
VERSION_NEW -> String that specifies the GEOS-Chem version
number pertaining to FILENEW. If not specified, then
FULLCHEM_EMISSIONS will look for this at the end of
the filename FILENEW.
VERSION_OLD -> String that specifies the GEOS-Chem version
number pertaining to FILEOLD If not specified, then
FULLCHEM_EMISSIONS will look for this at the end of
the filename FILEOLD.
OUTFILENAME -> Name of the text file where emission totals
and differences will be sent. Default is "emissions.txt".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
==================================
GetVersionInfo (function)
WriteHeader
WriteTracers
External Subroutines Required:
==================================
CTM_SUM_EMISSIONS
UNDEFINE
STRPAD (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Assumes the version number is located at the end of
both FILENEW and FILEOLD
(2) Assumes that both FILENEW and FILEOLD contain the
following GEOS-CHEM diagnostic categories:
(a) ND06: DUSTSRCE
(b) ND07: BC-ANTH, BC-BIOB, BC-BIOF, PL-BC=$,
OC-ANTH, OC-BIOB, OC-BIOF, PL-OC=$
(c) ND08: SALTSRCE
(d) ND11: ACETSRCE
(e) ND13: DMS-BIOG, SO2-AC-$, SO2-AN-$, SO2-EV-$,
SO2-NV-$, SO4-AN-$, NH3-ANTH, NH3-BIOB,
NH3-BIOG, NH3-NATU, SO2-SHIP
(f) ND28: BIOBSRCE
(g) ND29: CO--SRCE
(h) ND32: NO-AC-$, NO-AN-$, NO-BIOB, NO-FERT,
NO-LI-$, NO-SOIL
(i) ND34: BIOFSRCE
(j) ND36: ANTHSRCE
(k) ND46 BIOGSRCE
EXAMPLE:
FULLCHEM_EMISSIONS, FILENEW='ctm.bpch.v10-01e', $
FILEOLD='ctm.bpch.v10-01d', $
OUTFILENAME='emissions.txt'
; Prints emissions & differences between
; versions v10-01d and v10-01e
MODIFICATION HISTORY:
bmy, 18 Jun 2001: VERSION 1.00
bmy, 20 Jun 2001: VERSION 1.01
- now omit ALD2 (#11) from ANTHROPOGENIC
bmy, 20 Sep 2001: VERSION 1.02
- now print ND11 acetone sources, sinks
bmy, 15 Aug 2002: VERSION 1.03
- renamed to FULLCHEM_EMISSIONS
- renamed FILE_NEW to FILENEW and
FILE_OLD to FILEOLD
bmy, 17 Jan 2003: VERSION 1.04
- also sum up sulfate emission categories
bmy, 27 Mar 2003: VERSION 1.05
- adjust FORMAT string for branch versions
- now also print out NH3-NATU source
bmy, 09 Apr 2004: VERSION 1.06
- Now print out emissions of BC/OC tracers
- Now print out hydrophilic BC/OC which
came from hydrophobic BC/OC
bmy, 28 Apr 2004: VERSION 1.07
- Now print out dust emissions
bmy, 03 May 2004: VERSION 1.08
- Now print out seasalt emissions
bmy, 21 May 2004: VERSION 1.09
- Now print out ship exhaust SO2 emissions
bmy, 08 Jul 2005: VERSION 1.10
- Updated for 43 tracers
bmy, 10 Jan 2011: VERSION 1.11
- Now make numeric fields 13 chars wide to
allow for wider title headers
bmy, 16 Dec 2011: GAMAP VERSION 2.16
- Remove ACET from dryleaf and ACET from
grass; these are obsolete GEIA quantities
mps, 23 Jan 2014: - Now report NH3 emissions in Tg N
bmy, 18 Aug 2014: GAMAP VERSION 2.18
- Now display Anthro + Biofuels together
which facilitates use w/ HEMCO emissions
bmy, 18 Aug 2014: - Now pass VERSION_NEW and VERSION_OLD as
keywords. If these are not specified,
then FULLCHEM_EMISSIONS will obtain these
from the filenames FILENEW and FILEOLD.
ewl, 18 Mar 2015: - Replace SO2-BF-$ and SO4-BF-$ with SO2-BIOF
and SO4-BIOF in anthro+biofuel section.
(See /n/home09/ryantosca/IDL/gamap2/benchmark/fullchem_emissions.pro)
NAME:
FUTURE2BPCH
PURPOSE:
Converts future emission growth factor files from the obsolete
binary format to binary punch format (so that they can be
read by GAMAP).
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
FUTURE2BPCH, [ Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the input file containing fossil
fuel scale factors. If omitted, SCALEFOSS2BPCH
will prompt the user for a filename via a dialog box.
OUTFILENAME -> Name of the binary punch file containing
fossil fuel scale factors. Default is to add a
".bpch" extension to INFILENAME.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required
==================================================
CTM_TYPE (function) CTM_GRID (function)
NYMD2TAU (function) CTM_MAKE_DATAINFO (function)
CTM_WRITEBPCH EXTRACT_FILENAME (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
FUTURE2BPCH, INFILENAME='scalefoss.liq.2x25.1998', $
OUTFILENAME='scalefoss.liq.2x25.1998.bpch'
; Converts scalefoss files to BPCH format.
MODIFICATION HISTORY:
bmy, 25 Jan 2006: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read bpch as big-endian
(See /n/home09/ryantosca/IDL/gamap2/file_io/future2bpch.pro)
NAME:
GAMAP
PURPOSE:
Menu-driven user interface for creating plots with
the GAMAP package subroutines. The actual data retrieval
and plotting is done with ctm_plot.pro. This routine
mainly collects all user requests and passes them on to
CTM_PLOT.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
GAMAP, [ DiagN [, Keywords ] ]
INPUTS:
DIAGN -> A diagnostic number or category to restrict
the record selection (default is: use all).
KEYWORD PARAMETERS:
General keywords:
-----------------------------------------------------------------
FILENAME -> CTM output file name. Default is to display a
pickfile dialog and let the user select. You can have
wildcards ('*', '?') in your filename which restricts
the file selection.
/NOFILE -> Don't query for filename but display all records that
have already been loaded. This can save you a couple of
mouse clicks when you want to create several plots with
data from one file, and it also useful when you want
to plot data from 'external' files that were converted
with ctm_make_datainfo. If a filename is given or no
data were loaded, the file selection dialog will appear
anyhow.
/RESETDEFAULTS -> If set, will reset all GAMAP values to their
defaults.
/HELP -> Displays a help page.
RESULT -> Returns a structure with the data subset as plotted and
the respective X and Y coordinates. Returns only one data
record though.
TOPTITLE -> Add a specific title centered on top of each page
of output.
Keywords to restrict the number of records displayed for selection:
-----------------------------------------------------------------
TRACER -> A tracer number to restrict record selection
TAU0 -> Time value (at beginning of record)
DATE -> 6 digit date (e.g. 940101) at the beginning of the
output record (this gets translated into a TAU0
value via the function nymd2tau). You can specify more
than one date at a time using a vector (e.g. [940101, 940301]).
For the GISS model(s), you also have to specify /GISS_Date in
order to get correct tau values. The time is assumed to
be 00 GMT. For other times use the TAU0 keyword as
TAU0=nymd2tau(dates,times).
/GISS_Date -> set this flag if you are using the DATE keyword
with GISS model output.
Keywords defining output options (these override defaults in
gamap.defaults)
-----------------------------------------------------------------
/PS -> If set, will directly send output to the 'idl.ps' file.
If not set, GAMAP will prompt the user whether to create
the 'idl.ps' file.
OUTFILENAME -> Name of file to send PostScript output to.
/NOTIMESTAMP -> Do not include a user ID and time stamp
on the postscript plot. Unnecessary if the TIMESTAMP value
in gamap.defaults is set to 0.
XSIZE, YSIZE, XOFFSET, YOFFSET -> GAMAP will pass these
keywords to routine OPEN_DEVICE, for setting the size
and margins of PostScript output.
/DO_BMP -> If set, GAMAP will save animation frames as BMP
files. If not set, GAMAP will prompt the user whether
to save animation frames to BMP files. DO_BMP overrides
the default setting in "gamap.defaults".
BMPFILENAME -> Name of BMP file to save animation frames to.
If the token %N% is used in BMPFILENAME, then GAMAP
will replace %N% with the actual frame number. If
BMPFILENAME is not set, or if DO_BMP is set to *QUERY in
"gamap.defaults", GAMAP will prompt user to supply
BMPFILENAME.
/DO_GIF -> If set, GAMAP will save animation frames as GIF
files. If not set, GAMAP will prompt the user whether
to save animation frames to GIF files. DO_GIF overrides
the default setting in "gamap.defaults".
GIFFILENAME -> Name of GIF file to save animation frames to.
If the token %N% is used in GIFFILENAME, then GAMAP
will replace %N% with the actual frame number. If
GIFFILENAME is not set, or if DO_GIF is set to *QUERY in
"gamap.defaults", GAMAP will prompt user to supply
GIFFILENAME.
/DO_JPEG -> If set, GAMAP will save animation frames as BMP
files. If not set, GAMAP will prompt the user whether
to save animation frames to JPEG files. DO_JPEG overrides
the default setting in "gamap.defaults".
JPEGFILENAME -> Name of JPEG file to save animation frames to.
If the token %N% is used in JPEGFILENAME, then GAMAP
will replace %N% with the actual frame number. If
JPEGFILENAME is not set, or if DO_JPEG is set to *QUERY in
"gamap.defaults", GAMAP will prompt user to supply
JPEGFILENAME.
/DO_PNG -> If set, GAMAP will save animation frames as PNG
files. If not set, GAMAP will prompt the user whether
to save animation frames to PNG files. DO_PNG overrides
the default setting in "gamap.defaults".
PNGFILENAME -> Name of PNG file to save animation frames to.
If the token %N% is used in PNGFILENAME, then GAMAP
will replace %N% with the actual frame number. If
PNGFILENAME is not set, or if DO_PNG is set to *QUERY in
"gamap.defaults", GAMAP will prompt user to supply
PNGFILENAME.
/DO_TIFF -> If set, GAMAP will save animation frames as TIFF
files. If not set, GAMAP will prompt the user whether
to save animation frames to TIFF files. DO_TIFF overrides
the default setting in "gamap.defaults".
TIFFFILENAME -> Name of TIFF file to save animation frames to.
If the token %N% is used in TIFFFILENAME, then GAMAP
will replace %N% with the actual frame number. If
TIFFFILENAME is not set, or if DO_PNG is set to *QUERY in
"gamap.defaults", GAMAP will prompt user to supply
TIFFFILENAME.
/POLAR -> Set this keyword for polar pots. This forces latitude
ranges to extend to one pole and longitude ranges to span
the globe. Polar plots only work for global (at least
longitudinally) data sets. Currently, polar plots are
supported only for contour plots.
_EXTRA=e -> Picks up extra keywords for CTM_PLOT, etc...
OUTPUTS:
SUBROUTINES:
Internal subroutines:
------------------------------------------------------
GAMAP_CheckDataBlockConsistency (function)
GAMAP_FindNearestCenters (function)
GAMAP_GetDataBlockRanges (function)
GAMAP_GetDefaultRanges
GAMAP_AutoYRange (function)
GAMAP_PrintDimInfo
GAMAP_QueryAnimationOptions
GAMAP_QueryAverageOrTotal
GAMAP_QueryPostScriptOptions
GAMAP_SelectDataBlocks (function)
GAMAP_SelectPlotType
GAMAP_QueryIsoPleth
GAMAP_StoreGridInfo
GAMAP_UserRangeEntry (function)
GAMAP_GetFrameFileName (function)
Also uses external subroutines:
------------------------------------------------------
CHOICE (function) CLOSE_DEVICE
CTM_PLOT OPEN_DEVICE
STRREPL (function) STRWHERE (function)
DEFAULT_RANGE (function) CHKSTRU (function)
REPLACE_TOKEN (function) CTM_GRID (function)
MAKE_SELECTION(function) TVREAD (function)
REQUIREMENTS:
None
NOTES:
(1) GAMAP can read ASCII punch files with GEOS or GISS, model II
diagnostics, binary punch files (as defined in Jan 1999),
and GEOS-CTM binary restart files. Binary punch files
are processed much faster and allow "windowing" of output.
(2) For pixel plots, GAMAP can only plot cylindrical maps
with rectangular projections. Arbitrary map projections
should be possible with any type of contour plot. For
polar plots, use the /POLAR keyword. Other projections
have not been tested and may lead to unexpected results.
(3) GAMAP forces map ranges to coincide with the grid box
edges, so that the map and pixel plot will be aligned.
Each "pixel" size corresponds to one full grid box.
For grids with half-polar boxes, it is therefore recommended
not to plot the polar latitudes, since those boxes will
show up as full-size boxes and shift the rest of the plot
accordingly.
(4) When the user selects multiple data blocks, GAMAP will produce
a multi-panel plot if !p.multi indicates more than one panel
on the screen (use the MULTIPANEL procedure to turn it on).
If you plot only one panel per screen, GAMAP will automatically
start XInterAnimate to present your own movie to you. Be
aware that XInterAnimate is limited by your system resources.
With default window sizes, we can usually display at least
30 frames. ADDENDUM: 3-D isopleth maps will not be
animated. (bmy, 1/22/01)
(5) Animation frames can also be written to GIF or MPEG
files. Defaults can be set in "gamap.defaults", or
specified via the command line. You can also save individual
GAMAP plots as GIF files. If you want to animate them later
(e.g. using ULead's GIF-Animator), make sure to specify the
RANGE keyword to get identical color schemes (or use contours).
(6) The GAMAP authors wish to point out that it is still relatively
expensive to produce color plots on the printer. We encourage
you to try out contour plots and make a test print on a black
and white printer before you make a color print.
(7) The 3-D isopleth maps do not quite work with MULTIPANEL, since
they are produced with screen capture in the Z-Buffer. Hence
Hence, the X window device has to be re-initialized each time,
which negates the MULTIPANEL utility. PostScript plots of 3-D
isopleth maps will print one plot per page. We can live with
this for the time being. Isopleth maps can also be written
to GIF files.
(8) Now uses D. Fanning's TVREAD function to perform better
device-independent screen capture. (cf. www.dfanning.com)
EXAMPLES:
(1)
GAMAP
; operates fully interactively
MULTIPANEL,nplots=6 ; turn on multi-panel environment
GAMAP
; same as above, but produce multi-panel plots with
; 6 plots per page
(2)
GAMAP, 'IJ-AVG-$', tra=4
; Will create a CO (tracer=4) plot for the ND45 diagnostic.
; GAMAP will display dialog pickfile box and will scan the
; file for all records with ND45 and tracer 4. Those will be
; displayed and the user can then select a record to be plotted.
(3)
GAMAP, [ 'IJ-AVG-$', 'BIOBSRCE' ], tra=[2,4], $
date=[19940601, 19940801], $
FileName='~bmy/terra/CTM4/ctm.pch',/ps
; In this example the file is fully specified, hence no file
; selection dialog will be displayed. GAMAP scans the file
; for all records of 'IJ-AVG-$' and 'BIOBSRCE' and tracers
; 2 (OX) and 4 (NOX) and it seelcts only those records that
; begin on the first of JUNE or AUGUST 1994. Because the ps
; flag is set, the output will be directed to the postscript
; file 'idl.ps' without first being displayed on the screen.
MODIFICATION HISTORY:
mgs, 12 Nov 1998: VERSION 1.00
bmy, 16 Nov 1998: - added defaults for LAT, LEV, LON, PTYPE
- now prompts for PS
- now prompts user for /PS output
bmy, 17 Nov 1998: - now call DEFAULT_RANGE to ensure that
that LAT, LON, LEVEL have two elements,
even if there is only one unique value.
- now uses N_UNIQ.PRO to test for the number
of unique elements in LON, LAT, and LEVEL.
mgs, 17 Nov 1998: - finishing touches for first release.
- added NOFILE keyword
- added plot type b/w contours
mgs, 18 Nov 1998: - added timestamp as default when closing
postscript files
bmy, 08 Jan 1999: - Will also prompt for totaling (if
averaging is not selected)
bmy, 13 Jan 1999: - now prompt user for OUTFILENAME
bmy, 15 Jan 1999: VERSION 1.02
- add support for 3-D data slices
- clean up user interface so that the user
menu of plotting options is only invoked
when plotting a 2-D map.
bmy, 19 Jan 1999: - added binary flag masking
- added defaults for averaging and selection
- improved echoback of information to user
bmy, 20 Jan 1999: - prompts user again if data block selection
or averaging selection is out of range
- fixed bug: now default data block
selection is saved.
- Reset PS to 0 and OUTFILENAME to '' if we
are plotting a 0-D or 3-D data block
- updated comments
mgs, 21 Jan 1999: - dimensional information now in subroutine
- improved binary masking
- added several Quit options
- Postscript options now controlled from
gamap.defaults
- removed NoTimeStamp keyword (now set in
gamap.defaults)
bmy, 12 Feb 1999: VERSION 1.03
- now works with data blocks that are
sub-regions of the globe
- added functions GAMAP_GetDataBlockRanges
GAMAP_SelectDataBlock, and
GAMAP_QueryAverageOrTotal
- updated comments
bmy, 17 Feb 1999: VERSION 1.20
- Replace DATAINFO.OFFSET by DATAINFO.FIRST,
which contains the I, J, L indices of
the first grid box
- Animation facility added
- added functions GAMAP_GetModelInfo,
GAMAP_CheckDataBlockConsistency,
GAMAP_SelectPlotType, and
GAMAP_QueryPostScriptOptions.
- Also renamed function GAMAP_SelectDataBlock to
GAMAP_SelectDataBlocks, since one can now
select multiple data blocks
bmy, 18 Feb 1999: - added /RESETDEFAULTS keyword
- removed /ANIMATE keyword
bmy, 19 Feb 1999: - added NOAUTOYRANGE keyword
- added function GAMAP_AutoYRange
- added GIFFILENAME keyword
- added GIF_SAV to common block SAVEVALUES
- call REPLACE_TOKEN to replace token text
in DEFAULTGIFFILENAME
bmy, 22 Feb 1999: - added more animation options
- added DO_GIF, DO_MPEG, DO_ANIMATE, and
MPEGFILENAME keywords
- added GAMAP_QueryAnimationOptions routine
bmy, 23 Feb 1999: - small bug fixes
bmy, 04 Mar 1999: - added internal routines GAMAP_FindNearestEdges
and GAMAP_GetDefaultRanges
- now force lat/lon ranges to coincide with
grid box edges
- warn user if lat range contains half-polar
boxes, since TVIMAGE will treat them as
whole boxes and the map overlay will be
inaccurate!
bmy, 05 Mar 1999: - Clean up FILEINFO/DATAINFO matching process
- renamed/reorganized internal functions\
bmy, 20 Mar 1999: - bug fix for default ranges (may need more
fixing later on)
mgs, 22 Mar 1999: - added ALREADY_PS flag for multi-panel use
- animation now only if !p.multi does not
have more than 1 panel to display
mgs, 23 Mar 1999: - improved comments and examples
- removed unnecessary function MatchFileInfo...
(easier with make_selection)
- changed all "string booleans" to booleans
- Do_Animation now an entirely local variable
mgs, 25 Mar 1999: - few minor bug fixes
- improved handling of default ranges
- detect out of range in record selection
- now allows for 2D field plots
bmy, 17 May 1999: - now resolve DEFAULT_RANGE explicitly and
call DEFRANGE_STR2NUM separately
- few minor fixes in GAMAP_UserRangeEntry for
data blocks that straddle the date line.
mgs, 19 May 1999: - some more cleaning
- implemented SAVE option after data record
selection
- user selection for longitudes greatly improved
- some adjustments in FindNearestEdges, notably
for range 0..360. Unfortunately, the 0 meridian
gridline will be omitted in such plots. If we
wanted to include it we would need to carry
an extra GLOBAL flag because lower and upper
edges (grid box indices) are identical.
mgs, 20 May 1999: - added option to save record seelction to file.
mgs, 24 May 1999: - yet more work had to be done to make lon/lat
selection as user would expect it to work.
- renamed FindNearestEdges to ..Centers
mgs, 25 May 1999: - still more fiddling. Yuck!
RELEASE OF GAMAP VERSION 1.40
bmy, 26 May 1999: - Added polar plot capabilities
- fixed reset of plot ranges when latitude is +-90
mgs, 27 May 1999: - already_ps flag now also prevents user query.
- default lat range for global fields now back
to -88..88 only for "reset" conditions. Otherwise
-90..90 is recognized and remembered.
mgs, 28 May 1999: - added RESULT keyword.
- added TOPTITLE keyword.
bmy, 28 May 1999: - restrict plot type menu for polar plots
bmy & mgs, 02 Jun 1999: - add /NOERASE to MULTIPANEL call when
testing for last plot on page
- updated some comments
mgs, 30 Jun 1999: - make sure to return only one lat/lon box
if user enters single value (even on edges).
bmy, 07 Jul 1999: - small bug fixes
bmy, 15 Sep 1999: GAMAP VERSION 1.43
- changes for 23L GISS-II-PRIME model
- minor bug fixes
bmy, 25 Oct 1999: GAMAP VERSION 1.44
- added /MULTIPLE keyword -- option to
write to a GIF file w/ multiple frames
bmy, 23 Nov 1999: - /SMALLCHEM now works correctly!
bmy, 26 Apr 2000: GAMAP VERSION 1.45
- now make sure tracer numbers are mod 100L
when saving data blocks to disk
bmy, 19 Jun 2000: - now create NS string array by concatenating
smaller arrays of < 1024 elements
bmy, 20 Jun 2000: - bug fix -- set NS[0] blank for string output
bmy, 03 Oct 2000: GAMAP VERSION 1.46
bmy, 22 Jan 2001: GAMAP VERSION 1.47
- removed obsolete code
- now produce a 3-D isopleth map instead of
calling the volume slicer routine
- added ISOPLETH keyword
- added internal subroutine GAMAP_QueryIsopleth
- allow PostScript output for 3-D maps, and
suppress animation for 3-D maps.
bmy, 13 Mar 2001: - remove a couple more instances of the
obsolete STR_SEP routine. Replaced with
STRSPLIT( /EXTRACT ).
bmy, 28 Jun 2001: GAMAP VERSION 1.48
- bug fix in GAMAP_StoreDataInfo: for
GENERIC grids with NLAYERS=0, be sure to
call CTM_GRID with the /NO_VERTICAL flag.
bmy, 29 Aug 2001: - added XSIZE, YSIZE, XOFFSET, YOFFSET
keywords to pass to OPEN_DEVICE
mje & bmy, 17 Dec 2001: GAMAP VERSION 1.49
- add _EXTRA=e in call to CTM_WRITEBPCH,
so that we can pass the /APPEND keyword
bmy, 17 Jan 2002: GAMAP VERSION 1.50
- now call STRBREAK wrapper routine from
the TOOLS subdirectory for backwards
compatiblity for string-splitting
- use FORWARD_FUNCTION to declare STRBREAK
bmy, 24 Jan 2002: - deleted obsolete code
bmy, 06 Dec 2002: GAMAP VERSION 1.52
- removed /DO_MPEG and MPEGFILENAME keywords
- now use D. Fanning's TVREAD for better
device-independent screen capture
- removed /MULTIPLE keyword for GIF output
- added /DO_PNG, /DO_BMP, /DO_JPEG,
/DO_TIFF keywords
- added internal function GAMAP_GetFrameFileName
bmy, 13 Nov 2003: GAMAP VERSION 2.01
- comment out XINTERANIMATE options
bmy, 27 Aug 2004: GAMAP VERSION 2.03
- now call CTM_PLOT_TIMESERIES to plot data
from bpch files containing GEOS-CHEM station
timeseries output (e.g. ND48 diagnostic)
bmy, 27 Oct 2004: - now pass /QUIET keyword to GAMAP_AUTOYRANGE,
CTM_PLOT_TIMESERIES, and CTM_PLOT
- hardwire QUIET=1 in to suppress extra printing
bmy, 28 Jun 2005: GAMAP VERSION 2.04
- Strip white spaces in FILENAME, if present
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy & phs, 20 Nov 2007: GAMAP VERSION 2.11
- If any 4D data blocks are encountered,
then only use the first 3 dimensions
phs, 22 Sep 2009: GAMAP VERSION 2.13
- Added /NoDialog to all call to TVRead
bmy, 26 Feb 2010: GAMAP VERSION 2.14
- Now allow polar maps to use pixel plots
bmy, 11 Feb 2011: GAMAP VERSION 2.15
- Updated welcome screen
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/gamap.pro)
NAME:
GAMAP2_HTML
PURPOSE:
Wrapper routine for IDL2HTML. Is used to call IDL2HTML
repeatedly in order to create HTML documentation for each
of the source code files in the GAMAP installation. The
user may sort routines by alphabetical order or by category.
CATEGORY:
Documentation
CALLING SEQUENCE:
GAMAP2_HTML [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTDIR -> Specifies the directory in which HTML documenation
will be created. Passes this to IDL2HTML.
/ALL_ROUTINES -> Select this option to create an HTML file
with documentation information about all routines
in the GAMAP directory. The output file name will be
"gamap2_html.pro".
/BY_ALPHABET -> Select this option to create HTML documentation
files for GAMAP routines by alphabetical order. A file
will be created for each letter of the alphabet.
/BY_CATEGORY -> Select this option to create HTML documentation
files for GAMAP routines according to category (as
specified by the "CATEGORY" tag of the IDL doc header).
A files will be created for each individual category.
NOTE: GAMAP routines may be cross-linked across more
than one category.
OUTPUTS:
SUBROUTINES:
External Routines Required:
============================
IDL2HTML
PROGRAM_DIR (function)
REQUIREMENTS:
None
NOTES:
(1) See also the documentation to IDL2HTML and the IDL manual
for routine MK_HTML_HELP.
(2) One of /ALL_ROUTINES, /BY_ALPHABET, or /BY_CATEGORY must
be selected.
EXAMPLES:
(1)
GAMAP2_HTML, /ALL_ROUTINES, OUTDIR='manual/html'
; Creates HTML documentation from the std headers to
; each of the IDL source code programs in the GAMAP
; installation. Writes output to the manual/html
; directory. The output file name is "gamap2.html",
; which directory.
(2)
GAMAP2_HTML, /BY_ALPHABET, OUTDIR="manual/html"
; Creates HTML documentation from the std headers to
; each of the IDL source code programs in the GAMAP
; installation. Will search through the IDL doc
; headers and create a new HTML file for each
; letter of the alphabet.
(3)
GAMAP2_HTML, /BY_CATEGORY, OUTDIR='manual/html'
; Creates HTML documentation from the std headers to
; each of the IDL source code programs in the GAMAP
; installation. Will search through the IDL doc
; headers and create a new HTML file for each
; category.
MODIFICATION HISTORY:
bmy & phs, 23 Jul 2007: GAMAP VERSION 2.10
bmy, 20 Nov 2007: GAMAP VERSION 2.11
- Added new category for timeseries routines
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Now check to see if OUTDIR exists
(See /n/home09/ryantosca/IDL/gamap2/doc/gamap2_html.pro)
NAME:
GAMAP2_MANUAL_CREATE
PURPOSE:
This routine creates the HTML documentation pages for each of
the GAMAP routines. This is a convenience wrapper routine
which calls both GAMAP2_HTML and FIX_MANUAL_HTML.
CATEGORY:
Documentation
CALLING SEQUENCE:
GAMAP2_MANUAL_CREATE
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Routines Required:
============================
GAMAP2_HTML
FIX_MANUAL_HTML
REQUIREMENTS:
None
NOTES:
Will save output to the ../manual/html/* directories.
EXAMPLES:
GAMAP2_MANUAL_CREATE
; Creates HTML documentation from the std headers to
; each of the IDL source code programs in the GAMAP
; installation. Writes output to the manual/html
; directory.
MODIFICATION HISTORY:
bmy, 01 Jul 2008: GAMAP VERSION 2.12
(See /n/home09/ryantosca/IDL/gamap2/doc/gamap2_manual_create.pro)
NAME:
GAMAP2_REVISIONS
PURPOSE:
Wrapper routine for REVISIONS, used to create a "REVISIONS"
file for each code directory in the GAMAP installation.
CATEGORY:
Documentation
CALLING SEQUENCE:
GAMAP2_REVISIONS
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
PROGRAM_DIR (function)
REVISIONS
REQUIREMENTS:
None
NOTES:
The REVISIONS routine requires the tag "MODIFICATION HISTORY"
to be present. Files without this tag (e.g. data files or
input files) will not be included in the REVISIONS output.
EXAMPLE:
GAMAP2_REVISIONS
; Search through all of the directories in the GAMAP
; installation and create a REVISIONS file containing
; the modification histories of each *.pro file.
MODIFICATION HISTORY:
bmy, 17 Jul 2007: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/doc/gamap2_revisions.pro)
NAME:
GAMAP_CMN
PURPOSE:
Contains global common block for Global Atmospheric Model
output Analysis Package include file (include with @gamap_cmn)
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
@gamap_cmn
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
Referenced by gamap_init.pro and gamap.pro
NOTES:
None
MODIFICATION HISTORY:
mgs, 14 Aug 1998 INITIAL VERSION
mgs, 21 Jan 1999: - added postscript variables
bmy, 22 Feb 1999: - added options for animation (GIF, MPEG filenames)
bmy, 10 Dec 2002: GAMAP VERSION 1.52
- removed DO_MPEG and DEFAULTMPEGFILENAME
- added DO_BMP and DEFAULTBMPFILENAME
- added DO_JPEG and DEFAULTJPEGFILENAME
- added DO_PNG and DEFAULTPNGFILENAME
- added DO_TIFF and DEFAULTTIFFFILENAME
bmy, 13 Nov 2003: GAMAP VERSION 2.01
- re-added DO_MPEG and DEFAULTMPEGFILENAME
- removed CREATEANIMATION, this was only
ever used for XINTERANIMATE (obsolete)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/gamap_cmn.pro)
NAME:
GAMAP_COLORS
PURPOSE:
Concatenates several different color tables (including
IDL standard color tables and the ColorBrewer color
tables) into single file for for use with GAMAP.
CATEGORY:
Color
CALLING SEQUENCE:
GAMAP_COLORS
INPUTS:
OUTFILENAME -> Name of the color table file to modify.
Default is "gamap_colors.tbl". GAMAP_COLORS will
locate this file with FILE_WHICH.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MYCT
REQUIREMENTS:
None
NOTES:
IDL's MODIFYCT function may require that the file to be
modified already be on disk.
EXAMPLE:
GAMAP_COLORS, 'new_gamap_colors.tbl'
; Will modify the colortable file
; 'new_gamap_colors.tbl'.
MODIFICATION HISTORY:
bmy, 18 Apr 2008: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/color/gamap_colors.pro)
NAME:
GAMAP_INIT
PURPOSE:
Initialize global common block for Global Atmospheric Model
(output) Analysis Package (GAMAP). This routine is called
automatically when gamap_cmn.pro is included in a file
( @gamap_cmn.pro ), but it executes only once. User
preferences are read from the file gamap.defaults in the
current directory or the directory where gamap_init.pro
resides.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
GAMAP_INIT
INPUTS:
none
KEYWORD PARAMETERS:
DEBUG -> set a (new) debug level (0 or 1).
OUTPUTS:
none
SUBROUTINES:
Uses FILE_EXIST, EXTRACT_PATH, and OPEN_FILE
REQUIREMENTS:
None
NOTES:
If you change the definition of the common block
in gamap_cmn.pro, make sure to accomodate these changes
in GAMAP_INIT.
EXAMPLE:
GAMAP_INIT
MODIFICATION HISTORY:
mgs, 14 Aug 1998: VERSION 1.00
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 05 Oct 1998: - type assignment fix to DEBUG when read
mgs, 08 Oct 1998: - now runs through after CTM_CLEANUP and does
not delete global pointers if valid.
- added DEBUG keyword
mgs, 21 Jan 1999: - added postscript options
bmy, 19 Feb 1999: - added GIF_FILENAME
bmy, 22 Feb 1999: VERSION 1.01
- added more animation options
- changed POSTSCRIPT to DO_POSTSCRIPT
- default path now amalthea
mgs, 23 Mar 1999: - slight change in defaults
bmy, 19 Jan 2000: GAMAP VERSION 1.44
- replaced the deprecated STR_SEP function
with STRSPLIT for IDL 5.3+
- Now STRTRIM each token so that the case
statement will find matches
- cosmetic changes, updated comments
bmy, 13 Mar 2001: GAMAP VERSION 1.47
- now supports MacOS operating system
bmy, 07 Jun 2001: - removed obsolete code prior to 3/13/01
bmy, 17 Jan 2002: GAMAP VERSION 1.50
- now call STRBREAK wrapper routine from
the TOOLS subdirectory for backwards
compatiblity for string-splitting;
- use FORWARD_FUNCTION to declare STRBREAK
bmy, 10 Dec 2002: GAMAP VERSION 1.52
- added options for BMP, JPEG, PNG, TIFF output
- added internal function TRIMTOK
bmy, 13 Nov 2003: GAMAP VERSION 2.01
- re-added option for MPEG animation
- removed CREATEANIMATION, this was only
ever used for XINTERANIMATE (obsolete)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now use the IDL FILE_WHICH routine to
locate the gamap.defaults file
(See /n/home09/ryantosca/IDL/gamap2/internals/gamap_init.pro)
NAME:
GC_COMBINE_ND48
PURPOSE:
Combine timeseries data from the Geos-CHEM ND48
diagnostics contained in one or more binary punch files.
The goal is to combine, for one station, all the data blocks
(there is one per time step) into one single 4-D data block
(we want the time to be the 4th dimension). This is basically
to take advantage of support for 4D dataset in GAMAP v2-10.
GEOS-Chem ND48 (as in v7-04-12) outputs one file for all
stations and all time steps. GC_COMBINE_ND48 will write one
file but each timeseries will be in one data block instead of
as many as the number of timesteps. This will make reading
the timeseries with CTM_GET_DATA a lot faster.
Two basic signal processing before saving the data can be
applied: moving average and/or daily maximum.
LIMITATION: daily maximum will not make sense if series do
not cover full days.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, Time Series
CALLING SEQUENCE:
GC_COMBINE_ND48 [, Keywords ]
OPTIONAL INPUTS:
By defaults all stations are processed. And one output file
is created that contains all the stations timeseries.
KEYWORD PARAMETERS:
;============ For I/O files/directory =====================
INFILE -> one or more station file(s) from ND48
diagnostic. If more than one file is processed, it is
assumed that, once sorted in alphabetical order, they
are in chronological order (this is automatically the
case, if you insert YYYYMMDD into ND48 filenames in
input.geos).
INDIR -> Directory where to look for "stations" files. Can be
either input or output keyword:
Input: when defined, ALL files satisfying the MASK
keyword in the directory will be selected.
Ouput: set to a variable name that will contains the DIR
of the selected files.
It is ignored (both input and output roles) if INFILE is
provided.
If neither INFILE nor INDIR is set, then a dialog window
that allows multiple files selection (keep CTRL or SHIFT
key down) will pop-up.
MASK -> Pattern Mask to find files in INDIR. Default is
"stations*".
OUTFILENAME -> Name of the file that will contain the
new timeseries. Default is 'combined'+INFILE[0], in the
same directory as stations file. If the full path is not
included, the file is created in the working directory.
The routine prevents from overwriting any input file.
;================= Data Selection ======================
STATIONNB -> Station(s) number. Can be one or more elements
(up to the number of stations in ND48). Use to select a
subset of the stations instead of all of them.
TIME -> vector for selecting time span. The data covering
[min(TIME),max(TIME)] are selected. If only one
element, then the closest-in-time data is selected.
If min and/or max of TIME is outside the range of
available time steps, the first or last available time
step is used.
Note 1: this is also an output keyword. Then, if passed
by reference, TIME becomes the time vector in
output. See example (6).
Note 2: if using DMAX or DAVG, then TIME should be long
integer (YYYYMMDD), if not it should be Tau format.
;================= Signal Processing ======================
MAVG -> to apply a running average filter to the series. MAVG
value will define the boxcar size and must be GE
3. Even numbers are increased by +1. The IDL SMOOTH
routine is called and accept _extra keywords (NAN,
EDGE_TRUNCATE, and MISSING).
DMAX -> to select the daily maxima of the time series. If
both MAVG and Dmax are set, the moving average is
performed first and you get the daily max of the moving
average. (Local time is not accounted for: days start
and end at 0 UT everywhere).
DAVG -> to select the daily average of the time series. If
both MAVG and DAVG are set, the moving average is
performed first and you get the daily average of the
moving average. (Local time is not accounted for: days
start and end at 0 UT everywhere).
;================= Output keywords ========================
All the following keywords will apply to only ONE
station. The last one is used if none or more than one is
requested.
DATA -> set to a variable name that will hold the selected
timeseries data on exit. This is a 4D array
(1,1,lev,time) even though only one station is
selected.
LON -> set to a variable name that will hold the
longitude of the data set on exit.
LAT -> set to a variable name that will hold the
latitude of the data set on exit.
LEV -> set to a variable name that will hold the vector
of levels for the data set on exit.
TIME -> set to a variable name that will hold the time
vector for the station on exit. Given as Tau values,
unless DMAX or DAVG is set, then as YYYYMMDD.
LOCALTIME -> if set, the TIME vector is in local time
instead of UT. Has no effect if /DMAX or /DAVG.
;================= Others ========================
NOSAVE -> set to not save output into a BPCH file. Useful if
you just want to check results with output keywords.
VERBOSE -> Set to print informational message about the time
series. particularly useful to double check
area/location selected with subset keywords.
_EXTRA=e -> Picks up extra keywords for SMOOTH and
DIALOG_PICKFILE.
OUTPUTS:
See output keywords above.
SUBROUTINES:
REQUIREMENTS:
References many routines from GAMAP package. Requires GAMAP
v2.10 for handling 4D dataset.
NOTES:
If memory issues show up, try to save one timeseries (i.e.,
one station at a time).
EXAMPLES:
;; (1) Read multiple timeseries files selected w/ a pop-up
window (use SHIFT key for muliple selections). Save with the
default filename in the default directory:
GC_COMBINE_ND48
;; (2) Like example (1), but saves only the daily max of the
;; 9-hours average timeseries:
GC_COMBINE_ND48, /dmax, mavg=8
;; (3) read ALL stations files from directory '~/path/'
;; without a pop-up window (no interactivity, good for batch
;; processing). Default MASk and outfile name are used.
GC_COMBINE_ND48, indir='~/path/'
;; (4) Like example (3) but select only the first available
;; station, and save the result in a specified file:
GC_COMBINE_ND48, Station=1, indir='~/path/', outfile='~/path/series1.bpch'
;; (5) read files from directory '~/path/', and select 3rd station.
;; Do not save combined timeseries. Get outputs in variables
;; data, lon, lat and time.
GC_COMBINE_ND48, indir='~/path/', station=3, data=data, lon=lon, lat=lat, time=time
Help, reform(data)
PLOT, time, data[0,0,0,*], title='Lon= strtrim(lon,2)+'- Lat='+strtrim(lat,2)
;; (6) Like (5), but limit the time to 23rd-28th of July
;; 2001. Not the use of two commands to get the output
;; time vector.
time = [nymd2tau(20010723L,20010728l)]
GC_COMBINE_ND48, indir='~/path/', station=3, data=data, lon=lon, lat=lat, time=time
HELP, time
MODIFICATION HISTORY:
phs, 31 Jul 2007: GAMAP VERSION 2.10
- Initial version
phs, 11 Oct 2007: - few bugs fix
- added output keywords
phs, 15 Oct 2007: - added LOCALTIME keyword
phs, 18 Oct 2007: - do not save if output file is one of the
input file.
phs, 26 Oct 2007: - TIME can be use to select the time span
of the series.
Added DAVG keyword.
phs, 30 Oct 2007: - couple of minor fixes.
phs, 11 Aug 2009: - major fix: bug fix when same tracer
in several stations
bmy, 12 Mar 2009: GAMAP VERSION 2.14
- Typo at line 429 fixed
(See /n/home09/ryantosca/IDL/gamap2/timeseries/gc_combine_nd48.pro)
NAME:
GC_COMBINE_ND49
PURPOSE:
Combine timeseries data from several bpch files into 4D
data. Typically used with Geos-CHEM ND49 timeseries output
and met fields in bpch files (a3, a6, i6).
For met fields, see example (9) and (10).
Each ND49 and Met Fields file has data for one day. But,
files with time series that do no cover a day per file, can
also be processed. See example (11), but keep in mind that
the daily max or average options are then **** MEANINGLESS
****, and should not be used.
WHAT IS DONE:
(1) We combine all the data blocks for one tracer (there is
one per time step) into one single 4-D data block (with time
in 4th dimension). This takes advantage of support for 4D
dataset introduced in GAMAP v2-10.
(2) The combined series can be saved into a binary punch
file. You end up with one file per tracer that covers many
days of output, instead of one file per day for all
tracers. The space saving can be more than 60%.
(3) A subarea (even a single location) can be extracted. But
for multiple but not contiguous locations, call the routine
as many time as needed.
(4) Shorter timeseries can be selected/saved, by specifying
Tau range, or day (as YYYYMMDD long integer) range if daily
max or average is selected.
(5) Two basic signal processing before saving the data can be
performed: moving average and/or daily
maximum/minimum/average.
## LIMITATION ## : full days considered for ND49, ie,
GEOS-Chem runs should start and end at midnight (YYYYMMDD
000000 in input.geos)
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, Time Series
CALLING SEQUENCE:
GC_COMBINE_ND49 [, TRACER ][, CATEGORY ][, Keywords ]
INPUTS:
TRACER -> The tracer number. Default is 1.
CATEGORY -> The category name (default is "IJ-AVG-$")
for which to read data.
KEYWORD PARAMETERS:
;============ For I/O files/directory =====================
FILELIST -> list of files to process. Usually used as output
keyword to get the list of files selected with INDIR and
MASK or through a dialog window.
Can be used as input. Then INDIR and MASK are ignored.
INDIR -> Directory where to look for MASK files. If
provided, ALL files satisfying the MASK keyword in the
directory will be selected. If not provided, a dialog
window that allows multiple files selection (keep SHIFT
key down) will pop-up. See EXAMPLES below for tips.
If set to an undefined variable name, it will hold the
directory of the selected files (output keyword).
NOTE: If more than one file is processed, it is assumed
that, once sorted in alphabetical order, they are in
chronological order (this is the case with GEOS-Chem
default naming of ND49 output files: they contain
YYYYMMDD).
MASK -> Pattern Mask to find files in INDIR. Default is
"ts*.bpch".
OUTDIR -> Output directory where to save the file with the
new timeseries data set will be. Default is INDIR. If
the user has not write permission in INDIR, writintg is
cancelled.
OUTFILENAME -> Name of the file that will contain the
timeseries. Default is 'combts_%TRACERNAME%.bpch', for
COMB ined T ime S eries.
The routine prevents from overwriting any input file.
;============ To extract subset of data ===================
LON -> A one or two-elements vector specifying the longitude
of one location or one area. If LON is outside the ND49
area, the program print a warning, and uses border
value.
LAT -> same as LON, but for Latitudes
LEV -> same as LON, but for Levels. Refers to the model grid.
; - - you can also select indices into the requested 3D cube:
LLEV -> A one or two-element vector specifying the min and
max of available levels to be included in the file.
Default is ALL available levels.
Default FORTRAN indexing is used: LLEV #1 is the first
level ***requested*** in ND49. See LEV above otherwise.
ILON, JLAT -> same as LLEV but for Longitude and Latitude
indices. Starting at 1 at the first ***requested***
grid box in ND49.
TIME -> vector for selecting time span. The data covering
[min(TIME),max(TIME)] are selected. If only one
element, then the closest-in-time data are selected.
TIME must be given as Tau (double) or YYYYMMDD (long)
if /DMAX or /DAVG.
If both DMAX (or DAVG) and LOCALTIME are set, TIME is
ignored.
** TIP ** if you select a short time span, it may be
useful to limit the number of files to process
by redefining MASK or using FILELIST. That will
speed up the process.
;================= Signal Processing ======================
MAVG -> to apply a running average filter to the series. MAVG
value will define the boxcar size and must be GE
3. Even numbers are increased by +1. The IDL SMOOTH
routine is called and accept _extra keywords (NaN,
Edge_truncate, missing).
DMAX -> to select the daily maxima of the time series. If
both MAVG and Dmax are set, the moving average is
performed first and you get the daily max of the moving
average.
DAVG -> to select the daily average of the time series. If
both MAVG and DAVG are set, the moving average is
performed first and you get the daily average of the
moving average.
LOCALTIME -> to get DAVG or DMAX computed over local days
instead of UT days. See details below.
;================= Output keywords ========================
DATA -> set to a variable name that will hold the selected
timeseries data on exit. This is a 4D array
(nLon, nLat, nLevel, ntime) even if only one location is
selected.
OUTLON -> set to a variable name that will hold the vector
of longitudes of the data set on exit.
OUTLAT -> set to a variable name that will hold the vector
of latitudes of the data set on exit.
OUTLEV -> set to a variable name that will hold the vector
of Levels of the data set on exit.
OUTALT -> set to a variable name that will hold the vector
of altitudes for the data set on exit.
OUTTIME -> set to a variable name that will hold the time
vector corresponding to the data set on exit. Format
is Tau, or YYYYMMDD if /DMAX.
LOCALTIME -> if set, OUTTIME becomes a Nb_OutLon X Nb_TimeStep
array, with each vector OUTTIME[i,*] holding the time
vector in local time instead of UT. That vector will
apply to all j and k for DATA[i,j,k,*].
Specific case of... both DMAX (or DAVG) and LOCALTIME
being set. The daily max (average) is obtained after
shifting the timeseries, so they start at 00 LT
everywhere (or the first available time step just before
00 LT). The first max (average) value is for the first
complete local day of the series. The OUTTIME array is
then a [numbers of complete days, 2] array that gives
the local YYYYMMDD for both positive and negative
longitudes.
See also note about TAU0/TAU1 below.
Note that the time step of the series must be small
enough for the DMAX/DAVG w/r/t Local Time to be
reliable.
;================= Others ========================
NOSAVE -> set to not save output into a BPCH file. Useful if
you just want to check results with output keywords.
VERBOSE -> Set to print informational message about the time
series. Particularly useful to double check the
area/location selected with subset keywords.
_EXTRA=e -> Picks up extra keywords for SMOOTH and
DIALOG_PICKFILE.
OUTPUTS:
See output keywords above.
SUBROUTINES:
REQUIREMENTS:
References many routines from GAMAP package. Requires GAMAP
v2.10 for saving 4D dataset into binary punch file.
NOTES:
######## ND49 and Met Fields only. For ND48, see ########
######## GC_COMBINE_ND48 (not as well maintained) ########
Written with batch processing in mind. It is recommended to
save all ND49 outputs into one dedicated directory, and to
use keywords (INDIR, OUTDIR, OUTFILE..) and save the new
combined timeseries in a new directory.
About TAU0 and TAU1 : in the DataInfo structure, they are set
to the beginning and end of the timeseries. For daily data,
we compute them by setting HH:MM:SS to 00:00:00. If LocalTime
is set, UT is still used for TAU0 and TAU1, so we can use
only one value. If both LocalTime and DMAX are set, tau0 and
tau1 give the first and last (local) days for longitudes less
than 0 (west). For East longitudes, you need to add one day
to these to get the correct date.
EXAMPLES:
;; In the following examples, it is assumed that tracer 1
;; has been saved with ND49
;; (1) Read multiple timeseries files selected w/ a pop-up
window (use SHIFT key for muliple selections). Saved series
at ALL available locations into default directory and filename:
GC_COMBINE_ND49
exactly the same as:
GC_COMBINE_ND49, 1, 'IJ-AVG-$'
;; (2) Like example (1), but saves only the daily max of the
;; 9-hours average timeseries:
GC_COMBINE_ND49, 1, 'IJ-AVG-$', /dmax, mavg=8
;; (3) Like example (1), but do not save the timeseries. Get
;; the timeseries in the variable TS in output:
GC_COMBINE_ND49, 1, 'IJ-AVG-$', /nosave, data=TS
;; (4) read **ALL** MASK-files from directory '~/path/'
;; without a pop-up window (no interactivity, good for batch
;; processing):
GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='series1.dat'
;; (5) Like example (4), but with selection of ONE station:
GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='station1.bpch',$
lon=-65., lat=45., lev=1
;; (6) Like example (5), but with shorter time series (from
;; 2001/7/20 20:00 to 2001/7/23 2:00):
GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='station1.bpch',$
lon=-65., lat=45., lev=1, $
Time=[nymd2tau(20010720l,200000l),nymd2tau(20010723l,20000l)]
;; (7) Like example (6), but select Daily Max and for few
;; days only (from 23rd to 28th of July 2001):
GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='station1.bpch',$
lon=-65., lat=45., lev=1, /DMax,
Time=[20010723L,20010728L]
;; (8) read **ALL** MASK-files from a directory selected with
;; a pop-up window:
GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir=dialog_pickfile(/dir)
;; (9) read CLOUD FRACTION from GEOS-4 met fields. Interactive way.
GC_COMBINE_ND49, nosave=1, data=ts, $
mask='/as/data/master/ctm/GEOS_4x5.d/GEOS_4_v4/1985/02/*a6*', $
7, 'GMAO-2d', outtime=time
;; (10) read CLOUD FRACTION from GEOS-4 met fields. All data
from February 1985 automatically:
GC_COMBINE_ND49, nosave=1, data=ts, $
indir='/as/data/master/ctm/GEOS_4x5.d/GEOS_4_v4/1985/02/', $
mask='*a6*', $
7, 'GMAO-2d', outtime=time
;; (11) Read 3 series of 2004 GFED2 emissions (3hr, 8-day and
monthly):
; -- get data from MASK and DIRECTORY
dir3hr = '/as/data/geos/GEOS_1x1/GFED2_3hr_200901/2004/'
dirMon = '/as/data/geos/GEOS_1x1/GFED2_200601/2004/'
dir8day = '/as/data/geos/GEOS_1x1/GFED2_8day_200712/2004/'
mask3hr = 'GFED2.3hr.C_20040*.generic.1x1'
maskMon = 'GFED2_C_2004*.generic.1x1'
mask8day = 'GFED2_8day_C_2004*.generic.1x1'
gc_combine_nd49, 99, 'GFED2-BB', /nosave, data=d3hr, $
mask=mask3hr, indir=dir3hr, outTime=tau3hr, /verb
gc_combine_nd49, 99, 'GFED2-BB', /nosave, data=d8day, $
mask=mask8day, indir=dir8day, outTime=tau8day, /verb
gc_combine_nd49, 99, 'GFED2-BB', /nosave, data=dMon, $
mask=maskMon, indir=dirMon, outTime=tauMon, /verb
;-- Julian Time for each data set (the half time step is added to
; get the time series centered on their period, since we plot
; histograms, with psym=10)
temp = tau2yymmdd( tau3hr + 1.5 )
Jul3hr = JulDay(temp.month, temp.day, temp.year, temp.hour, temp.minute)
temp = tau2yymmdd( tau8day + (4.*24.) )
Jul8day = JulDay(temp.month, temp.day, temp.year, temp.hour, temp.minute)
temp = tau2yymmdd(tauMon + 15.*24.)
JulMon = JulDay(temp.month, temp.day, temp.year, temp.hour, temp.minute)
; -- convert from [g C/m2/time-period] to [Tg C/time-period]
GridInfo = CTM_GRID( CTM_TYPE( 'generic', res=[1., 1.] ) )
Surface = CTM_BOXSIZE( GridInfo, /cm2 )
dim = size(surface, /dimensions)
d3hr = d3hr * rebin( Surface, dim[0], dim[1], 1, (size(d3hr))[4] )
d8day = d8day * rebin( Surface, dim[0], dim[1], 1, (size(d8day))[4] )
dMon = dMon * rebin( Surface, dim[0], dim[1], 1, (size(dMon))[4] )
d3hr = d3hr * 1e-9
d8day = d8day * 1e-9
dMon = dMon * 1e-9
; -- Sum data over space, and convert to [ Tg C/s ]
sum3hr = total( total( total(d3hr, 1), 1), 1) / (3. * 3600.)
sum8day = total( total( total(d8day, 1), 1), 1) / (8. *24. * 3600.)
; -- Plot time series
dummy = label_date( date_format=['%D', '%M'] )
plot, Jul3hr, sum3hr, /ynozero, color=!myct.black, $
title='Total GFED2 emissions in 2004 (Tg C/sec)', $
/xstyle, $
xtickformat=['label_date', 'label_date', 'label_date'], $
xtickunit=['day', 'month'], $
position=[0.1, 0.15, 0.9, 0.9], $
psym=10
oplot, Jul8day, sum8day, thick=2., color=!myct.black, psym=10
MODIFICATION HISTORY:
phs, 6 Jun 2007: GAMAP VERSION 2.05
- Initial version
phs, 25 Jul 2007: GAMAP VERSION 2.10
- added Moving Average and Daily Max as
signal processing available before
saving/passing data.
- added Lon and Lat keywords to select one
location or a smaller area.
- added output keywords.
phs, 4 Oct 2007: - Bug fix for OUTTIME keyword
phs, 12 Oct 2007: - Added OUTLEV output keyword, and LEV
input keyword.
- INDIR can be used as output keyword.
phs, 15 Oct 2007: - added LOCALTIME keyword
phs, 18 Oct 2007: - do not save if output file is one of the
input file.
phs, 26 Oct 2007: - bug fix for LON and LAT
- added TIME keyword to limit
timeseries in time.
phs, 28 Oct 2007: - DMAX accounts for LOCALTIME if set.
- Bug fix for OutTime when /DMax.
phs, 04 Apr 2008: GAMAP VERSION 2.12
- added DAVG keyword
- now cleanup the /no_global pointers
- added the FILELIST keyword
phs, 17 Jul 2008: - Added comments
phs, 15 Aug 2008: GAMAP VERSION 2.13
- Bug fix for OutTime when /DMax or /DMean
and input are from at least two different
months
mb & phs, 02 Dec 2008: - DIM is forced to 32-bit integer (LONG)
phs, 08 Jan 2009: - Now can process files that cover time
periods different from one day.
bmy, 14 Apr 2010: GAMAP VERSION 2.14
- Add _EXTRA=e to CTM_GET_DATA so as to pass
down any flags for nested grids
(See /n/home09/ryantosca/IDL/gamap2/timeseries/gc_combine_nd49.pro)
NAME:
GETDATABLOCK
PURPOSE:
Retrieve information stored in a DATA block somewhere
within an IDL routine. The DATA block must be "hidden"
as comment lines for the IDL compiler. The data will be
returned as string array.
CATEGORY:
General
CALLING SEQUENCE:
GETDATABLOCK, DATA [, FILENAME=FILENAME, ,LABEL=LABEL ]
INPUTS:
KEYWORD PARAMETERS:
FILENAME -> optional filename. Normally, the data block is
read from the file that contains the current procedure
LABEL -> a unique identifier for the start of the data block.
Default is '/DATA/'. The end of the data block is reached
at the end of file or if the block of comment lines ends.
OUTPUTS:
DATA -> a string array with the information contained in the
data block
SUBROUTINES:
External Subroutines Required:
======================================
FILE_EXIST (function) ROUTINE_NAME
REQUIREMENTS:
None
NOTES:
The file with the datablock is always searched in !PATH
EXAMPLE:
GETDATABLOCK, SDATA
; This will retrieve a data block labeled '/DATA/'
; from the file of the current IDL routine
MODIFICATION HISTORY:
mgs, 22 Apr 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/general/getdatablock.pro)
NAME:
GETETA
PURPOSE:
Defines the eta levels for the various hybrid model grids.
GETETA is called by function CTM_GRID.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
RESULT = GETETA( MNAME [, NLAYERS [, Keywords ] ] )
INPUTS:
MNAME -> The name of the model for which eta level
information is desired ('GEOS4' or 'GEOS4_30L').
NLAYERS -> Specifies the number of eta layers for the
model type. Default is 55 layers.
KEYWORD PARAMETERS:
PSURF -> Surface pressure in hPa. If PSURF is not specified,
GETETA will use 1013.25 hPa (e.g. 1 atmosphere).
/CENTERS -> Returns to the calling program an array
containing the eta coordinate at grid box centers.
/EDGES -> Returns to the calling program an array
containing the eta coordinate at grid box edges.
A -> Returns to the calling program the "A" vector of
values that define the hybrid grid. A has units of
[hPa].
B -> Returns to the calling program the "B" vector of
values that define the hybrid grid. B is unitless.
PRESSURE -> Returns the pressure [hPa] at the grid box edges
(if /EDGES is set) or the pressure at the grid box centers
(if /CENTERS is set).
OUTPUTS:
RESULT -> contains the array of eta edges (if /EDGES is
set), or eta centers (if /CENTERS is set).
SUBROUTINES:
None
REQUIREMENTS:
Called by CTM_GRID.PRO
NOTES:
Supported models:
-----------------------------------------------------------
(1 ) GCAP, 23-layer (name: "GCAP" )
(2 ) GEOS-4, 55-layer (name: "GEOS4" )
(3 ) GEOS-4 30-layer (name: "GEOS4_30L" )
(4 ) GEOS-5, 72-layer (name: "GEOS5" )
(5 ) GEOS-5 47-layer (name: "GEOS5_47L" )
(6 ) GEOS-FP 72-layer (name: "GEOSFP" )
(7 ) GEOS-FP 47-layer (name: "GEOSFP_47L" )
(8 ) MERRA, 72-layer (name: "MERRA" )
(9 ) MERRA 47-layer (name: "MERRA_47L" )
(10) MERRA2, 72-layer (name: "MERRA2" )
(11) MERRA2, 47-layer (name: "MERRA2_47L" )
(12) GISS_II_PRIME 23-layer (name: "GISS_II_PRIME")
(13) MATCH 52-layer (name: "MATCH" )
Computing pressure and eta coordinates:
-----------------------------------------------------------
In a vertical column, the pressure at the bottom edge of
grid box (L) is given by:
Pe(L) = A(L) + ( B(L) * Psurface )
and the pressure at the vertical midpoint of grid box (L)
is just a simple average of the pressures at the box edges:
Pc(L) = ( Pe(L) + Pe(L+1) ) * 0.5
From PEDGE and PCENTER, we can construct the unitless coordinate
ETA (which is very similar to the sigma coordinate) as follows:
ETAe(L) = ( Pe(L) - Ptop ) / ( Psurface - Ptop )
ETAc(L) = ( Pc(L) - Ptop ) / ( Psurface - Ptop )
For GAMAP plotting routines, we will use the ETA coordinate
for hybrid models instead of the sigma coordinate.
Psurface is a function of longitude and latitude. GAMAP uses
a default Psurface of 1013 hPa (1 atm). However, you should
always compute the pressure edges and centers from an accurate
surface pressure field (i.e. from met field data files or from
GEOS-Chem or other model output.
EXAMPLE:
EETA = GETETA( 'GEOS4' PSURF=984.0, /EDGES );
; assigns GEOS-1 eta edges to array EETA
CETA = GETETA( 'GEOS4', /CENTERS, PRESSURE=CPRESS )
; assigns GISS-II eta centers to array CETA
; (Optional) also returns the pressure at level centers
MODIFICATION HISTORY:
bmy, 06 Nov 2001: GAMAP VERSION 1.49
- based on routine "getsigma.pro"
bmy, 04 Nov 2003: GAMAP VERSION 2.01
- now supports "GEOS4_30L" grid
- now tests for model name using STRPOS
instead of just a straight match
- stop w/ an error for non-hybrid grids
- now supports 23-layer GISS_II_PRIME model
- now supports 52-layer MATCH model
bmy, 18 Jun 2004: GAMAP VERSION 2.02a
- now supports GCAP 23-layer hybrid grid
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
bmy, 15 Oct 2009: GAMAP VERSION 2.13
- Now supports GEOS-5 grids
bmy, 29 Nov 2010: GAMAP VERSION 2.15
- Now returns hybrid-grid A and B
values via the A & B keywords
- Now returns the pressure corresponding
to ETA via the PRESSURE keyword
- Renamed /CENTER to /CENTERS
(See /n/home09/ryantosca/IDL/gamap2/internals/geteta.pro)
NAME:
GETMODELANDGRIDINFO
PURPOSE:
Given a DATAINFO structure, returns the corresponding
MODELINFO and GRIDINFO structures.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids, Structures
CALLING SEQUENCE:
CTM_GETMODELANDGRIDINFO, THISDATAINFO, MODELINFO, GRIDINFO
INPUTS:
THISDATAINFO -> A single of DATAINFO structure which
contains the following fields:
** Structure H3DSTRU, 13 tags, length=72:
ILUN LONG
FILEPOS LONG
CATEGORY STRING
TRACER INT
TRACERNAME STRING
TAU0 DOUBLE
TAU1 DOUBLE
SCALE FLOAT
UNIT STRING
FORMAT STRING
STATUS INT
DIM INT
OFFSET INT
DATA POINTER
KEYWORD PARAMETERS:
LON -> set to a variable that will hold the longitude
centers of the data set. Grid Offsets of data that
do not cover the globe are accounted for.
LAT -> same as LON, but for Latitude centers.
LEVEL -> same as LON, but holds levels indices, starting at 1.
OUTPUTS:
MODELINFO -> Returns to the calling program the model
information structure (see "ctm_type.pro") which
corresponds to THISDATAINFO.
GRIDINFO -> Returns to the calling program the grid
information structure (see "ctm_grid.pro") which
corresponds to THISDATAINFO.
SUBROUTINES:
External Subroutines Required:
==============================
GAMAP_CMN (include file)
CTM_GRID (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; Read data from "myfile.bpch"
; DATAINFO is an array of structures
CTM_GET_DATA, DATAINFO, FILE='myfile.bpch'
; Loop over all data blocks in the file
FOR D = 0L, N_ELEMENTS( DATAINFO )-1L DO BEGIN
; Pick the DATAINFO structure for the Dth data block
THISDATAINFO = DATAINFO[D].DATA
; Get MODELINFO and GRIDINFO structures for the Dth data block
GETMODELANDGRIDINFO, THISDATAINFO, MODELINFO, GRIDINFO
...
ENDFOR
MODIFICATION HISTORY:
bmy, 24 Apr 2002: GAMAP VERSION 1.50
bmy, 28 Jun 2006: GAMAP VERSION 2.05
- Bug fix for multi-level GENERIC grids
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 13 May 2008: GAMAP VERSION 2.12
- Added LON and LAT keyword to return data
(not global grid) longitude and latitude centers.
phs, 8 Oct 2008: GAMAP VERSION 2.13
- Added LEVEL keyword to return levels.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/getmodelandgridinfo.pro)
NAME:
GETSIGMA (function)
PURPOSE:
Defines the sigma levels for the various grids.
GETSIGMA is called by function CTM_GRID.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
RESULT = GETSIGMA( MNAME [ NLAYERS [ , keywords ] ] )
INPUTS:
MNAME -> The name of the model for which sigma level
information is desired (e.g. 'geos1', 'giss_ii', etc.)
NLAYERS -> Specifies the number of sigma layers for the
GISS family of models. Default is 9 layers.
KEYWORD PARAMETERS:
CENTER -> Returns to the calling program an array
containing the sigma centers.
EDGES -> Returns to the calling program an array
containing the sigma edges.
/HELP -> Prints a help screen and returns a value
of -1 to the calling program.
OUTPUTS:
RESULT contains the array of sigma edges (if /EDGES is
set), or sigma centers (if /CENTERS is set).
SUBROUTINES:
REQUIREMENTS:
NOTES:
Supported models:
-------------------------------------------------------
(1 ) GEOS-1 20-layer (6 ) GEOS-3 30-layer
(2 ) GEOS-STRAT 46-layer (7 ) GISS-II 9-layer
(3 ) GEOS-STRAT 26-layer (8 ) GISS-II-PRIME 9-layer
(4 ) GEOS-2 70-layer (9 ) GISS-II-PRIME 23-layer
(5 ) GEOS-2 47-layer (10) FSU 14-layer
(6 ) GEOS-3 48-layer (11) MOPITT 7-layer
You can add more grids as is necessary.
EXAMPLE:
ESIG = GETSIGMA( 'GEOS1' /EDGES );
; assigns GEOS-1 sigma edges to array ESIG
CSIG = GETSIGMA( 'GISS_II', 9, /CENTERS )
; assigns GISS-II sigma centers (9 layer model) to array CSIG
MODIFICATION HISTORY:
mgs, 02 Mar 1998: VERSION 1.00
bmy, 19 Jun 1998: - added dummy FSU sigma edges and centers
- brought comments up to date
bmy, 16 Oct 1998: - added 26 layer GEOS-STRAT sigma levels
mgs, 25 Nov 1998: - improved defaulting of NLayers
bmy, 24 Feb 1999: - updated FSU sigma centers & edges
with values provided by Amanda Staudt
bmy, 27 Jul 1999: GAMAP VERSION 1.42
- added GISS-II-PRIME 23-layer sigma levels
- updated comments, cosmetic changes
bmy, 16 May 2000: GAMAP VERSION 1.45
- added GEOS-2 grids (47 and 70 layers)
bmy, 19 Jun 2000: - added GEOS-2 36 pressure-layer grid
bmy, 26 Jul 2000: GAMAP VERSION 1.46
- added GEOS-3 grid (48 layers)
bmy, 26 Jul 2001: GAMAP VERSION 1.48
- added GEOS-3 grid (30 layers, regridded)
bmy, 18 Dec 2003: GAMAP VERSION 2.01
- Now recognizes GEOS3_30L grid name
- Now sets 30 layers as default for GEOS3_30L
- Removed HELP keyword, you can use usage.pro
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/getsigma.pro)
NAME:
GET_CHARSIZE_NORM
PURPOSE:
Returns the size in normal coordinates of an average
character. The function accounts for !P.MULTI, !P.CHARSIZE,
and the charsize scaling you pass to a plotting routine with
the CHARSIZE keyword.
CATEGORY:
Plotting, Strings
CALLING SEQUENCE:
RESULT = GET_CHARSIZE_NORM( CHARSIZE [, Keywords ] )
INPUTS:
CHARSIZE -> A N-elements vector that gives the character
size, in character unit: 1.0 is normal size, 2.0 is
double size, etc. Default is 1.0.
KEYWORD PARAMETERS:
/DEVICE -> Set this switch to compute the average character
size in device units (which is usually pixel) instead of
the default normal coordinates.
OUTPUTS:
A N-by-2 array that gives average character size in
normal coordinates:
RESULT[*,0] are along the X direction,
RESULT[*,1] are along the Y direction.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
PRINT, GET_CHARSIZE_NORM
0.00878049 0.0168750
PRINT, GET_CHARSIZE_NORM( /DEVICE )
7.20000 10.8000
MULTIPANEL, 6
PRINT, GET_CHARSIZE_NORM( [1, 2, 3.5 ], /DEVICE )
3.60000 7.20000 12.6000 ; => X sizes in pixel
5.40000 10.8000 18.9000 ; => Y sizes in pixel
MODIFICATION HISTORY:
phs, 3 Dec 2007: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/plotting/get_charsize_norm.pro)
NAME:
GET_CONC_RANGE
PURPOSE:
Returns a default plotting range for given GEOS-Chem tracers
This will be used to create concentration plots for GEOS-Chem
benchmarking.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
GET_CONC_RANGE, TRACERNAME, THIS_RANGE, THIS_UNIT
INPUTS:
TRACERNAME -> Name of the tracer for which a default
plotting range will be returned.
KEYWORD PARAMETERS:
None
OUTPUTS:
THIS_RANGE -> A 2 element vector with the [min,max] values
to be used in creating a tracer difference plot.
THIS_UNIT -> String with the units of the data.
SUBROUTINES:
None
REQUIREMENTS:
Routine READ_CONC_RANGE must be called before this routine
may be used. This will normally be done at the top of
driver routine BENCHMARK_1YR.
NOTES:
(1) Meant to be used in conjunction with the GEOS-Chem
benchmark plotting codes.
(2) Default ranges for each tracer are read from a file by the
complementary routine READ_DIFF_RANGE and stored in the
GDR common block.
EXAMPLE:
READ_CONC_RANGE, 'conc_range.1mon'
GET_CONC_RANGE, 'NOx', THIS_LOBOUND, THIS_HIBOUND, THIS_UNIT
PRINT, THIS_LOBOUND, THIS_HIBOUND
0.50000 2.00000
PRINT, THIS_UNIT
ppbv
; Prints the default plotting range and unit for NOx
MODIFICATION HISTORY:
bmy, 05 Sep 2012: VERSION 1.00
bmy, 24 Jan 2014: GAMAP VERSION 2.17
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/benchmark/get_conc_range.pro)
NAME:
GET_DEFAULTFORMAT (function)
PURPOSE:
Return format string that will produce legible and
concise strings for a given value range. The format
should be applied in a string() statement and the
string should be trimmed.
CATEGORY:
Strings
CALLING SEQUENCE:
MYFORMAT = GET_DEFAULTFORMAT(minval,maxval [,/LOG])
INPUTS:
MINVAL, MAXVAL -> the range of values that shall be
displayed with this format.
KEYWORD PARAMETERS:
/LOG -> set this keyword if you plan logarithmic labels.
(changes behaviour for 0.001)
DEFAULTLEN -> 1 or 2 strings with the default length
specification for 'f' and 'e' formats. If only one
string is passed, it will be used for both, otherwise
the first string applies to 'f' and the second to 'e'.
Example: DEFAULTLEN='10.3' results in 'f10.3'.
THRESHOLD -> threshold value to switch from 'f' to 'e' format.
Default is '2' for linear and '3' for log scale. This
value is determined by the negative decadal log of (maxv-minv)
plus 2.
OUTPUTS:
MYFORMAT -> A format string (e.g. '(f14.2)' )
SUBROUTINES:
none
REQUIREMENTS:
none
NOTES:
None
EXAMPLE:
PRINT, GET_DEFAULTFORMAT( 0.01, 1. )
'(f14.2)'
PRINT, GET_DEFAULTFORMAT( 0.0001, 0.01 )
'(e12.3)'
MODIFICATION HISTORY:
mgs, 17 Mar 1999: VERSION 1.00
mgs, 25 Mar 1999: - added DEFAULTLEN keyword
mgs, 19 May 1999: - DEFAULTLEN now converted to string.
- added THRESHOLD keyword
bmy, 27 Sep 2002: TOOLS VERSION 1.51
- made default exponential format e12.2
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/get_defaultformat.pro)
NAME:
GET_DIFF_RANGE
PURPOSE:
Returns a default plotting range for given GEOS-Chem tracers
This will be used to create absolute difference plots for
GEOS-Chem benchmarking.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
RANGE = GET_DIFF_RANGE( TRACERNAME )
INPUTS:
TRACERNAME -> Name of the tracer for which a default
plotting range will be returned.
KEYWORD PARAMETERS:
None
OUTPUTS:
RANGE -> A 2 element vector with the [min,max] values
to be used in creating a tracer difference plot.
SUBROUTINES:
None
REQUIREMENTS:
Routine READ_DIFF_RANGE must be called before this routine
may be used. This will normally be done at the top of
driver routine BENCHMARK_1MON.
NOTES:
(1) Meant to be used in conjunction with the GEOS-Chem
benchmark plotting codes.
(2) Default ranges for each tracer are read from a file by the
complementary routine READ_DIFF_RANGE and stored in the
GDR common block.
EXAMPLE:
READ_DIFF_RANGE, 'diff_range.1mon'
PRINT, GET_DIFF_RANGE( 'NOx' )
-0.100000 0.100000
; Prints the default plotting range for NOx
MODIFICATION HISTORY:
bmy, 14 Nov 2007: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/benchmark/get_diff_range.pro)
NAME:
GET_FREELUN (function)
PURPOSE:
Return next available logical unit number. Unlike
the internal GET_LUN procedure, this function is not
restricted to unit numbers above 100, and it will
detect any blocked unit number.
CATEGORY:
File & I/O
CALLING SEQUENCE:
lun = GET_FREELUN([LUN])
INPUTS:
none
KEYWORD PARAMETERS:
none
OUTPUTS:
The lowest available logical unit number. This number is
also returned in the LUN parameter for later use.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
OPENW, GET_FREELUN( LUN ), FILENAME
; Open a file and get the next free unit number.
MODIFICATION HISTORY:
mgs, 17 Sep 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/file_io/get_freelun.pro)
NAME:
GET_GEOS5_PRESS
PURPOSE:
Returns zonal mean pressure edges and pressure centers
for the GEOS-5 grid (47 layers or 72 layers). Because in
GEOS-5 we cannot compute the pressures at grid box edges
and centers, we must read them in from disk.
CATEGORY:
GAMAP Internals, GAMAP Models & Grids
CALLING SEQUENCE:
GET_GEOS5_PRESS, PEDGE, PMID [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
FILENAME -> Specifies the name of the file containing
average pressures on the GEOS-5 grid. If FILENAME
is omitted, then GET_GEOS5_PRESS will use the default
filename: "pedge.geos5.{RESOLUTION}.year".
NLAYERS -> Specifies the number of layers in the GEOS-5
grid. NLAYERS can be either 47 or 72. Default is 47.
RESOLUTION -> Specifies the resolution of the GEOS-5 grid.
Default is 4x5.
PSURF -> If specified, then PEDGE and PMID will be 1-D
vectors, with the surface pressure (i.e. PEDGE[0])
being closest to the passed value of PSURF.
/VERBOSE -> Set this switch to toggle verbose output.
OUTPUTS:
PEDGE -> Array (or vector if PSURF is specified) of pressures
at GEOS-5 grid box edges. The PEDGE values have been
averaged over 12 months and also averaged over longitudes
(i.e. zonal mean).
PMID -> Array (or vector if PSURF is specified) of pressures
at GEOS-5 grid box centers. The pressures have been
averaged over 12 months and also averaged over longitudes
(i.e. zonal mean).
SUBROUTINES:
External Subroutines Required:
===================================
CTM_GET_DATA CTM_TYPE (function)
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) At present, we only have saved out a file containing
pressure edges from the GEOS-5 47-layer model.
EXAMPLE:
(1)
GET_GEOS5_PRESS, PEDGE, PMID, RES=2
; Returns pressues at grid box edges (PEDGE) and centers
; (PMID) for the GEOS-5 47L model at 2 x 2.5 resolution.
; PEDGE is a 2-D array of size 91x48. PMID is also a
; 2-D array of size 91x47.
(2)
GET_GEOS5_PRESS, PEDGE, PMID, RES=2, PSURF=1000.0
; Returns pressues at grid box edges (PEDGE) and centers
; (PMID) for the GEOS-5 47L model at 2 x 2.5 resolution.
; for the column with the closest surface pressure to
; PSURF=1000 hPa. PEDGE is a 1-D vector w/ 48 elements.
; PMID is also a 1-D vector w/ 47 elements.
MODIFICATION HISTORY:
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
phs, 25 Feb 2008: - check on File_Which output
dbm & ccc, 15 Dec 2009: GAMAP VERSION 2.14
- Make sure PSURF is a scalar
(See /n/home09/ryantosca/IDL/gamap2/internals/get_geos5_press.pro)
NAME:
GET_IS_EDGED (function)
PURPOSE:
Determine if a GEOS-5 data field is defined on the
vertical grid box edges or centers.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
RESULT = GET_IS_EDGED( NAME )
INPUTS:
NAME -> Name of the tracer or met field to be tested.
KEYWORD PARAMETERS:
OUTPUTS:
RESULT -> Returns 1 if the tracer or met field specified by
NAME is defined on grid box vertical edges, or 0
otherwise.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
(1) This is currently a KLUDGE. Figure out a more
robust way of determining if fields are defined on
level edges or level centers later on. (bmy, 7/16/07)
(2) Add more names to the CASE statement as necessary.
EXAMPLES:
(1)
PRINT, GET_IS_EDGED( 'PEDGE' )
1
; The GEOS-5 PEDGE field is defined on the vertical
; grid edges, so GET_IS_EDGED returns 1.
(2)
PRINT, GET_IS_EDGED( 'UWND' )
0
; The GEOS-5 UWND field is defined on the vertical
; grid centers, so GET_IS_EDGED returns 0.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/get_is_edged.pro)
NAME:
GET_RANGE
PURPOSE:
Enter the data range into a variable descriptor array
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
GET_RANGE,data,vardesc [,minvalid]
INPUTS:
DATA -> The data array (NLINES, NVARS)
VARDESC -> The variable descriptor array (see GTE_VARDESC).
Must contain NVARS elements, and a 2-element vector
tagged RANGE. These values will be changed.
MINVALID -> minimum valid data value to discriminate against
missing values etc. Default is -1.0E30.
KEYWORD PARAMETERS:
none
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required
===============================
GTE_VARDESC (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; read binary data and retrieve range
READ_BDT0001, '~/tmp/*.bdt', DATA, VARDESC
GET_RANGE, DATA, VARDESC
MODIFICATION HISTORY:
mgs, 24 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/get_range.pro)
NAME:
GIF2PS
PURPOSE:
Translates GIF images to PostScript format.
CATEGORY:
Graphics
CALLING SEQUENCE:
GIF2PS [, FILENAME [, Keywords ] ]
INPUTS:
FILENAME (optional) -> Name of the input GIF file.
If FILENAME is omitted then GIF2PS will prompt
the user to supply a file name via a dialog box.
FILENAME may contain wild card characters.
KEYWORD PARAMETERS:
OUTFILENAME -> Name of the output PostScript file.
Default is "idl.ps".
/FLIP_BW -> Set this keyword to turn black pixels into
white pixels and vice-versa. This is useful for
creating PostScript files of GIF images that have a
dark background color.
XOFFSET, YOFFSET (optional) -> Set these keywords to specify
the X and Y Margins in inches. Defaults are
XMARGIN = 0.5 inches and YMARGIN = 0.5 inches.
_EXTRA=e -> Picks up extra keywords for OPEN_DEVICE,
TVIMAGE, and CLOSE_DEVICE.
OUTPUTS:
Sends output to a PostScript file, whose name is given
by the OUTFILENAME keyword.
SUBROUTINES:
External Subroutines Required:
==============================
EXTRACT_FILEPATH (function)
DIALOG_PICKFILE (function)
TVIMAGE
REQUIREMENTS:
None
NOTES:
(1) Image processing options are limited to flipping the
black and white pixels. This should be good enough
for most purposes.
(2) XMARGIN and YMARGIN assume that we are printing out for
standard USA 8.5 x 11" page. Device sizes listed below
are also in inches.
EXAMPLE:
(1)
GIF2PS, 'my_gif.gif', OUTFILENAME='my_ps.ps'
; Translates the image in "my_gif.gif" to
; the PostScript file "my_ps.ps".
(2)
GIF2PS, 'my_gif.gif', OUTFILENAME='my_ps.ps', /FLIP_BW
; Same as in (1), but also changes all black
; pixels to white and vice-versa.
(3)
GIF2PS, 'my_gif.gif', OUTFILENAME='my_ps.ps', /FLIP_BW, $
XMARGIN=0.5, YMARGIN=0.5
; Same as in (2), but also will "pad" the image with
; 0.5" of white space around each side.
MODIFICATION HISTORY:
bmy, 28 Jan 2000: VERSION 1.45
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/graphics/gif2ps.pro)
NAME:
HCOLORBAR
PURPOSE:
Plot a horizontal colorbar.
%%% NOTE: This is obsolete, you should use COLORBAR instead! %%%
CATEGORY:
Color
CALLING SEQUENCE:
HCOLORBAR, CX, CY, [,keywords]
INPUTS:
CX -> [Min X, Max X] vector in NORMAL coords
CY -> [Min Y, Max Y] vector in NORMAL coords
KEYWORD PARAMETERS:
COLORS -> array of color levels
LABELS -> string array of labels for the color levels
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
HCOLORBAR assumes n_elements(COLORS) >= n_elements(LABELS)+1
NOTES:
(1) HCOLORBAR is more or less obsolete. You should use
the COLORBAR routine instead. However, there may be
some applications where HCOLORBAR is required, so we
keep this routine for backwards compatibility with
older IDL code.
(2) The colorbar will be plotted as follows:
LABELS(0) LABELS(1) LABELS(NL-1)
+-----------+-----------+----------- // --------------+------------+
| COLORS(0) | COLORS(1) | COLORS(2) // COLORS(NL-1) | COLORS(NL) |
+-----------+-----------+----------- // --------------+------------+
COLORS(0) = color index for data < first contour level
COLORS(1) = color index for data between 1st and 2nd levels
...
COLORS(NL) = color index for data >= the last contour level
LABELS(0) = label for the first contour level
LABELS(1) = label for the 2nd contour level, etc...
...
LABELS(NL) = label for data >= the last contour level
EXAMPLE:
HCOLORBAR, [0.025, 0.275], [0.680, 0.690], $
COLORS=[0,1,2,3,4,5], LABELS=['1','2','3','4','5']
MODIFICATION HISTORY:
bmy, 10 Nov 1994: VERSION 1.00
bmy, 24 Jun 1997: VERSION 1.01
bmy, 30 Sep 1997: TOOLS VERSION 1.10
bmy, 20 Nov 1997: TOOLS VERSION 1.11
bmy, 02 Aug 1999: TOOLS VERSION 1.43
- minor bug fix
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/color/hcolorbar.pro)
NAME:
HDF_GETSD
PURPOSE:
Convenience routine to read scientific dataset variables
from Hierarchical Data Format (HDF) files
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
DATA = HDF_GETSD( FID, NAME [, _EXTRA=e ] )
INPUTS:
FID -> HDF File ID, as returned by routine HDF_SD_START.
NAME -> Name of the scientific dataset variable that
you want to extract from the file.
KEYWORD PARAMETERS:
_EXTRA=e -> Passes extra keywords to routine HDF_SD_GETDATA.
OUTPUTS:
DATA -> Array containing extracted data from the HDF file.
SUBROUTINES:
None
REQUIREMENTS:
Need to use a version of IDL w/ HDF routines installed.
NOTES:
Taken from MOP02Viewer by Yottana Khunatorn (bmy, 7/17/01)
EXAMPLE:
; Make sure HDF is supported on this platform
IF ( HDF_EXISTS() eq 0 ) then MESSAGE, 'HDF not supported!'
; Open the HDF file and get the file ID # (FID)
FID = HDF_SD_START( 'fvdas_flk_01.ana.eta.20011027.hdf', /Read )
IF ( FID lt 0 ) then MESSAGE, 'Error opening file!'
; Read the UWND field from disk
DATA = HDF_GETSD( fId, 'UWND' )
; Close the file
HDF_SD_END, FID
MODIFICATION HISTORY:
bmy, 05 Nov 2001: VERSION 1.00
bmy, 23 Apr 2002: TOOLS VERSION 1.50
- updated documentation
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/hdf_getsd.pro)
NAME:
HDF_GETSDATTR
PURPOSE:
Convenience routine to read attributes (global or variable-
associated) from Hierarchical Data Format (HDF) files.
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
DATA = HDF_GETSDATTR( ID, NAME [ , Keywords ] )
INPUTS:
ID -> HDF File ID as returned by routine HDF_SD_START,
or scientific dataset ID, as returned by routine
HDF_SD_SELECT.
NAME -> Name of the attribute to be read from the HDF file.
KEYWORD PARAMETERS:
COUNT -> Returns the total number of values in the
specified attribute to the calling program.
HDF_TYPE -> Returns the HDF type of the attribute to the
calling program. HDF types are returned as a scalar
string. Possible returned values are DFNT_NONE,
DFNT_CHAR, DFNT_FLOAT32, DFNT_FLOAT64, DFNT_INT8,
DFNT_INT16, DFNT_INT32, DFNT_UINT8, DFNT_UINT16, and
DFNT_UINT32.
TYPE -> Returns the IDL type pf the attribute to the calling
program. The type of the attribute is returned as a
scalar string. Possible returned values are BYTE, INT,
LONG, FLOAT, DOUBLE, STRING, or UNKNOWN.
OUTPUTS:
DATA -> Array containing attribute data from the HDF file.
SUBROUTINES:
IDL HDF routines used:
==========================
HDF_SD_AttrInfo
HDF_SD_AttrFind (function)
REQUIREMENTS:
Need to use a version of IDL w/ HDF routines installed.
NOTES:
None
EXAMPLE:
; Make sure HDF is supported on this platform
IF ( NCDF_EXISTS() eq 0 ) then MESSAGE, 'HDF not supported!'
; Open the HDF file and get the file ID # (FID)
FID = HDF_SD_START( 'fvdas_flk_01.ana.eta.20011027.hdf', /READ )
IF ( FID lt 0 ) then MESSAGE, 'Error opening file!'
; Read the Ak, Bk, and PTOP attributes from the HDF file
; These are GLOBAL attributes associated w/ the file
AK = HDF_GETSDATTR( FID, 'ak' )
BK = HDF_GETSDATTR( FID, 'bk' )
PTOP = HDF_GETSDATTR( FID, 'ptop' )
; Close the HDF file
HDF_SD_END, FID
MODIFICATION HISTORY:
bmy, 30 Apr 2002: TOOLS VERSION 1.50
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/hdf_getsdattr.pro)
NAME:
HDF_GETVD
PURPOSE:
Convenience routine to read VDATA variables
from Hierarchical Data Format (HDF) files
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
VDATA = HDF_GETVD( FID, NAME [, _EXTRA=e ] )
INPUTS:
FID -> HDF File ID, as returned by routine HDF_OPEN.
NAME -> Name of the VDATA variable that you
want to extract from the file.
KEYWORD PARAMETERS:
_EXTRA=e -> Passes extra keywords to routine HDF_VD_READ.
OUTPUTS:
VDATA -> Array containing extracted data from the HDF file.
SUBROUTINES:
None
REQUIREMENTS:
Need to use a version of IDL w/ HDF routines installed.
NOTES:
Taken from MOP02Viewer by Yottana Khunatorn (bmy, 7/17/01)
EXAMPLE:
FID = HDF_OPEN( 'fvdas_flk_01.ana.eta.20011027.hdf', /Read )
IF ( FID lt 0 ) then Message, 'Error opening file!'
PTOP = HDF_GETVD( fId, 'PTOP' )
HDF_CLOSE, FID
; Opens an HDF-format file and gets the file ID. Then
; call HDF_GETSD to return the PTOP variable from the
; file. Then close the file and quit.
MODIFICATION HISTORY:
bmy, 05 Nov 2001: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/hdf_getvd.pro)
NAME:
HDF_SETSD
PURPOSE:
Convenience routine to write data into the Hierarchical Data
Format Scientific Dataset (HDF-SD) structure
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
HDF_SETSD, FID, DATA, NAME [, Keywords ]
INPUTS:
FID -> HDF File ID, as returned by routine HDF_SD_START.
DATA -> Data (array or scalar) to be written to HDF-SD format.
NAME -> Name under which the data array will be saved
to the HDF file.
KEYWORD PARAMETERS:
LONGNAME -> Longer descriptive name for the data. This will
be saved as the "long_name" attribute. Default is ''.
RANGE -> A 2-element vector containing the [min,max] of
the data array. If not passed, RANGE will be computed
(but only for numeric data types). RANGE will be saved
to the HDF file as the "valid_range" attribute.
_EXTRA=e -> picks up extra keywords for HDF_SD_SETINFO, such
as FILL, UNIT, COORDSYS, etc...
OUTPUTS:
None
SUBROUTINES:
Uses the following IDL HDF routines:
===========================================
HDF_SD_Create (function) HDF_SD_SetInfo
HDF_SD_AddData HDF_SD_EndAccess
DATATYPE (function)
REQUIREMENTS:
Need to use a version of IDL w/ HDF routines installed.
NOTES:
(1) Since HDF supports the STRING type, we do not have to
treat BYTE data like ASCII characters (cf ncdf_set.pro)
EXAMPLE:
; Find out if HDF is supported on this platform
IF ( HDF_EXISTS() eq 0 ) then MESSAGE, 'HDF not supported!'
; Open the HDF file
FID = HDF_SD_START( 'myhdf.hdf', /Create )
IF ( FID lt 0 ) then Message, 'Error opening file!'
; Write data to disk
HDF_SETSD, FID, DATA, 'NOx', $
LONGNAME='Nitrogen Oxide',$
UNIT='v/v', $
FILL=0.0,
; Close HDF File
HDF_SD_END, FID
; Writes NOx data to an HDF file.
MODIFICATION HISTORY:
bmy, 17 Apr 2002: TOOLS VERSION 1.50
bmy, 11 Sep 2002: TOOLS VERSION 1.51
- Now call routine DATATYPE to determine
the type of the data so that we can
write all data types to the HDF file.
- Don't add the RANGE attribute to
the HDF file for a string type value.
- Updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/hdf_setsd.pro)
NAME:
HIST_ND
PURPOSE:
Perform an N-dimensional histogram, also known as the joint
density function of N variables, ala HIST_2D.
CATEGORY:
Regridding
CALLING SEQUENCE:
hist=HIST_ND(V,BINSIZE,MIN=,MAX=,NBINS=,REVERSE_INDICES=)
INPUTS:
V: A NxP array representing P data points in N dimensions.
BINSIZE: The size of the bin to use. Either an N point vector
specifying a separate size for each dimension, or a scalar,
which will be used for all dimensions. If BINSIZE is not
passed, NBINS must be.
OPTIONAL INPUTS:
MIN: The minimum value for the histogram. Either a P point
vector specifying a separate minimum for each dimension, or
a scalar, which will be used for all dimensions. If
omitted, the natural minimum within the dataset will be
used.
MAX: The maximum value for the histogram. Either a P point
vector specifying a separate maximmum for each dimension, or
a scalar, which will be used for all dimensions. If omitted,
the natural maximum within the dataset will be used.
NBINS: Rather than specifying the binsize, you can pass NBINS,
the number of bins in each dimension, which can be a P point
vector, or a scalar. If BINSIZE it also passed, NBINS will
be ignored, otherwise BINSIZE will then be calculated as
binsize=(max-min)/nbins. Note that *unlike* RSI's version
of histogram as of IDL 5.4, this keyword actually works as
advertised, giving you NBINS bins over the range min to max.
KEYWORD PARAMETERS:
MIN,MAX,NBINS: See above
REVERSE_INDICES: Set to a named variable to receive the
reverse indices, for mapping which points occurred in a
given bin. Note that this is a 1-dimensional reverse index
vector (see HISTOGRAM). E.g., to find the indices of points
which fell in a histogram bin [i,j,k], look up:
ind=[i+nx*(j+ny*k)]
ri[ri[ind]:ri[ind+1]-1]
See also ARRAY_INDICES for converting in the other
direction.
OUTPUTS:
hist: The N-Dimensional histogram, of size N1xN2xN3x...xND
where the Ni's are the number of bins implied by the data,
and/or optional inputs min, max and binsize.
OPTIONAL OUTPUTS:
The reverse indices.
EXAMPLE:
v=randomu(sd,3,100)
h=hist_nd(v,.25,MIN=0,MAX=1,REVERSE_INDICES=ri)
SEE ALSO:
HISTOGRAM, HIST_2D
MODIFICATION HISTORY:
Mon Mar 5 09:45:53 2007, J.D. Smith
Correctly trim out of range elements from the
histogram, when MIN/MAX are specified. Requires IDL
v6.1 or later.
Tue Aug 19 09:13:43 2003, J.D. Smith
Slight update to BINSIZE logic to provide consistency
with HIST_2D.
Fri Oct 11 10:10:01 2002, J.D. Smith
Updated to use new DIMENSION keyword to MAX/MIN.
Fri Apr 20 12:57:34 2001, JD Smith
Slight update to NBINS logic. More aggressive keyword
checking.
Wed Mar 28 19:41:10 2001, JD Smith
Written, based on HIST_2D, and suggestions of CM.
phs, bmy, 30 May 2008: GAMAP VERSION 2.12
- Added to GAMAP under "Regridding" category
(See /n/home09/ryantosca/IDL/gamap2/regridding/hist_nd.pro)
NAME:
HYSTAT (function)
PURPOSE:
Compute atmospheric pressures in hydrostatic equilibrium.
This function is adapted from the Harvard photochemical
point model (CHEM1D).
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
pressure = HYSTAT,alt,temp,psurf,g0,rearth
INPUTS:
ALT -> Altitude in km. This can be a single value or an array.
TEMP -> Temperatures corresponding to the altitudes in ALT
PSURF -> A surface pressure value in mbar. Default is 1013.25 mbar.
G0 -> acceleration du eto gravity in m/s2. Default is 9.80665 m/s2 .
REARTH -> Radius of the earth in km. Default is 6356.77 km.
KEYWORD PARAMETERS:
none
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
ALT = FINDGEN(20) ; create altitude array 0..19 km
TEMP = TEMP = 205.+(19-ALT)*4. ; a semi-realistic temperature
; profile
PRESS = HYSTAT(ALT,TEMP) ; compute pressures
PRINT, PRESS
1013.25 896.496 791.815 698.104 614.349
539.613 473.041 413.843 361.298 314.745
273.581 237.254 205.261 177.146 152.492
130.924 112.098 95.7080 81.4736 69.1443
MODIFICATION HISTORY:
mgs, 21 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/hystat.pro)
NAME:
IDL2HTML
PURPOSE:
Wrapper for MK_HTML_HELP. Can be used to create HTML files
which contain the comments from the standard doc headers
that are included with each IDL routine.
CATEGORY:
Documentation
CALLING SEQUENCE:
IDL2HTML, PATH, [ , Keywords ]
INPUTS:
PATH -> A file path (can be a directory, single file name,
or file mask) for the IDL routines whose doc headers
you wish to convert to HTML format.
KEYWORD PARAMETERS:
/ALPHABETICAL -> Set this switch to create a separate HTML
documentation file for files beginning with each letter
of the alphabet. This is useful if you have a lot of
files to process.
/CATEGORY -> If specified, IDL2HTML will create a HTML file
for all *.pro files corresponding to a given category
(as specified by the CATEGORY tag in the standard
IDL documentation headers).
HTMLFILE -> Name of the HTML file that will be created.
A default file name will be used if HTMLFILE is omitted.
OUTDIR -> Name of the directory into which the HTML
documentation files will be written.
_EXTRA=e -> Passes extra keywords to MK_HTML_HELP.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
ADD_SEPARATOR (function) EXTRACT_FILENAME (function)
IS_DIR (function) STRWHERE (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
IDL2HTML, '~/IDL/tools/', OUTDIR='~/doc/html/', /ALPHABETICAL
; Will create HTML files with documentation from the
; IDL routines in the ~/IDL/tools directory. Will
; place the output in the ~/doc/html directory.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/doc/idl2html.pro)
NAME:
IMAGE_MAP
PURPOSE:
Overlay an image and a map (satellite projection)
CATEGORY:
Plotting
CALLING SEQUENCE:
IMAGE_MAP, A
INPUTS:
A -> The two-dimensional array to display.
KEYWORD PARAMETERS:
WINDOW_SCALE -> Set this keyword to scale the window size to
the image size. Otherwise, the image size is scaled to
the window size. This keyword is ignored when outputting
to devices with scalable pixels (e.g., PostScript).
[original as in image_contour]
ASPECT-> Set this keyword to retain the image's aspect ratio.
Square pixels are assumed. If WINDOW_SCALE is set, the
aspect ratio is automatically retained.
[original as in image_contour]
INTERP -> If this keyword is set, bilinear interpolation
is used if the image is resized.
[original as in image_contour]
CENTERX -> longitudinal position of geostationary satellite
(default -135 = GEOS-9)
DIST -> distance of satellite from Earth surface (in earth radii)
(default = 7)
CONTINENTS -> superimpose map continents on the image
OUTPUTS:
No explicit outputs.
COMMON BLOCKS:
None
SIDE EFFECTS:
The currently selected display is affected.
RESTRICTIONS:
None
NOTES:
Derived from IDL routine image_contour.
Not very flexible - quick hack to analyze PEM-T data
PROCEDURE:
If the device has scalable pixels, then the image is written over
the plot window.
MODIFICATION HISTORY:
mgs, 01 Oct 1997: based on IMAGE_CONT by DMS, May, 1988.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/plotting/image_map.pro)
NAME:
IND_COMB
PURPOSE:
Combine two index arrays that result from different
WHERE calls to the same data set.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = IND_COMB( INDEX1, INDEX2, TYPE [, keywords ] )
INPUTS:
INDEX1, INDEX2 --> the two index arrays (may be single
integers or -1, but must be given)
TYPE --> a string containing the type of index combination:
The result will contain an index value if the index is
contained in ...
type eq "OR": ... at least one of INDEX1 or INDEX2
type eq "AND": ... INDEX1 and INDEX2
type eq "NOR": ... neither INDEX1 nor INDEX2
type eq "XOR": ... only one of INDEX1 or INDEX2
type eq "NAND": ... not in both
The default combination is "OR".
KEYWORD PARAMETERS:
TOTALN --> optional: number of elements in the data set.
If not given, this value is calculated as
max([index1,index2]). If this argument is passed,
the user has full responsibility that array indices
are not exceeded. ATTENTION: types NAND and NOR may
give wrong results if TOTALN is not specified
(see example).
OUTPUTS:
RESULT -> An array of type lon that contains the combined
indices and can be used as an array subscript.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
DATA = FINDGEN(100)+1
IND1 = WHERE(DATA le 50)
IND2 = WHERE(DATA ge 50 AND DATA lt 80)
RES = IND_COMB(IND1,IND2,"OR")
print,'1:',min(data(res)),max(data(res))
RES = IND_COMB(IND1,IND2,"AND")
print,'2:',min(data(res)),max(data(res))
RES = IND_COMB(IND1,IND2,"NOR") ; <------ WRONG !!
print,'3:',res
RES = IND_COMB(IND1,IND2,"NOR",TOTALN=100)
print,'4:',min(data(res)),max(data(res))
RES = IND_COMB(IND1,IND2,"XOR")
print,'5:',min(data(res)),max(data(res))
RES = IND_COMB(IND1,IND2,"NAND") ; <------ WRONG !!
print,'6:',min(data(res)),max(data(res))
RES = IND_COMB(IND1,IND2,"NAND",TOTALN=100)
print,'7:',min(data(res)),max(data(res))
IDL will print:
1: 1 79
2: 50 50
3: -1 <------ WRONG !!
4: 80 100
5: 1 79
6: 1 79 <------ WRONG !!
7: 1 100
MODIFICATION HISTORY:
mgs, 04 Dec 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/general/ind_comb.pro)
NAME:
INTERPOLATE_2D
PURPOSE:
Interpolates a 2-D array from one grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
NEWDATA = INTERPOLATE_2D( DATA, OLDXMID, OLDYMID, $
NEWXMID, NEWYMID [, Keywords ] )
INPUTS:
DATA -> A 2-D array containing the data to be interpolated.
OLDXMID -> A 1-D vector containing the X-coordinates (e.g.
longitude) corresponding to the DATA array.
OLDYMID -> A 1-D vector containing the Y-coordinates (e.g.
latitude) corresponding to the DATA array.
NEWXMID -> A 1-D vector containing the X-coordinates (e.g.
longitude) of the new grid onto which DATA will be
interpolated.
NEWYMID -> A 1-D vector containing the Y-coordinates (e.g.
latitude) of the new grid onto which DATA will be
interpolated.
KEYWORD PARAMETERS:
/DOUBLE -> Set this switch to force computation in double
precision. Default is to use single precision.
OUTPUTS:
NEWDATA -> A 2-D array containing the data on the new grid.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
INTERPOLATE_2D can be used to interpolate from coarse grids
to fine grids or fine grids to coarse grids. This routine
uses the IDL INTERPOL command.
EXAMPLE:
; Define old grid (GEOS-Chem 2x25)
OLDTYPE = CTM_TYPE( 'GEOS4', RES=2 )
OLDGRID = CTM_GRID( OLDTYPE )
; Define new grid (GEOS-Chem 4x5)
NEWTYPE = CTM_TYPE( 'GEOS4', RES=4 )
NEWGRID = CTM_GRID( NEWTYPE )
; Interpolate DATA array from 2x25 to 4x5
NEWDATA = INTERPOLATE_2D( DATA, $
OLDGRID.XMID, OLDGRID.YMID, $
NEWGRID.XMID, NEWGRID.YMID )
; Interpolate a data array from the GEOS-Chem
; 2 x 2.5 grid to the GEOS-Chem 4 x 5 grid
MODIFICATION HISTORY:
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/interpolate_2d.pro)
NAME:
INV_INDEX
PURPOSE:
Find the indices that do NOT match a WHERE condition
CATEGORY:
General
CALLING SEQUENCE:
RESULT = INV_INDEX( INDEX, TOTALN )
INPUTS:
INDEX -> An index array, e.g. previously generated by a
WHERE command (may be -1)
TOTALN -> the number of elements in the reference data
set, i.e. totaln = n_elements(index)+n_elements(result)
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> an integer array with all indices that were NOT
in index or -1 if index was complete
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The function returns -1 if one of the following errors occurs:
- invalid number of arguments
- index variable is undefined
- totaln is less than n_elements(index)
- totaln less or equal 1, i.e. no associated data
The last error does not produce an error message, since this
feature was found to be very useful (in EXPLORE, the widget based
interactive data explorer)
EXAMPLE:
DATA = FINDGEN( 50 )
INDEX = WHERE( DATA ge 25 )
INVERS = INV_INDEX( INDEX, N_ELEMENTS( DATA ) )
PRINT, INVERS
0 1 2 3 4 5 6 7 8 9
10 11 12 13 14 15 16 17 18 19
20 21 22 23 24
; Find the elements of DATA that are greater than 25
; and then print the inverse condition
MODIFICATION HISTORY:
mgs, 10 May 1997: VERSION 1.00
mgs, 18 Aug 1997: - added template and check if n_elements(index) eq 0
mgs, 05 Apr 1999: - bug fix: needed to make sure result is type long
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/inv_index.pro)
NAME:
IN_RANGE
PURPOSE:
IN_RANGE checks to see if an input value lies
between a minimum value and a maximum value.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = IN_RANGE(VALUE, MINVAL, MAXVAL)
INPUTS:
VALUE -> The value to be checked
MINVAL -> The minimum value
MAXVAL -> The maximum value
KEYWORD PARAMETERS:
OUTPUTS:
If MINVAL <= VALUE <= MAXVAL, IN_RANGE returns 0
If VALUE < MINVAL, IN_RANGE returns 1
If VALUE > MAXVAL, IN_RANGE returns 1
SUBROUTINES:
None
REQUIREMENTS:
None
EXAMPLE:
IF ( NOT IN_RANGE( VALUE, 0, 100 ) ) $
THEN PRINT, 'VALUE is not in between 0-100'
; Print a message if VALUE lies outside
; of the range 0-100
MODIFICATION HISTORY:
bmy, 24 Sep 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/general/in_range.pro)
NAME:
ISALGEBRAIC (function)
PURPOSE:
Locates the position of algebraic characters in a string
(e.g. locations that are EITHER digits '.' OR +/- signs).
CATEGORY:
Strings
CALLING SEQUENCE:
Result = ISALGEBRAIC( S [, Keywords ] )
INPUTS:
S -> The string to be tested.
KEYWORD PARAMETERS:
OUTPUTS:
Result -> The value of the function. RESULT is an index array
(integer) that contains as many elements as S has
characters. If S is a single character, then RESULT will
be scalar. Where RESULT = 1, the corresponding characters
in S are algebraic.
SUBROUTINES:
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
print, ISALGEBRAIC( '-100;+100' )
; prints 1 1 1 1 0 1 1 1 1
MODIFICATION HISTORY:
bmy, 17 Nov 1998: VERSION 1.00
mgs, 17 Nov 1998: - removed INVERT keyword. It's
simply 1-isalgebraic
- added test for '.'
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/isalgebraic.pro)
NAME:
ISALNUM (function)
PURPOSE:
IDL analog to the 'isalnum' routine in C. Locates
alphanumeric characters ( A...Z, a...z, 0..9 ) in a string.
CATEGORY:
Strings
CALLING SEQUENCE:
Result = ISALNUM( S )
INPUTS:
S -> The string to be tested.
KEYWORD PARAMETERS:
None
OUTPUTS:
Result -> The value of the function. RESULT is an index array
that contains as many elements as S has characters.
If S is a single character, then RESULT will be scalar.
Where RESULT = 1, the corresponding characters in S
are alphanumeric
SUBROUTINES:
ISALPHA (function)
ISDIGIT (function)
REQUIREMENTS:
NOTES:
None
EXAMPLE:
print, isalnum( 'ABCD0123#' )
; prints, 1 1 1 1 1 1 1 1 0
print, isalnum( '#' )
; prints 0
MODIFICATION HISTORY:
bmy, 01 Jun 1998: VERSION 1.00
bmy, 02 Jun 1998 - now use BYTE function in where statement
instead of hardwired constants
bmy, 02 Jun 1998 VERSION 1.10
- now uses ISALPHA and ISDIGIT
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/isalnum.pro)
NAME:
ISALPHA (function)
PURPOSE:
IDL analog to the 'isalpha' routine in C. Locates the
positions of alphabetic characters ( A...Z, a...z ).
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = ISALPHA( S )
INPUTS:
S -> The string to be tested.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The value of the function. RESULT is an index array
that contains as many elements as S has characters.
If S is a single character, then RESULT will be scalar.
Where RESULT = 1, the corresponding characters in S
are alphabetic.
SUBROUTINES:
ISUPPER (function)
ISLOWER (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, ISALPHA( 'ABcd0123' )
1 1 1 1 0 0 0 0
PRINT, ISALPHA( '#' )
0
MODIFICATION HISTORY:
bmy, 29 May 1998: VERSION 1.00
bmy, 01 Jun 1998: - now returns 0 for condition FALSE
- fixed bug that allowed byte values from
91-96 to be treated as letters
bmy, 02 Jun 1998 - now use BYTE function in where statement
instead of hardwired constants
bmy, 02 Jun 1998 VERSION 1.10
- now uses ISUPPER and ISLOWER
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/isalpha.pro)
NAME:
ISDIGIT (function)
PURPOSE:
IDL analog to the 'isdigit' routine in C. Locates
numeric characters ( '0' ... '9') in a string.
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = ISDIGIT( S )
INPUTS:
S -> The string to be tested.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The value of the function. RESULT is an index array
that contains as many elements as S has characters.
If S is a single character, then RESULT will be scalar.
Where RESULT = 1, the corresponding characters in S
are numeric.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
print, isdigit( '3001ABcd' )
; prints, 1 1 1 1 0 0 0 0
print, isdigit( '#' )
; prints 0
MODIFICATION HISTORY:
bmy, 29 May 1998: VERSION 1.00
bmy, 01 Jun 1998: - now returns 0 for condition FALSE
bmy, 02 Jun 1998 - now use BYTE function in where statement
instead of hardwired constants
bmy, 02 Jun 1998 VERSION 1.10
- now can analyze an entire string
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/isdigit.pro)
NAME:
ISGRAPH (function)
PURPOSE:
IDL analog to the 'isgraph' routine in C. Locates all
graphics characters in a string.
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = ISGRAPH( S )
INPUTS:
S -> The string to be tested.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The value of the function. RESULT is an index array
that contains as many elements as S has characters.
If S is a single character, then RESULT will be scalar.
Where RESULT = 1, the corresponding characters in S
are graphics characters.
SUBROUTINES:
None
REQUIREMENTS:
NOTES:
Graphics characters are printing characters (i.e. they can be
seen on the screen or on a printout) but EXCLUDE the
space ( ' ' ) character.
EXAMPLE:
print, isgraph( 'ABCD !#~%' )
1 1 1 1 0 1 1 1 1
print, isgraph( string( 9B ) ) ; horizontal tab
0
MODIFICATION HISTORY:
bmy, 01 Jun 1998: VERSION 1.00
bmy, 02 Jun 1998 - now use BYTE function in where statement
instead of hardwired constants
bmy, 02 Jun 1998 VERSION 1.10
- now can analyze an entire string
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/isgraph.pro)
NAME:
ISLEAP (function)
PURPOSE:
Returns 1 for each year that is a leap year.
CATEGORY:
Date & Time
CALLING SEQUENCE:
RESULT = ISLEAP( YEAR )
INPUTS:
YEAR -> A year or an array of years. Must be "4 digit" years.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> An integer value or array with 1 for each
year that is a leap year.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
For many purposes one should take a look at built-in
IDL date functions first (version > 5.0).
EXAMPLE:
YEARS = FINDGEN(25) + 1980
PRINT, 365 + ISLEAP(YEARS), FORMAT='(10i4)'
366 365 365 365 366 365 365 365 366 365
365 365 366 365 365 365 366 365 365 365
366 365 365 365 366
; Compute the number of days in each year
; from 1980 to 2005 using ISLEAP to add
; either 1 or 0 to 365.
MODIFICATION HISTORY:
mgs, 02 Oct 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/date_time/isleap.pro)
NAME:
ISLOWER (function)
PURPOSE:
IDL analog to the 'islower' routine in C. Locates all
lowercase alphabetic characters in a string.
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = ISLOWER( S )
INPUTS:
S -> The string to be tested
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The value of the function. RESULT is an index array
that contains as many elements as S has characters.
If S is a single character, then RESULT will be scalar.
Where RESULT = 1, the corresponding characters in S
are lowercase alphabetic.
SUBROUTINES:
None
REQUIREMENTS:
NOTES:
None
EXAMPLE:
print, islower( 'abcdefG' )
1 1 1 1 1 1 0
print, islower( 'A' )
0
MODIFICATION HISTORY:
bmy, 01 Jun 1998: VERSION 1.00
bmy, 02 Jun 1998: VERSION 1.10
- now can analyze entire strings
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/islower.pro)
NAME:
ISOPLETH_MAP
PURPOSE:
Plots a 3-D (longitude, latitude, altitude) isopleth of
a data concentration field atop a world map.
CATEGORY:
GAMAP Utilities
CALLING SEQUENCE:
ISOPLETH_3D
INPUTS:
DATA -> The data array to be plotted. DATA must be
3-dimensional.
XMID, YMID, ZMID -> XMID is the array of longitude grid box
centers. YMID is the array of latitude grid box centers.
ZMID is the array of altitude grid box centers.
ISOPLETH_MAP will be able to label the X, Y, and Z axes
based on the values of XMID, YMID, ZMID.
KEYWORD PARAMETERS:
ISOPLETH -> Value of data for which to show an iso-contour surface.
Default is 35.0 [ppbv].
/LOW -> Set this keyword to display the low side of the iso-contour
surface (i.e., the contour surfaces enclose high data values).
If this keyword is omitted or is 0, the high side of the
contour surface is displayed and the contour encloses low
data values. If this parameter is incorrectly specified,
errors in shading will result.
TITLE1 -> First line of the title that is to be placed atop the plot
window. TITLE is passed explicitly to avoid keyword name
duplication in the _EXTRA=e facility. A default title
string of "Volume Rendering" will be used if TITLE is not
passed explicitly.
TITLE2 -> Second line of the title string for the top of the plot
window. This line should be used for specifying the value
and units of the isosurface. A default string such as:
"ISOSURFACE = 20.000 [ppbv]" will be created if TITLE2 is
not passed explicitly. Also, if TITLE2 is not passed
explicitly, the format descriptor string passed via the
FORMAT keyword will be used to determine the number of
decimal places
USTR -> String to specify the units of the isocontour surface
(e.g. '[ppbv]', '[kg/s]', etc). Default is a null
string, ''.
FORMAT -> Format descriptor string used in generating a default
value of TITLE2. Default is '(f14.3)'.
MPARAM -> A 3 element vector containing values for
[ P0Lat, P0Lon, Rot ], for the MAP_SET command.
Default is [ 0, 0, 0 ]. Elements not specified are
automatically set to zero.
LIMIT -> A four-element vector which specifies the latitude
and longitude extent of the map. The elements of LIMIT
are arranged thus: [ LatMin, LonMin, LatMax, LonMax ].
Default is to set LIMIT = [ -90, -180, 90, 180 ] (i.e.
to include the entire globe). P0Lon will be computed
to fit into the LIMIT range unless it is explicitely
requested in MParam.
MCOLOR -> Color index of the map outline and title characters.
Default is 1 (MYCT black).
ACOLOR -> Color index of the 3-D axes which surround the map
plot. Defaults is 1 (MYCT black).
[XYZ]MARGIN -> A 2-element array specifying the margin on
the left (bottom) and right (top) sides of the plot
window, in units of character size. Defaults are
XMARGIN=[ 5, 3 ], YMARGIN=[ 3, 3], ZMARGIN=[ 3, 3 ].
These are used to put some "white space" into the plot
window for aesthetic purposes.
WINPARAM -> An integer vector with up to 5 elements:
WINPARAM(0) = window number (if negative, a window
will be opened with the /FREE option.
WINPARAM(1) = X dimension of window in pixels (width)
WINPARAM(2) = Y dimension of window in pixels (height)
OUTPUTS:
A picture will be displayed in the X-window device.
SUBROUTINES:
External Subroutines Required:
================================
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL MAP_LABELS
TVIMAGE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages
NOTES:
(1) Does not quite work for multi-panel plots, due to the
screen capturing done in the Z-buffer.
(2) Verified that the map and data coincide (bmy, 1/19/01)
EXAMPLE:
ISOPLETH_MAP, DATA, XMID, YMID, ZMID, $
ISOPLETH=40, MPARAM=[0, 180, 0], MCOLOR=1, ACOLOR=1
; Will display a 35 [ppbv] isopleth with black
; map labels, lines, and axes. MPARAM is set to
; accept longitude values (XMID) in the range of
; 0 - 360.
MODIFICATION HISTORY:
bmy, 23 Jan 2001: GAMAP VERSION 1.47
- based on example code by David Fanning
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 17 Jul 2008: GAMAP VERSION 2.12
- Now set N_COLORS to !D.TBLE_SIZE
phs, 17 Jul 2008: GAMAP VERSION 2.13
- Bug fix: !D.TBLE_SIZE should be !D.TABLE_SIZE
phs, 14 Oct 2009: - added AZ (so it is used for surface and
not map_set) and ZVALUE keywords
- added _EXTRA keyword to open_device for PS
- more control over TITLE2
phs, 29 Oct 2009: GAMAP VERSION 2.14
- now draws the fram even if there is no
iso-surface
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/isopleth_map.pro)
NAME:
ISPRINT (function)
PURPOSE:
IDL analog to the 'isprint' routine in C. Returns 1 if
a character is a printable character (including space).
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = ISPRINT( S )
INPUTS:
S -> The string to be tested.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The value of the function. RESULT is an index array
that contains as many elements as S has characters.
If S is a single character, then RESULT will be scalar.
Where RESULT = 1, the corresponding characters in S
are printable.
SUBROUTINES:
None
REQUIREMENTS:
NOTES:
Printing characters can be seen on the screen (these exclude
control characters).
EXAMPLE:
print, isprint( '!X3d ' )
1 1 1 1 0
print, isprint( string( 9B ) ) ; horizontal tab
0
MODIFICATION HISTORY:
bmy, 01 Jun 1998: VERSION 1.00
bmy, 02 Jun 1998 - now use BYTE function in where statement
instead of hardwired constants
bmy, 02 Jun 1998: VERSION 1.10
- now uses ISGRAPH
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/isprint.pro)
NAME:
ISSPACE (function)
PURPOSE:
IDL analog to the 'isspace' routine in C. Locates
white space characters in a string.
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = ISSPACE( S )
INPUTS:
S -> The string to be tested.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The value of the function. RESULT is an index
array that contains as many elements as S has
characters. If S is a single character, then RESULT
will be scalar. Where RESULT = 1, the corresponding
characters in S are numeric.
SUBROUTINES:
None
REQUIREMENTS:
NOTES:
None
EXAMPLES:
PRINT, ISSPACE( ' ' )
1 1 1 1 1
PRINT, ISSPACE( 'A' )
0
MODIFICATION HISTORY:
bmy, 01 Jun 1998: VERSION 1.00
bmy, 02 Jun 1998: - now use BYTE function in where statement
instead of hardwired constants (where
possible)
bmy, 02 Jun 1998: VERSION 1.10
- now can analyze an entire string
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/isspace.pro)
NAME:
ISUPPER (function)
PURPOSE:
IDL analog to the 'isupper' routine in C. Locates all
uppercase alphabetic characters in a string.
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = ISUPPER( S )
INPUTS:
S -> The string to be tested
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The value of the function. RESULT is an index array
that contains as many elements as S has characters.
If S is a single character, then RESULT will be scalar.
Uppercase alphabetic characters in S are thus
denoted by the condition ( RESULT eq 1 ).
SUBROUTINES:
None
REQUIREMENTS:
Assumes that the ASCII character set is the character set
installed on the system. The byte values will be different
for other character sets such as EBSDIC.
NOTES:
None
EXAMPLE:
PRINT, ISUPPER( 'ABCDEFg' )
1 1 1 1 1 1 0
PRINT, ISUPPER( 'a' )
0
MODIFICATION HISTORY:
bmy, 01 Jun 1998: VERSION 1.00
bmy, 02 Jun 1998: VERSION 1.10
- now can analyze entire strings
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/isupper.pro)
NAME:
IS_DEFINED
PURPOSE:
Tests if a program argument is defined (i.e. if it
was passed any value(s) from the calling program).
CATEGORY:
General
CALLING SEQUENCE:
RESULT = IS_DEFINED( ARG )
INPUTS:
ARG -> The argument to be tested.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, IS_DEFINED( ARG )
0
; Because ARG has not been yet assigned a value,
; IS_DEFINED( ARG ) returns 0.
(2)
ARG = 1
PRINT, IS_DEFINED( ARG )
1
; Because ARG now has not been yet assigned a value,
; IS_DEFINED( ARG ) now returns 1.
MODIFICATION HISTORY:
D.Fanning, 02 Jul 1998: INITIAL VERSION
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/general/is_defined.pro)
NAME:
IS_DIR (function)
PURPOSE:
Tests if a directory exists
CATEGORY:
File & I/O
CALLING SEQUENCE:
RESULT = IS_DIR( PATH )
INPUTS:
PATH -> The variable to be tested.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> =1 if directory exists, =0 otherwise
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, IS_DIR( '~/IDL/tools/' )
1
; Test the existence of the ~/IDL/tools directory.
MODIFICATION HISTORY:
R.Bauer, 26 Jan 1999: INITIAL VERSION
- from Forschungszentrum Juelich GmbH ICG-1
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/file_io/is_dir.pro)
NAME:
IS_SELECTED (function)
PURPOSE:
Return a boolean vector with 1 for each element of VAR
that is contained in SELECTION. This is a generalization
of WHERE(VAR eq value) in that value can be an array
instead of a single value.
CATEGORY:
General
CALLING SEQUENCE:
INDEX = IS_SELECTED(VAR,SELECTION)
INPUTS:
VAR -> The data vector
SELECTION -> A vector with chosen values. If no selection
is given, the function returns a vector with all entries
set to zero.
KEYWORD PARAMETERS:
none
OUTPUTS:
INDEX -> An integer vector of length n_elements(VAR)
that contains 1 for each element of VAR that has
one of the SELECTION values.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
A = [ 1, 1, 1, 2, 2, 3 ]
B = [ 2, 3 ]
PRINT, IS_SELECTED( A, B )
0 0 0 1 1 1
(2)
PRINT, WHERE( IS_SELECTED( A, B ) )
3 4 5
; (i.e. indices of A that correspond to a value of 2 or 3)
; equivalent to:
print,where(A eq 2 or A eq 3)
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/is_selected.pro)
NAME:
JPEG2PS
PURPOSE:
Translates JPEG images to PostScript format.
CATEGORY:
Graphics
CALLING SEQUENCE:
JPEG2PS [, FILENAME [, Keywords ] ]
INPUTS:
FILENAME (optional) -> Name of the input JPEG file.
If FILENAME is omitted then JPEG2PS will prompt
the user to supply a file name via a dialog box.
FILENAME may contain wild card characters.
KEYWORD PARAMETERS:
OUTFILENAME -> Name of the output PostScript file.
Default is "idl.ps".
/FLIP_BW -> Set this keyword to turn black pixels into
white pixels and vice-versa. This is useful for
creating PostScript files of JPEG images that have a
dark background color.
XOFFSET, YOFFSET (optional) -> Set these keywords to specify
the X and Y Margins in inches. Defaults are
XMARGIN = 0.5 inches and YMARGIN = 0.5 inches.
_EXTRA=e -> Picks up extra keywords for OPEN_DEVICE,
TVIMAGE, and CLOSE_DEVICE.
OUTPUTS:
Sends output to a PostScript file, whose name is given
by the OUTFILENAME keyword.
SUBROUTINES:
External subroutines required:
------------------------------
EXTRACT_FILEPATH (function)
DIALOG_PICKFILE (function)
TVIMAGE
REQUIREMENTS:
References routines from the TOOLS package.
NOTES:
(1) Image processing options are limited to flipping the
black and white pixels. This should be good enough
for most purposes.
(2) XMARGIN and YMARGIN assume that we are printing out for
standard USA 8.5 x 11" page. Device sizes listed below
are also in inches.
(3) Refer to the READ_JPEG procedure manual pages for
JPEG image handling options.
EXAMPLE:
(1)
JPEG2PS, 'my_jpg.jpg', OUTFILENAME='my_ps.ps'
; Translates the image in "my_jpg.jpg" to
; the PostScript file "my_ps.ps".
(2)
JPEG2PS, 'my_jpg.jpg', OUTFILENAME='my_ps.ps', /FLIP_BW
; Same as in (1), but also changes all black
; pixels to white and vice-versa.
(3)
JPEG2PS, 'my_jpg.jpg', OUTFILENAME='my_ps.ps', /FLIP_BW, $
XMARGIN=0.5, YMARGIN=0.5
; Same as in (2), but also will "pad" the image with
; 0.5" of white space around each side.
MODIFICATION HISTORY:
bmy, 28 Jan 2000: VERSION 1.45
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/graphics/jpeg2ps.pro)
NAME:
JV_DIFF
PURPOSE:
Creates difference (new - old) plots of J-values at both the
surface and 500 hPa.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
JV_DIFF, FILES, LEVELS, TAUS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
LEVELS -> A 4-element vector containing the level indices
for the GEOS-Chem surface layer and 500 hPa layer.
for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
NOTE: This is in Fortran notation (starting from 1!)
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range to +/- 5%.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==================================================
PlotJVDiff
External Subroutines Required:
==================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA EXTRACT_FILENAME (function)
GETMODELANDGRIDINFO MULTIPANEL
MYCT OPEN_DEVICE
TVMAP
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON
EXAMPLE:
FILES = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
LEVELS = [ 1, 1, 13, 13 ]
TAUS = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
JV_DIFF, FILES, LEVELS, TAUS, VERSIONS, $
/PS, OUTFILENAME='myplot.ps'
; Creates J-value difference plots [ v7-04-11 - v7-04-10 ]
; for July 2001 at the surface and 500 hPa.
; The max & min of the data will be fixed at +/- 5%.
JV_DIFF, FILES, LEVELS, TAUS, VERSIONS, $
/DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Same as above, but this time the full dynamic
; range of the data will be displayed.
MODIFICATION HISTORY:
mps, 02 Dec 2013: - Initial version, based on jv_ratios.pro
mps & bmy, 29 May 2014: GAMAP VERSION 2.18
- Compatible with extra J-Value tracers
in v10-01c and higher versions
(See /n/home09/ryantosca/IDL/gamap2/benchmark/jv_diff.pro)
NAME:
JV_MAP
PURPOSE:
Creates plots of J-values at both the surface and 500 hPa.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
JV_MAP, FILE, LEVELS, TAU, VERSION, [, Keywords ]
INPUTS:
FILE -> The name of the file containing data to be plotted.
LEVELS -> A 4-element vector containing the level indices
for the GEOS-Chem surface layer and 500 hPa layer.
for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
NOTE: This is in Fortran notation (starting from 1!)
TAU -> The TAU value (hours GMT from /1/1985) corresponding
to the data to be plotted.
VERSION -> The model version number corresponding to the
data to be plotted.
KEYWORD PARAMETERS:
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range to +/- 5%.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Required:
==================================================
PlotJVMap
External Subroutines Required:
==================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA EXTRACT_FILENAME (function)
GETMODELANDGRIDINFO MULTIPANEL
MYCT OPEN_DEVICE
TVMAP
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON
EXAMPLE:
FILE = 'ctm.bpch.v10-01i'
LEVELS = [ 1, 1, 13, 13 ]
TAUS = NYMD2TAU( 20130701 )
VERSIONS = 'v10-01i'
JV_MAP, FILES, LEVELS, TAUS, VERSIONS, $
/PS, OUTFILENAME='myplot.ps'
; Creates J-value plots for v10-01i for July 2013
; at the surface and 500 hPa.
; The max & min of the data will be fixed at +/- 5%.
JV_MAP, FILE, LEVELS, TAU, VERSION, $
/DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Same as above, but this time the full dynamic
; range of the data will be displayed.
MODIFICATION HISTORY:
mps, 19 Apr 2014: VERSION 1.01
- Adapted from jv_ratio.pro
mps & bmy, 29 May 2014: GAMAP VERSION 2.18
- Compatible with extra J-Value tracers
in v10-01c and higher versions
(See /n/home09/ryantosca/IDL/gamap2/benchmark/jv_map.pro)
NAME:
JV_RATIO
PURPOSE:
Creates ratio (new/old) plots of J-values at both the surface
and 500 hPa.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
JV_RATIO, FILES, LEVELS, TAUS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
LEVELS -> A 4-element vector containing the level indices
for the GEOS-Chem surface layer and 500 hPa layer.
for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
NOTE: This is in Fortran notation (starting from 1!)
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range to +/- 5%.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==================================================
ComputeJVRatios PlotJVRatios
External Subroutines Required:
==================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA EXTRACT_FILENAME (function)
GETMODELANDGRIDINFO MULTIPANEL
MYCT OPEN_DEVICE
TVMAP
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON
EXAMPLE:
FILES = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
LEVELS = [ 1, 1, 13, 13 ]
TAUS = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
JV_RATIO, FILES, LEVELS, TAUS, VERSIONS, $
/PS, OUTFILENAME='myplot.ps'
; Creates J-value ratio plots [ v7-04-11 / v7-04-10 ]
; for July 2001 at the surface and 500 hPa.
; The max & min of the data will be fixed at +/- 5%.
JV_RATIO, FILES, LEVELS, TAUS, VERSIONS, $
/DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Same as above, but this time the full dynamic
; range of the data will be displayed.
MODIFICATION HISTORY:
bmy, 14 Aug 2002: VERSION 1.01
- Adapted from Isabelle Bey's "cat_plot.pro"
- you may now specify different TAU values
bmy, 13 Sep 2002: VERSION 1.02
for FILENEW and FILEOLD via the TAU0 keyword
bmy, 04 Oct 2004: VERSION 1.03
- Remove MIN_VALID from call to TVMAP
bmy, 09 Nov 2007: VERSION 1.04
- Modified argument list and some
internal variable names.
bmy, 20 Nov 2007: VERSION 1.05
- Now draw out-of-bounds triangles for
the colorbar when using the "small"
data ranges. New feature of TVMAP.
bmy, 07 May 2008: VERSION 1.06
- Now allow for comparing models on 2
different vertical grids.
bmy, 08 Feb 2011: VERSION 1.07
- Now display in the top-of-plot title
if the dynamic range option is used.
bmy, 08 Jun 2011: VERSION 1.08
- Now create log plots in range 0.5 - 2.0
- Added /DO_FULLCHEM keyword
- Adjust colorbar so that the 0.9 - 1.1
range shows up in white.
- Now restore !MYCT sysvar to previous
settings upon exiting the program
mps & bmy, 29 May 2014: GAMAP VERSION 2.18
- Compatible with extra J-Value tracers
in v10-01c and higher versions;
(See /n/home09/ryantosca/IDL/gamap2/benchmark/jv_ratio.pro)
NAME:
KNMHC
PURPOSE:
Returns an array of reaction rates for various non-methane
hydrocarbon reactions as a function of temperature and pressure.
NOTE: Reaction rates may need updating to the latest JPL dataset.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = KNMHC( T, P [, Keywords ] )
INPUTS:
T -> Temperature in [K].
P -> Pressure in [hPa].
KEYWORD PARAMETERS:
NAMES -> Returns to the calling program a list of the names
for the various chemical species
OUTPUTS:
RESULT -> An array of rate constants corresponding to
the species contained in NAMES.
SUBROUTINES:
External Subroutines Required:
================================
KTROE (function)
REQUIREMENTS:
None
NOTES:
(1) This should probably be rewritten to return a structure.
(2) Definitely needs updating of rate constants.
EXAMPLE:
RESULT = KNMHC( 300, 1000, NAMES=NAMES )
PRINT, NAMES
CO CH4 C2H2 C2H4 C2H6 C3H6 C3H8 i-BUT CH3CL
PRINT, RESULT
2.40000e-13 6.60071e-15 7.55980e-13 8.14644e-12
2.45774e-13 5.08118e-11 1.10803e-12 2.34511e-12
3.76143e-14
; Compute rate constants for 300K and 1000hPa pressure
MODIFICATION HISTORY:
mgs, 1998? INITIAL VERSION
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- added std doc header
- updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/knmhc.pro)
NAME:
KTROE
PURPOSE:
compute reaction rate coefficient for a 3rd order reaction
using Troe's formula as given in JPL97-4
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
k=KTROE(T,p,k0300,n,kinf300,m [,keywords])
INPUTS:
T --> temperature in K
p --> pressure in mbars
k0300, n --> constants to get k0(T) { see JPL97,table 2 }
kinf300, m --> constants to get kinf(T) { see JPL97,table 2 }
KEYWORD PARAMETERS:
k0, kinf, fc --> will return individual terms of the Troe expression
OUTPUTS:
K -> a rate coefficient
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
no error checking is done except for the correct
number of arguments
EXAMPLE:
MODIFICATION HISTORY:
mgs, 20 Mar 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/ktroe.pro)
NAME:
LEGEND
PURPOSE:
Annotate a plot with a legend. Make it as simple as possible
for the user.
CATEGORY:
Plotting
CALLING SEQUENCE:
LEGEND, [several keywords]
INPUTS:
KEYWORD PARAMETERS:
HALIGN, VALIGN -> horizontal and vertical alignment of legend
with respect to plot window. Ranges from 0 to 1, and is
interpreted "dynamically": e.g. a value of 0.3 places
30% of the box left (below) 0.3*plotwindow size.
Defaults are 0.98 and 0.03, i.e. the lower right corner.
WIDTH -> width of the legend box. This parameter is defaulted
to 40% of the plot area or may be adjusted to hold the
longest LABEL string if CHARSIZE is given. If WIDTH is
specified, it is used to determine the CHARSIZE. However,
if both are given, they are both used and may lead to
ugly results.
POSITION -> a four element vector that gives complete control
over the position of the legend box. Normally, you don't
need this keyword, but it may be handy in a multi-plot
situation where you want to place a legend independently
of any individual plotting area. It can also be convenient
if you want to place legends interactively: simply call
a rubberband program that returns the region coordinates
in normalized units, and pass this vector to the LEGEND
program.
PLOTPOSITION -> 4 element vector that specifies the plotting
area. Default is taken from !P.POSITION if set, otherwise
[0.2,0.1,0.9,0.9] is used as default. As noted above,
sizing and positioning of the legend box is with respect
to the plot position unless POSITION is specified.
SYMBOL -> a vector (or one integer) containing symbol numbers
to plot. -1 can be used to skip one entry. These values
are arguments to the SYM() function. If you like to
label plain IDL symbols, use the PSYM keyword instead.
PSYM -> same as symbol, but passes its values directly to PSYM
in the plots command, i.e. produces generic IDL symbols.
SYMSIZE -> symbol size. Normally, this value is adjusted auto-
matically to match the character size.
COLOR -> a number or vector of color values for the symbols.
One entry is used per symbol. If only one entry is
provided, all symbols are plotted in the same color.
Default is black.
LINE -> a vector with linestyles. Symbols and lines can be
used together. Entries with -1 are skipped.
LCOLOR -> color values for the lines
THICK -> line thickness. Can be any number of element. The
program cycles through them if there is more lines
than elements in THICK. Defaut is 1 for all.
LABEL -> a string array containing the legend text lines.
One line should correspond to one symbol. If you have a
two line entry, you can either pass it as two lines or
use the '!C' carriage return command. In both cases you
have to set the SYMBOL and LINE values that correspond
to the second line to -1 in order to skip the symbol for
it. If you use '!C', your next LABEL should be blank.
TEXTCOLOR -> A color value for the label and title output.
Default is black.
TITLE -> a title string for the legend.
CHARSIZE -> character size for all labelling. Default is to
determine the character size automatically so that the largest
LABEL and TITLE fit into the legend box. On the other hand you
can specify CHARSIZE and have the legend size itself.
SPACING -> spacing between legend lines. Default is 2, lower values
produce narrower spacing and may be useful for extensive
legends. You can set the IDL default line spacing by setting
SPACING to float(!D.Y_CH_SIZE)/!D.X_CH_SIZE.
NLINES -> number of lines the legend box shall hold. Normally,
this value is determined automatically from the maximum number
of entries in SYMBOL, PSYM, LINE, and LABEL. It may however
be useful to set NLINES manually if you want to ADD extra
curve identifiers lateron (see ADD keyword), or if your
last LABEL is a multi line entry (using the '!C' character).
FRAME -> draw a frame around the legend box. The value of FRAME
is equal to the color index that will be used to draw the
FRAME (hence /FRAME draws a black frame with MYCT).
BOXCOLOR -> a background fill color for the legend box. Default is
0 (which corresponds to white in MYCT). If you specify a
negative number, no background box is drawn and your legend
may interfere with part of the plot.
ADD -> set this keyword to add one or more entries to an existing
legend. All positioning and size keywords are ignored in this
case, and the new entries are appended at the bottom. You
should use the NLINES keyword in the first call to legend in
order to properly size your legend box, or (if you draw
no FRAME and have a neutral BOXCOLOR) you can set VALIGN to
e.g. 0.98 to start from the top of the plotting area.
Technical NOTE: adding entries to an existing legend is
most flexible with the use of the LEGSTRU keyword which will
return a structure with all necessary parameters to continue
labelling at the next call. It is also accomplished by means
of a common block to facilitate its use. In this case, you can
only continue the legend you last worked on.
LEGSTRU -> a named variable that will contain information to
continue labelling with the /ADD keyword. Needs to be passed
back into LEGEND if it shall be used. Otherwise, information
is taken from a common block.
OUTPUTS:
None
SUBROUTINES:
DRAWLEGSYM : plots a single plot symbol and line.
REQUIREMENTS:
LEGEND uses the STR_SIZE function by David Fanning
and FORMSTRLEN to determine "true" size of label strings.
If ADD keyword is used, you also need CHKSTRU.
A plot must have been produced prior to calling LEGEND
NOTES:
A few color statements require MYCT in the present form
of this program. See definitions of variables Black and
White at the beginning of the program.
EXAMPLES:
(1)
PLOT, FINDGEN(60), $
SIN(FINDGEN(60)*!PI/15.), $
COLOR=!MYCT.BLACK
LEGEND, SYMBOL=[1,2,3], $
LABEL=['Curve A','Curve B','Curve C']
; Plot a simple data curve and produce
; legend at lower right corner
(2)
LEGEND, SYMBOL=[4,5,6], $
LABEL=['Curve D','Curve E','Curve F'], $
HALIGN=0.5, $
VALIGN=0.98, $
BOXCOLOR=-1, $
CHARSIZE=1.2
; Place legend at center of x and at top of y, don't
; draw a background box, write the labels with charsize
; 1.2 and size the legend box automatically
(4)
LEGEND, SYMBOL=[1,-1,6,-1,2,-1], $
LINE=[-1,0,-1,2,-1,3], $
COLOR=[1,1,2,2,3,3], $
LCOLOR=[1,1,2,2,3,3], $
LABEL=['PEM-West A','model', $
'PEM-West B','model', $
'TRACE-A','model'], $
NLINES=8, $
FRAME=1, $
BOXCOLOR=5, $
TITLE='GTE missions', $
HALIGN=0.1, $
VALIGN=0.06, $
CHARSIZE=1.2
; Draw a legend on a yellow background. It has 6
; entries but leaves room for 2 more lines which
; will be filled later. Use different colors for
; symbols and lines. Symbols and lines are alternating.
; Draw a frame around legend and add a title.
(5)
LEGEND, SYMBOL=[4,-1], $
LINE=[-1,4], $
COLOR=4, $
LCOLOR=4, $
LABEL=['PEM-Tropics A','model'], $
/ADD
; Now add two extra entries to the last legend
; (This will use the structure stored in the
; common block)
;
; To make use of the more flexible "widget-proof"
; structure, simply add legstru=legstru to the last
; two calls.
(6)
!P.POSITION = [0.6,0.5,0.93,0.93]
RECTANGLE, !P.POSITION, XBOX, YBOX ; Get rectangle coordinates
POLYFILL, XBOX, YBOX, /NORM, COLOR=0 ; Clear rectangle
PLOT, FINDGEN(60), SIN(FINDGEN(60)*!PI/15.),$
COLOR=!MYCT.BLACK, /NOERASE
LEGEND, SYMBOL=[1,2,3],$
LABEL=['Curve A','Curve B','Curve C']
!P.POSITION = 0 ; reset !p.position
; Produce an inset plot positioned via !P.POSITION
; and add a legend. The same effect can be reached
; by passing the position=[..] parameter to the plot
; command and the same vector as PLOTPOSITION to legend.
MODIFICATION HISTORY:
mgs, 23 Jun 1998: VERSION 1.00
mgs, 24 Jun 1998: - now uses !X.Window and !Y.Window to get
default size of the plotting window (thanks DWF)
mgs, 25 Jun 1998: - added THICK keyword
mgs, 27 Oct 1998: - more room for lines
- now uses formstrlen instead of strlen
mgs, 28 Nov 1998: - box width not incremented by 1 if plotmode=0
mgs, 25 Jun 1999: - added TEXTCOLOR keyword
dbm & bmy, 23 Aug 2005: TOOLS VERSION 2.04
- now pass _EXTRA=e to XYOUTS
- cosmetic changes
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
phs, 23 Apr 2007: GAMAP VERSION 2.13
- fixes for various Thickness
(See /n/home09/ryantosca/IDL/gamap2/plotting/legend.pro)
NAME:
LITTLE_ENDIAN (function)
PURPOSE:
Determines if the computer system on which we are
running IDL has little-endian byte ordering.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = LITTLE_ENDIAN
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Returns 1 if the machine on which you are running IDL
is a little endian machine, or 0 otherwise.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, LITTLE_ENDIAN
1
; Returns 1 if we are running IDL on a
; little-endian machine, or zero otherwise
MODIFICATION HISTORY:
R.Mallozi, 02 Jul 1998: INITIAL VERSION
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/little_endian.pro)
NAME:
LOCALTIME
PURPOSE:
Returns the local time at a particular location, given the
Universal Time (aka Greenwich Time) and longitude.
CATEGORY:
Date & Time
CALLING SEQUENCE:
RESULT = LOCALTIME( UTC, LON )
INPUTS:
UTC -> Universal Time (aka Greenwich Time) in hours.
UTC may be either a scalar or a vector.
LON -> Longitude in degrees. LON may be in the range
-180..180 or 0..360. LON may be either a scalar
or a vector.
KEYWORD PARAMETERS:
/DOUBLE -> Set this switch to return local time in
double precision. Default is to return local time
in single precision.
OUTPUTS:
RESULT -> The local time corresponding to UTC and LON.
If UTC and LON are vectors, then RESULT will also
be a vector of local times.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, LOCALTIME( 0, -71.06 )
19.2627
; Returns the local time (approx 19.26 decimal, which
; is approx 19:15 PM) at Boston (lon=71.06W) when
; it is 00:00 UTC.
(2)
PRINT, LOCALTIME( 0, -71.06, /DOUBLE )
19.262667
; Same as Example (1), but returns local time
; as double precision.
(3)
PRINT, LOCALTIME( [0,1,2], -71.06, /DOUBLE )
19.262667 20.262667 21.262667
; Returns the local times at Boston (as in
; Examples (1) and (2)) when it is 00:00, 01:00,
; and 02:00 UTC time.
MODIFICATION HISTORY:
dbm, 30 Jul 2007: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/date_time/localtime.pro)
NAME:
LOGLEVELS (function)
PURPOSE:
Compute default values for logarithmic axis labeling or
contour levels. For a range from 1 to 100 these would be
1., 2., 5., 10., 20., 50., 100. If the range spans more
than (usually) 3 decades, only decadal values will be
returned unless the /FINE keyword is set.
CATEGORY:
Plotting
CALLING SEQUENCE:
RESULT = LOGLEVELS( [ RANGE | MIN=MIN, MAX=MAX ] $
[,/FINE ] [ ,COARSE=DEC ] )
INPUTS:
RANGE -> A 2-element vector with the minimum and maximum
value to be returned. Only levels _within_ this range
will be returned. If RANGE contains only one element,
this is interpreted as MAX and MIN will be assumed as
3 decades smaller. RANGE superseeds the MIN and MAX
keywords. Note that RANGE must be positive definite
but can be given in descending order in which case
the labels will be reversed.
KEYWORD PARAMETERS:
MIN, MAX -> alternative way of specifying a RANGE. If only
one keyword is given, the other one is computed as
3 decades smaller/larger than the given parameter.
RANGE superseeds MIN and MAX.
/FINE -> always return finer levels (1,2,5,...)
COARSE -> the maximum number of decades for which LOGLEVELS
shall return fine labels. Default is 3. (non-integer
values are possible).
OUTPUTS:
RESULT -> A vector with "round" logarithmic values within
the given range. The original (or modified) RANGE will
be returned unchanged if RANGE does not span at least
one label interval. The result will always contain at
least two elements.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
If COARSE is lt 0, the nearest decades will be returned
instead. The result will always have at least two elements.
If COARSE forces decades, the result values may be out-of-
range if RANGE spans less than a decade.
Caution with type conversion from FLOAT to DOUBLE !!
EXAMPLE:
RANGE = [ MIN( DATA, MAX=M ), M ]
C_LEVEL = LOGLEVELS( RANGE )
CONTOUR, ..., C_LEVEL=C_LEVEL
; Define log levels for the CONTOUR command
MODIFICATION HISTORY:
mgs, 17 Mar 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/plotting/loglevels.pro)
NAME:
LOOP
PURPOSE:
This routine provides a wrapper for function calls that accept
only scalars so that they can operate on arrays.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = LOOP( name, arg, p1, p2, p3, p4)
INPUTS:
NAME -> the name of the function (string)
ARG -> the argument (array)
P1 .. P4 -> optional function parameters
KEYWORD PARAMETERS:
Unfortunately None. Would be nice if _EXTRA would work.
OUTPUTS:
RESULT -> Vector with the same number of elements as ARG.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
A = [ 0.05, 0.01, 0.001 ]
PRINT, LOOP( "CHISQR_CVF", A, 17 )
27.5871 33.4087 40.7903
; Define a vector of arguments and then then loop
; thru the vector, calling CHISQR_CVF each time.
; Then display the vector of results.
MODIFICATION HISTORY:
mgs, 05 Dec 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/loop.pro)
NAME:
MAKE_CH_DATA
PURPOSE:
Driver program for CREATE_NESTED_DATA. Hardwired to
the North-America nested-grid of Qinbin Li.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_CH_DATA
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
None
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_CH_MET
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/make_ch_data.pro)
NAME:
MAKE_CH_MET
PURPOSE:
Driver program for CREATE_NESTED_MET. Hardwired to
the China/SE Asia nested-grid of Yuxuan Wang.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_CH_MET [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
MONYR -> Specifies the month & year (e.g. '2001/06/' )
FMASK -> File mask (default is '*')
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
None
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_NA_MET
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/make_ch_met.pro)
NAME:
MAKE_EUR_DATA
PURPOSE:
Driver program for CREATE_NESTED_DATA. Hardwired to
the North-America nested-grid of Qinbin Li.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_EUR_DATA
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_EUR_DATA
MODIFICATION HISTORY:
bmy, 15 May 2003: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/make_eur_data.pro)
NAME:
MAKE_EUR_MET
PURPOSE:
Driver program for CREATE_NESTED_MET. Hardwired to
the European nested-grid of Isabelle Bey.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_EUR_MET
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
None
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_EUR_MET
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/make_eur_met.pro)
NAME:
MAKE_MULTI_NC
PURPOSE:
Convert bpch files (matching a mask) to netCDF format.
The routine can work recursively : files in subdirectories
are also searched for.
This is a convenient generic wrapper for GAMAP routine
Bpch2coards.pro, to work on several files and directories at
once.
When working recursively, the directory tree in the input
directory is recreated as needed in the output directory.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
MAKE_MULTI_NC
INPUTS:
none
KEYWORD PARAMETERS:
MASK -> string, default is '*', that is all files
INPUT_PARENT_DIR -> top directory of files to convert, if
not specified, a dialog window pops up
OUTPUT_PARENT_DIR -> top directory destination for netCDF
files, if not specified, a dialog window pops up.
RECURSION -> to search subdirectories. Default is 0
(OFF). Set to 1 to turn it on.
TOKEN -> set if you want to replace 'bpch' with 'nc' in all
part of the full name. Default is to have extension
".nc" added to file name only.
OUTPUTS:
None
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
To work recursively on the directories, I use FILE_SEARCH
with 2 arguments. This is not possible with MFINDFILE, and
works only with IDL 5.5 and above.
EXAMPLES:
indir = '/as/data/geos/GEOS_1x1/EDGAR_200607/'
outdir = '/home/phs/data/EDGAR_200607/nc/'
mask = '*1x1'
make_multi_nc, input_parent_dir=indir, out=outdir, mask=mask, /r
MODIFICATION HISTORY:
Thu Oct 29 16:40:28 2009, Philippe Le Sager
now pass _extra keyword to BPCH2COARDS (eg /NAMER
needed for nested data)
Thu Feb 19 11:12:16 2009, Philippe Le Sager
renamed MAKE_MULTI_NC. Added recursion keyword
(default is OFF). Now **AUTOMATICALLY** creates missing
subdirectory in output directory tree, when in
recursive mode.
Tue Jan 27 10:40:49 2009, Philippe Le Sager
v1, based on make_c_nc.pro to work on several
directories at once.
bmy, 30 Nov 2010: GAMAP VERSION 2.15
- Updated comments and category in header
bmy, 01 Feb 2012: GAMAP VERSION 2.16
- Skip processing ASCII text files
mps, 04 Mar 2015: - Bug fix: Now assign InFileName before checking
file type
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_multi_nc.pro)
NAME:
MAKE_NA_DATA
PURPOSE:
Driver program for CREATE_NESTED_DATA. Hardwired to
the North-America nested-grid of Qinbin Li.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_NA_DATA
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
None
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_NA_MET
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/make_na_data.pro)
NAME:
MAKE_NA_MET
PURPOSE:
Driver program for CREATE_NESTED_MET. Hardwired to
the North-America nested-grid of Qinbin Li.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_NA_MET
INPUTS:
None
KEYWORD PARAMETERS:
MONYR -> Specifies the month & year (e.g. '2001/06/' )
FMASK -> File mask (default is '*')
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
None
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_NA_MET
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/make_na_met.pro)
NAME:
MAKE_NC_RECURSIVE
PURPOSE:
Converts files matching a mask to netCDF format.
The routine works recursively. This is a convenience
wrapper for GAMAP routine bpch2coards.pro, to work on
several directories at once.
You just need to (1) create the same directory tree in the
output location, then (2) run the routine once.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
MAKE_NC_RECURSIVE
INPUTS:
none
KEYWORD PARAMETERS:
MASK -> string, default is '*', that is all files
INPUT_PARENT_DIR -> top directory of files to convert, if
not specified, a dialog window pops up
NEW_PARENT_DIR -> top directory destination for netCDF
files, if not specified, a dialog window pops up
TOKEN -> set if you want to replace 'bpch' with 'nc' in all
part of the full name
OUTPUTS:
None
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
To work recursively on the directories, I use FILE_SEARCH
with 2 arguments. This is not possible with MFINDFILE, and
works only with IDL 5.5 and above.
EXAMPLE:
; after creating a subdirectories tree in outdir similar to the
; one in indir:
indir = '/as/data/geos/GEOS_1x1/EDGAR_200607/'
outdir = '/home/phs/data/EDGAR_200607/nc/'
mask = '*1x1'
make_nc_recursive, input_parent_dir=indir, new=outdir, mask=mask
MODIFICATION HISTORY:
Tue Jan 27 10:40:49 2009, Philippe Le Sager
v1, based on make_c_nc.pro to work on several
directories at once.
bmy, 30 Nov 2010: GAMAP VERSION 2.15
- Updated comments and categories in header
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_nc_recursive.pro)
NAME:
MAKE_PDF
PURPOSE:
Wrapper program for the Unix utility "ps2pdf". Creates
a PDF file for each PostScript file located in the
a user-specified directory.
CATEGORY:
File & I/O
CALLING SEQUENCE:
MAKE_PDF, DIR
INPUTS:
DIR -> Directory where PostScript files reside.
PDF files will be written out to this directory.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
ADD_SEPARATOR (function)
MFINDFILE (function)
REPLACE_TOKEN (function)
REQUIREMENTS:
You need "ps2pdf" installed on your system. This ships
with most versions of Unix or Linux.
Also requires routines from the GAMAP package.
NOTES:
PDF files will have the same names as the PostScript files
but with the *.pdf extension.
EXAMPLES:
MAKE_PDF, 'output'
; Create *.pdf Files from all *.ps files
; in the "output" directory.
MODIFICATION HISTORY:
bmy, 30 Nov 2010: GAMAP VERSION 2.15
- Initial version
bmy, 08 Jun 2011: - Make sure that the directory ends with a
path separator
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_pdf.pro)
NAME:
MAKE_RESTART
PURPOSE:
Creates a restart file for GEOS-Chem.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
MAKE_RESTART [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is "GEOS4_30L".
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
OUTFILENAME -> Name of the restart file that will be created.
Default is "restart.bpch".
TAU0 -> TAU value (hours from 0 GMT on 01 Jan 1985) that
that will be used to timestamp the restart file.
The default TAU0 value 140256.00 (corresponds to
0 GMT on 01 Jan 2001).
TRACERLIST -> A scalar value (or vector) of tracer numbers
to write to the restart file. Default is 1.
DATAVALUE -> Specifies the data value that will be assigned
to all grid boxes in the restart file. Default is 0e0.
DIAGN -> Specifies the diagnostic category name that will
be used to index data fields in the restart file.
Default is "IJ-AVG-$".
UNIT -> Use this keyword to overwrite the default unit
string (as specified in the "tracerinfo.dat" file)
for each data block in the restart file.
/NO_VERTICAL -> Set this switch to create a restart file
with 2-D data blocks (e.g. lon x lat) instead of 3-D
data blocks (e.g. lon x lat x alt).
DIM -> Allows you to manually set the dimensions of the
data blocks (for nested grids). DIM is passed to
CTM_MAKE_DATAINFO.
FIRST -> Allows you to manually set the starting indices
(in Fortran notation, starting from 1) of the data
block. FIRST is passed to CTM_MAKE_DATAINFO.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===================================================
CTM_GET_DATABLOCK (function) CTM_GRID (function)
CTM_MAKE_DATAINFO (function) CTM_TYPE (function)
CTM_WRITEBPCH NYMD2TAU
REQUIREMENTS:
None
NOTES:
(1) You must make sure that your "diaginfo.dat" and
"tracerinfo.dat" file lists the diagnostic categories
and tracers that you wish to save to the restart file.
EXAMPLE:
MAKE_RESTART, OUTMODELNAME='GEOS4_30L', $
OUTRESOLUTION=2, $
OUTFILENAME='restart.2x25.2005010100', $
TAU0=NYMD2TAU( 20050101L ), $
DATAVALUE=100e0, $
TRACERLIST=[1,2,3,4,5,6], $
UNIT='ppbv', $
DIAGN='IJ-AVG-$'
; Create a GEOS-4 30-level 2x25 restart file for
; CO2 tracers 1-6, setting all tracers equal to
; 100 ppbv.
MODIFICATION HISTORY:
bmy, 19 Jul 2007: VERSION 1.00
bmy, 27 Oct 2010: GAMAP VERSION 2.15
- Added DIM and FIRST for setting the
region properly for nested grids
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_restart.pro)
NAME:
MAKE_SELECTION (function)
PURPOSE:
Convert an array of selected values to an index array that
identifies the selected values in a list or data array.
CATEGORY:
General
CALLING SEQUENCE:
INDEX = MAKE_SELECTION( NAMES, SELNAMES [,keywords] )
INPUTS:
NAMES -> A list or array of values to choose from
SELNAMES -> A list of selected values
KEYWORD PARAMETERS:
ONLY_VALID -> Return only indices of found values. Values not
found are skipped. Default is to return 1 index value for
each SELNAME, which is -1 if SELNAME is not contained in
NAMES. If ONLY_VALID is set, the -1 values will be deleted,
and a value of -1 indicates that no SELNAME has been found
at all.
REQUIRED -> Normally, MAKE_SELECTION will return indices for
all values that are found, simply ignoring the selected
values that are not in the NAMES array (although an error
message is displayed). Set this keyword to return with
-1 as soon as a selected value is not found.
QUIET -> Suppress printing of the error message if a
selected value is not found (the error condition will
still be set).
OUTPUTS:
INDEX -> A (long) array with indices to reference the
selected values in the NAMES array.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
If the NAMES array contains multiple entries of the same value,
only the index to the first entry will be returned.
A selection can contain multiple instances of the same value.
The index array will contain one entry per selected item
(See example below)
EXAMPLES:
(1)
NAMES = [ 'Alfred','Anton','Peter','John','Mary']
INDEX = MAKE_SELECTION( NAMES, ['Peter','Mary'] )
PRINT, INDEX
2 4
(2)
VALS = INDGEN(20)
INDEX = MAKE_SELECTION( VALS, [9,-5,8,7,7,8,9] )
PRINT, INDEX
9 -1 8 7 7 8 9
(3)
INDEX = MAKE_SELECTION( VALS,[9,-5,8,7,7,8,9], /ONLY_VALID )
PRINT, INDEX
9 8 7 7 8 9
(4)
INDEX = MAKE_SELECTION( vals, [9,-5,8,7,7,8,9], /REQUIRED )
PRINT, INDEX
-1
MODIFICATION HISTORY:
mgs, 28 Aug 1998: VERSION 1.00
mgs, 29 Aug 1998: - changed behaviour and added ONLY_VALID keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/make_selection.pro)
NAME:
MAPS
PURPOSE:
Creates lon-lat maps of GEOS-Chem tracers at the
surface and 500 hPa levels.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
MAPS, FILE, LEVELS, TAUS, TRACERS, VERSION, [, Keywords ]
INPUTS:
FILE -> The name of the file containing data to be plotted.
LEVELS -> A 4-element vector containing the level indices
for the GEOS-Chem surface layer and 500 hPa layer.
for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
NOTE: This is in Fortran notation (starting from 1!)
TAU -> The TAU value (hours GMT from /1/1985) corresponding
to the data to be plotted.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSION -> The model version number corresponding to the
data to be plotted.
KEYWORD PARAMETERS:
/DO_FULLCHEM -> Set this switch to plot the chemically
produced OH in addition to the advected tracers.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Provided:
==================================================
PlotMap
External Subroutines Required:
==================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA EXTRACT_FILENAME (function)
GETMODELANDGRIDINFO MULTIPANEL
MYCT OPEN_DEVICE
TVMAP CHKSTRU (function)
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILE = 'ctm.bpch.v7-04-11'
LEVELS = [ 1, 1, 13, 13 ]
TAUS = NYMD2TAU( 20010701 )
TRACERS = INDGEN( 43 ) + 1
VERSIONS = 'v7-04-11'
MAPS, FILE, LEVELS, TAU, TRACERS, VERSION, $
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'
; Creates tracer maps of GEOS-CHEM v7-04-11 for July 2001.
; Output is sent to PostScript file "myplot.ps".
MODIFICATION HISTORY:
bmy, 14 Nov 2007: VERSION 1.01
- Based on "tracer_map.pro"
bmy, 07 May 2008: VERSION 1.06
- Now allow for comparing models on 2
bmy, 08 Jun 2011: VERSION 1.07
- Added /DO_FULLCHEM keyword
- Now restore !MYCT sysvar to previous
settings upon exiting the program
mps, 29 Mar 2013: - Now plot chemically produced HO2
(See /n/home09/ryantosca/IDL/gamap2/benchmark/maps.pro)
NAME:
MAPS_AOD
PURPOSE:
Creates column maps of aerosol optical depths from 1-month
GEOS-Chem benchmark simulation output.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
MAPS_AOD_1YR, FILES, TRACERS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "red", 'green", and "blue" GEOS-Chem model
versions that are to be compared.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$") to be plotted.
VERSIONS -> A 2-element vector containing the model version
names from the "red", 'green", and "blue" simulations.
KEYWORD PARAMETERS:
/DYNRANGE -> Set this switch to create plots using the entire
dynamic range of the data (centered around zero). The
default is to use pre-defined data ranges.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Provided:
=========================================
PLOTDIFF
External Subroutines Required:
=========================================
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL COLORBAR_NDIV (function)
CTM_PLOT CHKSTRU (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLE:
FILES = [ 'ctm.bpch.v9-02p', 'ctm.bpch.v9-02q' ]
TAUS = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
TRACERS = [ 1, 2, 4 ]
VERSIONS = [ 'v9-02p', 'v9-02q' ]
DIFFERENCES_1YR, FILES, TAUS, TRACERS, VERSIONS, $
/PS, OUTFILENAME=myplot.ps'
; Creates maps from 2 different model versions
; using output from GEOS-Chem 1-month benchmark simulations.
DIFFERENCES_1YR, FILES, TAUS, TRACERS, VERSIONS, /DYNRANGE, $
/PS, OUTFILENAME=PSNAME
; Same as above, but will create difference maps using
; the full dynamic range of the data (centered around zero)
; instead of using pre-defined min & max values.
MODIFICATION HISTORY:
bmy, 05 Sep 2012: VERSION 1.01
- Initial version
mps, 16 Sep 2013: - Modified for 1-month benchmark output
bmy, 24 Jan 2014: GAMAP VERSION 2.17
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/benchmark/maps_aod.pro)
NAME:
MAP_LABELS
PURPOSE:
Constructs map labels from numerical values, in either
numerical format (e.g. "-90", "0", "90" ), or in
directional format ( e.g. "90S, "0", "90N" ).
CATEGORY:
Plotting
CALLING SEQUENCE:
MAP_LABELS, LATLABEL, LONLABEL [ , Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
LATRANGE, LONRANGE -> The range of latitudes (longitudes)
for the map or plot area.
LATS, LONS -> Returns to the calling program the array of
latitudes (longitudes) used to construct the map labels.
Can also be use as input: if LATS has one element, the
LATS vector is build with LATS+n*DLAT; if it has more
than one element, it is not modified and is the final
grid.
DLAT, DLON -> Returns to the calling program the latitude
(longitude) interval between grid lines.
Now, can also be used as input so the user can specify
the grid spacing.
/MAPGRID -> If set, will assume that latitude and longitude
labels are for grid lines on a world map. Also compute
normal coordinates which can be used for placing the
labels next to the map.
NORMLATS -> 2D Array containing normal X and Y
coordinates for placing latitude labels outside map
boundaries. These are computed only if /MAPGRID is set.
NORMLONS -> 2D-Array containing normal X and Y
coordinates for placing latitude labels outside map
boundaries. These are computed only if /MAPGRID is set.
Keywords Passed to CONSTRUCT_MAP_LABELS:
========================================
FORMAT -> Format descriptor string used in converting the
values from DATA into string representation. The
default value is '(i10)'.
/NUMERIC -> If set, will return latitude or longitude
labels in numerical format (e.g. "-90", "0", "+90").
If not set, will return latitude or longitude labels
in directional format (e.g. "90S, "0", "90N")
/NODEGREE -> If set, will prevent the raised degree symbol
from being appended to MAPLABEL. Default is to add the
raised degree symbol to MAPLABEL.
OUTPUTS:
LATLABEL -> String array of latitude labels
LONLABEL -> String array of longitude labels
SUBROUTINES:
Internal Subroutines Used:
=================================
CONSTRUCT_MAP_LABELS (function)
GET_GRIDSPACING
External Subroutines Required:
=================================
STRREPL (function)
REQUIREMENTS:
None
NOTES:
(1) LATLABEL and LONLABEL are in the range of -180..180 degrees.
(2) We should at some point allow the user to supply individual values
that override the default spacing.
EXAMPLES:
(1) For use in conjunction with the PLOT command...
MAP_LABELS, YTICKNAME, XTICKNAME, $ ; Call MAP_LABELS
LATRANGE=[ -90,90], LONRANGE=[-180,180], $ ; to get the
LATS=LATS, LONS=XTICKV, $ ; lat and lon
_EXTRA=e ; tick labels
PLOT, XARR, YARR, XTICKV=XTICKV, $ ; call PLOT,
XTICKNAME=XTICKNAME, $ ; using the
XTICKS=N_ELEMENTS( XTICKV )-1, $ ; labels as
_EXTRA=e ; tick names
(2) For use in conjunction with MAP_SET and MAP_GRID
LIMIT = [ -90, -180, 90, 180 ] ; set up the
MAP_SET, LIMIT=Limit, _EXTRA=e ; world map
LATRANGE = [ Limit[0], Limit[2] ] ; define lat and
LONRANGE = [ Limit[1], Limit[3] ] ; lon ranges
MAP_LABELS, LATLABEL, LONLABEL, $ ; call MAP_LABELS
LATS=LATS, LATRANGE=LATRANGE, $ ; to return
LONS=LONS, LONRANGE=LONRANGE, $ ; the lat/lon
NORMLATS=NORMLATS, NORMLONS=NORMLONS, $ ; values, labels
/MAPGRID, _EXTRA=e ; normal coordinates
MAP_GRID, LATS=LATS, LONS=LONS, _EXTRA=e
; Plots the grid lines on the map
XYOUTS, NORMLATS[0,*], NORMLATS[1,*], $
LATLABEL, ALIGN=1.0, /NORMAL
; Plots latitude labels using normal coordinates
XYOUTS, NORMLONS[0,*], NORMLONS[1,*], $
LONLABEL, ALIGN=0.5, /NORMAL
; Plots longitude labels using normal coordinates
(2) For use in conjunction with TVMAP to control grid
TVMAP, DIST(42)
MODIFICATION HISTORY:
mgs, 19 Feb 1999: VERSION 1.00
bmy, 26 Feg 1999: VERSION 1.10
- now works for maps that are smaller
than global size.
bmy, 04 Mar 1999: VERSION 1.11
- added DEBUG keyword for output
- now computes NORM_XLAT correctly for
grids that are centered on -180 degrees
mgs, 17 Mar 1999: - cleaned up
- replaced Norm[XY]... by two dimensional
NormLons and NormLats
- Longitude conversion now done in CONSTRUCT_...
- calls MAP_SET if /MAPGRID is set and no
map has been established.
bmy, 25 Mar 1999: - double default DLON if more than 2 plots
per page
mgs, 23 Apr 1999: - bug fix for LON labels in Pacific mode
mgs & bmy, 03 Jun 1999: - fix for Pacific ranges in GET_GRIDSPACING
bmy, 17 Nov 2005: GAMAP VERSION 2.04
- Now allows for a spacing of 1 degree
if the plot range is smaller or equal to
10 degrees
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 29 Feb 2008: GAMAP VERSION 2.12
- Grid spacing can be set by user with
DLON and DLAT
- LONS/LATS can be use as input to specify
the start (if 1 element) or the entire
grid (more than 1 element)
- GET_GRIDSPACING is now a procedure
phs, 14 Mar 2008: - Added a new method to find the Labels
position. This can be used to overwrite
the old position with two new keywords,
NEWLONLAB and NEWLATLAB. Useful for map
projection defined with SCALE instead
of LIMIT. Need to pass MapPosition to work.
(See /n/home09/ryantosca/IDL/gamap2/plotting/map_labels.pro)
NAME:
MCF_LIFETIME
PURPOSE:
Computes the methylchloroform (CH3CCl3, aka "MCF") lifetime
w/r/t tropospheric OH from monthly-mean GEOS-Chem archived
fields.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
MCF_LIFETIME, FILE, [ Keywords ]
INPUTS:
FILE -> Specifies the name of the file with GEOS-Chem
diagnostic output (bpch format or otherwise).
KEYWORD PARAMETERS:
LON -> A 2-element vector containing the minimum and maximum
longitude values to include in the computation of the MCF
lifetime. Default is [ -180, 180 ].
LAT -> A 2-element vector containing the minimum and maximum
latitude values to include in the computation of the MCF
lifetime. Default is [ -90, 90 ].
LEV_a -> A 2-element vector containing the minimum and maximum
levels (i.e. all vertical levels) to include in the
computation of the MCF lifetime. Default is [ 1, 47 ]
(corresponding to the GEOS-5 47-level simulation).
LEV_t -> a 2-element vector containing the minimum and
maximum tropospheric levels to include in the
computation of the MCF lifetime. Default is [ 1, 38 ]
(corresponding to the value of the max tropospheric
level LLTROP for a GEOS-5 47-level simulation.)
TAU0 -> TAU value (hours from 0 GMT on 1985/01/01) with which
the GEOS-Chem diagnostic data blocks are timestamped.
Default is 179664.00 (corresponding to 0 GMT on
2005/07/01).
/VERBOSE -> Will cause MCF_LIFETIME to print the methyl
chlofororm lifetime to the screen. The default is to
suppress printing.
OUTPUTS:
LIFE_YEARS -> Returns the MCF lifetime w/r/t tropopsheric
OH in years.
SUBROUTINES:
External subroutines required:
==============================
CTM_BoxSize (function)
CTM_Get_DataBlock (function)
Nymd2Tau (function)
REQUIREMENTS:
MCF_LIFETIME requires that the following GEOS-Chem
diagnostics be present in the input file:
(a) Grid box surface area [m2 ] (DXYP, tracer #1)
(b) Grid box heights [m ] (BXHGHT-$, tracer #1)
(c) Air number density [molec/m3 ] (BXHGHT-$, tracer #4)
(d) Chemically produced OH [molec/cm3] (CHEM-L=$, tracer #1)
(e) Time spent in tropopause [fraction ] (TIME-TPS, tracer #1)
(f) Temperature [K ] (DAO-3D-$, tracer #5)
Requires routines from the GAMAP package.
NOTES:
Derivation of MCF lifetime w/r/t tropospheric OH
----------------------------------------------------------
We assume that MCF has a uniform mixing ratio in air (=1).
Thus the density of air can be substituted for the density
of MCF in the equations below.
The lifetime of MCF w/ respect to tropospheric OH is:
T_OH = Atmospheric Burden / Tropospheric loss rate
The atmospheric burden of MCF is:
SUM{ AIRDEN(I,J,L) * VOLUME(I,J,L) }
where:
I = longitudes
J = latitudes
L = levels from the surface to top of atmosphere
AIRDEN = Air density at ([I,J,L) in molec/cm3
VOLUME = Grid box volume at (I,J,L) in cm3
The tropospheric loss rate of MCF is:
SUM{ K(I,J,X) * OH(I,J,X) * AIRDEN(I,J,X) * VOLUME(I,J,X) }
where
I = longitudes
J = latitudes
X = levels from the surface to the
location of the tropopause at (I,J)
(we only count boxes fully in the tropopause)
K(I,J,X) = 1.64e-12 * EXP( -1520 / T(I,J,X) )
T(I,J,X) = Temperature at grid box (I,J,X)
T_OH has several reported values in the literature:
(a) Spivakovsky et al (2000) : 5.7 years
(b) Prinn et al (2001) : 6.0 years
Derivation of total MCF lifetime:
----------------------------------------------------------
Once you have obtained the MCF lifetime w/r/t tropospheric
OH, you can compute the total lifetime of MCF as:
1/T_total = 1/T_OH + 1/T_strat + 1/T_ocean
where
T_total = total lifetime of MCF in atmosphere
T_OH = the output of this function
T_strat = 43 years (cf. Spivakovsky et al)
T_ocean = 94 years (range 81-145 years, cf WMO/UNEP)
References:
----------------------------------------------------------
(1) Prather, M. and C. Spivakovsky, "Tropospheric OH and
the lifetimes of hydrochlorofluorocarbons", JGR,
Vol 95, No. D11, 18723-18729, 1990.
(2) Lawrence, M.G, Joeckel, P, and von Kuhlmann, R., "What
does the global mean OH concentraton tell us?",
Atm. Chem. Phys, 1, 37-49, 2001.
(3) WMO/UNEP Scientific Assessment of Ozone Depletion: 2010
EXAMPLE:
LIFE = MCF_LIFETIME( 'ctm.bpch', $
LON=[-180,-180], $
LAT=[ -90, 90], $
LEV_A=[ 1, 47 ], $
LEV_T=[ 1, 38 ], $
TAU0=NYMD2TAU( 20050101 ) )
; Will return the MCF lifetime w/r/t tropospheric OH
; (in years) based on GEOS-Chem diagnostic output at
; model date 2005/01/01.
MODIFICATION HISTORY:
bmy, 08 Jun 2011: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/benchmark/mcf_lifetime.pro)
NAME:
MEAN
PURPOSE:
Computes the mean value of an array, along a given dimension.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = MEAN( X, DIM, _EXTRA=e )
INPUTS:
X -> The input vector or array.
DIM -> The dimension along which to compute the mean of X.
DIM may be omitted if the X is 1-dimensional.
KEYWORD PARAMETERS:
_EXTRA=e -> Passes extra keywords to the TOTAL command.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
Multidimensional version from Kevin Ivory (04/03/1997)
EXAMPLES:
(1)
PRINT, MEAN( FINDGEN(10) )
IDL prints:
4.50000
; Prints the mean of a 1-D array
(2)
ARRAY = MEAN( DIST(10,10), 2 )
HELP, ARRAY
PRINT, ARRAY
IDL prints:
ARRAY FLOAT = Array[10]
2.50000 2.79703 3.36695 4.08519 4.89073
5.75076 4.89073 4.08519 3.36695 2.79703
; Prints the mean of a 2-D array along
; the second dimension.
MODIFICATION HISTORY:
ivory, 04 Mar 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Cosmetic changes, added comments
(See /n/home09/ryantosca/IDL/gamap2/math_units/mean.pro)
NAME:
MERGE_FERT_SOILPREC
PURPOSE:
Merges nonzero soil fertilizer and soil precipitation
data onto the same indexing scheme. Also computes
NLAND, the number of land boxes used in "commsoil.h".
CATEGORY:
Regridding
CALLING SEQUENCE:
MERGE_FERT_SOILPREC [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
FERTFILE -> Name of the binary punch file containing soil
fertilizer data to be merged. The default file name
is hardwired (change as necessary).
SOILPRECFILE -> Name of the binary punch file containing soil
precipitation data to be merged. The default file name
is hardwired (change as necessary).
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
OUTPUTS:
Writes to ASCII output files:
fert_scale.dat.{MODELNAME}.{RESOLUTION}
climatprep{RESOLUTION}.dat.{MODELNAME}
SUBROUTINES:
External Subroutines Required:
==============================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
REQUIREMENTS:
None
NOTES:
(1) Input files must be binary punch files, created with
routines REGRID_FERT and REGRID_SOILPREC.
(2) Output files are in ASCII format and are compatible
with the existing Harvard CTM routines.
EXAMPLE:
MERGE_FERT_PRECIP, FERTFILE='nox_fert.geos1.2x25', $
PRECIPFILE='soil_precip.geos1.2x25', $
OUTDIR='/scratch/bmy'
; Will merge the soil fertilizer data contained in
; "nox_fert.geos1.2x25" and the soil precip data
; contained in soil_precip.geos1.2x25". Output files
; will be sent to the /scratch/bmy directory.
MODIFICATION HISTORY:
bmy, 04 Aug 2000: VERSION 1.00
- adapted from older IDL code
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/merge_fert_soilprec.pro)
NAME:
MERGE_OH
PURPOSE:
Creates a "Merged OH" file, with OH from the GEOS-CHEM
model in the troposphere and zonal mean OH from a 2-D
model in the stratosphere.
CATEGORY:
Regridding
CALLING SEQUENCE:
MERGE_OH, MODELNAME
INPUTS:
None
KEYWORD PARAMETERS:
MODELNAME -> Name of the model (e.g. GEOS1, GEOS-STRAT)
for which we are going to merge tropospheric OH with
stratospheric OH.
RESOLUTION -> Horizontal latitude resolution of the grid.
RESOLUTION=2 specifies 2 x 2.5 grid and
RESOLUTION=4 specifies 4 x 5 grid.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
====================================================
CTM_TYPE (function) CTM_GET_DATABLOCK (function)
CTM_GRID (function) CTM_MAKE_DATAINFO
REQUIREMENTS:
None
NOTES:
(1) The output file name has the form:
OH_3Dglobal.{MODELNAME}.{RESOLUTION}
(2) Filenames are currently hardwired for 4x5,
EXAMPLE:
MERGE_OH, MODELNAME='GEOS3', RESOLUTION=4
; Will merge stratospheric and tropospheric OH
; at the GEOS-1 4 x 5 resolution into a single
; binary punch file.
MODIFICATION HISTORY:
bey, 21 Jul 2000: VERSION 1.00
bmy, 11 Aug 2000: VERSION 1.01
- added standard header, updated comments
- renamed to "merge_oh.pro"
bmy, 04 Feb 2002: VERSION 1.02
- rewrote for expediency
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/merge_oh.pro)
NAME:
MFINDFILE
PURPOSE:
Find all the files that match a given specification.
MFINDFILE is a wrapper for IDL routines FILE_SEARCH
(v5.5 and higher) and FINDFILE (v5.4 and lower).
CATEGORY:
File & I/O
CALLING SEQUENCE:
LISTING = MFINDFILE( MASK )
INPUTS:
FILEMASK -> a path and filename specification to look for.
KEYWORD PARAMETERS:
none
OUTPUTS:
A string list containing all the files that match the
specification.
SUBROUTINES:
External Routines Required:
===========================
ADD_SEPARATOR (function)
REQUIREMENTS:
None
NOTES:
(1) For IDL 5.5+, use FILE_SEARCH to return a listing of
files with the given path name specified by MASK. This
should work regardless of platform.
(2) For IDL 5.4- running under Unix, The built-in FINDFILE()
function has problems on whenever a lot of files are
matching the file specification. This is due to the fact
that filename expansion is done by the shell before
interpreting a command. Too many files cause too long
commands which are not accepted. This causes FINDFILE()
to return an empty list of candidates. (cf. www.dfanning.com)
Therefore, we implement a workaround where we issue a
"ls -1" command under the Unix shell. This isn't 100%
foolproof either but it's better than nothing.
(3) For IDL 5.5- running under other operating systems,
call the built-in IDL FINDFILE routine as usual.
EXAMPLE:
LIST = MFINDFILE( '~mgs/terra/chem1d/code/*.f' )
; returns all fortran files in Martin's chem1d directory.
MODIFICATION HISTORY:
mgs, 14 Sep 1998: VERSION 1.00
bmy, 14 Oct 2003: TOOLS VERSION 1.53
- Now use built-in FINDFILE() routine to
return file listing for IDL 5.3 and higher
bmy, 06 Nov 2003: TOOLS VERSION 2.01
- return to pre v1-53 algorithm
bmy, 28 May 2004: TOOLS VERSION 2.02
- For IDL 5.5+, now use FILE_SEARCH to return
a list of files corresponding to MASK
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/mfindfile.pro)
NAME:
MODEL2AIRNUMDENS
PURPOSE:
Returns the monthly averaged Air Number Density in
each grid box for one GEOS-Chem model.
This let you get the Number Density from the average monthly
pressure of the model.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
airNumDens = Model2AirNumDens( Model [, tau] )
INPUTS:
Model : string for model name ("GEOS4_30L", "GEOS5_47L", ...)
OPTIONAL INPUTS:
Tau : tau0 for which Air Numb density is look for. The year
does not matter, the month value is extracted. Default
is 0D0, which selects January.
OUTPUTS:
A 3D array (same size as the model 3D grid) with Air
Density Number in [molec/cm3].
PROCEDURE:
GetModelAndGridInfo, DataInfo, Model, Grid
airnumden = Model2AirNumDens( CTM_NamExt( Model ), DataInfo.tau0 )
MODIFICATION HISTORY:
Wed Sep 2 10:54:41 2009, Philippe Le Sager
Gamap v2.13 - Init version
bmy, 30 Nov 2010: GAMAP VERSION 2.15
- Updated comments and category in header
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/model2airnumdens.pro)
NAME:
MULTIPANEL
PURPOSE:
This routine provides an easy-to-use interface to
IDL's !p.multi mechanism and it can be used
to retrieve the position vector of the next plot
in line (even if !p.multi is not set). You can
specify plot margins and a page margin in normalized
coordinates.
For multi-panel plots, multipanel works in three
stages (somewhat similar to XInterAnimate):
1) set up a multi-panel page by specifying the number
of rows and columns or the maximum number of plots
on the page.
2) advance to the next plot position and return that
position. If the page was filled (i.e. the maximum
number of plots (advance steps) has been made, it
will be erased (unless /NOERASE is set).
3) turn the multi-panel environment off and reset margin
values.
Subsequent PLOT, MAP_SET, etc. commands should use the
POSITION vector returned from this routine and they should
use the /NOERASE keyword.
CATEGORY:
Plotting
CALLING SEQUENCE:
Get position of next plot
MULTIPANEL,position=p
Setting up multi-panel pots
MULTIPANEL,[rows=r,cols=c | nplots=n] [,options]
Advance to the next panel (and get its position)
MULTIPANEL,/advance [,position=p] [,options]
Reset multi-panel environment to start over at the first panel
MULTIPANEL,/reset [,options]
Turn multi-panel environment off (reset !p.multi and some other
parameters)
MULTIPANEL,/OFF
INPUTS:
Optionally you can give the number of plots (keyword NPLOTS) as
a parameter instead. Th euse of a parameter will override the
keyword.
KEYWORD PARAMETERS:
General keywords (honored under all circumstances)
-------------------------------------------------------------------
POSITION -> Returns a 4-element vector with the position of
the next plot in the line. As always this vector contains
[X0,Y0,X1,Y1].
MARGIN -> specify a margin around the plot in normalized
coordinates. This keyword does not change any IDL
system variables and will thus only become "visible"
if you use the POSITION returned by MULTIPANEL in subsequent plot
commands.
MARGIN can either be one value which will be applied to
all four margins, or a 2-element vector which results in
equal values for the left and right and equal values for
the bottom and top margins, or a 4-element vector with
[left,bottom,right,top].
OMARGIN -> specify a page margin around all panels in normalized
coordinates. Works like MARGIN.
Note that you can change the values of MARGIN and OMARGIN after
you set up your plot page. The values given with MARGIN and OMARGIN
remain active until you specify a new one or use the /OFF keyword.
/NOERASE -> This keyword prevents erasing the screen (or page)
when setting a multi-panel environment or after a page was
filled. NOERASE is automatically turned ON when the /OFF
keyword is given.
Informational keywords:
-------------------------------------------------------------------
FIRSTPANEL -> returns 1 if the current plotting panel is
the first one on a page
LASTPANEL -> returns 1 if the current plotting panel is the last
on a page
Setting up a multi-panel page:
-------------------------------------------------------------------
ROWS, COLS -> specify the number of rows and columns
you want on your page. If one is specified, the
other one must be given as well. Alternatively,
you can use the NPLOTS keyword.
NPLOTS -> maximum number of plots on one page. The
number of rows and columns is automatically computed
so that the plots "approach a square" and they are
returned in the ROWS and COLS keywords. Setting
NPLOTS to a ROWS*COLS value is equivalent to using
ROWS and COLS. If you specify an "uneven" number
(e.g. 5), multipanel,/advance will erase the page
after 5 plots instead of 6.
/PORTRAIT -> Normally, ROWS tends to be larger than COLS
when NPLOTS is used (e.g. 12 gives 4 rows and 3 cols).
Use this keyword to revert this behaviour.
/LANDSCAPE -> Make ROWS larger than COLS if necessary. This
is the default. Thi skeyword is actually unnecessary and
was introduced for purely aesthetic reasons (symmetry).
Advance to the next plot:
-------------------------------------------------------------------
/ADVANCE -> this keyword issues a hidden plot command to find
out the position of the next plot to be made. The position
is then returned in the POSITION keyword. The value of
!P.MULTI[0] is increased afterwards so that you can issue
your plot command without explicitely specifying the
position or /NOERASE. When the maximum number of plots set
with NPLOTS is reached, MULTIPANEL,/ADVANCE will erase the
screen and reset the plot position to the upper left corner.
CURPLOT -> use this keyword to advance to a specific plot position
on the page. If you specify 0, the screen will be erased.
CURPLOT also returns the current plot number. If you don't
want to set the plot number but just query it, you must pass
an undefined variable (see procedure UNDEFINE.PRO).
Reset the plot position (and erase the screen)
-------------------------------------------------------------------
/RESET -> does just this.
Turn multi-panel environment off
-------------------------------------------------------------------
/OFF -> Overrides all other keywords. Resets !p.multi to 0.
OUTPUTS:
none.
SUBROUTINES:
function GET__PLOTPOSITION() issues a dummy plot command
and returns the plot position from the ![xy].window
variables.
REQUIREMENTS:
none. (example uses RECTANGLE.PRO)
NOTES:
Side effect: Opens a window in standard size if none was open
before. This happens because the next plot position is
determined by issuing a hidden (or dummy) plot command with
no visible output.
Make sure to use POSITION=P,/NOERASE with all your PLOT, MAP_SET
CONTOUR, etc. commands. In fact, you don't _need_ /NOERASE for
PLOT, but it guarantees consistent behaviour with MAP_SET etc.)
A PLOT command without /NOERASE will advance to the next panel
and thereby interfere with MULTIPANEL's plot counter.
If you don't use MARGIN and OMARGIN, the values in ![XY].margin
![XY].omargin will take effect.
A common block is used to store the current plot number and
margin information. This limits the use to one window at a time
(although you can save all parameters elsewhere and supply them
to the routine on a window-by-window basis).
EXAMPLES:
(1)
MULTIPANEL, position=p
PLOT, findgen(10), color=1, position=p, /noerase
; Just retrieve the position of the next plot
(2)
MULTIPANEL, MARGIN=[0.1,0.05], POSITION=P
PLOT, FINDGEN(10), COLOR=1, POSITION=P, /NOERASE
; same thing but use a specific margin (2-element form)
;
; If you want to see both previous plots together use
; /NOERASE with MULTIPANEL
(3)
; Set up for 5 plots
MULTIPANEL, NPLOTS=5
FOR I = 0, 4 DO BEGIN
; Get current plot position
MULTIPANEL, POSITION=P, MARGIN=0.04
; Do the plot
PLOT, FINDGEN(10), COLOR=!MYCT.BLACK,$
POSITION=P, /NOERASE
; Go to the next panel
; Note that the screen would be erased after the last plot
; without the /NoErase keyword.;
MULTIPANEL, /ADVANCE, /NOERASE
ENDFOR
; Multi-panel example
(4)
MULTIPANEL, /OFF, OMARGIN=0.01, MARGIN=0., $
POSITION=P, /NOERASE
RECTANGLE, P, XVEC, YVEC
PLOTS, XVEC, YVEC, COLOR=!MYCT.BLACK, /NORM
; Now let's draw a frame around everything
MODIFICATION HISTORY:
mgs, 19 Mar 1999: VERSION 1.00
mgs, 22 Mar 1999: - improved documentation, changed OMARGIN
to accept normalized coordinates.
- position now also returned if turned OFF
- added FIRSTPANEL and LASTPANEL keywords
- allow NPLOTS to be specified as parameter
mgs, 02 Jun 1999: - now saves old values of !X, !Y, and !P
and restores them when turned OFF.
mgs, 03 Jun 1999: - save !X, !Y, and !P only if !p.multi was
really off
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/plotting/multipanel.pro)
NAME:
MULTISORT
PURPOSE:
hierarchical sorting of a data set, each column can be sorted
reversely. Works well together with W_SORT, a widget interface
that handles up to three sort levels/columns. COLUMNS are defined
as first array index (e.g. DATA=FLTARR(5,20) has 5 columns).
CATEGORY:
Math & Units
CALLING SEQUENCE:
multisort,data,index=index,revert=revert
INPUTS:
DATA --> a 2D array to be sorted
KEYWORD PARAMETERS:
INDEX --> an integer or integer array containing the indices for
which the array shall be sorted (e.g. [ 3,1,0 ] will sort DATA
first by column 3, then within groups of same values for column
3 values will be sorted by column 1, and finally by column 0.
Default is to sort by the first column.
REVERT --> an integer or integer array indicating which columns shall
be sorted in reverse order. REVERT=1 reverts all sorting,
REVERT=[0,1,0] reverts the sort order only for the 2nd column.
Default is 0, i.e. do not revert.
OUTPUTS:
The DATA array will be sorted according to the specifications.
SUBROUTINES:
testsort : little test program (historic debugging purposes)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
MULTISORT, DATA, INDEX=[3,1,0], REVERT=[0,1,0]
; Sort data first in column 3, then in reverse order
; for column 1, and finally ascending order for column 0.
MODIFICATION HISTORY:
mgs, 30 Jun 1997: VERSION 1.00
mgs, 08 Apr 1998: - now stand-alone routine and documentation
mgs, 22 Dec 1998: - bug fix (startindex must be -1)
mgs, 17 Mar 1999: - bug fix: now has default 0 for revert
(thanks to G. Fireman)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/multisort.pro)
NAME:
MYCT
PURPOSE:
Define a set of standard drawing colors and load a colortable
on top of these. The color table can be manipulated in various
ways (see KEYWORD PARAMETERS).
The standard MYCT drawing colors are as follows. These
were implemented by Chris Holmes, based on the ColorBrewer
definitions. These colors are less saturated than the
traditional MYCT drawing colors, and are easier to read
on the screen:
0 : white 9 : lightblue
1 : black 10 : lightorange
2 : red 11 : lightpurple
3 : green 12 : 85% grey
4 : blue 13 : 67% grey
5 : orange 14 : 50% grey
6 : purple 15 : 33% grey
7 : lightred 16 : 15% grey
8 : lightgreen 17 : white
However, if you use the /BRIGHT_COLORS keyword to MYCT, you
may still use the traditional MYCT drawing colors (which were
created by Martin Schultz). These are defined as follows:
0 : white 9 : lightgreen
1 : black 10 : lightblue
2 : red 11 : black
3 : green 12 : 85% grey
4 : blue 13 : 67% grey
5 : yellow 14 : 50% grey
6 : magenta 15 : 33% grey
7 : cyan 16 : 15% grey
8 : lightred 17 : white
With MYCT, you may load any of the standard IDL color tables
or any of the ColorBrewer color tables. For backwards
compatibility, MYCT also supports several customized color
tables that used to be defined with the CUSTOM_COLORTABLE
routine.
MYCT reads color table definitions from an IDL *.tbl file.
The default file name is "gamap_colors.tbl". You may specify
a different file with the CTFILE keyword (see below). Also,
if you wish to add a custom color table, the best way to
proceed is to create your own *.tbl file with your custom
color table definitions. See the routine GAMAP_COLORS for
more information.
CATEGORY:
Color
CALLING SEQUENCE:
MYCT, [ TABLE ] [ , keywords ]
INPUTS:
TABLE (optional) -> Number or name of the IDL color table
to be used. If no number or name is provided, the
routine will default to color table 0 (which for the
"gamap_colors.tbl" file is B-W LINEAR). The MYCT
drawing colors will be loaded first, and the color
table will be loaded on top of that. You can choose
the bottom color index for the color table with the
BOTTOM keyword. MYCT will ensures that the system
variable !D.N_COLORS is set correctly.
KEYWORD PARAMETERS:
/BRIGHT_COLORS -> Selects the older set of MYCT drawing colors
to be loaded at the bottom of the colortable. Default is
to select the newer set of MYCT drawing colors, which
are less saturated and easier to read on the screen.
BOTTOM -> specify where to start color table (see BOTTOM keyword
in LOADCT). Default is number of standard drawing colors+1
or 0 (if NO_STD is set). If BOTTOM is less than the number
of standard drawing colors (17), no standard colors will be
defined (equivalent to setting NO_STD). RANGE has no
effect on the DIAL/LIDAR colortable. Default is 18.
NOTE: You should not normally have to change this value.
CTFILE -> Specify a file containing the color table
definitions. Default is "gamap_colors.tbl", which is
a combination of the standard IDL color tables plus
the ColorBrewer color tables. (See routine GAMAP_COLORS.)
NCOLORS -> number of color indices to be used by the color table.
Default is !D.N_COLORS-BOTTOM.
/NO_STD -> prevents definition of standard drawing colors.
RANGE -> a two element vector which specifies the range of colors
from the color table to be used (fraction 0-1). The colortable
is first loaded into the complete available space, then
the selected portion is interpolated in order to achieve the
desired number of colors. RANGE is only effective when
a TABLE parameter is given. RANGE has no effect on the
customized colortables.
/REVERSE -> Set this switch to reverse the color table.
/REVERSE works for both IDL and custom color tables.
SATURATION -> factor to scale saturation values of the extra
color table. Saturation ranges from 0..1 (but the factor
is free choice as long as positive). SATURATION has no
effect on the customized colortables. Default is 1.
USERDEF -> set to load the user defined colortable. The table
is defined in the Define_UserDef routine. It can be
loaded in three different ways:
MyCt, -1
MyCt, /user
MyCt, 'user'
In the later version, the string is not case sensitive,
and can be any string that contains the word "user".
VALUE -> factor to scale the "value" of the added colortable.
(i.e. this is like the contrast knobon a TV set). Value
ranges from 0..1; 0 = black, 1 = white. Default is 1.
/USE_CURRENT -> By default, MYCT will reset the color table
to all white before loading a new colortable. Set
/USE_CURRENT to prevent this from happening.
/VERBOSE -> Set this switch to print out information about
the color table that has just been selected.
/XINTERACTIVE -> to call XLOADCT instead of LOADCT for
interactivity. Has no effect if a custom colortable is
loaded.
The following keywords are kept for backwards compatibility.
These will replicate the color tables that used to be defined
with the now obsolete CUSTOM_COLORTABLE routine.
/BuWhRd -> Loads 19-color BLUE-WHITE-RED color table
/BuWhWhRd -> Loads 20-color BLUE-WHITE-WHITE-RED color table
/BuYlRd -> Loads 11-color BLUE-YELLOW-RED color table
/BuYlYlRd -> Loads 12-color BLUE-YELLOW-YELLOW-RED color table
/DIAL -> Loads the 26-color DIAL/LIDAR color table
(cf. E. Browell)
/DIFF -> Synonym for /BuWhRd.
/ModSpec -> Loads the 11 color MODIFIED SPECTRUM color table
/WhBu -> Loads the 10-color WHITE-BLUE color table
/WhGrYlRd -> Loads the 20-color WHITE_GREEN-YELLOW-RED color table
(cf. Aaron van Donkelaar)
/WhGyBk -> Loads the 10-color the WHITE-GRAY-BLACK color
/WhRd -> Loads the 10-color the WHITE-RED color table
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Provided:
===============================
MYCT_Drawing_Colors
External Subroutines Required:
===============================
COMPRESS_DIV_CT
DATATYPE (function)
XCOLORS
REQUIREMENTS:
None
NOTES:
(1) It is recommended to use the COLOR keyword in all PLOT
commands. This will ensure correct colors on (hopefully)
all devices. In order to get 256 colors on a postscript
printer use DEVICE,/COLOR,BITS_PER_PIXEL=8
(2) MYCT will also save several parameters in the MYCT system
variable, so that graphics programs can access them.
(3) MYCT uses the "gamap_colors.tbl" file. This file
contains all of the IDL standard color table definitions
all of the olorBrewer color table definitions, and some
extra colortables. If you wish to add a color table
you should probably use routine GAMAP_COLORS to create
a new *.tbl file. Then call MYCT and specify the name
of the new *.tbl file with the CTFILE keyword.
(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
(6) NOTE: Use a temporary hack to center the ColorBrewer
diverging color tables. (phs, 4/23/08)
EXAMPLES:
MYCT, 8, /NO_STD
; load IDL colortable green-white (#8)
; identical result as loadct,3
MYCT, 'EOS B', NCOLORS=20
; change first 17 colors to standard drawing colors
; and add EOS-B (#27) color table in indices 18-36
MYCT, 0, NCOLORS=20, /REVERSE, /NO_STD, /Use_Current
; add reversed grey scale table on top
MYCT, 'EOS B', NCOLORS=40, /NO_STD, /Use_Current, $
RANGE=[0.1,0.7], SATURATION=0.7
; add a less saturated version of a fraction
; of the EOS-B color table in the next 40 indices
; NOTE that color indices above 97 will still contain
; the upper portion of the green-white color table.
MYCT, 0 /REVERSE
; On b/w terminals MYCT can be used to reverse
; the IDL black & white (#0) colortable
MYCT, /DIAL, NCOLORS=120
; Loads the DIAL LIDAR color table with 120 colors
MYCT, /BuYlYlRd
MYCT, 'RdBu', /MIDCOLORPRESENT, /YELLOW, NCOLORS=20
; Both of these commands do the same thing: loads
; the ColorBrewer "RdBu" colortable and inserts yellow
; into the 2 middle colors. This is a good choice
; if you are creating an absolute or % difference plot.
MODIFICATION HISTORY:
mgs, 06 Feb 1997: VERSION 1.00
mgs, 03 Aug 1997: - added input parameter and template
mgs, 26 Mar 1998: - added NCOLORS keyword
mgs, 06 Apr 1998: - added BOTTOM, RANGE, and RGB keywords
mgs, 04 May 1998: - added test for null device
mgs, 03 Jun 1998: - return if !D.N_COLORS is less than 3 (b/w)
mgs, 16 Jun 1998: - bug fix: range check now after tvlct
mgs, 18 Jul 1998: - bug re-visited, added HLS keyword and changed
default to HSV. Also added SATURATION and
VALUE keywords.
mgs, 12 Aug 1998: - re-written with bug fixes and more concise.
removed RGB and HLS keywords, added REVERSE
and NO_STD keywords.
mgs, 14 Jan 1999: - limit oldcolors and ncolors to MaxColors (256)
on PC with TrueColor Graphics to ensure
compatibility with Unix.
bmy, 26 Sep 2002: TOOLS VERSION 1.51
- added /DIAL keyword to specify the DIAL/LIDAR
colortable from Ed Browell et al.
- now save MYCT parameters into a system variable
so that plotting routines can access them.
bmy, 22 Oct 2002: TOOLS VERSION 1.52
- fixed minor bugs in defining the !MYCT variable
bmy, 28 May 2004: TOOLS VERSION 2.02
- removed TESTMYCT routine, it's obsolete
- Bug fix: make sure RANGE is defined before
saving it to the !MYCT variable
bmy, 09 Jun 2005: TOOLS VERSION 2.04
- Added default value for RANGE keyword
bmy, 05 Oct 2006: TOOLS VERSION 2.05
- Now also define the DIFFERENCE color table
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now calls CUSTOM_COLORTABLE to define
several custom colortables
- Now allow /REVERSE to reverse custom
color table indices
- Added /VERBOSE keyword for printing info
about the selected color table
- Added /BuWhWhRd keyword for the
BLUE-WHITE-WHITE-RED colortable
- Added /BuYlYlRd keyword for the
BLUE-YELLOW-YELLOW-RED colortable
- Added /UserDef keyword to select
a user-defined color table.
cdh & bmy, 19 Nov 2007: GAMAP VERSION 2.11
- Now implement newer, less-saturated MYCT
drawing colors as defaults
- Added /BRIGHT_COLORS keyword to use
the older drawing colors for backwards
compatibility.
phs, 17 Apr 2008: GAMAP VERSION 2.12
- Now passes _extra to LOADCT, so a different
table file (*.tbl) can be used for example.
- bug fix: ncolors is correctly passed to
LOADCT if RANGE is not set.
- Added the XINTERACTIVE keyword to use
XCOLORS instead of LOADCT when no custom
table is loaded.
- Now use extra !MYCT tags: NAME, INDEX, FILE
- Added MIDCOLORPRESENT, USE_CURRENT keywords
phs, 22 Sep 2008: GAMAP VERSION 2.13
- Re-Added UserDef keyword. Users can define
(and then load) their own color table in the
Define_UserDef subroutine.
(See /n/home09/ryantosca/IDL/gamap2/color/myct.pro)
NAME:
MYCT_DEFAULTS (function)
PURPOSE:
Returns a structure associating the names of MYCT
drawing colors with their numeric values, plus
the default bottom and number of colors.
CATEGORY:
Color
CALLING SEQUENCE:
C = MYCT_DEFAULTS()
INPUTS:
None
KEYWORD PARAMETERS:
/GRAYSCALE -> If set, will define a grayscale colortable
such that the lowest color is white, and the highest
color is dark grey. Otherwise the standard "TRACE-P"
colortable (based on Mac Style #25) will be defined.
NCOLORS -> Specifies the number of colors for MYCT. The
default is 120, but if your terminal can support more,
you may specify a higher value.
OUTPUTS:
C -> Structure with the following tag names:
WHITE : Color index for "drawing color" WHITE
BLACK : Color index for "drawing color" BLACK
RED : Color index for "drawing color" RED
GREEN : Color index for "drawing color" GREEN
BLUE : Color index for "drawing color" BLUE
ORANGE : Color index for "drawing color" ORANGE
PURPLE : Color index for "drawing color" PURPLE
LIGHTRED : Color index for "drawing color" LIGHTRED
LIGHTGREEN : Color index for "drawing color" LIGHTGREEN
LIGHTBLUE : Color index for "drawing color" LIGHTBLUE
LIGHTORANGE : Color index for "drawing color" LIGHTORANGE
LIGHTPURPLE : Color index for "drawing color" LIGHTPURPLE
YELLOW : Color index for "drawing color" YELLOW
MAGENTA : Color index for "drawing color" MAGENTA
CYAN : Color index for "drawing color" CYAN
GRAY85 : Color index for "drawing color" 85% GRAY
GRAY67 : Color index for "drawing color" 67% GRAY
DARKGRAY : Color index for "drawing color" 67% GRAY
GRAY50 : Color index for "drawing color" 50% GRAY
MEDIUMGRAY : Color index for "drawing color" 50% GRAY
GRAY33 : Color index for "drawing color" 33% GRAY
GRAY : Color index for "drawing color" 33% GRAY
LIGHTGRAY : Color index for "drawing color" 33% GRAY
GRAY15 : Color index for "drawing color" 15% GRAY
FILE : Name of the color table (*.tbl) file
NAME : Color table name
INDEX : Color table index
BOTTOM : Color table starts at this index
NCOLORS : Number of colors
RANGE : Range of IDL color table to be used
SAT : Saturation value for MYCT
VALUE : Hue value for MYCT
REVERSE : REVERSE=1 means light --> dark
REVERSE=0 means dark --> light
SUBROUTINES:
None
REQUIREMENTS:
Designed to be used by the GAMAP routine "myct.pro".
NOTES:
(1) This routine is designed to be called by MYCT_DEFINE.
You should not normally have to call MYCT_DEFAULTS.
(2) MYCT defines a colortable such that the first 17
colors are "drawing" colors, or pure colors intended
for use with the PLOT, CONTOUR, MAP_SET, etc. commands.
MYCT then loads a standard IDL colortable (with NCOLORS
specifying the number of individual colors) into color
indices 18 and higher.
(3) New drawing colors (that are less saturated and
easier to read on the screen) are now the defaults.
See the documentation to the MYCT routine for more info.
EXAMPLE:
C = MYCT_DEFAULTS()
; Defines a grayscale colortable for use w/ MYCT.
MODIFICATION HISTORY:
bmy, 23 Jul 2001: TOOLS VERSION 1.48
- adapted from "default_colors.pro"
bmy, 04 Feb 2004: TOOLS VERSION 2.01
- Increased grayscale color range slightly
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- renamed DIAL to CUSTOM, to reflect that
we have other custom colortables in use
cdh & bmy, 19 Nov 2007: GAMAP VERSION 2.11
- Added names for the new MYCT drawing colors
bmy, 21 Apr 2008: GAMAP VERSION 2.12
- Removed obsolete settings and keywords
- Removed IS_CUSTOM tag name from !MYCT
- Added INDEX, FILE tag names to !MYCT
(See /n/home09/ryantosca/IDL/gamap2/color/myct_defaults.pro)
NAME:
MYCT_DEFINE
PURPOSE:
Defines the !MYCT system variable with default values.
!MYCT is used to make colortable parameters available to
plotting programs.
CATEGORY:
Color
CALLING SEQUENCE:
MYCT_DEFINE
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MYCT_DEFAULTS (function)
REQUIREMENTS:
None
NOTES:
This routine should be called from your "idl_startup.pro"
batch file, so that !MYCT will be defined and ready for
use by all other routines that need it.
EXAMPLE:
MYCT_DEFINE
; Defines the !MYCT system variable
MODIFICATION HISTORY:
bmy, 30 Sep 2002: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/color/myct_define.pro)
NAME:
NCDF_GET
PURPOSE:
Convenience routine to read data into netCDF format.
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
DATA = NCDF_GET( FID, NAME [, Keywords ] )
INPUTS:
FID -> netCDF File ID, as returned by routine NCDF_OPEN.
NAME -> Name under which the data array will be saved
to the netCDF file.
KEYWORD PARAMETERS:
VARINFO -> Returns a structure containing information
about the variable read in from disk. The structure
has the following form:
{ NAME : "", $
DATATYPE : "", $
NDIMS : 0L, $
NATTS : 0L, $
DIM : LONARR(NDIMS) }
LONGNAME -> Returns the value saved under the "long_name"
attribute in the netCDF file.
UNIT -> Returns the value of the "unit" attribute
saved in the netCDF file.
RANGE -> Returns the value of the "valid_range"
saved in the netCDF file
_EXTRA=e -> Picks up extra keywords got NCDF_VarGet.
OUTPUTS:
DATA -> Array containing extracted data from the netCDF file.
SUBROUTINES:
Uses the following IDL netCDF routines:
========================================
NCDF_VarId (function) NCDF_VarGet
NCDF_VarInfo (function) NCDF_AttGet
NCDF_AttName (function)
REQUIREMENTS:
Need to use a version of IDL w/ netCDF routines installed.
NOTES:
(1) Only looks for the "long_name", "unit", and "valid_range"
attributes. The user can extend this as he/she desires.
For a more general program, see ~/IDL/tools/ncdf_read.pro
by Martin Schultz.
EXAMPLE:
; Define array to write to file
ARRAY = DIST( 100, 50 )
; Find out if netCDF is supported on this platform
IF ( NCDF_EXISTS() eq 0 ) then MESSAGE, 'netCDF not supported!'
; Open netCDF file and get the file ID # (FID)
FID = NCDF_OPEN( 'myfile.nc' )
IF ( FID lt 0 ) then Message, 'Error opening file!'
; Read data from the netCDF file
; Return data attributes in the VARINFO array
; Also returns the text from the UNIT string
DATA = NCDF_GET( FID, 'BIOBSRCE::NOx', $
VARINFO=VARINFO, UNIT=UNIT )
; Close the netCDF file
NCDF_CLOSE, FID
MODIFICATION HISTORY:
bmy, 22 May 2002: TOOLS VERSION 1.50
bmy, 21 Oct 2003: TOOLS VERSION 1.53
- If we can't find a netCDF variable name,
then try again using a "sanitized" name
w/ all bad characters stripped out
bmy, 28 Jun 2007: TOOLS VERSION 2.06
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Added /VERBOSE keyword to reduce
warning messages
(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_get.pro)
NAME:
NCDF_READ
PURPOSE:
Open a netCDF file and read data from it. The data is
returned as a structure whose tag names are the names of
the variables with blanks etc. replaced. If no variables
are specified with the VARIABLES keyword, only dimensional
information is returned. You can load all variables using
the ALL keyword. Other keyword options include OFFSET, COUNT, STRIDE,
NO_DIMENSIONS, NO_STRUCT, DIMNAMES, VARNAMES, VARDIMS, ATTRIBUTES.
Thus, this program includes ncdump functionality.
If no filename is given, a file selection dialog is
opened with the default mask '*.nc'. The name of the selected
file is returned in the TRUENAME keyword. A file selection
dialog also appears when the file cannot be found (see
OPEN_FILE.PRO). This can be turned off with the NO_DIALOG
keyword. The VERBOSE keyword provides information while
analyzing and reading the file.
AUTHOR:
Dr. Martin Schultz
Max-Planck-Institut fuer Meteorologie
Bundesstr. 55, D-20146 Hamburg
email: martin.schultz@dkrz.de
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
NCDF_READ, result, filename=, truename=,
variables=, all=, varnames=,
vardimid=, vardims=, attributes=,
count=, offset=, stride=,
dimnames=, dims=, no_dimensions=,
no_struct=, no_dialog=, verbose=, title=
ARGUMENTS:
RESULT(out) -> a structure containing all the variable data
from the netCDF file. If only one variable is specified
and the NO_STRUCT keyword set, then RESULT will be an
array instead of a structure. Use the ALL keyword
to load all variables at once. Note, that the COUNT, OFFSET,
and STRIDE keywords can affect the size of RESULT.
RESULT is set to -1L if an error occurs before the structure
has been built. You can use CHKSTRU.PRO to test for this.
KEYWORD PARAMETERS:
FILENAME(in) -> the name of the netCDF file to be opened.
NCDF_READ uses OPEN_FILE to check the validity of
the file first. You can specify a search mask
instead of a filename in which case a file selection
dialog is displayed (unless you set the NO_DIALOG
keyword). The TRUENAME keyword contains the name
of the selected file or an empty string if the
file selection was canceled.
TRUENAME(out) -> the (fully qualified) name of the file selected
with the file selection dialog or an unaltered copy
of FILENAME if FILENAME is a valid filename.
VARIABLES(in) -> a string array containing the names of variables
for which data shall be read. Default is to read
only the dimensional information from the file.
(Currently) no warning is issued if a variable is not in the file.
ALL(in) -> set this keyword to load all variables stored in the
netCDF file. Generally, you cannot usethis keyword together with
COUNT, OFFSET, and STRIDE.
VARNAMES(out) -> a string array containing the names of all variables
as stored in the file. Note, that the tag names of e.g. the
result structure are filtered with the Valid_TagName function.
VARDIMID(out) -> a structure with integer arrays containing the
dimension ID's for all variables. See also VARDIMS which returns
the dimensions themselves.
VARDIMS(out) -> a structure with integer arrays containing the
dimensions for all variables in the netCDF file. These are not
kept in sync with potential COUNT, OFFSET, and STRIDE values,
but reflect the data sizes as stored in the file.
ATTRIBUTES(out) -> a structure holding the variable and global
attributes stored in the netCDF file (global attributes
are stored in tag name GLOBAL).
COUNT(in) -> an integer array containing the number of values to
be read for each dimension of the variables. Mapping of the
COUNT dimensions to the variable dimensions is achieved via
the first entry in the VARIABLES list and the COUNT parameter
will be applied to all variables that have that dimension.
Example: The first variable has dimensions LON, LAT, LEV,
the second variable has dimensions LON, LAT, and the third
variable has LAT, LEV. A COUNT of [40,20,10] would lead to
result dimensions of [40,20,10], [40,20], and [20,10].
OFFSET(in) -> an integer array containing the offsets for each
dimension of the variables to be read. Dimension mapping
is the same as for COUNT.
STRIDE(in) -> an integer array containing the stride for each
dimension of the variables to be read. Dimension mapping
is the same as for COUNT.
DIMNAMES(out) -> a string array containing the names of the
dimensions stored in the netCDF file.
DIMS(out) -> a long array containing the dimension values. Purely
for convenience. Use VARDIMS to retrieve the dimensions of
the variables.
TITLE(in) -> A title for the file selection dialog if an
incomplete or incorrect filename is specified. This
keyword is ignored if the no_dialog keyword is set.
NO_DIMENSIONS(in) -> set this keyword if you do not want to store
the dimensional variables from the file in the result structure.
DIMNAMES and DIMS will still be retrieved.
NO_STRUCT(in) -> if only one variable is selected with the
VARIABLE keyword, you can set this keyword to return only
the data for this variable as an array. This keyword implies
the functionality of NO_DIMENSIONS.
NO_DIALOG(in) -> set this keyword if you do not want interactive
behaviour when a file mask is given instead of a filename or
when the specified file does not exist.
VERBOSE(in) -> set this keyword to get detailed information while
reading the netCDF file.
SUBROUTINES:
Valid_TagName : replaces invalid characters in variable names so that
a structure can be built.
ncdf_attributes : retrieves global and variable attributes from netcdf
file and stores them as structure.
ncdf_dimensions : retrieves size and name for all dimensions in netcdf file.
ncdf_varnames : retrieves names and dimension information for all variables
in the netCDF file.
ncdf_mapdims : map dimension indices for COUNT, OFFSET, and STRIDE with
dimensions of first selected variable.
ncdf_TestDimensions : compute the COUNT, OFFSET, and STRIDE vectors that
must be applied for retrieving the data of one variable.
REQUIREMENTS:
uses OPEN_FILE and STRREPL.
NOTES:
Correct handling of dimensional information requires that the variables
storing the dimension values have the same name as the dimensions
themselves - a common feature in most netCDF standards.
I am still working on a netcdf file object which will be even
more powerful. At some point ncdf_read will only be a
procedure interface to this objec!
EXAMPLE:
ncdf_read,result,/All
; plot ozone vs. temperature
plot,result.temperature,result.ozone
MODIFICATION HISTORY:
mgs, 18 Sep 1999: VERSION 1.00
mgs, 29 Feb 2000: - added variables keyword
- added CATCH error handler
mgs, 21 Mar 2000: - bug fix for tag names
mgs, 09 May 2000: VERSION 2.00
- now only reads dimensions as default
- added ALL keyword to compensate
- returns dimnames and attributes
(makes ncdf_detail obsolete)
- added COUNT, OFFSET and STRIDE keywords
- added NO_DIMENSIONS and NO_DIALOG
keywords and more
mgs, 22 Aug 2000: - added title keyword
bmy, 22 May 2002: GAMAP VERSION 1.50
- Now replace ":", "=", "#" with "_" in
structure tag names, so IDL won't choke
bmy, 21 Oct 2003: GAMAP VERSION 1.53
- also replace "(" and ")" in tag names
- replace "$" with "S" (close to dollar sign)
- replace "*" with "A" (for Asterisk)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_read.pro)
NAME:
NCDF_SET
PURPOSE:
Convenience routine to write data into netCDF format.
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
NCDF_SET, FID, DATA, NAME, DIMS [, Keywords ]
INPUTS:
FID -> netCDF File ID, as returned by routine NCDF_CREATE.
DATA -> Data (array or scalar) to be written to netCDF file.
NAME -> Name under which the data array will be saved
to the netCDF file.
KEYWORD PARAMETERS:
LONGNAME -> Longer descriptive name for the data.
This will be saved as the "long_name" attribute.
RANGE -> A 2-element vector containing the [min,max] of
the data array. If not passed, RANGE will be computed
(but only if DATA is a numeric type). RANGE is saved
to the netCDF file as the "valid_range" attribute.
UNIT -> String containing the units of the data.
This will be saved as the "unit" attribute.
_EXTRA=e -> Picks up extra keywords
OUTPUTS:
None
SUBROUTINES:
Uses the following routines:
=====================================================
NCDF_Control NCDF_VarDef (function)
NCDF_AttPut DATATYPE (function from TOOLS)
NCDF_VarPut NCDF_VALID_NAME (function from TOOLS)
REQUIREMENTS:
Need to use a version of IDL w/ netCDF routines installed.
NOTES:
(1) For now, treat BYTE data like CHAR data. This is
most likely since netCDF does not support STRING types,
strings have to be stored as arrays of bytes.
EXAMPLE:
; Define array to write to file
ARRAY = DIST( 100, 50 )
; Find out if netCDF is supported on this platform
IF ( NCDF_EXISTS() eq 0 ) then MESSAGE, 'netCDF not supported!'
; Open netCDF file and get the file ID # (FID)
FID = NCDF_CREATE( 'myfile.nc', /CLOBBER )
IF ( FID lt 0 ) then Message, 'Error opening file!'
; Set dimensions for netCDF file
S = SIZE( ARRAY, /DIM )
DIM1 = NCDF_DIMDEF( FID, 'Length', S[0] )
DIM2 = NCDF_DIMDEF( FID, 'Width', S[1] )
; Go into netCDF DATA mode
NCDF_CONTROL, FID, /ENDEF
; Call NCDF_SET to write the array to the file
NCDF_SET, FID, ARRAY, 'My Data', [ DIM1, DIM2 ], $
LONGNAME='Data array created by me!', $
UNIT='unitless'
; Close the netCDF file
NCDF_CLOSE, FID
MODIFICATION HISTORY:
bmy, 19 Apr 2002: TOOLS VERSION 1.50
bmy, 10 Sep 2002: TOOLS VERSION 1.51
- Now call routine DATATYPE to determine
the type of the data so that we can
write to the netCDF file appropriately
- Don't add the RANGE attribute to
the netCDF file for a string type value.
- Updated comments
bmy, 21 Oct 2003: TOOLS VERSION 1.53
- now "sanitize" the netCDF variable name
w/ routine NCDF_VALID_NAME. The new netCDF
library in IDL 6.0+ chokes on bad characters.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_set.pro)
NAME:
NCDF_VALID_NAME
PURPOSE:
Strips invalid characters from a string which is to be
used as a netCDF variable name. Based on original code
by Martin Schultz.
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
RESULT = NCDF_VALID_NAME( ARG )
INPUTS:
ARG -> netCDF variable name string to be examined.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> New netCDF name string with "bad" characters
replaced by "good" characters.
SUBROUTINES:
External Subroutines Used:
==========================
STRREPL (function)
REQUIREMENTS:
None
NOTES:
In IDL 6.0+, the netCDF library has been updated. Some
characters which used to be allowed in netCDF variable names
are no longer allowed. Therefore, use this function to
replace "bad" characters with "good" characters when
reading or writing to/from netCDF files.
EXAMPLE:
RESULT = NCDF_VALID_NAME( 'IJ-AVG-$::CO' )
PRINT, RESULT
; Prints "IJ-AVG-S__CO"
MODIFICATION HISTORY:
bmy, 21 Oct 2003: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_valid_name.pro)
NAME:
NUMDEN
PURPOSE:
Calculates the number density of air for a given temperature
and pressure.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = NUMDEN( T, P, /DOUBLE )
INPUTS:
T -> Temperature (or vector of temperatures) in K.
P -> Pressure (or vector of pressures) in hPa.
Default is 1000 hPa.
KEYWORD PARAMETERS:
/DOUBLE -> Set this switch to return the number density
in double precision. Default is to return the number
density in single precision.
OUTPUTS:
RESULT -> Number density of air in molec/cm3. If T and
P are vectors, then RESULT will be a vector of
number densities
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, NUMDEN( 298.0, 1013.0 )
2.46206e+19
; Prints the number density of air
; at 298K and 1013 hPa.
(2)
PRINT, NUMDEN( 298.0, 1013.0, /DOUBLE )
2.4620635e+19
; Prints the number density of air ; at 298K and
; 1013 hPa. Computation is done in double precision.
MODIFICATION HISTORY:
dbm, 30 Jul 2007: GAMAP VERSION 2.10
phs, 1 Sep 2009: GAMAP VERSION 2.13
- let you pass array
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/numden.pro)
NAME:
NYMD2TAU (function)
PURPOSE:
Computes the value of TAU, which is the elapsed hours between
the current date/time and the beginning of an epoch. This is
the starting date for 3D model data assimilation.
CATEGORY:
Date & Time
CALLING SEQUENCE:
RESULT = NYMD2TAU( NYMD, [NHMS [,NYMD0, NHMS0]] )
INPUTS:
NYMD (long) -> YY/MM/DD for this date (e.g. 940101)
You can either specify year as 4 digits or 2 digits.
With 2 digits, year < 50 will be assumed to be 2000+YY.A
NHMS (long) -> HH/MM/SS for this date (e.g. 060000)
will be defaulted to 000000
NYMD0 (long) -> YY/MM/DD for the start of the epoch
default is {19}850101 which is the GEOS-1 start
NHMS0 (long) -> HH/MM/SS for the start of the epoch
will be defaulted to 000000
KEYWORD PARAMETERS:
/GEOS1 -> use 1985/01/01 as epoch start
/GISS_II -> use 1980/01/01 as epoch start
OUTPUTS:
RESULT -> The function returns the TAU value as a
double-precision number
SUBROUTINES:
NYMD2STRU : extracts year, month, day, hour, minute and seconds from
NYMD and NHMS values.
JULDAY (IDL user library procedure)
REQUIREMENTS:
NOTES:
Function NYMD2STRU is also contained in function TAU2YYMMDD.
Take care when changes are necessary !
EXAMPLE:
; (1) Compute TAU value for 0h on Jan 1, 1994, with the
; epoch starting on 0h on Jan 1, 1980 (GISS II value).
;
TAU = nymd2tau( 940101L, 0L, 800101L, 0L )
; (2) Compute TAU value for 0h on Jan 1, 1994, for the
; default GEOS-1 epoch (850101L, 0L).
;
TAU = nymd2tau( 940101L, 0L )
; (3) Compute GISS model II tau values for the first of
; each month in 1990
date = [ 900101L, 900201L, 900301L, 900401L, 900501L, 900601L, $
900701L, 900801L, 900901L, 901001L, 901101L, 901201L ]
tau = nymd2tau(date,/GISS)
MODIFICATION HISTORY:
bmy, 26 Mar 1998: VERSION 1.00
mgs, 26 Mar 1998: - now year 2000 compliable
mgs, 23 Mar 1999: - now handles vectors as input
bmy, 23 Mar 2005: GAMAP VERSION 2.03
- Added /NO_Y2K keyword to suppress
special Y2K treatment of dates (i.e.
treat dates w/ 2 digits as from 1900's)
- renamed internal function NYMD2STRU to
N2T_NYMD2STRU to avoid conflict with
similar function in "tau2yymmdd.pro"
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/date_time/nymd2tau.pro)
NAME:
N_UNIQ (function)
PURPOSE:
Returns the number of unique elements in an array.
CATEGORY:
General
CALLING SEQUENCE:
Result = N_UNIQ( Arr )
INPUTS:
ARR -> The array to be searched for unique values.
KEYWORD PARAMETERS:
None
OUTPUTS:
Returns the number of unique values in ARR as the value
of the function
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, N_UNIQ( [10, 20, 30] )
3
(2)
PRINT, N_UNIQ( [10,10] )
1
MODIFICATION HISTORY:
bmy, 17 Nov 1998: VERSION 1.00
mgs, 17 Nov 1998: - little streamlining
mgs, 16 Mar 1999: - don't print out warning for empty argument
and return 0 instead of -1
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/n_uniq.pro)
NAME:
OPEN_DEVICE
PURPOSE:
If hard copy is to be generated, OPEN_DEVICE opens the
PostScript device. Otherwise OPEN_DEVICE opens an Xwindow.
CATEGORY:
Graphics
CALLING SEQUENCE:
OPEN_DEVICE [,OLD_DEVICE] [,keywords]
INPUTS:
OLD_DEVICE -> This is now obsolete, and is only maintained
for backwards compatibility.
KEYWORD PARAMETERS:
/PS -> will send PostScript file to printer
FILENAME -> The name to be given the PostScript file.
Default: idl.ps
/LANDSCAPE -> will enable PostScript landscape mode
/PORTRAIT -> will enable PostScript portrait mode
XOFFSET, YOFFSET -> Keywords for the DEVICE command. XSIZE
specifies the horizontal offset (in inches) of the page,
and YSIZE specifies the vertical offset (in inches) of
the page. Defaults are as follows:
Plot type XOFFSET YOFFSET
-------------------------------------------------
Portrait 0.25 0.25
Landscape 0.75 0.75
XSIZE, YSIZE -> Keywords for the DEVICE command. XSIZE
specifies the horizontal size (in inches) of the page,
and YSIZE specifies the vertical size (in inches) of
the page. Defaults are as follows:
Plot type XSIZE YSIZE
-------------------------------------------------
Portrait 8.0 10.0
Landscape 11 - 2*XOFFSET 8.5 - 2*YOFFSET
/COLOR -> will enable PostScript color mode
WINPARAM -> An integer vector with up to 5 elements:
WINPARAM(0) = window number (if negative, a window
will be opened with the /FREE option.
WINPARAM(1) = X dimension of window in pixels (width)
WINPARAM(2) = Y dimension of window in pixels (height)
WINPARAM(3) = X offset of window (XPOS)
WINPARAM(4) = Y offset of window (YPOS)
TITLE -> window title
/Z -> If set, will initialize the Z-buffer device. If WINPARAM
is specified, then the size of the Z-buffer region will be
WINPARAM[1] x WINPARAM[2] pixels. If WINPARAM is not
specified, then the size of the Z-buffer region will be
set to a default size of 640 x 512 pixels.
NCOLORS -> If /Z is set, NCOLORS specifies the number of colors
that will be made available to the Z-buffer device.
_EXTRA=e -> additional keywords that are passed to the call to
the DEVICE routine (e.g. /ENCAPSULATED)
OUTPUTS:
OLD_DEVICE -> stores the previous value of !D.NAME for
use in CLOSE_DEVICE. Note that CLOSE_DEVICE will automatically
set the default screen device if OLD_DEVICE is not provided,
hence it will only rarely be used.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
If PS=0 then
Open Xwindow WINPARAM(0), which is WINPARAM(1) pixels wide
in the X-direction, and WINPARAM(2) pixels wide in the
Y-direction.
If PS=1 then
depending on /PORTRAIT or /LANDSCAPE and /COLOR
postscript is enabled in either portrait or landscape
mode as color or b/w plot
The key parameter which determines whether to open a postscript
file or a screen window is PS. Therefore, e.g. in a widget
application, you can pass a standard set of parameters for both,
postscript and screen, to this routine, and determine the device
to be chosen by a button state or checkbox which is passed into PS.
Also is currently hardwired for 8.5 x 11 inch paper (US
format). Need to extend this to European A4 paper soon.
EXAMPLES:
(1)
OPEN_DEVICE, WINPARAM=[0,800,800]
; opens a screen window of size 800x800
; pixels at the default position
(2)
OPEN_DEVICE, /LANDSCAPE, FILENAME='myplot.ps'
; opens a postscript file named myplot.ps in
; b/w and landscape orientation
(3)
OPEN_DEVICE, PS=PS, /PORTRAIT, /COLOR, WIN=2
; depending on the value of PS either a color
; postscript file named idl.ps is opened or screen
; window number 2 in default size.
(4)
OPEN_DEVICE, /Z
; Opens the IDL Z-buffer device. The current
; color table will be preserved in the Z-buffer device.
MODIFICATION HISTORY:
bmy 15 Aug 1997: VERSION 1.00
bmy, 19 Aug 1997: VERSION 1.01
mgs, 20 Aug 1997: VERSION 1.02
mgs, 09 Apr 1998: VERSION 1.10
- added 2 more parameters for WINPARAM
and TITLE keyword
bmy, 28 Jul 2000: VERSION 1.46
- now make XSIZE, XOFFSET, YSIZE, YOFFSET keywords
- cosmetic changes, updated comments
bmy, 30 Jan 2001: VERSION 1.47
- added /Z and NCOLORS keywords for the Z-buffer
- updated comments
bmy, 26 Jul 2001: VERSION 1.48
- use default window size of 640 x 512 for
the Z-buffer, if WINPARAM isn't specified.
bmy, 27 Aug 2001: - now call DEVICE with XSIZE, YSIZE,
XOFFSET, YOFFSET for /LANDSCAPE plots
- Updatedd comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/graphics/open_device.pro)
NAME:
OPEN_FILE
PURPOSE:
Open a file for input. This routine can automatically
decide whether to use DIALOG_PICKFILE, and it contains
basic error handling. After successful operation the
file with logical unit LUN will be open for input.
CATEGORY:
File & I/O
CALLING SEQUENCE:
OPEN_FILE,filemask,lun [,keywords]
INPUTS:
FILEMASK -> a filename with path information that may
contain wildcards ('*', '?')
LUN -> a named variable that will contain the logical unit
number upon return. If a unit number > 0 is passed,
an attempt is made to open the file with this number,
otherwise, a free unit is selected with /GET_LUN. In case
of an error, LUN contains -1. This can be used instead of
the RESULT keyword to detect errors (see below).
(both parameters are mandatory !)
KEYWORD PARAMETERS:
FILENAME -> a named variable that will contain the complete
filename upon return (i.e. the file selected with PICKFILE)
WRITE -> Set this keyword to open a file for read and write
operations. Normally, a file is opened for reading only.
RESULT -> a named variable that will return the error status
of the operation. A value of 0 indicates the file was
opened sucessfully, otherwise the value of !Error_State.Code
is returned.
PICKFILE -> logical flag to force use of the DIALOG_PICKFILE
routine, even if a complete filemask without wildcards was
passed.
TITLE -> the title of the pickfile dialog. Default is
'Choose a file'.
DEFAULTMASK -> A default filemask to be used when no filename
is given or the filename does not contain wildcards and
/PICKFILE is set. This mask will also be used if the
file cannot be opened because of 'FILE NOT FOUND' error.
NO_PICKFILE -> prevents the pickfile dialog for batch operation.
The filemask must not contain wildcards.
Normally a 'FILE NOT FOUND' condition leads to
a second attempt with the /PICKFILE flag set (recursive
call). Use this flag if you want to abort instead.
_EXTRA keywords are passed to the openr routine
(e.g. /F77_UNFORMATTED)
OUTPUTS:
SUBROUTINES:
REQUIREMENTS:
Uses EXTRACT_FILENAME function
NOTES:
EXAMPLE:
(1)
; Quick and dirty with pickfile dialog
OPEN_FILE,'*.dat',ilun
if (ilun le 0) then stop ; check error condition
(2)
; A few more options invoked
OPEN_FILE,'~/data/thisfile.dat',lun,default='*.dat', $
title='Choose a data file',filename=name
IF (LUN LE 0) THEN STOP ; check error condition
PRINT, FILENAME,' was opened successfully
; NOTE that filename does not have to be identical with
; '~/data/thisfile.dat' !
; readf,lun,...
CLOSE, LUN
FREE_LUN, LUN
MODIFICATION HISTORY:
mgs, 13 Aug 1998: VERSION 1.00
- extracted from ctm_read3dp_header.pro and
modified
mgs, 14 Aug 1998: - small bug fix: handle empty filename
string correctly
mgs, 22 Aug 1998: - added WRITE keyword to open writable files
mgs, 22 Oct 1998: - now always returns LUN=-1 in case of an error
mgs, 21 Jan 1999: - Added explicit F77_Unformatted keyword and set
Swap_If_Little_Endian or Swap_If_Big_Endian
automatically
mgs, 10 Feb 1999: - bug fix: swap_if was wrong way round
mgs, 12 May 1999: - ok. finally got the hang of byte swapping!
It's the machine architecture not the operating
system! Now changed it so that !VERSION.ARCH is
tested for 'x86'
mgs, 20 May 1999: - abandoned SWAP_IF completely and use explicit
SWAP_ENDIAN keyword in users grace now.
bmy, 14 Oct 2003: TOOLS VERSION 1.53
- For IDL 6.0+, if PATH is a null string, then
manually reset it to './'. This will avoid
the contents of the !PATH variable from being
listed in the dialog box.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
cdh & phs, 30 Jun 2008: GAMAP VERSION 2.12
- declare dummy GET_LUN keyword. It
prevents passing GET_LUN w/ _extra to
openr/w, since LUN is already assigned in
all cases.
(See /n/home09/ryantosca/IDL/gamap2/file_io/open_file.pro)
NAME:
ORG_CORR
PURPOSE:
Calculate reduced major axis. Given two vectors X and Y, this
subroutine computes the Gradient and Y intercept of the line
given by the reduced major axis. The main advantage of this
is that the best fit line of X and Y will be the same as the
best fit line of Y and X.
CATEGORY:
Math & Units
CALLING SEQUENCE:
ORG_CORR, X, Y, R, NP, GRADIENT, INTERCEPT, $
GRADIENT_ERR, INTERCEPT_ERR [, VERBOSE=VERBOSE ]
INPUTS:
X -> Vector containing X-axis values.
Y -> Vector containing Y-axis values.
R -> Correlation coefficient
NP -> Number of elements of X and Y arrays to process.
NP should be smaller than or equal to the number of
elements of X and Y.
KEYWORD PARAMETERS:
/VERBOSE -> Set this switch to print the gradient,
intercept, and standard errors to the screen.
The default is not to print these values.
OUTPUTS:
GRADIENT -> Gradient of reduced major axis
INTERCEPT -> Y-Intercept of reduced major axis
GRADIENT_ERR -> Standard error in gradient.
INTERCEPT_ERR -> Standard error in Y-intercept.
SUBROUTINES:
External Subroutines Required:
==============================
SIGN (function)
REQUIREMENTS:
References routines from the TOOLS package.
NOTES:
(1) More details are in Hirsch and Gilroy, Water Res. Bull.,
20(5), Oct 1984.
(2) Standard errors also calculated according to Miller and
Kahn, Statistical Analysis in the Geological Sciences,
1962, pp. 204-210.
(3) Computations are now performed in double precision.
EXAMPLE:
MODIFICATION HISTORY:
pip, clh, bmy, 10 Oct 2002: TOOLS VERSION 1.52
bmy, 26 Jan 2007: TOOLS VERSION 2.06
- Now compute gradient of YNEW with max
& min values & subscripts of. This avoids
the assumption that the first & last
elements of YNEW are different.
(Fix submitted by Mike Barkley, 1/26/07)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/org_corr.pro)
NAME:
PAUSE
PURPOSE:
Halts program execution until the user presses RETURN.
CATEGORY:
General
CALLING SEQUENCE:
PAUSE
INPUTS:
MSG -> Specify a message to be displayed before pausing
program execution. MSG may be omitted.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
PRINT, DATA
PAUSE
; Prints a data array and then pauses to allow
; the user time to examine the results.
PRINT, DATA
PAUSE, 'look at data'
; Same as above exmaple, but this time, print an
; informational message before pausing.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/pause.pro)
NAME:
PEDGE (function)
PURPOSE:
Given the pressures at the centers of a model grid, returns
the pressures at the edges of the grid.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = PEDGE( MID, PSURF )
INPUTS:
MID -> Vector of pressure centers that defines the grid.
MID will be sorted in descending order.
PSURF -> Surface pressure (which also corresponds to the
lowest pressure edge). Default is 1000.0 (mb).
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The vector of pressures at level edges [hPa]
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The relationship between sigma centers and sigma edges is
as follows:
MID[N] = ( EDGE[N] + EDGE[N+1] ) / 2
or conversely:
EDGE[N+1] = ( 2 * MID[N] ) - EDGE[N]
where EDGE[N] is the lower pressure edge, and EDGE[N+1]
is the upper sigma edge of the box with center MID[N].
The boundary condition PE[0] = PSURF is necessary to
start the iteration.
EXAMPLE:
RESULT = PEDGE( [ 900, 700, 500 ], 1000.0 )
PRINT, RESULT
1000.00 800.000 600.000 400.000
; Prints edges between levels 900, 700, 500 hPa
; with the surface pressure being 1000 hPa.
MODIFICATION HISTORY:
bmy, 17 Jun 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/pedge.pro)
NAME:
PERCENTILES
PURPOSE:
Compute percentiles of a data array (both ways: data that
correspond to %, and % that correspond to data)
CATEGORY:
Math & Units
CALLING SEQUENCE:
Y = PERCENTILES( DATA [,VALUE=value-array] )
INPUTS:
DATA -> the vector containing the data
KEYWORD PARAMETERS:
VALUE --> array or scalar that specify percentile(s) to
compute. If /REVERSE is set, a percentage that
correspond to Value is return.
Default percentile to compute is standard set of min
(0%), 25%, median (=50%), 75%, and max(100%) which can
be used for box- and whisker plots. The values in the
VALUE array must lie between 0. and 1.
If /REVERSE, default value is mean(data)
INTERPOLATE --> Behaves like EVEN keyword for MEDIAN.
If no element of the data falls exactly on the requested
percentile value, then the 2 adjacent data elements are
linearly interpolated to the requested percentile value.
When using the INTERPOLATE keyword, returned values may
not be elements of the input array.
/NAN --> if set, ignores NaN values. You must use that
keyword if your dataset may have NaN.
/REVERSE --> to get % corresponding to data value, instead of
data corresponding to %
OUTPUTS:
Y -> The function returns an array with the percentile
values or -1 if no data was passed or value contains
invalid numbers.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
x = (findgen(31)-15.)*0.2 ; create sample data
y = exp(-x^2)/3.14159 ; compute some Gauss distribution
p = percentiles(y,value=[0.05,0.1,0.9,0.95])
print,p
IDL prints : 3.92826e-05 0.000125309 0.305829 0.318310
MODIFICATION HISTORY:
mgs, 03 Aug 1997: VERSION 1.00
mgs, 20 Feb 1998: - improved speed and memory usage
(after tip from Stein Vidar on newsgroup)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
cdh & jaf, 21 Oct 2009: GAMAP VERSION 2.13
- fixed incorrect values for small sample sizes
- removed unnecessary loop
- added NaN keyword
phs, 22 Oct 2009: - added REVERSE keyword
- updated handling of NaN
cdh, 19 Jun 2012: - added INTERPOLATE keyword
(See /n/home09/ryantosca/IDL/gamap2/math_units/percentiles.pro)
NAME:
PHYSCONST
PURPOSE:
Creates a system variable named !PHYSCONST which contains
various physical constants.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
PHYSCONST
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
NOTES:
The !PHYSCONST system variable contains both the short names
(e.g. C) and long names (e.g. SPEED_OF_LIGHT) for the various
physical constatnts.
EXAMPLE:
PHYSCONST
HELP, !PHYSCONST, /STRU
** Structure <108c0378>, 18 tags, length=144, data length=144, refs=2:
C DOUBLE 2.9979000e+08
SPEED_OF_LIGHT DOUBLE 2.9979000e+08
H DOUBLE 6.6260000e-34
PLANCK DOUBLE 6.6260000e-34
E DOUBLE 1.6020000e-19
ELEMENTARY_CHARGE DOUBLE 1.6020000e-19
ME DOUBLE 9.1090000e-31
ELECTRON_MASS DOUBLE 9.1090000e-31
NA DOUBLE 6.0220000e+23
AVOGADRO DOUBLE 6.0220000e+23
R DOUBLE 8.3140000
MOLAR_GAS DOUBLE 8.3140000
K DOUBLE 1.3810000e-23
BOLTZMANN DOUBLE 1.3810000e-23
SIGMA DOUBLE 5.6710000e-08
STEFAN_BOLTZMANN DOUBLE 5.6710000e-08
G DOUBLE 9.8066500
ACCELERATION_DUE_TO_GRAVITY DOUBLE 9.8066500
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/physconst.pro)
NAME:
PIE
PURPOSE:
This procedure plots a pie chart.
CATEGORY:
Plotting
CALLING SEQUENCE:
PIE, DATA
INPUTS:
DATA -> The data vector to be plotted in the pie chart.
KEYWORD PARAMETERS:
BORDERCOLOR -> The color of the circumference line of the
pie chart. The default is the background color.
BORDERTHICK -> The thickness of the circumference line of
the pie chart.
COLORS -> A vector containing the color table for the
pie slices.
DATA -> If set, the plot is done in data coordinates.
The default is normal coordinates.
DEVICE -> If set, the plot is done in device coordinates.
The default is normal coordinates.
NORMAL -> If set, the plot is done in normal coordinates.
This is the default.
NPOINTS -> The total number of points to be used for
defining all of the arcs, measured around the
circumference.
XPOS, YPOS -> The [X,Y] coordinates of the centre of the
pie chart.
RADIUS -> The radius of the pie chart.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PIE, [2,3,4,5]
; Make a pie chart of the values 2, 3, 4, and 5.
MODIFICATION HISTORY:
Written by: Edward C. Wiebe, 1998-02-05.
Modified: Daithi A. Stone (stoned@atm.ox.ac.uk), 2002-04-12
(re-wrote, added documentation)
Modified: DAS, 2005-08-05 (replaced SUM.PRO use with TOTAL;
removed CONSTANTS.PRO use)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- updated comments
(See /n/home09/ryantosca/IDL/gamap2/plotting/pie.pro)
NAME:
PLANE_PLOT
PURPOSE:
Plots data from the GEOS-CHEM plane following diagnostic
atop a world map. Multiple flights can be plotted.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
PLANE_PLOT, VAR, FLTID [, Keywords ]
INPUTS:
VAR -> Variable name for which to plot data. VAR should
match the variable names in the GEOS-CHEM input file
"Planeflight.dat" (e.g. TRA_001, GMAO_TEMP, REA_O1D, etc.)
FLTID -> Flight ID(s) for which to plot data. These should
match the flight ID's in the GEOS-CHEM input file
"Planeflight.dat" (e.g. P3B01, DC801, etc.)
KEYWORD PARAMETERS:
FILENAME -> Name of the file containing GEOS-CHEM plane
following diagnostic output. If FILENAME is omitted,
then a dialog box will prompt the user to supply a file
name.
LIMIT -> A 4-element vector with [MINLAT,MINLON,MAXLAT,MAXLON],
which will specify the bottom left and top right corners
of the map plot in degrees. Default is to plot the
entire Northern Hemisphere [0,-180,90,180].
MPARAM -> A 3 element vector which specifies the LAT0, LON0,
and ROT values to be passed to MAP_SET. Default is
[0,0,0].
SYMBOL -> Number of the symbol used to plot each data point.
SYMBOL corresponds to the types of symbols defined with
the routine "sym.pro" in the TOOLS package. Default is
1 (filled circle).
SYMSIZE -> Size of the plot symbol. Default is 1.5
_EXTRA=e -> Passes extra keywords to MAP_SET, MAP_GRID,
and MAP_CONTINENTS.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================
COLORBAR
CTM_READ_PLANEFLIGHT (function)
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
PLANE_PLOT, 'O3', 'P3B04', $
LIMIT=[20,-120,50,-60], $
FILENAME='plane.log'
; Plots GEOS-CHEM O3 data (stored in "plane.log) from
; the model grid boxes corresponding to flight P3BO4
; over the USA.
PLANE_PLOT, 'O3', ['P3B04','DC801'], $
LIMIT=[20,-120,50,-60], $
FILENAME='plane.log'
; Plots GEOS-CHEM O3 data (stored in "plane.log) from
; the model grid boxes corresponding to flights P3BO4
; and DC801 over the USA.
MODIFICATION HISTORY:
bmy, 23 Apr 2004: GAMAP VERSION 2.03
bmy, 13 Mar 2006: GAMAP VERSION 2.05
- Slight modifications for new version
of ctm_read_planeflight.pro
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/plane_plot.pro)
NAME:
PLOTSIGMA
PURPOSE:
PLOTSIGMA plots the sigma level extent of various CTM's
(including GISS-II, GISS-II', GEOS-1, GEOS-STRAT, GEOS-2,
and FSU) side by side for comparison. Useful for making
viewgraphs.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
PLOTSIGMA, MODELNAME [, keywords ]
INPUTS:
MODELNAME -> A string (or array of strings) containing the
names of the models to be plotted. Default is [ 'GEOS1' ].
KEYWORD PARAMETERS:
/PLEFT -> Will cause pressure to be plotted (with regular
spacing) along the left Y-axis. Default is to plot
altitude (with regular spacing) along the left Y-axis).
/PS -> Causes output to be sent to the PostScript Device.
SURFP -> The surface pressure in mb used to convert sigma
levels into absolute pressures. Default is 1010.
YRANGE -> Specifies the plotting range [Ymin, Ymax]
along the left Y-axis. Default is [ 0, 32 ] km.
OUTPUTS:
None
SUBROUTINES:
External subroutines required:
--------------------------------------------
CTM_TYPE (function) CTM_GRID (function)
USSA_PRESS (function) USSA_ALT (function)
MYCT_DEFAULTS (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PLOTSIGMA, /PLEFT, $
['GISS_II', 'GEOS1', 'GEOS_STRAT', 'FSU' ], $
YRANGE=[1010, 150], SURFP=1010.0
; plots sigma levels for GISS-II, GEOS-1, GEOS-STRAT,
; and FSU models, with pressure on the left Y-axis,
; assuming a surface pressure of 1010 mb, for the range
; of 1010 mb to 150 mb.
PLOTSIGMA, $
['GISS_II', 'GEOS1', 'GEOS_STRAT', 'FSU' ], $
YRANGE=[0, 16], SURFP=1010.0
; Same as above, but plots with altitude on left Y-axis,
; and for the range 0 km - 16 km.
MODIFICATION HISTORY:
bmy, 15 Aug 1997: VERSION 1.00
bmy, 30 Oct 1997: VERSION 1.01
bmy, 15 Jun 1998: VERSION 1.10
- now uses CTM_TYPE, CTM_GRID
bmy, 17 Jun 1998: GAMAP VERSION 1.20
bmy, 19 Jun 1998: - add array for color indices
- also supports FSU model
bmy, 03 Jan 2000: GAMAP VERSION 1.44
- eliminate call to MYCT and keywords
- cosmetic changes
bmy, 06 Sep 2000: GAMAP VERSION 1.46
- added text string for GEOS-3
bmy, 26 Jun 2001: GAMAP VERSION 1.48
- now pass _EXTRA=e to PLOT command
- added extra error checking
bmy, 23 Jul 2001: - now use MYCT_DEFAULTS() to set up
MYCT color information
bmy, 28 Sep 2002: GAMAP VERSION 1.51
- now gets color information from the
!MYCT system variable
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Modified for GEOS-4 and GEOS-5
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/plotsigma.pro)
NAME:
PLOT_CPD
PURPOSE:
Plots a cumulative probability distribution from a data array.
CATEGORY:
Plotting
CALLING SEQUENCE:
PLOT_CPD, DATA, [ , Keywords ]
INPUTS:
DATA -> The array holding the data points to plot as a
cumulative probability distribution.
KEYWORD PARAMETERS:
COLOR -> Sets the color of the plot window and data.
Default is !MYCT.BLACK.
CHARSIZE -> Sets the size of the text in the plot window.
Default is 1.8.
/OVERPLOT -> Set this switch to overplot data atop an
existing plot window. Default is to create a new plot.
SYMBOL -> Input argument for SYM, which will define the type
of plot symbol. Default is 6 (open circle).
XMARGIN, YMARGIN -> Specifies the "cushion" of space around
the plot window. Defaults are XMARGIN=[10,1], and
YMARGIN=[4,2].
XMINOR, YMINOR -> Specifies the number of minor ticks (i.e.
small ticks between the major ticks) along the X and Y
axes. Defaults are is XMINOR=4 and YMINOR=4.
XRANGE, YRANGE -> Defines the plot range along the X and Y
axes. Defaults are XRANGE=[-4,4] and YRANGE=[0,100].
XTICKNAME, YTICKNAME -> Specifies the tick labels on the
X and Y axes.
XTICKS, YTICKS -> Specifies the number of major ticks (i.e.
along the X and Y axes. Defaults are is XTICKS=8 and
YTICKS=4.
XTITLE, YTITLE -> Specifies the X and Y axis title strings.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===================================
QQNORM (function) SYM (function)
REQUIREMENTS:
Requires routines from both TOOLS and GAMAP packages.
NOTES:
None
EXAMPLE:
PLOT_CPD, FINDGEN(200), COLOR=!MYCT.BLACK
PLOT_CPD, FINDGEN(100), COLOR=!MYCT.RED, /OVERPLOT
; Plot 2 data arrays as cumulative probability
; distributions. The 2nd array (red) is overplotted
; onto the existing plot window.
MODIFICATION HISTORY:
swu & bmy, 10 Oct 2006: TOOLS VERSION 2.05
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/plotting/plot_cpd.pro)
NAME:
PLOT_GPROF
PURPOSE:
Reads a GNU Profile (gprof) text output and creates a bar graph
of how long subroutines take to execute. This is useful in
examining code for computational bottlenecks.
CATEGORY:
Plotting
CALLING SEQUENCE:
PLOT_GPROF, FILENAME [,keywords]
INPUTS
FILENAME -> Text file containing profiling output from gprof.
KEYWORD PARAMETERS:
N_DISPLAY -> The number of routines to display, from slowest
to fastest. The default is 30.
BARCOLOR -> The color table value that will be used to plot
the bars. Default is !MYCT.RED.
/VERBOSE -> If set, will print a listing of the N_DISPLAY
slowest routines. The routine name, execution time,
and percentage of total run time will be printed.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
Uses these GAMAP routines
==========================
STRPAD (function)
STRRIGHT (function)
NOTES:
For instructions on using the GNU Profiler (gprof) and creating
a text file with profiling output, please see this wiki page:
http://wiki.geos-chem.org/Profiling_GEOS-Chem.
EXAMPLE:
PLOT_GPROF, 'Profile_Gfortran_Intel.txt', N_DISPLAY=40, /VERBOSE
; Creates a bar plot showing the 40 slowest routines
; contained in the GNU profiler output file named
; "Profile_Gfortran_Intel.txt". Also will print the
; profiling info to the screen.
MODIFICATION HISTORY:
bmy, 15 Dec 2016: GAMAP VERSION 2.19
- Initial version
(See /n/home09/ryantosca/IDL/gamap2/plotting/plot_gprof.pro)
NAME:
PLOT_MASSCONS
PURPOSE:
Plots the evolution of total mass vs. time from the
geosfp_2x25_masscons simulation.
CATEGORY
Benchmarking
CALLING SEQUENCE:
PLOT_MASSCONS, FILENAME, _EXTRA=e
INPUTS:
FILENAME -> Name of the file containing the total mass
printed every 6 hours from the geosfp_2x25_masscons
simulation. Default is "tracer_mass_kg.dat".
OUTPUT:
None (creates a plot)
KEYWORD PARAMETERS:
/VERBOSE -> Print extra information (min and max of time
and total mass) to the screen.
_EXTRA =e -> Passes extra keywords to PLOT and OPLOT routins.
SUBROUTINES:
External Subroutines Required:
===============================
NYMD2TAU (function)
STRBREAK (function)
STRSCI (function)
REQUIREMENTS:
None
NOTES:
This could probably be written a little more efficiently.
Also, plotting output has been kept very basic, as we are
mostly using this for quick validation plots, which do not
need to be fancy.
EXAMPLE:
PLOT_MASSCONS, 'tracer_mass_kg_2017.dat'
; Creates a plot from the data in the given file name.
MODIFICATION HISTORY:
bmy, 22 Feb 2017: GAMAP VERSION 2.19
- Initial version
(See /n/home09/ryantosca/IDL/gamap2/benchmark/plot_masscons.pro)
NAME:
PMID (function)
PURPOSE:
Given the pressures at the vertical edges of a model grid,
return the pressures at the centers of the grid.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = PMID( EDGE )
INPUTS:
EDGE -> Vector of pressures or pressure-altitudes at
the edges of the model grid [hPa]
KEYWORD PARAMETERS:
OUTPUTS:
RESULT -> The vector of pressures at the grid centers [hPa]
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The relationship between sigma centers and sigma edges is
as follows:
MID[N] = ( EDGE[N] + EDGE[N+1] ) / 2.0
where EDGE[N] is the lower sigma edge, and EDGE[N+1]
is the upper sigma edge of the box with center MID[N].
EXAMPLE:
Result = PMID( [ 1000.0, 800.0, 600.0, 400.0 ] )
print, Result
900.000 700.000 500.000
MODIFICATION HISTORY:
bmy, 17 Jun 1999: VERSION 1.00
bmy, 22 Oct 1999: VERSION 1.44
- Now use SHIFT to compute the average
between successive edges
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/pmid.pro)
NAME:
PROFILES
PURPOSE:
Creates longitudinal difference profiles of tracers along
15S latitude and 42N latitude.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
PROFILES, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
ALTRANGE -> A 2-element vector containing the altitude range
(in km) of the data to be plotted. ALTRANGE will be
passed to CTM_EXTRACT.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DO_FULLCHEM -> Set this switch to plot the chemically
produced OH in addition to the advected tracers.
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range to predetermined values as returned
by routine GET_DIFF_RANGE.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
=======================================================
PlotProfile
External Subroutines Required:
=======================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_EXTRACT (function) CTM_GET_DATA
GET_DIFF_RANGE (function) GETMODELANDGRIDINFO
EXTRACT_FILENAME (function) MULTIPANEL
CHKSTRU (function) MYCT
OPEN_DEVICE TVMAP
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLE:
FILES = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
ALTRANGE = [ 0, 20 ]
TAUS = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
TRACERS = INDGEN( 43 ) + 1
VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
PROFILES, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, $
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'
; Creates ratio plots of two GEOS-CHEM versions
; (in this case v7-04-11 / v7-04-10) for July 2001.
; Output is sent to PostScript file "myplot.ps".
; The min and max of the data on each plot panel is
; restricted to pre-defined values returned by
; function GET_DIFF_RANGE.
PROFILES, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, $
/DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Same as the above example, but the min & max of
; each plot panel corresponds to the dynamic range
; of the data (centered around zero)
MODIFICATION HISTORY:
bmy, 14 Nov 2007: VERSION 1.01
- Initial version
bmy, 20 Nov 2007: VERSION 1.02
- Now draw out-of-bounds triangles for
the colorbar when using the "small"
data ranges. New feature of TVMAP.
bmy, 08 Feb 2011: VERSION 1.03
- Now display in the top-of-plot title
if the dynamic range option is used.
bmy, 08 Jun 2011: VERSION 1.04
- Added /DO_FULLCHEM keyword
- Now call COLORBAR with the UPOS keyword
to place the colorbar unit string properly
- Now use appropriate settings for creating
plots w/ the full dynamic range (/DYNRANGE)
- Now restore !MYCT sysvar to previous
settings upon exiting the program
- Better adjust colorbar position for /PS
bmy, 11 May 2012: GAMAP VERSION 2.16
- Modify the error check to allow
comparison of equivalent vertical grids
(e.g. GEOS-5, MERRA, GEOS-5.7) even if
the model names differ
mps, 04 Mar 2016: - Include MERRA2 in the check for equivalent
vertical grids
(See /n/home09/ryantosca/IDL/gamap2/benchmark/profiles.pro)
NAME:
PROGRAM_DIR
PURPOSE:
Given a file, returns the directory in which the file resides.
CATEGORY:
File & I/O
CALLING SEQUENCE:
RESULT = PROGRAM_DIR( FILE [, Keywords ] )
INPUTS:
FILE -> Name of the file for which a directory search
will be performed.
KEYWORD PARAMETERS:
/FULL_PATH -> Set this switch to return the directory
name as an absolute path (e.g. /users/home/IDL/)
instead of a relative path (e.g. ~/IDL).
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
EXPAND_PATH (function)
EXTRACT_FILENAME (function)
REQUIREMENTS:
None
NOTES:
(1) Unix is case-sensitive. It is recommended to keep
file names in all lowercase on Unix to avoid file
search confusion.
EXAMPLES:
(1)
PRINT, PROGRAM_DIR( 'myct.pro' )
~/IDL/tools/
; Finds the directory in which "myct.pro" resides.
(2)
PRINT, PROGRAM_DIR( 'myct.pro', /FULL_PATH )
/users/ctm/bmy/IDL/tools
; Same as the above example, but this time returns
; the directory as an absolute path name.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/program_dir.pro)
NAME:
PULL_PL
PURPOSE:
Copies datablocks from NRT bpch files for category PORL-L=$
to a separate file for archival purposes.
CATEGORY:
Regridding
CALLING SEQUENCE:
PULL_PL, DATE
INPUTS:
DATE -> YYYYMMDD of the date for which to extract data.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=============================================
CTM_GET_DATA CTM_MAKE_DATAINFO (function)
CTM_WRITEBPCH GETMODELANDGRIDINFO
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PULL_PL, 20051201
- Extracts PORL-L=$ data for 2005/12/01.
MODIFICATION HISTORY:
rch & bmy, 06 Dec 2005: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/pull_pl.pro)
NAME:
PWD
PURPOSE:
Print current working directory
CATEGORY:
General
CALLING SEQUENCE:
PWD [,result]
INPUTS:
none
KEYWORD PARAMETERS:
none
OUTPUTS:
RESULT -> (optional) string containing the current directory
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
Set !QUIET to 1 if you only want to return the working directory
but no screen output.
EXAMPLE:
PWD
; Prints current directory.
MODIFICATION HISTORY:
mgs, 23 Dec 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/pwd.pro)
NAME:
QQNORM
PURPOSE:
Procedure: sort the data, assign actual "probability" and
calculate the expected deviation from the mean.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = QQNORM( DATA )
INPUTS:
DATA -> Vector containing the data values. NOTE: DATA
will be sorted in ascending order and then returned.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Array where each element contains the expected
deviation from the mean of DATA.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
RESULT = QQNORM( DATA )
; Computes expected deviation from the mean.
MODIFICATION HISTORY:
mgs, 14 Dec 1998: VERSION 1.0
- extracted from w_calc.pro
pip, clh, bmy, 10 Oct 2002: TOOLS VERSION 1.52
amf, swu, bmy, 10 Oct 2006: TOOLS VERSION 2.05
- Now use simpler algorithm from
Arlene Fiore's code
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/qqnorm.pro)
NAME:
RATIOS
PURPOSE:
Creates ratio plots ( New/Old ) for GEOS-Chem tracers and OH.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
RATIOS, FILES, LEVELS, TAUS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
LEVELS -> A 4-element vector containing the level indices
for the GEOS-Chem surface layer and 500 hPa layer.
for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
NOTE: This is in Fortran notation (starting from 1!)
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DO_FULLCHEM -> Set this switch to plot the chemically
produced OH in addition to the advected tracers.
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range from 0.5 to 2.0.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
===========================================
ComputeRatios PlotRatio
External Subroutines Required:
============================================
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL COLORBAR_NDIV (function)
TVMAP UNDEFINE
CTM_GET_DATA, EXTRACT_FILENAME (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILES = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
LEVELS = [ 1, 1, 13, 13 ]
TAUS = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
TRACERS = INDGEN( 43 ) + 1
VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
RATIOS, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'
; Creates ratio plots of two GEOS-CHEM versions
; (in this case v7-04-11 / v7-04-11) for July 2001.
; Output is sent to PostScript file "myplot.ps".
; The min & max of the data will be fixed at -/+ 5%.
RATIOS, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
/DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Same as above, but this time the full dynamic range
; of the data will be displayed.
MODIFICATION HISTORY:
bmy, 14 Nov 2007: VERSION 1.01
- based on older routine "tracer_ratio.pro"
bmy, 20 Nov 2007: VERSION 1.02
- Now draw out-of-bounds triangles for
the colorbar when using the "small"
data ranges. New feature of TVMAP.;
bmy, 07 May 2008: VERSION 1.03
- Now allow for comparing models on 2
different vertical grids.
bmy, 08 Feb 2011: VERSION 1.04
- Now display in the top-of-plot title
if the dynamic range option is used.
bmy, 08 Jun 2011: VERSION 1.05
- Now create log plots in range 0.5 - 2.0
- Added /DO_FULLCHEM keyword
- Adjust colorbar so that the 0.9 - 1.1
range shows up in white.
- Now restore !MYCT sysvar to previous
settings upon exiting the program
- Better adjust colorbar position for /PS
mps, 29 Mar 2013: - Now plot HO2 ratios
(See /n/home09/ryantosca/IDL/gamap2/benchmark/ratios.pro)
NAME:
READDATA
PURPOSE:
This subroutine reads in almost any ASCII file and returns
two arrays containing the names of the variables and their
values. The data is read line by line or in one step if
LINES is specified.
CATEGORY:
File & I/O
CALLING SEQUENCE:
READDATA, FILENAME, DATA, HEADER [, NCOL, NDAT ] [, KEYWORDS ]
INPUTS:
FNAME -> Name of fname to be read, e.g. 'flight12.dat'
KEYWORD PARAMETERS:
COLS -> number of columns to be read (must be used if no header
is read in, i.e. /NOHEADER is specified). Can be used
to read in a subset of columns if the file contains a header
line with variable names (i.e. if *not* /NOHEADER).
LINES -> number of lines to be read (not much faster for large
data sets, but allows to read in a subset of the data)
DELIM -> Separator between names in the header (default=',')
SKP1 -> Number of lines to be skipped before the variable
definition (default=0)
SKP2 -> .. after the variable definition (default=0)
SKIP -> same as SKP1 (SKP1 will overwrite SKIP. SKIP may be
not longer supported in future versions !)
AUTOSKIP -> for files that state the number of comment lines
in the first line. If keyword NOHEADER is not set, READDATA
expects a list of variable names as last comment line.
AUTOSKIP overrides settings of SKP1 and SKP2.
TRANSPOSE -> Normally, 1st array dimension is for variables,
2nd is for observations. /TRANSPOSE will reverse that
order (see note).
NOHEADER -> don't read a header (COLS must be specified in
this case !)
NODATA -> don't read data (stop after header). DATA parameter
must still be specified !
COMMENTS -> returns string array of all the comment lines in
the data file for later use
MAXCOMMENTS -> limits maximum number of comment lines to be
retrieved (default: 255)
QUIET -> Normally, READDATA prints the number of variables
found and number of data lines read. Use this option
to suppress all output.
/DOUBLE -> If set, will return data in double precision.
(Default is to return data in single precision.)
NAN_REPLACEMENT -> Allows you to provide a replacement value
for the following types of missing data fields: NaN,
nan, NA, na, Infinity, infinity, Missing, missing.
OUTPUTS:
DATA -> data array that was read in
NAMES -> string array of names in header
NCOL -> integer containing the number of columns
NDAT -> long integer containing the number of observations
COMMENTS -> string array containing all header lines.
If AUTOSKIP is set, skp1, and skp2 will contain the
actual amount of lines to skip (e.g. for re-storing
header information in EXPLORE)
SUBROUTINES:
External Subroutines Required:
==============================
OPEN_FILE
STRBREAK (function)
USAGE
REQUIREMENTS:
None
NOTES:
Default of the returned DATA array is: 1st index = variable,
2nd index = observation. Use the /TRANSPOSE option for reverse order
If /NOHEADER is used, then COLS must specify the actual number of
data columns in FNAME. Otherwise it can be used to read a subset of
the data from 0 to cols-1 columns.
IDL Parameters are optional. Of course, you should not readdata without
passing a DATA argument, but you can ignore the HEADER,NCOL, and NDAT
params.
EXAMPLES:
(1)
READDATA,'mydata.dat',DATA,HEADER,DELIM=' ',SKIP=5
... will read in the ASCII file mydata.dat and store the data in DATA.
The header information will be stored in HEADER. The header items are
seperated by blank spaces, and the first 5 lines should be ignored.
To pick a certain variable afterwards, type:
VAR = DATA(WHERE HEADER EQ 'MYVAR'),*)
(2)
READDATA,'noheader.dat',DATA,DELIM=';',NCOLS=3
... will read a three column ASCII file with no header information.
You can manually make up a header with
HEADER = ['VAR1','VAR2','VAR3']
or you can pass the HEADER argument and receive ['X1','X2','X3'] as
header.
(3)
READDATA,'mydata.dat',DATA,HEADER,DELIM=' ',SKP1=5,LINES=60,COLS=4, $
COMMENTS=COMMENTS
... will read in 60 lines and 4 columns of the ASCII file mydata.dat
and return 6 comment lines in COMMENTS (5 + variable names)
MODIFICATION HISTORY:
mgs 03/12/1997: - last update : 05/22/97
mgs 01 Aug 1997: - added template
mgs 15 Sep 1997: - added LINES option and removed some twitch in the
handling of TRANSPOSE. Unfortunately,
LINES does not improve the speed as
desired, but you can restrict the reading to
a smaller subset of the data.
mgs 26 Sep 1997: MAJOR REVIEW
- bug fixes in noheader option
- bug fixes in COLS and NCOL handling
- removed units option and created comments
keyword instead. program now reads in
all header lines into a string array
including the variable names line.
- automatic generation of a header if
/NOHEADER is specified
mgs 06 Nov 1997: - Added AUTOSKIP option for easier reading
of e.g. NASA formatted files.
mgs 01 Dec 1997: added MAXCOMMENTS keyword and limit
- skp1 now returns correct amount if
autoskip is set
mgs 30 Dec 1997: added NODATA keyword
mgs 21 Aug 1998: now uses open_file routine to allow wildcards
bmy 12 May 2005: added /DOUBLE keyword to force double precision
bmy & phs, 21 Aug 2007: GAMAP VERSION 2.10
- Now use STRBREAK, which is version independent
- Remove internal function USE_READDATA; we
now call USAGE to display program options
if the wrong # of arguments are passed
- Updated comments
bmy, 12 Dec 2012: GAMAP VERSION 2.16
- Now give the user the option to read in
data as characters and then to strip out
strings such as "NaN" or "NA" via the
- NAN_REPLACEMENT keyword
(See /n/home09/ryantosca/IDL/gamap2/file_io/readdata.pro)
NAME:
READ_BDT0001
PURPOSE:
Read a simple binary data file with size information
and variable names and units (format BDT0001).
CATEGORY:
File & I/O
CALLING SEQUENCE:
READ_BDT0001,filename,data,vardesc,nvars,nlines [,keywords]
INPUTS:
FILENAME -> Name of the file to read or a file mask that
will be used in the PICKFILE dialog (see OPEN_FILE)
If FILENAME is a named variable, the actual filename
will be returned and replace a template.
KEYWORD PARAMETERS:
NAMES -> a named variable will contain a string array with
NVARS variable names
UNITS -> ... a string array with NVARS physical units
COMMENTS -> A named variable that will return comment lines
stored in the data file. NOTE that comments are not
saved in vardesc.
DEFAULTMASK -> Default mask for PICKFILE dialog (see
OPEN_FILE).
FILE_ID -> A named variable will return the file identifier
string (80 characters). This string will be returned
even if the file is of wrong type and no data was read.
TYPE -> A named variable will contain the data type
_EXTRA keywords are passed on to OPEN_FILE
OUTPUTS:
DATA -> an array with NLINES * NVARS values. The type of the
data array depends on the information stored in the file.
VARDESC -> A variable descriptor structure (see GTE_VARDESC)
NVARS -> number of variables in file
NLINES -> number of data lines
SUBROUTINES:
REQUIREMENTS:
Uses OPEN_FILE
NOTES:
See also WRITE_BDT0001
Format specification:
file_ID : 80 byte character string
NVARS, NLINES, NCOMMENTS, TYPE : 4 byte integer (long)
NAMES : NVARS*40 byte character string
UNITS : NVARS*40 byte character string
COMMENTS : NCOMMENTS records of 80 byte length
DATA : 8 byte float (double) array NLINES*NVARS
EXAMPLE:
READ_BDT0001,'~/tmp/*.bdt',data,vardesc,comments=comments
; Will read a file that the user selects with the PICKFILE
; dialog. No information about the actual filename is
; returned.
FILE = '~/tmp/*.bdt'
READ_BDT0001,FILE,data,vardesc,nvars,nlines,file_id=file_id
; Does the same thing, but this time FILE will contain the
; actual filename. The number of variables and lines are
; returned in NVARS and NLINES, the file identifier string
; is returned in file_id
MODIFICATION HISTORY:
mgs, 24 Aug 1998: VERSION 1.00
mgs, 23 Dec 1998: VERSION 1.10:
- DATA now undefined if unsuccessful
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read data as big-endian
(See /n/home09/ryantosca/IDL/gamap2/file_io/read_bdt0001.pro)
NAME:
READ_BIN and PLOT_BIN
PURPOSE:
Read a simple binary 2-D file. The file must be F77
unformatted and contain the XDIM and YDIM information
as LONG integers in the first record.
CATEGORY:
File & I/O
CALLING SEQUENCE:
READ_BIN,FILENAME,DATA [,keywords]
PLOT_BIN,DATA [,keywords]
INPUTS:
FILENAME -> Name of the file to read
DATA (for PLOT_BIN) -> The data array as read with READ_BIN
KEYWORD PARAMETERS:
XDIM, YDIM -> return the dimensions of the data set.
_EXTRA -> used to pass extra keywords to OPEN_FILE. Probably
only useful with /SWAP_ENDIAN.
/PLOT -> Call PLOT_BIN directly.
(for PLOT_BIN)
MIN, MAX -> minimum and maximum to be used for conversion of
data to a byte array for display with TVIMAGE
TOP -> top value for BYTSCL
CT -> colortable numebr to use
/MAP -> set this keyword to overlay a map (isotropic cylindrical
projection)
OUTPUTS:
DATA -> The data array returned from READ_BIN
SUBROUTINES:
Uses OPEN_FILE and TVIMAGE
REQUIREMENTS:
None
NOTES:
Rather primitive program but demonstrates the principle use
of binary data files and TVIMAGE.
EXAMPLES:
READ_BIN,'~/mydata/*.bdat', DATA
PLOT_BIN, DATA, MIN=MIN(DATA,MAX=M), MAX=M
; is equivalent to
READ_BIN, '~/mydata/*.bdat', DATA, /PLOT
MODIFICATION HISTORY:
mgs, 15 Jan 1999: VERSION 1.00
mgs, 15 Jun 1999: - added header
- added PLOT keyword and _EXTRA
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read data as big-endian
(See /n/home09/ryantosca/IDL/gamap2/file_io/read_bin.pro)
NAME:
READ_CONC_RANGE
PURPOSE:
Reads a file containing default plotting range for given
GEOS-Chem tracers. This will be used to create absolute
difference plots for GEOS-Chem benchmarking.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
READ_CONC_RANGE, INPUTFILE
INPUTS:
INPUTFILE -> Name of the file that contains the default
plotting ranges for each GEOS-Chem tracer. Default
is "diff_range.1mon".
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================
OPEN_FILE STRBREAK (function)
REQUIREMENTS:
READ_CONC_RANGE must be called first to read the file with
default plotting ranges. This is normally done at the top
of driver routine BENCHMARK_1MON. After this has been done,
function GET_CONC_RANGE may be used to return the default
plotting range from within another program.
NOTES:
(1) Meant to be used in conjunction with the GEOS-Chem
benchmark plotting codes.
(2) Default ranges for each tracer are read from a file by
this routine and stored in the GDR common block.
EXAMPLE:
READ_CONC_RANGE, 'conc_range.1mon'
GET_CONC_RANGE, 'NOx', THIS_LOBOUND, THIS_HIBOUND, UNIT
PRINT*, THIS_LOBOUND, THIS_HIBOUND, UNIT
-0.100000 0.100000, ppbv
; Prints the default plotting range for NOx
MODIFICATION HISTORY:
bmy, 05 Sep 2012: VERSION 1.00
bmy, 24 Jan 2014: GAMAP VERSION 2.17
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/benchmark/read_conc_range.pro)
NAME:
READ_DIFF_RANGE
PURPOSE:
Reads a file containing default plotting range for given
GEOS-Chem tracers. This will be used to create absolute
difference plots for GEOS-Chem benchmarking.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
READ_DIFF_RANGE, INPUTFILE
INPUTS:
INPUTFILE -> Name of the file that contains the default
plotting ranges for each GEOS-Chem tracer. Default
is "diff_range.1mon".
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================
OPEN_FILE STRBREAK (function)
REQUIREMENTS:
READ_DIFF_RANGE must be called first to read the file with
default plotting ranges. This is normally done at the top
of driver routine BENCHMARK_1MON. After this has been done,
function GET_DIFF_RANGE may be used to return the default
plotting range from within another program.
NOTES:
(1) Meant to be used in conjunction with the GEOS-Chem
benchmark plotting codes.
(2) Default ranges for each tracer are read from a file by
this routine and stored in the GDR common block.
EXAMPLE:
READ_DIFF_RANGE, 'diff_range.1mon'
PRINT, GET_DIFF_RANGE( 'NOx' )
-0.100000 0.100000
; Prints the default plotting range for NOx
MODIFICATION HISTORY:
bmy, 14 Nov 2007: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/benchmark/read_diff_range.pro)
NAME:
READ_EPTOMS
PURPOSE:
Read Earth Probe TOMS data as retrieved from
http://jwocky.gsfc.nasa.gov and store them as datainfo
records so that they can be displayed with GAMAP.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
READ_EPTOMS [,DATA] [,keywords]
INPUTS:
KEYWORD PARAMETERS:
FILENAME -> filename of TOMS data
DATAINFO -> A named variable will return the newly
created daatinfo structure.
MODELINFO, GRIDINFO -> named variables will return
the "model" and grid information for the EP-TOMS
data. The grid is a 2-dimensional "generic" grid.
OUTPUTS:
DATA -> contains 2D array with EP-TOMS data (for use without
GAMAP).
SUBROUTINES:
uses open_file, ctm_type, ctm_grid, ctm_make_datainfo
REQUIREMENTS:
None
NOTES:
For tropical ozone in March, I used the following options
in the call to GAMAP:
myct,27,ncol=32,bot=20,range=[0.15,0.8]
c_lev = [150,200,220,230,240,250,260,270,280, $
290,300,310,320,330,340,350,375,400]
gamap,/nofile,c_lev=c_lev,c_col=[0,17,2*indgen(21)+18], $
/cbar,mlinethick=2,ncolors=32,bottom=18, $
cbmin=220,cbmax=400,div=10 [,frame0=4]
(the frame0 keyword is used to save GIF files)
EXAMPLE:
read_eptoms,file='/data/pem-tb/satellite/eptoms/*.ept'
gamap [... options]
MODIFICATION HISTORY:
mgs, 02 Apr 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/read_eptoms.pro)
NAME:
READ_H5DATASET
PURPOSE:
Convenience routine to read dataset variables
from Hierarchical Data Format version 5 (HDF5) files.
Also works for HDF-EOS files!
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
DATAFIELD = READ_H5DATASET( FID, DATASET_NAME )
INPUTS:
FID -> HDF5 File ID, as returned by routine H5F_OPEN
DATASET_NAME -> Name of the scientific dataset variable that
you want to extract from the file.
KEYWORD PARAMETERS:
None
OUTPUTS:
DATAFIELD -> Array containing extracted data from the HDF file.
SUBROUTINES:
None
REQUIREMENTS:
Need to use a version of IDL w/ HDF5 library installed.
NOTES:
From Trevor Beck (trevor.beck@noaa.gov) for GOME-2.
EXAMPLE:
; Specify the file name
FILE = 'GOME_xxx_1B_M02_20070105012056Z_20070105030556Z_R_O_20080613081807Z.337p4_356p1.brs.hcho.he5'
; Make sure the file is a HDF5 file
IF ( H5F_IS_HDF5( FILE ) eq 0 ) then MESSAGE, 'Not an HDF-5 file!'
; Open the HDF file and get the file ID # (FID)
FID = H5F_OPEN( FILE )
IF ( FID lt 0 ) then MESSAGE, 'Error opening file!'
; Read the AMF field from disk
; NOTE: the swath name is "Column"
AMF = READ_H5DATASET( FID, "/Column/Amf" )
; Close the file
H5_CLOSE, FID
MODIFICATION HISTORY:
bmy, 28 May 2009: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/file_io/read_h5dataset.pro)
NAME:
READ_MLD
PURPOSE:
Read Ocean mixed layer depth data as retrieved from
http://www.nodc.noaa.gov/OC5/mixdoc.html and store
them as datainfo records so that they can be displayed
with GAMAP.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
READ_MLD [,DATA] [,keywords]
INPUTS:
None
KEYWORD PARAMETERS:
FILENAME -> filename of MLD data
DATAINFO -> A named variable will return the newly
created daatinfo structure.
MODELINFO, GRIDINFO -> named variables will return
the "model" and grid information for the EP-TOMS
data. The grid is a 2-dimensional "generic" grid.
OUTPUTS:
DATA -> contains 2D array with mixed layer depth data
(for use without GAMAP).
SUBROUTINES:
uses open_file, ctm_type, ctm_grid, ctm_make_datainfo
REQUIREMENTS:
None
NOTES:
In the call to GAMAP you must use the /NOFILE option.
EXAMPLE:
READ_MLD, FILE='~/download/mixed_layer_depth/mld*'
GAMAP, /NOFILE, ...
MODIFICATION HISTORY:
mgs, 30 Jun 1999: VERSION 1.00 (derived from read_eptoms)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/read_mld.pro)
NAME:
READ_SONDE
PURPOSE:
Read climatological ozone sonde data as compiled by
Jennifer A. Logan at Harvard University.
If successful, the procedure returns a structure
with all information from a sondeXXX.* file.
Ozone concentrations are automatically converted to ppbv.
The data can be downloaded via ftp from io.harvard.edu
path= pub/exchange/sonde. Please read the README files!
CATEGORY:
Atmospheric Sciences, File & I/O
CALLING SEQUENCE:
READ_SONDE,filename,data
INPUTS:
filename -> Name of the file containing the sonde data.
This parameter can contain wildcards (*,?) in which case
a file selection dialog will be displayed. If filename
is a variable, it will be replaced by the actual filename
that was opened.
KEYWORD PARAMETERS:
MBAR -> return ozone concentrations in mbar rather than ppbv
STATIONS -> Can be used either as input or output for a list
of station codes, locations and names as retrieved with
procedure read_sondestations. STATIONS must be specified
(or is returned) as an array of structures.
OUTPUTS:
DATA -> A structure containing the following fields:
TITLE STRING 'Ozone sonde data'
STATION STRING
STATIONCODE INT
TIMERANGE STRING (See /n/home09/ryantosca/IDL/gamap2/atm_sci/read_sonde.pro)
NAME:
READ_SONDESTATIONS
PURPOSE:
Retrieve station codes and geographical locations for
ozone sonding stations as listed in file station.codes
from Jennifer A. Logan's ozone sonde climatology.
This routine is called from procedure READ_SONDE, and
only needs to be called explicitely if the station.codes
file resides neither in the current directory nor the
directory of the sonde data files.
The procedure will read the file station.codes once then
store the information in a common block for later use.
CATEGORY:
Atmospheric Sciences, File & I/O
CALLING SEQUENCE:
READ_SONDESTATIONS,stations [,filename]
INPUTS:
FILENAME (optional) -> if given, it specifies the path and filename
of the file that is normally called station.codes.
FILENAME may contain wildcards (*,?) in which case a
file selector dialog is displayed.
KEYWORD PARAMETERS:
None
OUTPUTS:
STATIONS -> An array with structures containing the stations
codes (integer), latitude, longitude, altitude (float),
amd name (string).
SUBROUTINES:
Uses OPEN_FILE and EXTRACT_FILENAME (used in OPEN_FILE)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
read_sondestations,stations,'station.codes'
; if called for the first time, reads file station.codes
; and returns information for all stations in stations.
; NOTE: In this case, the filename argument could have been
; omitted.
MODIFICATION HISTORY:
mgs, 02 Nov 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/read_sondestations.pro)
NAME:
RECTANGLE
PURPOSE:
Converts a vector with corner coordinates into X and Y
vectors that can be used with PLOTS, POLYFILL, or similar
IDL plotting commands.
CATEGORY:
Plotting
CALLING SEQUENCE:
RECTANGLE, CORNERS, XVEC, YVEC [, Keywords ]
INPUTS:
CORNERS -> A 1-D vector with [ X0, Y0, X1, Y1 ] coordinates.
(X0,Y0) is the bottom left corner of the plot region and
(X1,Y1) is the top right corner of the plot region.
KEYWORD PARAMETERS:
EXPAND -> A value that will be used to expand the size
of the rectangle by the same amount on all sides.
Default is 0.
OUTPUTS:
XVEC -> A 1-D vector with the X-coordinates listed in the
proper order for the POLYFILL or PLOTS commands.
YVEC -> A 1-D vector with the X-coordinates listed in the
proper order for the POLYFILL or PLOTS commands.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; Get a plot position vector from MULTIPANEL
MULTIPANEL, 2, POSITION=POSITION
PRINT, POSITION
0.112505 0.0874544 0.466255 0.956280
; Convert to X and Y vectors for PLOTS input
RECTANGLE, POSITION, XPOINTS, YPOINTS
PRINT, XPOINTS
0.112505 0.466255 0.466255 0.112505 0.112505
PRINT, YPOINTS
0.0874544 0.0874544 0.956280 0.956280 0.0874544
; Call PLOTS to draw a box
PLOTS, XPOINTS, YPOINTS, THICK=2, COLOR=1, /NORMAL
MODIFICATION HISTORY:
mgs, 13 Apr 1998: INITIAL VERSION
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/plotting/rectangle.pro)
NAME:
REGRIDAVHRR_LAI
PURPOSE:
Regrids LAI from a 0.5 x 0.5 grid onto a
CTM grid of equal or coarser horizontal resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDAVHRR_LAI [, Keywords ]
INPUTS:
NONE
KEYWORD PARAMETERS:
YEAR (string) -> 4 character string for the year in process
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
OUTPUTS:
Writes files:
vegtype.global
lai{MONTHNUM}.global
lai.global.{YEAR}.bpch
SUBROUTINES:
External Subroutines Required:
===============================================
CTM_TYPE (function) CTM_GRID (function)
CTM_RESEXT (function) CTM_GETWEIGHT
CTM_Make_DataInfo (function)
CTM_WriteBpch (fucntion)
nymd2tau (function)
Internal Subroutines:
==============================
RL_GETWEIGHT
REQUIREMENTS:
References routines from both GAMAP and TOOLS directories
NOTES:
(1) Filenames are hardwired -- change as necessary
(2) Regridding can take a while, especially at 1x1 resolution.
EXAMPLE:
REGRIDAVHRR_LAI, '2000', MODELNAME='GEOS1', RES=2, OUTDIR='~/scratch/bmy/'
; Regrids 1 x 1 NOx fertilizer data onto the GEOS-1
; 2 x 2.5 resolution grid. The output file will be
; written to the '~/scratch/bmy/' directory.
MODIFICATION HISTORY:
bmy, 04 Aug 2000: VERSION 1.00
- adapted from old FORTRAN code
bmy, 15 Jan 2003: VERSION 1.01
- renamed to "regridh_lai.pro"
- renamed MODELNAME to OUTMODELNAME
- renamed RESOLUTION to OUTRESOLUTION
tmf, 18 Jun 2003: VERSION 2.00
- adapted from bmy's "regridh_lai.pro"
- renamed to "regridavhrr.pro"
- modified to read in Boston University's
0.5x0.5 AVHRR LAI
- modified to output bpch files on CTM grid
at the same time
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridavhrr_lai.pro)
NAME:
REGRIDH_3D_OH
PURPOSE:
Horiziontally regrids 3-D OH data from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_3D_OH [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing OH data to be
regridded. If not specified, then a dialog box
will ask the user to supply a file name.
OUTFILENAME -> Name of file to contain the regridded OH.
If not specified, then REGRID_3D_OH will use default
output file name "OH_3Dglobal.{MODELNAME}.{RESOLUTION}".
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded. If
OUTMODELNAME is not specified, then REGRID_3D_OH will
use the same model name as the input grid.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_REGRIDH (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages
NOTES:
(1) The merged OH file is generated by "merge_oh.pro".
EXAMPLE:
REGRIDH_3D_OH, INFILENAME='OH_3Dglobal.geos3.2x25', $
OUTFILENAME='OH_3Dglobal.geos3.4x5', $
OUTRESOLUTION=4
; Horizontally regrids 3-D OH file from the GEOS-3
; 2 x 2.5 grid to the GEOS-3 4 x 5 grid.
MODIFICATION HISTORY:
bmy, 12 Sep 2002: VERSION 1.01
bmy, 22 Dec 2003: VERSION 1.02
- totally rewritten for GAMAP v2-01
- now call PTR_FREE to free the memory
- added DIAGN keyword
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_3d_oh.pro)
NAME:
REGRIDH_AEROSOL
PURPOSE:
Horiziontally regrids aerosol concentrations from
one CTM grid to another. Total mass is conserved.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_AEROSOL [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
MONTH -> Month of year for which to process data.
Default is 1 (January).
INFILENAME -> Name of the file containing data to be regridded.
If omitted, then REGRIDH_AEROSOL will prompt the user to
select a filename with a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
REGRIDH_AEROSOL will use the same model name as the
input grid.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
OUTFILENAME -> Name of the file which will contain the
regridded data.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "ARSL-L=$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRIDH (function) CTM_NAMEXT (function)
CTM_RESEXT (function) CTM_MAKE_DATAINFO (function)
CTM_GET_DATA CTM_WRITEBPCH
GETMODELANDGRIDINFO UNDEFINE
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
(1) It is best to regrid the aeorsol dust files 1 month
at a time, since it can take quite a while to regrid
all of the tracers and levels. One can then use GAMAP
to concatenate the monthly files.
(2) Aerosol concentrations are used in the photolysis code
since they also cause the incoming solar radiation
to be scattered out of a column.
(3) Assumes that the input file is already in binary punch
format. To regrid data directly from Paul Ginoux's
GOCART model simulations, use "regridh_dust.raw.pro".
EXAMPLE:
REGRIDH_AEROSOL, INFILENAME='aerosol.geos3.2x25', $
OUTFILENAME='aerosol.geos3.4x5', $
OUTRESOLUTION=4, MONTH=1
; Regrids January aerosol data from 2 x 2.5 GEOS-3
; resolution to 4 x 5 resolution.
MODIFICATION HISTORY:
bmy, 15 Jan 2003: VERSION 1.01
bmy, 22 Dec 2003: VERSION 1.02
- rewritten for GAMAP v2-01
- call PTR_FREE to free the pointer heap memory
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_aerosol.pro)
NAME:
REGRIDH_AIRCRAFT_DATA
PURPOSE:
Driver program for routines REGRIDH_AIRCRAFT_NOX
and REGRIDH_AIRCRAFT_FUEL.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_AIRCRAFT_DATA [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
/NOX -> Set this switch to regrid aircraft NOx data.
/SOx -> Set this switch to regrid aircraft SOx data.
OUTMODELNAME -> A string containing the name of the model
grid onto which the NOx emissions will be regridded.
Default is 'GEOS3'.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the NOX emissions will be regridded.
OUTRESOLUTION 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.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================
REGRIDH_AIRCRAFT_NOX (function)
REGRIDH_AIRCRAFT_FUEL (function)
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
Input & output directories are hardwired for now,
you can change them as is necessary.
EXAMPLE:
REGRIDH_AIRCRAFT_DATA, /NOX, $
OUTMODELNAME='GEOS3', $
OUTRESOLUTION=1
; Regrids aircraft NOx data from native
; resolution to GEOS-3 1x1 grid.
MODIFICATION HISTORY:
bmy, 23 Dec 2003: VERSION 1.01
- Initial version
bmy, 28 Apr 2008: GAMAP VERSION 2.12
- Corrected typo at line 142
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_aircraft_data.pro)
NAME:
REGRIDH_AIRCRAFT_FUEL
PURPOSE:
Regrids aircraft emissions to GEOS-CHEM grid resolution.
Can also trim to nested-grid resolution if necessary.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_AIRCRAFT_FUEL [, 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.
OUTMODELNAME -> A string containing the name of the model
grid onto which the NOx emissions will be regridded.
Default is 'GEOS3'.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the NOX emissions will be regridded.
OUTRESOLUTION 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.
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].
/USE_SAVED_WEIGHTS -> Set this flag to tell CTM_REGRIDH to
use previously-saved mapping weights. Useful if you
are regridding many files at once.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_REGRIDH (function) OPEN_FILE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages
NOTES:
EXAMPLE:
REGRIDH_AIRCRAFT_FUEL, INFILENAME='total_1992_apr.kg_day.3d', $
OUTFILENAME='airapr.1x1', $
OUTMODELNAME='GEOS3', $
OUTRESOLUTION=1, $
XRange=[-140,40], $
YRange=[10,60]
; Regrids aircraft fuel emissions to a GEOS-3 1x1
; nested grid resolution given by
MODIFICATION HISTORY:
bmy, 10 Apr 2003: VERSION 1.00
bmy, 29 Nov 2006: VERSION 1.01
- Updated for SO2 output
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_aircraft_fuel.pro)
NAME:
REGRIDH_AIRCRAFT_NOX
PURPOSE:
Regrids aircraft NOx emissions to GEOS-CHEM grid resolution.
Can also trim to nested-grid resolution if necessary.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_AIRCRAFT_NOX [, 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. If omitted, a dialog
box will prompt the user to supply a filename.
OUTMODELNAME -> A string containing the name of the model
grid onto which the NOx emissions will be regridded.
Default is 'GEOS3'.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the NOX emissions will be regridded.
OUTRESOLUTION 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.
/USE_SAVED_WEIGHTS -> Set this flag to tell CTM_REGRIDH to
use previously-saved mapping weights. Useful if you
are regridding many files at once.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_REGRIDH (function) OPEN_FILE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages
NOTES:
EXAMPLE:
REGRIDH_AIRCRAFT_NOX, InFileName='total_1992_apr.kg_day.3d', $
OutFileName='airapr.1x1', $
OUTMODELNAME='GEOS3', $
OUTRESOLUTION=1, $
XRange=[-140,40], $
YRange=[10,60]
; Regrids aircraft NOx emissions to a GEOS-3 1x1
; nested grid resolution given by
MODIFICATION HISTORY:
bmy, 10 Apr 2003: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_aircraft_nox.pro)
NAME:
REGRIDH_ANTHRO
PURPOSE:
Regrids 1 x 1 GEIA anthropogenic emissions "merge file"
onto a CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_ANTHRO [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTFILENAME -> Name of the directory where the output file will
be written. Default is 'merge_nobiofuels.geos.{resolution}'.
/COPY -> If set, will just copy the 1 x 1 data from the ASCII
file to a binary punch file format, w/o regridding.
OUTPUTS:
Writes to binary "merge" file:
merge.{MODELNAME}.{RESOLUTION}.bpch
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRID (function)
CTM_RESEXT (function) CTM_MAKE_DATAINFO (function)
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
(1) The path names for the files containing 1 x 1 data are
hardwired -- change this number as is necessary.
(2) Also assumes 10 fossil fuel emission species --
change this number as is necessary.
(3) Now use CTM_REGRIDH, which is much quicker since it
saves the mapping weights
EXAMPLE:
REGRIDH_ANTHRO, OUTMODELNAME='GEOS_STRAT', $
OUTRESOLUTION=4
; Regrids 1 x 1 GEIA fossil fuel emissions onto the
; 4 x 5 GEOS-STRAT grid. The default output filename
; will be "merge_nobiofuels.geos.4x5".
MODIFICATION HISTORY:
bmy, 01 Aug 2000: VERSION 1.00
bmy, 14 Mar 2001: VERSION 1.01
- now write output to binary punch file format
bmy, 30 Oct 2001: VERSION 1.02
- added /COPY keyword
- now can also copy data from 1 x 1 ASCII
file to binary punch file w/o regridding
bmy, 09 Jan 2003: VERSION 1.03
- renamed to "regridh_anthro.pro"
- now uses CTM_REGRIDH, which is faster
when regridding multiple arrays
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_anthro.pro)
NAME:
REGRIDH_AVHRRCO
PURPOSE:
Regrids AVHRR biomass burning emissions at
1 x 1 resolution to CTM resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_AVHRRCO [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
/COPY -> Use this switch to write the original 1 x 1
biomass burning data to a binary punch file without
regridding.
OUTPUTS:
Writes binary punch files:
bioburn.avhrr.mon.{RESOLUTION}
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_RESEXT (function)
CTM_NAMEXT (function) NYMD2TAU (function)
CTM_REGRIDH (function) CTM_WRITEBPCH
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
(1) The path names for the files containing 1 x 1 data are
hardwired -- change as necessary!
(2) Sometimes you might have to close all files and call
"ctm_cleanup.pro" in between calls to this routine.
(3) Can be extended to other tracers than CO...
EXAMPLE:
REGRIDH_AVHRRCO, OUTMODELNAME='GEOS_STRAT', $
OUTRESOLUTION=4
; Regrids 1 x 1 AVHRR CO biomass burning data
; onto the 4 x 5 GEOS-STRAT grid
MODIFICATION HISTORY:
clh & bmy, 09 Jun 2000: VERSION 1.00
- adapted from "regrid_bioburn.pro"
bmy, 14 Nov 2002: VERSION 1.01
- now use CTM_REGRIDH for horiz regridding
- renamed to "regridh_avhrrco.pro"
bmy, 23 Dec 2003: VERSION 1.02
- updated for GAMAP v2-01
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_avhrrco.pro)
NAME:
REGRIDH_BIOBURN
PURPOSE:
Regrids 1 x 1 biomass burning emissions for various tracers
onto a CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_BIOBURN [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
/COPY -> Use this switch to write the original 1 x 1
biomass burning data to a binary punch file without
regridding.
/SEASONAL -> Use this switch to process seasonal biomass
burning files (instead of interannual variability
files).
YEAR -> 4-digit year number for which to regrid data
for interannual variability biomass burning. YEAR
is ignored if SEASONAL=0. Default is 1996.
OUTPUTS:
Writes binary punch files:
bioburn.seasonal.{MODELNAME}.{RESOLUTION} OR
bioburn.interannual.{MODELNAME}.{RESOLUTION}.YEAR
SUBROUTINES:
Internal Subroutines:
=================================================
RBB_GetWeight RBB_GetTracerInfo (function)
RBB_ReadData
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_WRITEBPCH
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
(1) The path names for the files containing 1 x 1 data are
hardwired -- change as necessary!
(2) Now assumes 13 biomass burning tracers -- change this
number as necessary.
(3) REGRID_BIOBURN now will produce output for a whole
year in one file. This is most convenient.
(4) Sometimes you might have to close all files and call
"ctm_cleanup.pro" in between calls to this routine.
EXAMPLE:
REGRIDH_BIOBURN, OUTMODELNAME='GEOS_STRAT', OUTRESOLUTION=4, $
/SEASONAL, WEIGHTFILE="weights_gen1x1_geos4x5.dat"
; Regrids seasonal 1 x 1 biomass burning data from February
; for CO (tracer #2) onto the 4 x 5 GEOS-STRAT grid, using
; mapping weights stored in "weights_gen1x1_geos4x5.dat".
MODIFICATION HISTORY:
bmy, 09 Jun 2000: VERSION 1.00
bmy, 14 Jul 2000: VERSION 1.01
- adapted for 9 biomass burning tracers
bmy, 24 Jul 2000: - added OUTDIR keyword
bmy, 13 Feb 2001: VERSION 1.02
- added ALK4, CH4, CH3I as biomass
burning tracers
bmy, 15 Feb 2001: VERSION 1.03
- now use pre-saved mapping weights,
for computational expediency
- now no longer use
- added /SEASONAL keyword to regrid
seasonal climatological biomass burning
instead of interannual variability BB.
bmy, 28 Jun 2001: VERSION 1.04
- added COPY keyword, to just write a 1x1
binary punch file w/o regridding
bmy, 02 Jul 2001: VERSION 1.05
- YEAR is now 4 digits
- now uses 1985 TAU values for seasonal
BB emissions and TAU values corresponding
to YEAR for interannual BB emissions
bmy, 21 Sep 2001: VERSION 1.06
- modified to handle Randall's year 2000
files for interannual variability
- renamed MODELNAME to OUTMODELNAME and
RESOLUTION to OUTRESOLUTION
bmy, 24 Sep 2001: VERSION 1.07
- now created TINFO array of structures
w/ information about each biomass tracer
- also save TOTB (CTM tracer #33) as g/cm2
bmy, 11 Feb 2002: VERSION 1.08
- now regrid all months of 2000
bmy, 14 Nov 2002: VERSION 1.09
- renamed to REGRIDH_BIOBURN
- removed WEIGHTFILE keyword
bmy, 23 Dec 2003: VERSION 1.10
- updated for GAMAP v2-01
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_bioburn.pro)
NAME:
REGRIDH_BIOBURN2
PURPOSE:
Regrids 1 x 1 biomass burning emissions for various tracers
onto a CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_BIOBURN [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTFILENAME ->
DIAGN ->
OUTPUTS:
Writes binary punch files:
bioburn.seasonal.{MODELNAME}.{RESOLUTION} OR
bioburn.interannual.{MODELNAME}.{RESOLUTION}.YEAR
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRID (function) CTM_NAMEXT (function)
CTM_RESEXT (function) CTM_WRITEBPCH
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
none
EXAMPLE:
REGRIDH_BIOBURN, INFILENAME='biomass.seasonal.generic.1x1', $
OUTMODELNAME='GEOS4'
OUTRESOLUTION=2 $
OUTFILENAME='biomass.seasonal.geos.2x25'GEOS_STRAT',
; Regrids seasonal 1 x 1 biomass burning data
; onto the GEOS_4 2 x 2.5 grid.
MODIFICATION HISTORY:
bmy, 08 Apr 2004: VERSION 1.00
bmy, 20 Oct 2005: VERSION 1.01
- If units are per m3, m2, cm3, or cm2 then
set PER_UNIT_AREA flag in routine CTM_REGRIDH;
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_bioburn2.pro)
NAME:
REGRIDH_BIOFUEL
PURPOSE:
Regrids 1 x 1 biofuel burning emissions for NOx or CO
onto a CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_BIOFUEL [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
/COPY -> If set, then will just copy 1 x 1 "raw" biofuel
data from native ASCII format to binary punch format.
OUTPUTS:
Writes binary punch files:
biofuel.generic.1x1 (if /COPY is set) OR
biofuel.geos.{RESOLUTION} (if OUTRESOLUTION=2 or =4)
SUBROUTINES:
External Subroutines Required:
===============================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRIDH (function) CTM_NAMEXT (function)
CTM_RESEXT (function) CTM_WRITEBPCH
Internal Subroutines
===============================================
RBF_READDATA (function)
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
The path names for the files containing 1 x 1 data are
hardwired -- change as necessary!
EXAMPLE:
(1)
REGRIDH_BIOFUEL, MODELNAME='GEOS_STRAT', RESOLUTION=[5,4]
; Regrids 1 x 1 biofuel data to the 4 x 5 GEOS-STRAT grid
MODIFICATION HISTORY:
bmy, 09 Jun 2000: VERSION 1.00
bmy, 12 Jul 2000: VERSION 1.01
- added NOx keyword
- now read original data with
internal function RBF_READDATA
bmy, 24 Jul 2000: - added OUTDIR keyword
bmy, 26 Jan 2001: VERSION 1.02
- added extra species names
bmy, 29 Oct 2001: VERSION 1.03
- added /COPY keyword to just copy data
from ASCII format to binary punch format
- now loop over multiple tracer names
- removed TRCNAME keyword
bmy, 28 Jan 2002: VERSION 1.04
- bug fix: now convert C2H6, C3H8 and
ACET from kg/yr to kg C/yr
bmy, 14 Nov 2002: VERSION 1.05
- renamed to REGRIDH_BIOFUEL
bmy, 23 Dec 2003: VERSION 1.06
- updated for GAMAP v2-01
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_biofuel.pro)
NAME:
REGRIDH_C3H8_C2H6
PURPOSE:
Horizontally regrids emissions of C3H8 and C2H6
from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_C3H8_C2H6 [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing C3H8 and C2H6 to
be regridded. If omitted, then REGRIDH_C3H8_C2H6 will
prompt the user to select a filename via a dialog box.
OUTFILENAME -> Name of output file containing the regridded
data. If OUTFILENAME is not specified, then REGRIDH_C3H8_C2H6
will ask the user to specify a file via a dialog box.
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded. If
OUTMODELNAME is not specified, REGRIDH_C3H8_C2H6 will
use the same model name as the input grid.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "IJ-AVG-$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRIDH (function) CTM_RESEXT (function)
CTM_MAKE_DATAINFO (function) CTM_WRITEBPCH
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
None
EXAMPLE:
REGRIDH_C3H8_C2H6, INFILENAME='C3H8_C2H6_ngas.geos.4x5', $
OUTFILENAME='C3H8_C2H6_ngas.geos.2x25', $
OUTRESOLUTION=2, $
; Regrids C3H8 and C2H6 data onto from the 4 x 5
; GEOS-3 grid to the the 2 x 2.5 GEOS-3 grid.
MODIFICATION HISTORY:
bmy, 08 Jan 2003: VERSION 1.00
bmy, 22 Dec 2003: VERSION 1.01
- rewritten for GAMAP v2-01
- now call PTR_FREE to free pointer memory
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_c3h8_c2h6.pro)
NAME:
REGRIDH_CM2_S
PURPOSE:
Horizontally Regrids a CTM quantity (such as emissions) in
units of [molec/cm2/s] or [atoms C/cm2/s] to a new CTM grid.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_CM2_S [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If OUTFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded. If not
passed, then the model name corresponding to the data
contained in INPUTFILE will be used as the default.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "IJ-AVG-$".
OUTPUTS:
Writes binary punch files:
bioburn.seasonal.{MODELNAME}.{RESOLUTION} OR
bioburn.interannual.{MODELNAME}.{RESOLUTION}.YEAR
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRID (function) CTM_NAMEXT (function)
CTM_RESEXT (function) CTM_WRITEBPCH
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
none
EXAMPLE:
REGRIDH_BIOBURN, INFILENAME='biomass.seasonal.generic.1x1', $
OUTMODELNAME='GEOS4'
OUTRESOLUTION=2 $
OUTFILENAME='biomass.seasonal.geos.2x25'GEOS_STRAT',
; Regrids seasonal 1 x 1 biomass burning data
; onto the GEOS_4 2 x 2.5 grid.
MODIFICATION HISTORY:
bmy, 08 Apr 2004: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_cm2_s.pro)
NAME:
REGRIDH_CROPLANDS
PURPOSE:
Regrids crop land fraction data from 0.5 x 0.5 degree
resolution to a coarser CTM grid.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_CROPLANDS [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of a netCDF file containing input
data to be be regridded. Default is
'~rmy/Croplands/crop92_v1.1_0.5.nc'.
OUTFILENAME -> Name of the binary punch file to contain
output data. Default is "croplands.bpch"
OUTMODELNAME -> A string containing the name of the model
grid on which the input data resides. Default is GENERIC.
OUTRESOLUTION -> 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 1.
OUTPUTS:
None -- writes output to file
SUBROUTINES:
Internal Subroutines
===================================================
RC_ReadData (function)
External Subroutines Required:
===================================================
NCDF_READ CTM_MAKE_DATAINFO (function)
CTM_TYPE (function) CTM_GRID (function)
CTM_WRITEBPCH UNDEFINE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
Some hardwiring for now...this is OK.
EXAMPLE:
REGRID_CROPLANDS, INFILENAME='croplands.nc', $
OUTMODELNAME='generic', $
OUTRESOLUTION=1, $
OUTFILENAME='newcroplands.bpch'
; Regrids 0.5 x 0.5 croplands data from "croplands.nc"
; file to 1 x 1 resolution. Output is to the binary
; punch file "newcroplands.bpch".
MODIFICATION HISTORY:
bmy, 19 Jul 2001: VERSION 1.00
bmy, 09 Jan 2003: VERSION 1.02
- Now use CTM_REGRIDH to regrid data
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_croplands.pro)
NAME:
REGRIDH_DUST
PURPOSE:
Horizontally regrids mineral dust concentrations [kg/m3]
from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_DUST [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
MONTH -> Month of year for which to process data. Default is
1 (January). Since the dust files are very large, it may
take several iterations to regrid an entire year of
data. You can break the job down 1 month at a time.
INFILENAME -> Name of the file containing the dust data
which is to be regridded. If INFILENAME is not specified,
then REGRIDH_DUST will prompt the user to specify a file
name via a dialog box.
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded. If not
specified, then OUTMODELNAME will be set to the same
value as the grid stored in INFILENAME.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
OUTFILENAME -> Name of the directory where the output file will
be written. If not specified, then a dialog box
will ask the user to supply a file name.
DIAGN -> Diagnostic category of data block that you want
to regrid. Default is "MDUST-$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
======================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRID (function) CTM_NAMEXT (function)
CTM_RESEXT (function) CTM_MAKE_DATAINFO (function)
CTM_WRITEBPCH GETMODELANDGRIDINFO
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDH_DUST, INFILENAME='dust.geos3.2x25', $
OUTRESOLUTION=4, $
OUTFILENAME='dust.geos3.4x5'
; Regrids dust data from 2 x 2.5 native resolution
; to 4 x 5 resolution for the GEOS-3 grid
MODIFICATION HISTORY:
bmy, 09 Jun 2000: VERSION 1.00
rvm, 18 Jun 2000: VERSION 1.01
bmy, 07 Jul 2000: VERSION 1.10
- added OUTDIR keyword
- save regridded data one month at a time
since regridding takes so long
bmy, 19 Dec 2003: VERSION 1.11
- Rewritten for GAMAP v2-01
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_dust.pro)
NAME:
REGRIDH_FERT
PURPOSE:
Regrids fertilizer NOx from a 1 x 1 grid onto a
CTM grid of equal or coarser horizontal resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_FERT [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTFILENAME -> Name of the binary punch file that will hold
regridded data. If not specified, the default OUTFILENAME
will be nox_fert.geos.{OUTRESOLUTION}
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_REGRIDH (function) CTM_WRITEBPCH
REQUIREMENTS:
None
NOTES:
(1) Filenames are hardwired -- change as necessary
(2) Regridding can take a while, especially at 1x1 resolution.
EXAMPLE:
REGRIDH_FERT, OUTMODELNAME='GEOS1', $
OUTRESOLUTION=2, $
OUTFILENAME='nox_fert.geos.2x25'
; Regrids 1 x 1 NOx fertilizer data onto the GEOS-1
; 2 x 2.5 resolution grid.
MODIFICATION HISTORY:
bmy, 01 Aug 2000: VERSION 1.00
bmy, 13 Jan 2003: VERSION 1.01
- renamed to "regridh_fert.pro"
- now uses CTM_REGRIDH
- removed OUTDIR, added OUTFILENAME
- updated comments
bmy, 23 Dec 2003: VERSION 1.02
- updated for GAMAP v2-01
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_fert.pro)
NAME:
REGRIDH_JO1D
PURPOSE:
Regrids JO1D data (used for acetone emissions)
from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_JO1D, [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the input file containing JO1D data
to be regridded. If INFILENAME is not specified, then
REGRIDH_JO1D will prompt the user to select a file via
a dialog box.
OUTFILENAME -> Name of the binary punch file which
will contain regridded data. Default is
"JO1D.{MODELNAME}.{RESOLUTION}"
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
then REGRIDH_RESTART will use the same model name as the
input grid.
OUTRESOLUTION -> Specifies the resolution of the output
model grid onto which the data will be regridded.
OUTRESOLUTION 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 for all models is 4x5.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
========================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_MAKE_DATAINFO (function) INTERPOLATE_2D (function)
CTM_GET_DATA GETMODELANDGRIDINFO
UNDEFINE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
None
EXAMPLE:
REGRIDH_JOID, INFILENAME='JO1D.geos.4x5', $
OUTFILENAME='JO1D.geos.2x25', $
OUTRESOLUTION=2
; Regrids JO1D data from 4 x 5 to 2 x 2.5 resolution.
MODIFICATION HISTORY:
bmy, 11 Aug 2000: VERSION 1.01
bmy, 23 Dec 2003: VERSION 1.02
- updated for GAMAP v2-01
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_jo1d.pro)
NAME:
REGRIDH_JV
PURPOSE:
Horizontally interpolates J-values from one CTM grid to another.
Can also be used to interpolate other data quantities.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_JV, [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDH_JV
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If OUTFILENAME is not specified, then REGRIDH_JV
will prompt the user to select a file via a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
then REGRIDH_JV will use the same model name as the
input grid.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "IJ-AVG-$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==========================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_MAKE_DATAINFO (function) INTERPOLATE_2D (function)
GETMODELANDGRIDINFO UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDV_JV, INFILENAME='JH2O2.geos4.4x5', $
OUTRESOLUTION='2'
OUTFILENAME='JH2O2.geos4.2x25'
; Regrids GEOS-4 stratospheric J-value data
; at 4 x 5 resolution to 2 x 2.5 resolution.
MODIFICATION HISTORY:
bmy, 11 Aug 2000: VERSION 1.01
bmy, 22 Dec 2003: VERSION 1.02
- updated for GAMAP v2-01
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_jv.pro)
NAME:
REGRIDH_KG
PURPOSE:
Regrids 1 x 1 data (e.g. emissions) in units of [kg], [kg/yr]
or similar mass units from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_KG [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> A string containing the name of the binary
punch (bpch) file with the data to be regridded.
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTFILENAME -> Name of the directory where the output file will
be written. Default is 'merge_nobiofuels.geos.{resolution}'.
DIAGN -> GAMAP diagnostic category name of the data blocks
to be regridded.
USE_SAVED_WEIGHTS -> Set this switch to manually force
REGRIDH_KG to re-use the mapping weights for regridding.
The default is to reset the mapping weights for each
new file that is read in.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRID (function)
CTM_RESEXT (function) CTM_MAKE_DATAINFO (function)
REQUIREMENTS:
None
NOTES:
Can also be used to regrid other quantities that are
are not per unit area (e.g. kg/s, kg/yr, Tg, etc.)
EXAMPLE:
REGRIDH_KG, INFILENAME="biofuel.generic.1x1",$
OUTFILENAME="biofuel.geos.1x1", $
OUTMODELNAME='GEOS3', $
OUTRESOLUTION=1
; Regrids 1 x 1 biofuel fuel emissions on the
; GENERIC 1x1 GRID to the GEOS 1x1 GRID.
MODIFICATION HISTORY:
bmy, 28 Jun 2006: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_kg.pro)
NAME:
REGRIDH_LAI
PURPOSE:
Regrids Leaf Area Indices and Olson Land Types from a
0.5 x 0.5 grid onto a CTM grid of equal or coarser
horizontal resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_LAI [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
OUTPUTS:
Writes files:
vegtype.global
lai{MONTHNUM}.global
SUBROUTINES:
External Subroutines Required:
===============================================
CTM_TYPE (function) CTM_GRID (function)
CTM_RESEXT (function) CTM_GETWEIGHT
Internal Subroutines:
==============================
RL_GETWEIGHT
REQUIREMENTS:
None
NOTES:
(1) Filenames are hardwired -- change as necessary
(2) Regridding can take a while, especially at 1x1 resolution.
EXAMPLE:
REGRIDH_LAI, MODELNAME='GEOS1', RES=2, OUTDIR='~/scratch/bmy/'
; Regrids 1 x 1 NOx fertilizer data onto the GEOS-1
; 2 x 2.5 resolution grid. The output file will be
; written to the '~/scratch/bmy/' directory.
MODIFICATION HISTORY:
bmy, 04 Aug 2000: VERSION 1.00
- adapted from old FORTRAN code
bmy, 15 Jan 2003: VERSION 1.01
- renamed to "regridh_lai.pro"
- renamed MODELNAME to OUTMODELNAME
- renamed RESOLUTION to OUTRESOLUTION
bmy, 18 Jun 2004: VERSION 1.02
- Bug fix: TMPAREA array needs to be
defined with N_TYPE, not N_MON
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_avhrr_lai.pro)
NAME:
REGRIDH_LAI
PURPOSE:
Regrids Leaf Area Indices and Olson Land Types from a
0.5 x 0.5 grid onto a CTM grid of equal or coarser
horizontal resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_LAI [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
OUTPUTS:
Writes files:
vegtype.global
lai{MONTHNUM}.global
SUBROUTINES:
External Subroutines Required:
===============================================
CTM_TYPE (function) CTM_GRID (function)
CTM_RESEXT (function) CTM_GETWEIGHT
Internal Subroutines:
==============================
RL_GETWEIGHT
REQUIREMENTS:
None
NOTES:
(1) Filenames are hardwired -- change as necessary
(2) Regridding can take a while, especially at 1x1 resolution.
EXAMPLE:
REGRIDH_LAI, MODELNAME='GEOS1', RES=2, OUTDIR='~/scratch/bmy/'
; Regrids 1 x 1 NOx fertilizer data onto the GEOS-1
; 2 x 2.5 resolution grid. The output file will be
; written to the '~/scratch/bmy/' directory.
MODIFICATION HISTORY:
bmy, 04 Aug 2000: VERSION 1.00
- adapted from old FORTRAN code
bmy, 15 Jan 2003: VERSION 1.01
- renamed to "regridh_lai.pro"
- renamed MODELNAME to OUTMODELNAME
- renamed RESOLUTION to OUTRESOLUTION
bmy, 18 Jun 2004: VERSION 1.02
- Bug fix: TMPAREA array needs to be
defined with N_TYPE, not N_MON
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_lai.pro)
NAME:
REGRIDH_MOLEC_CM2
PURPOSE:
Regrids 1 x 1 data (e.g. emissions) in units of [molec/cm2/s]
onto a CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_MOLEC_CM2 [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> A string containing the name of the binary
punch (bpch) file with the data to be regridded.
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTFILENAME -> Name of the directory where the output file will
be written. Default is 'merge_nobiofuels.geos.{resolution}'.
DIAGN -> GAMAP diagnostic category name of the data blocks
to be regridded.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRID (function)
CTM_RESEXT (function) CTM_MAKE_DATAINFO (function)
REQUIREMENTS:
None
NOTES:
Can also be used to regrid other quantities that are
per unit area (e.g. kg/m2/s, molec/cm3/s, etc).
EXAMPLE:
REGRIDH_MOLEC_CM2, INFILENAME="merge_nobiofuels.generic.1x1",$
OUTFILENAME="merge_nobiofuels.geos.1x1", $
OUTMODELNAME='GEOS3', $
OUTRESOLUTION=1
; Regrids 1 x 1 fossil fuel emissions on the
; GENERIC 1x1 grid to the GEOS 1x1 grid.
MODIFICATION HISTORY:
bmy, 28 Jun 2006: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_molec_cm2.pro)
NAME:
REGRIDH_NEP
PURPOSE:
Horizontally regrids NEP data from its resolution to a CTM grid.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_NEP [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
Default is: '~bmy/S/CO2/nep_gpp.nc'.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is 'GEOS3'.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "IJ-AVG-$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_RESEXT (function) CTM_REGRIDH (function)
CTM_MAKE_DATAINFO (function) CTM_WRITEBPCH
UNDEFINE
REQUIREMENTS:
None
NOTES:
Output filenames are hardwired.
EXAMPLE:
REGRIDH_NEP, INFILENAME='nep_gpp.nc', $
OUTMODELNAME='GEOS3', $
OUTRESOLUTION=4
; Regrids NEP data to the GEOS-3 4x5 grid.
MODIFICATION HISTORY:
bmy, 15 Apr 2003: VERSION 1.00
bmy, 23 Dec 2003: VERSION 1.01
- updated for GAMAP v2-01
- added DIAGN keyword
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_nep.pro)
NAME:
REGRIDH_NH3
PURPOSE:
Horizontally regrids NH3 emissions (anthro, biofuel, or
natural source) from one CTM grid to another. Can also
be used to regrid other data which have units of kg.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_NH3 [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If OUTFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
then REGRIDH_NH3 will use the same model name as the
input grid.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRIDH (function) GETMODELANDGRIDINFO
CTM_RESEXT (function) CTM_GET_DATA
CTM_WRITEBPCH UNDEFINE
REQUIREMENTS:
None
NOTES:
Assumes that input data is either [kg NH3/box] or [kg N/box].
EXAMPLE:
(1)
REGRIDH_NH3, INFILENAME='NH3_anthsrce.geos.2x25', $
OUTFILENAME='NH3_anthsrce.geos.1x1', $
OUTRESOLUTION=1
; Regrids 2 x 2.5 NH3 anthropogenic emissions
; to the 1 x 1 GEOS grid.
MODIFICATION HISTORY:
bmy, 28 Mar 2003: VERSION 1.01
bmy, 22 Dec 2003: VERSION 1.02
- rewritten for GAMAP v2-01
- now call PTR_FREE to free pointer memory
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_nh3.pro)
NAME:
REGRIDH_NPP
PURPOSE:
Horizontally regrids NPP data from native
resolution to a CTM grid.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_NPP [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
Default is: '~bmy/S/CO2/nep_gpp.nc'.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is 'GEOS3'.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "IJ-AVG-$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_RESEXT (function) CTM_REGRIDH (function)
CTM_MAKE_DATAINFO (function) CTM_WRITEBPCH
UNDEFINE
REQUIREMENTS:
None
NOTES:
Output filenames are hardwired.
EXAMPLE:
REGRIDH_NEP, INFILENAME='nep_gpp.nc', $
OUTMODELNAME='GEOS3', $
OUTRESOLUTION=4
; Regrids NEP data to the GEOS-3 4x5 grid.
MODIFICATION HISTORY:
bmy, 15 Apr 2003: VERSION 1.00
bmy, 23 Dec 2003: VERSION 1.01
- updated for GAMAP v2-01
- added DIAGN keyword
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_npp.pro)
NAME:
REGRIDH_O3PL
PURPOSE:
Horizontally regrids files containing GEOS-CHEM P(O3) and L(O3).
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_O3PL [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDV_O3PL
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If OUTFILENAME is not specified, then REGRIDV_PORL
will prompt the user to select a file via a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If omitted then OUTMODELNAME will
be determined automatically from INFILENAME.
OUTRESOLUTION -> Resolution of the model grid onto which
the data will be regridded. Default is 4.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "PORL-L=$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===========================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_GET_DATABLOCK (function) CTM_MAKE_DATAINFO (function)
TAU2YYMMDD (function) ZSTAR (function)
REPLACE_TOKEN (function) GETMODELANDGRIDINFO
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDH_O3PL, INFILENAME='~/2x25/rate.20010101', $
OUTFILENAME='~/4x5/rate.20010101', $
OUTRESOLUTION=4
; Regrids P(O3) and L(O3) data from 2x2.5 to 4x5
MODIFICATION HISTORY:
bmy, 27 Mar 2001: VERSION 1.00
bmy, 23 Dec 2003: VERSION 1.01
- renamed to "regridv_o3pl.pro"
- rewritten for GAMAP v2-01
- now looks for sfc pressure in ~/IDL/regrid/PSURF
bmy, 24 Feb 2004: VERSION 1.02
- now convert P(Ox) to kg/s and L(Ox) 1/s for
regridding -- then convert back after regridding
- now use REGRID_COLUMN to regrid P(Ox) in kg/s
- now use INTERPOL to regrid L(Ox) in 1/s
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_o3pl.pro)
NAME:
REGRIDH_OCEAN_ACET
PURPOSE:
Regrids ocean production & loss for tagged CO.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_OCEAN_ACET [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDH_OCEAN_ACET
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. Default is "acetone.geos.{RESOLUTION}".
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
then REGRIDH_OCEAN_ACET will use the same model name as the
input grid.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "EMISACET".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=====================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRIDH (function) CTM_MAKE_DATAINFO (function)
CTM_RESEXT (function) CTM_WRITEBPCH
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDH_OCEAN_ACET, INFILENAME='acetone.geos.2x25', $
OUTFILENAME='acetone.geos.1x1'
OUTRESOLUTION=1, $
; Regrids 2 x 2.5 ocean acetone data to the 1x1 grid.
MODIFICATION HISTORY:
bmy, 15 Jun 2003: VERSION 1.00
bmy, 23 Dec 2003: VERSION 1.01
- rewritten for GAMAP v2-01
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_ocean_acet.pro)
NAME:
REGRIDH_POPS
PURPOSE:
Regrids 1 x 1 POPS (persistent organic pollutants) emissions
onto a CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_POPS [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name (or array of names) of the ASCII file(s)
which contain(s) emissions for a POP species. If
omitted, then the user will be prompted to select a
file via a dialog box.
OUTFILENAME -> Name of the bpch file which will contain
regridded data. If omitted, then the user will be
prompted to select a file via a dialog box.
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRIDH (function) CTM_MAKE_DATAINFO (function)
CTM_WRITEBPCH READDATA
REQUIREMENTS:
None
NOTES:
Assumes GAMAP diagnostic category name of "POP-ANTH".
EXAMPLE:
REGRIDH_POPS, INFILENAME='EmisPCB28Mean',$
OUTMODELNAME='GEOS3', $
OUTRESOLUTION=2, $
OUTFILENAME='PCB28.bpch'
; Regrids 1x1 POPS emissions [kg/yr] to 4x5 GEOS grid
MODIFICATION HISTORY:
bmy, 23 May 2005: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_pops.pro)
NAME:
REGRIDH_PORL
PURPOSE:
Horizontally regrids production/loss or other data
in [molec/cm3/s] from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_PORL [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If omitted, then REGRIDH_PORL will prompt the user to
select a filename with a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If OUTFILENAME is not specified, then REGRIDH_PORL
will prompt the user to select a file via a dialog box.
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded. If not
specified, then OUTMODELNAME will be set to the same
value as the grid stored in INFILENAME.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
DIAGN -> Diagnostic category of data block that you want
to regrid. Default is "PORL-L=$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_REGRIDH (function) CTM_GET_DATA
CTM_WRITEBPCH GETMODELANDGRIDINFO
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDH_PORL, INFILENAME='data.geos3.4x5', $
OUTFILENAME="data.geoss.4x5'
OUTRESOLUTION=2, $
; Regrids data in molec/cm3 from GEOS-3 vertical
; resolution from 4x5 to 2 x 2.5 GEOs-3 resolution.
MODIFICATION HISTORY:
bmy, 01 Nov 2002: VERSION 1.01
bmy, 19 Sep 2003: VERSION 1.02
- now call PTR_FREE to free pointer memory
bmy, 19 Dec 2003: VERSION 1.03
- rewritten for GAMAP v2-01
- added DIAGN keyword
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_porl.pro)
NAME:
REGRIDH_RESP
PURPOSE:
Horizontally regrids heterogeneous respiration data (used for
acetone emissions) from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_RESP, [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDH_RESP
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. Default is "resp.geos.{RESOLUTION}".
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
then REGRIDH_RESP will use the same model name as the
input grid.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "HET-RESP".
OUTPUTS:
SUBROUTINES:
External Subroutines Required:
======================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_RESEXT (function) CTM_REGRIDH (function)
CTM_MAKE_DATAINFO (function) CTM_GET_DATA
CTM_WRITEBPCH UNDEFINE
REQUIREMENTS:
None
NOTES:
Assumes het-resp data has units [g C/m2/month].
EXAMPLE:
REGRIDH_RESP, INFILENAME='resp.geos.2x25', $
OUTFILENAME='resp.geos.4x5', $
OUTRESOLUTION=2
; Regrids heterogeneous respiration data from the
; 2 x 2.5 GEOS grid (surface only) to the 4 x 5 grid.
MODIFICATION HISTORY:
bmy, 11 Aug 2000: VERSION 1.01
bmy, 22 Dec 2003: VERSION 1.02
- rewritten for GAMAP v2-01
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_resp.pro)
NAME:
REGRIDH_RESTART
PURPOSE:
Horizontally regrids data in [v/v] mixing ratio from one
model grid to another. Data is converted to [kg] for
regridding, and then converted back to [v/v].
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_RESTART [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If OUTFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
then REGRIDH_RESTART will use the same model name as the
input grid.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "IJ-AVG-$".
/GCAP -> Set this switch to regrid a 4x5 GEOS-3 or GEOS-4
restart file to a "fake" GEOS grid containing 45 latitudes
but the same # of levels. You can then regrid the file
vertically using regridv_restart.pro.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRIDH (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_WRITEBPCH GETMODELANDGRIDINFO
INTERPOLATE_2D (function) UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDH_RESTART, INFILENAME='geos3.2x25.bpch', $
OUTFILENAME='geos3.4x5.bpch', $
OUTRESOLUTION=4
; Regrids GEOS-3 data from 2 x 2.5 to 4 x 5 resolution.
MODIFICATION HISTORY:
bmy, 22 Jan 2003: VERSION 1.01
bmy, 15 Apr 2003: VERSION 1.02
- now reads bpch file w/o using CTM_GET_DATA;
this keeps us from running out of memory
bmy, 22 Dec 2003: VERSION 1.03
- rewritten for GAMAP v2-01
- rewritten so that we can now regrid files
containing less than GRIDINFO.LMX levels
- reorganized a few things for clarity
bmy, 13 Apr 2004: VERSION 1.04
- now use surface pressure files on both
the input and output grids
- now use separate arrays for airmass
on the two grids
- now adjusts polar latitudes so as to avoid
artificial buildup of concentration when
regridding from coarse --> fine grids
bmy, 31 Jan 2005: VERSION 1.05
- Minor bug fix: INAREA and OUTAREA should
have units of [m2] for the airmass computation
- Now use /QUIET and /NOPRINT keywords in
call to CTM_GET_DATABLOCK
bmy, 26 May 2005: VERSION 1.06
- added /GCAP keyword for special handling
when creating restart files on 4x5 GCAP grid
- now references INTERPOLATE_2D function
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- fixed typo for fine -> coarse regridding
- Now use FILE_WHICH to locate surf prs files
bmy, 22 Nov 2010: GAMAP VERSION 2.15
- Remove pointer stuff to avoid errors.
Now just use the assignment
InData = *( DataInfo[D].Data )
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_restart.pro)
NAME:
REGRIDH_RESTART_NC
PURPOSE:
Horizontally regrids data in [v/v] mixing ratio from one
model grid to another. Data is converted to [kg] for
regridding, and then converted back to [v/v].
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_RESTART [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If OUTFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
then REGRIDH_RESTART will use the same model name as the
input grid.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "IJ-AVG-$".
/GCAP -> Set this switch to regrid a 4x5 GEOS-3 or GEOS-4
restart file to a "fake" GEOS grid containing 45 latitudes
but the same # of levels. You can then regrid the file
vertically using regridv_restart.pro.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRIDH (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_WRITEBPCH GETMODELANDGRIDINFO
INTERPOLATE_2D (function) UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDH_RESTART_NC, INFILENAME='geos3.2x25.nc', $
OUTFILENAME='geos3.4x5.nc', $
OUTRESOLUTION=4
; Regrids GEOS-3 data from 2 x 2.5 to 4 x 5 resolution.
MODIFICATION HISTORY:
jaf, 01 May 2016: Initial version based on regridh_restart.pro and
bpch2coards.pro
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_restart_nc.pro)
NAME:
REGRIDH_SCALEFOSS
PURPOSE:
Regrids 0.5 x 0.5 fossil fuel scale factors onto a
CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRID_SCALEFOSS [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
MODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
RESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.;
YEAR -> 4-digit year number (e.g. 1994) correspoinding
to the data to be regridded. Default is 1994.
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
OUTPUTS:
Writes output to binary files (*NOT* binary punch files):
scalefoss.liq.{RESOLUTION}.{YEAR}
scalefoss.tot.{RESOLUTION}.{YEAR}
SUBROUTINES:
External Subroutines Required:
================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRID (function) CTM_NAMEXT (function)
CTM_RESEXT (function)
Internal Subroutines:
================================================
RS_READ_DATA (function) RS_WRITE_DATA
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRID_SCALEFOSS, YEAR=1994, $
MODELNAME='GEOS_STRAT', $
RESOLUTION=[5,4]
; Regrids fossil fuel scale factor files for 1994 from
; 0.5 x 0.5 resolution onto the 4 x 5 GEOS-STRAT grid
MODIFICATION HISTORY:
bmy, 09 Jun 2000: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
phs, 08 Feb 2008: GAMAP VERSION 2.12
- added swap_endian keyword to OPEN_FILE
in RS_Read_Data and RS_WRITE_DATA
- fixed keywords checking
- replace ctm_regrid w/ ctm_regridh
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_scalefoss.pro)
NAME:
REGRIDH_SCALEFOSS_SOX
PURPOSE:
Regrids 0.5 x 0.5 fossil fuel scale factors onto a
CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRID_SCALEFOSS [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
MODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
RESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.;
YEAR -> 4-digit year number (e.g. 1994) correspoinding
to the data to be regridded. Default is 1994.
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
OUTPUTS:
Writes output to binary files (*NOT* binary punch files):
scalefoss.liq.{RESOLUTION}.{YEAR}
scalefoss.tot.{RESOLUTION}.{YEAR}
SUBROUTINES:
External Subroutines Required:
================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRID (function) CTM_NAMEXT (function)
CTM_RESEXT (function)
Internal Subroutines:
================================================
RS_READ_DATA (function) RS_WRITE_DATA
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRID_SCALEFOSS, YEAR=1994, $
MODELNAME='GEOS_STRAT', $
RESOLUTION=[5,4]
; Regrids fossil fuel scale factor files for 1994 from
; 0.5 x 0.5 resolution onto the 4 x 5 GEOS-STRAT grid
MODIFICATION HISTORY:
bmy, 09 Jun 2000: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_scalefoss_sox.pro)
NAME:
REGRIDH_SHIPSO2
PURPOSE:
Horizontally regrids emissions SOx from ship emissions
in [molec/cm2/s] from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_SHIPSO2 [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing C3H8 and C2H6 to
be regridded. If omitted, then REGRIDH_SHIPSO2 will
prompt the user to select a filename via a dialog box.
OUTFILENAME -> Name of output file containing the regridded
data. If OUTFILENAME is not specified, then REGRIDH_SHIPSO2
will ask the user to specify a file via a dialog box.
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded. If
OUTMODELNAME is not specified, REGRIDH_SHIPSO2 will
use the same model name as the input grid.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "IJ-AVG-$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRIDH (function) CTM_RESEXT (function)
CTM_MAKE_DATAINFO (function) CTM_WRITEBPCH
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDH_SHIPSO2, INFILENAME='shipSOx.geos.2x25', $
OUTFILENAME='shipSOx.geos.4x5', $
OUTRESOLUTION=4
; Regrids C3H8 and C2H6 data onto from the 4 x 5
; GEOS-3 grid to the the 2 x 2.5 GEOS-3 grid.
MODIFICATION HISTORY:
bmy, 08 Jan 2003: VERSION 1.00
bmy, 22 Dec 2003: VERSION 1.01
- rewritten for GAMAP v2-01
- now call PTR_FREE to free pointer memory
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_shipso2.pro)
NAME:
REGRIDH_SOILPREC
PURPOSE:
Regrids soil precipitation from 0.5 x 0.5 resolution
onto a CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_SOILPREC [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
Default: "~bmy/archive/data/soil_NOx_200203/05x05_gen/lcprc.asc"
OUTFILENAME -> Name of the file which will contain the regridded
data. Default is "soil_precip.geos.{RESOLUTION}".
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is "GEOS3".
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "SOILPREC".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_REGRIDH (function) CTM_BOXSIZE
CTM_WRITEBPCH UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDH_SOILPREC, OUTMODELNAME='GEOS3', $
OUTRESOLUTION=2, $
OUTFILENAME='soil_precip.geos.2x25'
; Regrids 0.5 x 0.5 soil precipitation data onto
; the GEOS-1 2 x 2.5 grid. Output will be sent
; to the "~bmy/regrid" directory.
MODIFICATION HISTORY:
bmy, 01 Aug 2000: VERSION 1.00
bmy, 08 Jan 2003: VERSION 1.01
- renamed to "regridh_soilprec.pro"
- removed OUTDIR, added OUTFILENAME
- updated comments
bmy, 23 Dec 2003: VERSION 1.02
- updated for GAMAP v2-01
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
bmy, 24 Apr 2008: GAMAP VERSION 2.12
- bug fix: N_ELEMENTS was misspelled
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_soilprec.pro)
NAME:
REGRIDH_SST
PURPOSE:
Horizontally regrids SST data from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_SST, [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If omitted, then REGRIDH_SST will prompt the user to
select a filename with a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If omitted, then REGRIDH_SST will prompt the
user to select a filename with a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is "SST.{MODELNAME}.{RESOLUTION}".
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "GMAO-2D".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
====================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_MAKE_DATAINFO (function) CTM_WRITEBPCH
GETMODELANDGRIDINFO UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRID_SST, INFILENAME='SST.geos.2x25', $
OUTFILENAME='SST.geos.1x1', $
OUTRESOLUTION=1
; Regrids SST data from 2 x 2.5 to 1x1 horizontal grid.
MODIFICATION HISTORY:
bmy, 28 Mar 2003: VERSION 1.01
bmy, 22 Dec 2003: VERSION 1.02
- rewritten for GAMAP v2-01
- now call PTR_FREE to free pointer memory
- added DIAGN keyword
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_sst.pro)
NAME:
REGRIDH_STRATJV
PURPOSE:
Horizontally regrids 2-D stratospheric J-Value files
from one CTM grid to another CTM grid.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_STRATJV [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
Default: ~bmy/archive/data/stratjv_200203/2x25_geos/stratjv.geos3.2x25
OUTFILENAME -> Name of output file containing the regridded
data. Default is "stratjv.{MODELNAME}.{RESOLUTION}.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
REGRIDV_DUST will use the same model name as the
input grid.
DIAGN -> Diagnostic category of data block that you want
to regrid. Default is "JV-MAP-$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===========================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_GET_DATABLOCK (function) CTM_MAKE_DATAINFO (function)
GETMODELANDGRIDINFO CTM_WRITEBPCH
UNDEFINE
REQUIREMENTS:
None
NOTES:
(1) 2-D Stratospheric J-Values are needed for the simple chemistry
mechanism in the stratosphere. They are originally obtained
by running the GEOS model with SLOW-J and then archiving
the J-Values with the ND22 diagnostic. These can then be
regridded to other vertical resolutions via REGRIDV_STRATJV.
EXAMPLE:
REGRIDV_STRATJV, INFILENAME='stratjv.geos3.4x5'
OUTFILENAME='stratjv.geos3.2x25'
OUTRESOLUTION=2
; Regrids GEOS-3 4x5 J-value data to 2x2.5 resolution.
MODIFICATION HISTORY:
bmy, 13 Jan 2003: VERSION 1.00
bmy, 22 Dec 2003: VERSION 1.01
- rewritten for GAMAP v2-01
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_stratjv.pro)
NAME:
REGRIDH_TAGCO_MASK
PURPOSE:
Regrids country mask (used to separate Tagged CO emissions)
from the GEOS-4 1 x 1.25 grid to another CTM grid.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_TAGCO_MASK [, Keywords ]
INPUTS:
KEYWORD PARAMETERS:
INFILENAME -> Name of the input file to be regridded. This
file is stored as binary F77 unformatted, with short
integers. The default filename is:
'~/bmy/archive/data/tagged_CO_200106/1x125_geos/tagco_mask.f77_unf'
OUTFILENAME -> Name of the file which will contain the
regridded data. Default is "tagco_mask.geos.{RESOLUTION}".
OUTMODELNAME -> Name of the CTM grid onto which the data will
be regridded. Default is "GEOS_4". NOTE: Since the
country mask is 2-D data, the vertical dimension of the
CTM grid will be ignored.
OUTRESOLUTION -> Resolution of the CTM grid onto which the
data will be regridded. Default is 4.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
========================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_MAKE_DATAINFO (function) INTERPOLATE_2D (function)
CTM_WRITEBPCH OPEN_FILE
REQUIREMENTS:
Requires routines from both the GAMAP and TOOLS packages.
NOTES:
None
EXAMPLE:
REGRIDH_TAGCO_MASK, INFILENAME='tagco_mask.f77_unf',$
OUTMODELNAME='GEOS_4", $
OUTRESOLUTION=2, $
OUTFILENAME='tagco_mask.geos.2x25'
; Regrids country mask for Tagged CO
MODIFICATION HISTORY:
bmy, 22 Jun 2004: VERSION 1.00
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Read input data as big-endian
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_tagco_mask.pro)
NAME:
REGRIDH_UNIT_AREA
PURPOSE:
Horizontally regrids quantities (such as emissions) in units
of [molec/cm2/s], [atoms C/cm2/s], [molec/m2/s], [atoms C/m2/s],
etc., from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_UNIT_AREA [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If OUTFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded. If not
passed, then the model name corresponding to the data
contained in INPUTFILE will be used as the default.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "IJ-AVG-$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
========================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_REGRIDH (function) CTM_WRITEBPCH
CTM_MAKE_DATAINFO (function) UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDH_UNIT_AREA, $
INFILENAME='biomass.seasonal.generic.1x1', $
OUTMODELNAME='GEOS4'
OUTRESOLUTION=2 $
OUTFILENAME='biomass.seasonal.geos.2x25'GEOS_STRAT',
; Regrids seasonal 1 x 1 biomass burning data
; onto the GEOS_4 2 x 2.5 grid.
MODIFICATION HISTORY:
bmy, 18 Aug 2005: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_unit_area.pro)
NAME:
REGRIDH_UVALBEDO
PURPOSE:
Horiziontally regrids UV albedo data from its native
resolution (1 x 1 or 1 x 1.25) to a CTM grid.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDH_UVALBEDO [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTFILENAME -> Name of the binary punch file containing
regridded UV Albedo data. The default value for
OUTFILENAME is uvalbedo.geos.{RESOLUTION}
FILL -> Value to fill "missing data" with. Default is
0.85 (typcial albedo over ice).
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Required:
=====================================================
READ_UVALBEDO (function)
External Subroutines Required:
=====================================================
MFINDFILE (function) CTM_TYPE (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_REGRIDH (function) CTM_MAKE_DATAINFO (function)
CTM_WRITEBPCH OPEN_FILE
UNDEFINE
REQUIREMENTS:
None
NOTES:
(1) Input file names are hardwired -- change as necessary
EXAMPLE:
REGRIDH_UVALBEDO, OUTFILENAME='uvalbedo.geos3.2x25', $
OUTMODELNAME='GEOS3', $
OUTRESOLUTION=2
; Regrids UV Albedos from the native grid to the
; 2 x 2.5 GEOS-3 horizontal grid. (This is
; actually the same horizontal grid as for 2 x 2.5
; GEOS-1, GEOS-STRAT, and GEOS-4.)
MODIFICATION HISTORY:
bmy, 06 Jul 2000: VERSION 1.00
bmy, 24 Jul 2000: VERSION 1.01
- added OUTDIR keyword
bmy, 16 Nov 2001: VERSION 1.02
- adapted for Koelemeijer et al 2001 data
bmy, 15 Jan 2003: VERISON 1.03
- renamed to "regridh_uvalbedo.pro"
- "read_uvalbedo.pro" is now an internal function
- now uses CTM_REGRIDH to do the regridding
bmy, 23 Dec 2003: VERSION 1.04
- updated for GAMAP v2-01
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_uvalbedo.pro)
NAME:
REGRIDVH_NOY
PURPOSE:
Regrids zonal mean P(NOY), [NO3], [O3], [NO], and
[NO2] data obtained from a 2-D stratospheric model
(Hans Schneider, Dylan Jones) onto GEOS-Chem levels.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDVH_NOY [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
Default is '~bmy/archive/data/pnoy_200106/raw/PNOY.data'.
OUTFILENAME -> Name of output file containing the regridded
data. Default is pnoy_nox_hno3.{MODELNAME}.{RESOLUTION}.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is "GEOS3".
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
DIAGN -> Diagnostic category of data block that you want
to regrid. Default is "PNOY-L=$".
OUTPUTS:
None.
SUBROUTINES:
Internal Subroutines:
============================================================
RN_ERROR_CHECK (function) RN_PLOT_COLUMN (function)
External Subroutines Required:
============================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_GET_DATABLOCK (function) CTM_MAKE_DATAINFO (function)
ZSTAR (function) CTM_WRITEBPCH
UNDEFINE
REQUIREMENTS:
References routines from both the GAMAP & TOOLS packages.
NOTES:
None
EXAMPLE:
REGRIDVH_NOY, INFILENAME='PNOY.data', $
OUTMODELNAME='GEOS1', $
OUTRESOLUTION=2
; Regrids P(NOy), HNO3, O3, NO, NO2 data from
; its native grid to the 2 x 2.5 GEOS-1 grid.
MODIFICATION HISTORY:
bmy, 29 Jun 2000: VERSION 1.00
bmy, 11 Aug 2000: VERSION 1.01
- added OUTDIR keyword
- FILENAME is now a keyword
bmy, 04 Dec 2000: VERSION 1.02
- bug fix: use 801 pts for GEOS-STRAT interpolation
bmy, 28 Mar 2001: VERSION 1.02
- now use cubic spline interpolation
- now use CTM_WRITEBPCH, CTM_NAMEXT, CTM_RESEXT
- renamed keyword MODELNAME to OUTMODELNAME
- renamed keyword RESOLUTION to OUTRESOLUTION
- renamed keyword FILENAME to INFILENAME
- updated comments
bmy, 19 Jun 2001: VERSION 1.03
- bug fix: make sure output is [v/v/s] or [v/v]
- now make sure concentrations aren't negative
after interpolating to CTM grid
bmy, 08 Jan 2003: VERSION 1.04
- renamed to "regridvh_noy.pro"
- now use linear interpolation in vertical
bmy, 23 Dec 2003: VERSION 1.05
- rewritten for GAMAP v2-01
- looks for sfc pressure file in ./PSURF subdir
- now supports output hybrid grid
bmy, 06 Aug 2004: VERSION 1.06
- now calls GET_GCAP_PRESSURE to get the
array of pressures (since it is a hybrid
grid w/ a wacky PTOP of 150 hPa.)
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Now suppresses verbose output
- Use FILE_WHICH to locate surf prs files
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridvh_noy.pro)
NAME:
REGRIDVH_PCO_LCO
PURPOSE:
Vertically and horizontally regrids zonal mean P(CO) and
L(CO) data obtained from a 2-D stratospheric model (Hans
Schneider, Dylan Jones) onto CTM sigma levels
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDVH_PCO_LCO [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing input
data to be regridded to the output grid specified
by MODELNAME and RESOLUTION. Default is "CO.P_L.data".
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=====================================================
CTM_TYPE (function) CTM_GRID (function)
ZSTAR (function) CTM_GET_DATABLOCK (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
REQUIREMENTS:
None
NOTES:
(1) Requires a file containing surface pressures on the
output CTM grid -- see /users/ctm/bmy/sup/data/regrid
directory for examples.
EXAMPLE:
REGRID_PCO_LCO, INFILENAME='CO.P_L.data', $
OUTMODELNAME='GEOS1', $
OUTRESOLUTION=2
; Regrids P(CO) and L(CO) data from its native grid
; to the 2 x 2.5 GEOS-1 grid.
MODIFICATION HISTORY:
bmy, 29 Jun 2000: VERSION 1.00
bmy, 11 Aug 2000: VERSION 1.01
- added OUTDIR keyword
- FILENAME is now a keyword
bmy, 28 Mar 2001: VERSION 1.02
- now use cubic spline interpolation
- now use CTM_WRITEBPCH, CTM_NAMEXT, CTM_RESEXT
- renamed keyword MODELNAME to OUTMODELNAME
- renamed keyword RESOLUTION to OUTRESOLUTION
- renamed keyword FILENAME to INFILENAME
bmy, 08 Jan 2003: VERSION 1.03
- renamed to "regridvh_pco_lco.pro"l
- now do linear interpolation in the vertical
bmy, 18 Dec 2003: VERSION 1.04
- rewritten for GAMAP v2-01
- Now looks for
- Now supports hybrid output grid
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
bmy, 28 Jan 2008: GAMAP VERSION 2.12
- Bug fix: PSFILE instead of PSFILENAME
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridvh_pco_lco.pro)
NAME:
REGRIDVH_STRATJV
PURPOSE:
Vertically regrids 2-D stratospheric J-Value data
from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDVH_STRATJV [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
Default is "stratjv.{MODELNAME}.{RESOLUTION}".
OUTFILENAME -> Name of output file containing the regridded
data. Default is "stratjv.{MODELNAME}.{RESOLUTION}"
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is "GEOS3".
OUTRESOLUTION -> Horizontal resolution of the model grid onto
which the data will be regridded. Default=4 (which
indicates a 4x5 grid).
DIAGN -> Diagnostic category of data block that you want
to regrid. Default is "JV-MAP-$".
OUTPUTS:
Writes output to the "stratjv.{MODELNAME}.{RESOLUTION}" file.
SUBROUTINES:
External Subroutines Required:
==========================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_GET_DATABLOCK (function) CTM_MAKE_DATAINFO (function)
ZSTAR (function) GET_GCAP_PRESSURE (function)
UNDEFINE
REQUIREMENTS:
None
NOTES:
2-D Stratospheric J-Values are needed for the simple chemistry
mechanism in the stratosphere. They are originally obtained
by running the GEOS model with SLOW-J and then archiving
the J-Values with the ND22 diagnostic. These can then be
regridded to other vertical resolutions via REGRID_STRATJV.
EXAMPLE:
REGRIDVH_STRATJV, INFILENAME='stratjv.geoss.4x5'
OUTMODELNAME='GEOS3', $
OUTRESOLUTION=4
OUTFILENAME='stratjv.geos3.4x5'
; Regrids the 4 x 4 GEOS-STRAT 2-D stratospheric
; J-value field to the GEOS-3 grid.
MODIFICATION HISTORY:
bmy, 06 Aug 2004: VERSION 1.01
bmy, 15 Feb 2007: VERSION 1.02
- Suppress verbose output
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridvh_stratjv.pro)
NAME:
REGRIDVH_STRATOH
PURPOSE:
Vertically and horizontally regrids 2-D stratospheric OH
fields (for the simplified stratospheric chemistry loss)
from native resolution onto a CTM grid.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDV_STRATOH [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing input data to be
regridded. Default is
'~bmy/archive/data/stratOH_200203/raw/OH.2d.model.data'
OUTFILENAME -> Name of file containing regridded output
data. Default is "stratoh.{MODELNAME}.{RESOLUTION}"
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
ZSTAR (function) ZMID (function)
ZEDGE (function) ADD_SEPARATOR (function)
REQUIREMENTS:
None
NOTES:
Stratospheric OH data was obtained from Hans Schneider
and Dylan Jones.
EXAMPLE:
REGRIDVH_STRATOH, INFILENAME='OH.2d.model.data', $
OUTMODELNAME='GEOS4', $
OUTRESOLUTION=2
; Regrids original stratospheric OH data to the
; 2 x 2.5 GEOS-4 grid (with 55 layers)
MODIFICATION HISTORY:
bmy, 30 Jun 2000: VERSION 1.00
bmy, 02 Aug 2000: VERSION 1.01
- FILENAME is now a keyword
bmy, 18 Dec 2003: VERSION 1.02
- renamed to REGRIDVH_STRATOH
- rewritten for GAMAP v2-01
- Now supports hybrid output grids
bmy, 15 Feb 2007: VERSION 1.03
- Bug fix for PS file name
- Suppress verbose printing
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
bmy, 28 Jan 2008: GAMAP VERSION 2.12
- Bug fix: don't hardwire path for PS file
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridvh_stratoh.pro)
NAME:
REGRIDV_3D_OH
PURPOSE:
Vertically regrids 3-D OH data from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDV_3D_OH [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing OH data to be
regridded. If not specified, then a dialog box
will ask the user to supply a file name.
OUTFILENAME -> Name of file to contain the regridded OH.
Default is "OH_3Dglobal.{MODELNAME}.{RESOLUTION}".
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
REGRIDV_3D_OH will use the same model name as the
input grid.
DIAGN -> Diagnostic category of data block that you want
to regrid. Default is "IJ-AVG-$".
/TROP_ONLY -> If set, will only regrid data within the
tropopause (i.e. up to the level specified by
MODELINFO.NTROP).
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
============================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_MAKE_DATAINFO (function) CTM_GET_DATABLOCK (function)
REGRID_COLUMN (function) GETMODELANDGRIDINFO
UNDEFINE
REQUIREMENTS:
None
NOTES:
(1) The merged OH file is generated by "merge_oh.pro".
EXAMPLE:
REGRIDV_3D_OH, INFILENAME='OH_3Dglobal.geos3.4x5', $
OUTFILENAME='OH_3Dglobal.geos4.4x5',$
OUTMODELNAME='GEOS4'
; Regrids GEOS-3 merged OH (48 layers) to the GEOS-4
; grid (55 layers) at 4x5 horizontal resolution
MODIFICATION HISTORY:
bmy, 02 Aug 2000: VERSION 1.00
- adapted from "regrid_oh_for_geos2.pro"
bmy, 05 Feb 2002: VERSION 1.01
- now conserves column mass
bmy, 14 Mar 2002: VERSION 1.02
- RENAMED TO "regridv_3d_oh.pro"
bmy, 22 Dec 2003: VERSION 1.03
- totally rewritten for GAMAP v2-01
- now supports hybrid grids
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridv_3d_oh.pro)
NAME:
REGRIDV_AEROSOL
PURPOSE:
Vertically regrids aerosol concentrations from one
CTM grid to another. Total mass is conserved.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDV_AEROSOL [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
MONTH -> Month of year for which to process data. Default is
the entire year. Since the aerosol files are very large,
it take several iterations to regrid an entire year of
data. You can break the job down 1 month at a time.
INFILENAME -> Name of the file containing data to be regridded.
If omitted, then REGRIDV_AEROSOL will prompt the user to
select a filename with a dialog box.
OUTFILENAME -> Name of output file containing the regridded
data. If OUTFILENAME is not specified, then REGRIDV_AEROSOL
will ask the user to specify a file via a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
REGRIDV_AEROSOL will use the same model name as the
input grid.
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "ARSL-L=$".
/TROP_ONLY -> If set, will only regrid data within the
tropopause (i.e. up to the level specified by
MODELINFO.NTROP).
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_GET_DATABLOCK (function) CTM_MAKE_DATAINFO (function)
REGRID_COLUMN (function) CTM_WRITEBPCH
CTM_GET_DATA GETMODELANDGRIDINFO
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDV_AEROSOL, INFILENAME='aerosol.geos3.4x5', $
OUTFILENAME='aerosol.geos4.4x5', $
OUTRESOLUTION=4, $
; Regrids dust data from the GEOS-3 4 x 5
; grid to the GEOS-4 4 x 5 grid.
MODIFICATION HISTORY:
bmy, 26 Jan 2001: VERSION 1.00
- based on "regrid_dust_weights.pro"
bmy, 13 Feb 2001: VERSION 1.01
- de-hardwired calls to CTM_BOXSIZE
bmy, 22 Feb 2001: VERSION 1.02
- now use improved version of SUMV.PRO
which can handle GEOS-1 --> GEOS-STRAT
vertical regridding
bmy, 28 Feb 2002: VERSION 1.03
- Now use REGRID_COLUMN as a robust way
to do the vertical regridding
bmy, 22 Dec 2003: VERSION 1.04
- rewritten for GAMAP v2-01
- now looks for sfc pressure in ~/IDL/regrid/PSURF
- now supports hybrid grids
- now call PTR_FREE to clear the heap memory
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridv_aerosol.pro)
NAME:
REGRIDV_DUST
PURPOSE:
Vertically regrids mineral dust concentrations [kg/m3]
from one CTM grid to another. Total mass is conserved.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDV_DUST [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
MONTH -> Month of year for which to process data. Default is
the entire year. Since the dust files are very large,
it take several iterations to regrid an entire year of
data. You can break the job down 1 month at a time.
INFILENAME -> Name of the file containing data to be regridded.
If omitted, then REGRIDV_DUST will prompt the user to
select a filename with a dialog box.
OUTFILENAME -> Name of output file containing the regridded
data. If OUTFILENAME is not specified, then REGRIDV_DUST
will ask the user to specify a file via a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
REGRIDV_DUST will use the same model name as the
input grid.
DIAGN -> Diagnostic category of data block that you want
to regrid. Default is "MDUST-$".
/TROP_ONLY -> If set, will only regrid data within the
tropopause (i.e. up to the level specified by
MODELINFO.NTROP).
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_GET_DATABLOCK (function) CTM_MAKE_DATAINFO (function)
REGRID_COLUMN (function) CTM_WRITEBPCH
CTM_GET_DATA GETMODELANDGRIDINFO
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDV_DUST, MONTH=1, $
INFILENAME='dust.geos3.2x25', $
OUTFILENAME='dust.geos4.4x5.01', $
OUTRESOLUTION=4
; Vertically regrids dust data from the GEOS-3
; 2 x 2.5 grid to the GEOS-3 4 x 5 grid for January.
MODIFICATION HISTORY:
bmy, 26 Jan 2001: VERSION 1.00
- based on "regrid_dust_weights.pro"
bmy, 13 Feb 2001: VERSION 1.01
- de-hardwired calls to CTM_BOXSIZE
bmy, 22 Feb 2001: VERSION 1.02
- now use improved version of SUMV.PRO
which can handle GEOS-1 --> GEOS-STRAT
vertical regridding
bmy, 28 Feb 2002: VERSION 1.03
- Now use REGRID_COLUMN as a robust way
to do the vertical regridding
bmy, 23 Dec 2003: VERSION 1.04
- rewritten for GAMAP v2-01
- now looks for sfc pressure ~/IDL/regrid/PSURF
- now supports hybrid grids
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridv_dust.pro)
NAME:
REGRIDV_JV
PURPOSE:
Vertically regrids J-values from one CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDV_JV, [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing input data to be
regridded to the output grid specified by MODELNAME
and RESOLUTION.
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTFILENAME -> Name of file containing regridded output
data. Written in binary punch format.
/TROP_ONLY -> Set this switch to only save data below
the tropopause.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
ZSTAR (function) CTM_GET_DATABLOCK (function)
CTM_GET_DATA CTM_MAKE_DATAINFO (function)
CTM_WRITEBPCH GETMODELANDGRIDINFO
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDV_JV, INFILENAME='JH2O2.geos3.4x5', $
OUTFILENAME='JH2O2.geos4.4x5', $
OUTMODELNAME='GEOS4'
; Regrids GEOS-3 stratospheric J-value data at 4 x 5
; resolution from GEOS-3 to GEOS-4 vertical resolution.
MODIFICATION HISTORY:
bmy, 11 Aug 2000: VERSION 1.01
bmy, 22 Dec 2003: VERSION 1.02
- renamed to "regridv_jv"
- now looks for sfc pressure in ~/IDL/regrid/PSURF
- now updated for GAMAP v2-01
- added /TROP_ONLY keyword
- updated comments
bmy, 07 Jul 2005: VERSION 1.03
- Now pass /QUIET keyword to CTM_GET_DATA
- Now pass /NOPRINT keyword to CTM_GET_DATABLOCK
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
ccc, 09 Oct 2009: GAMAP VERSION 2.13
- fix size of outdata 3rd dimension
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridv_jv.pro)
NAME:
REGRIDV_O3PL
PURPOSE:
Vertically regrids files containing GEOS-CHEM P(O3) and L(O3).
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRID_O3PL [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDV_O3PL
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If OUTFILENAME is not specified, then REGRIDV_PORL
will prompt the user to select a file via a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is "GEOS3".
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "PORL-L=$".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===========================================================
CTM_TYPE (function) CTM_GRID (function)
CTM_GET_DATABLOCK (function) CTM_MAKE_DATAINFO (function)
TAU2YYMMDD (function) ZSTAR (function)
REPLACE_TOKEN (function) GETMODELANDGRIDINFO
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDV_O3PL, INFILENAME='~/geoss/rate.971130', $
OUTFILENAME='~/geos3/rate.971130', $
OUTMODELNAME='GEOS3'
; Regrids P(O3) and L(O3) data from GEOS-STRAT
; 4 x 5 grid to GEOS-3 4 x 5 grid.
MODIFICATION HISTORY:
bmy, 27 Mar 2001: VERSION 1.00
bmy, 23 Dec 2003: VERSION 1.01
- renamed to "regridv_o3pl.pro"
- rewritten for GAMAP v2-01
- now looks for sfc pressure in ~/IDL/regrid/PSURF
bmy, 24 Feb 2004: VERSION 1.02
- now convert P(Ox) to kg/s and L(Ox) 1/s for
regridding -- then convert back after regridding
- now use REGRID_COLUMN to regrid P(Ox) in kg/s
- now use INTERPOL to regrid L(Ox) in 1/s
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridv_o3pl.pro)
NAME:
REGRIDV_PORL
PURPOSE:
Regrids production/loss or other data in [molec/cm3/s]
from one vertical CTM grid to another.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDV_PORL [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDV_PORL
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. If OUTFILENAME is not specified, then REGRIDV_PORL
will prompt the user to select a file via a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is "GEOS3".
DIAGN -> Diagnostic category of the data blocks that you
wish to regrid. Default is "PORL-L=$".
/TROP_ONLY -> Set this switch to only save regridded data
from the surface to the highest tropopause level
(e.g. MODELINFO.NTROP as returned from CTM_TYPE).
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_GET_DATABLOCK (function) CTM_MAKE_DATAINFO (function)
REGRID_COLUMN (function) CTM_WRITEBPCH
CTM_GET_DATA GETMODELANDGRIDINFO
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
REGRIDV_PORL, INFILENAME='data.geos3.4x5', $
OUTFILENAME="data.geos4.4x5', $
OUTMODELNAME='GEOS4'
; Regrids data in molec/cm3 from GEOS-3 vertical
; resolution to GEOS_4 vertical resolution.
MODIFICATION HISTORY:
bmy, 01 Nov 2002: VERSION 1.01
bmy, 19 Dec 2003: VERSION 1.02
- rewritten for GAMAP v2-01
- now looks for sfc pressure in ~/IDL/regrid/PSURF/
- now supports hybrid grids
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
ccc, 09 Oct 2009: GAMAP VERSION 2.13
- fix a keyword check
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridv_porl.pro)
NAME:
REGRIDV_RESTART
PURPOSE:
Vertically regrids data in [v/v] mixing ratio from one
model grid to another. Data is converted to [kg] for
regridding, and then converted back to [v/v].
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRIDV_RESTART [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the input file containing data to
be regridded. If not specified, then REGRIDV_RESTART
will prompt the user to select a file name with a
dialog box.
OUTFILENAME -> Name of the directory where the output file
will be written. If OUTFILENAME is not specified, then
REGRIDV_RESTART will prmopt the user to specify a file
name via a dialog box.
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. If OUTMODELNAME is not specified,
REGRIDV_AEROSOL will use the same model name as the
input grid.
DIAGN -> Diagnostic category of data block that you want
to regrid. Default is "IJ-AVG-$".
/TROP_ONLY -> If set, will only regrid data within the
tropopause (i.e. up to the level specified by
MODELINFO.NTROP).
/GCAP -> Set this flag to denote that we are regridding from
a 4x5 restart file on a GEOS-3 or GEOS-4 grid which has
previously been regridded to 45 latitudes.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
=======================================================
RVR_GetAirMass (function) RVR_GetPEdge (function)
External Subroutines Required:
===========================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_GET_DATABLOCK (function) CTM_MAKE_DATAINFO (function)
REGRID_COLUMN (function) GETMODELANDGRIDINFO
CTM_WRITEBPCH UNDEFINE
REQUIREMENTS:
None
NOTES:
None.
EXAMPLE:
REGRIDV_RESTART, INFILENAME='data.geos3.4x5', $
OUTMODELNAME='geos_strat', $
OUTFILENAME='data.geoss.4x5'
; Regrids 4 x 5 GEOS-3 data to the GEOS-STRAT grid.
MODIFICATION HISTORY:
bmy, 21 Jan 2003: VERSION 1.00
- adapted from "regridv_3d_oh.pro
bmy, 25 Jun 2003: VERSION 1.01
- added routine RVR_GetPEdge
- now uses ETA coords for GEOS-4 hybrid grid
bmy, 31 Oct 2003: VERSION 1.02
- now call PTR_FREE to free pointer memory
- now recognizes GEOS3_30L model name
- now recognizes GEOS4_30L model name
bmy, 19 Dec 2003: VERSION 1.03
- now supports hybrid grids
- added /TROP_ONLY switch to regrid only
as high as the tropopause
- now looks for sfc pressure in ~/IDL/regrid/PSURF
- removed routine RVR_GetPEdge
- modified routine RVR_GetAirMass
bmy, 17 Feb 2004: VERSION 1.04
- bug fix: replaced D with N as loop index
bmy, 01 Feb 2005 - Now suppress excessive printing to screen
with keywords /QUIET and /NOPRINT in
call to CTM_GET_DATABLOCK
bmy, 26 May 2005: VERSION 1.05
- added /GCAP keyword for special handling
when creating restart files on 4x5 GCAP grid
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
bmy, 04 Nov 2013: GAMAP VERSION 2.17
- Now make sure that the GCAP output grid uses
the proper vertical edge pressurs.
- Also remove all pointer references, use
*( DataInfo[D].Data ) directly
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridv_restart.pro)
NAME:
REGRID_BIOFUEL
PURPOSE:
Regrids 1 x 1 biomass burning emissions for NOx or CO
onto a CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRID_BIOFUEL [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
MODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
RESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
/NOX -> If set, will regrid NOx biofuel data. Default is
to regrid CO biofuel data.
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
OUTPUTS:
Writes binary punch files:
biofuel.NOx.{MODELNAME}.{RESOLUTION} (when NOX=1)
biofuel.CO.{MODELNAME}.{RESOLUTION} (when NOX=0)
SUBROUTINES:
External Subroutines Required:
================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_WRITEBPCH
Internal Subroutines
================================================
RBF_READDATA (function)
REQUIREMENTS:
None
NOTES:
The path names for the files containing 1 x 1 data are
hardwired -- change as necessary!
EXAMPLE:
(1)
REGRID_BIOFUEL, MODELNAME='GEOS_STRAT', RESOLUTION=[5,4]
; Regrids 1 x 1 CO biofuel data to the 4 x 5 GEOS-STRAT grid
(2)
REGRID_BIOFUEL, MODELNAME='GEOS_1', RESOLUTION=2, /NOX
; Regrids 1 x 1 NOx biofuel data to the 2 x 2.5 GEOS-1 grid
MODIFICATION HISTORY:
bmy, 09 Jun 2000: VERSION 1.00
bmy, 12 Jul 2000: VERSION 1.01
- added NOx keyword
- now read original data with
internal function RBF_READDATA
bmy, 24 Jul 2000: - added OUTDIR keyword
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regrid_biofuel.pro)
NAME:
REGRID_COLUMN
PURPOSE:
Vertically regrids a column quantity in such a way
as to preserve the total mass.
CATEGORY:
Regridding
CALLING SEQUENCE:
DATA2 = REGRID_COLUMN( DATA1, PEDGE1, PEDGE2 [, keywords ] )
INPUTS:
DATA1 -> Column vector containing data on the original
grid. DATA1 must be a mass-like quantity that does
not have any vertical dependence (e.g. molecules,
g, kg, kg/m2, molec/cm2, etc.)
PEDGE1 -> Pressures [hPa] at the edges of each layer on
the old vertical grid. PEDGE1 will thus have one
more element element than DATA1 (since DATA1 is
specified on the midpoints of each layer).
PEDGE2 -> Pressures [hPa] at the edges of each layer on
the new vertical grid. PEDGE2 will thus have one
more element element than DATA2 (since DATA2 is
specified on the midpoints of each layer).
KEYWORD PARAMETERS:
/DEBUG -> If set, will print debug information to the
screen, including totals before and after regridding.
/NO_CHECK -> If this keyword is set, then REGRID_COLUMN
will not check to see if the column sum was preserved
in going from the old grid to the new grid. This is
useful if you are regridding data from a grid with a
high model top to a grid with a lower model top
(such as from GEOS-3 to GEOS-1).
OUTPUTS:
DATA2 -> Column vector containing data on the new vertical
grid. The column sum of DATA2 will equal that of
DATA1. DATA2 will also be a mass-like quantity.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
(1) Adapted from FORTRAN code by Amanda Staudt, Bob
Yantosca, and Dale Allen originally used to interpolate
GEOS-3 data from Pressure to Sigma coordinates.
(2) The algorithm is brute force, but it works for all
kinds of grids. It will even work for grids where the new
vertical resolution is smaller than the original vertical
resolution.
(3) Processes one column at a time. For an entire lat/lon
region, you have to loop over each surface grid location
and call REGRID_COLUMN to process each column separately.
(4) Added /NO_CHECK keyword to facilitate regridding from
GEOS-3 to GEOS-1. Otherwise, you should never use this
keyword.
EXAMPLE:
; Surface pressure (assume same for both grids)
PSurf = 1000.0
; Define Input grid -- use GAMAP routines
InType = CTM_Type( 'GEOS_STRAT', res=2 )
InGrid = CTM_Grid( InType )
InPEdge = ( InGrid.SigEdge * ( PSurf - InType.PTOP ) ) + $
Intype.PTOP
; Define Output grid -- use GAMAP routines
OutType = CTM_Type( 'GEOS3', res=2, PSurf=1000.0 )
OutGrid = CTM_Grid( OutType )
OutPEdge = ( OutGrid.SigEdge * ( PSurf - OutType.PTOP ) ) +
OutType.PTOP
; Assume INDATA is in [kg], OUTDATA will be too
OutData = Regrid_Column( InData, InPEdge, OutPEdge )
; Regrid a column of mass from the 2 x 2.5
; GEOS-STRAT grid to the 2 x 2.5 GEOS-3 grid
MODIFICATION HISTORY:
bmy, 22 Jan 2002: TOOLS VERSION 1.50
bmy, 14 Mar 2002: - added /NO_CHECK keyword
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/regrid_column.pro)
NAME:
REGRID_DUST
PURPOSE:
Regrids 2.5 x 2.5 mineral dust concentrations
onto a CTM grid of equal or coarser resolution.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRID_DUST [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
MONTH -> Month of year for which to process data.
Default is 1 (January).
MODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
RESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
OUTPUTS:
Writes binary punch file:
dust.{MODELNAME}.{RESOLUTION}
SUBROUTINES:
External Subroutines Required:
=================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_BOXSIZE (function) CTM_REGRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
CTM_WRITEBPCH
REQUIREMENTS:
References routines from the GAMAP and TOOLS packages.
NOTES:
(1) The path names for the files containing dust data are
hardwired -- change as necessary!
(2) Even though photolysis rates are only needed in the
troposphere, we need to save the mineral dust for all
levels of the model. Scattering by mineral dust is
used to compute the actinic flux, and therefore we need
to account for this all the way to the atmosphere top.
(3) The regridding process can take a very long time to
complete. If you are regridding, it is recommended to
process one month at a time, and then to concatenate
the binary punch files using GAMAP.
EXAMPLE:
REGRID_DUST, MODELNAME='GEOS_STRAT', RESOLUTION=4
; Regrids dust data from 2 x 2.5 native resolution
; to 4 x 5 resolution for the GEOS-STRAT grid
MODIFICATION HISTORY:
bmy, 09 Jun 2000: VERSION 1.00
rvm, 18 Jun 2000: VERSION 1.01
bmy, 07 Jul 2000: VERSION 1.10
- added OUTDIR keyword
- save regridded data one month at a time
since regridding takes so long
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read input files as big-endian
(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_dust_raw.pro)
NAME:
REGRID_TOMS_SBUV
PURPOSE:
Regrids 5 x 10 O3 column data from both
TOMS and SBUV instruments onto a CTM grid.
CATEGORY:
Regridding
CALLING SEQUENCE:
REGRID_TOMS_SBUV [ , Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> A string containing the name of the model
grid onto which the data will be regridded.
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. 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 for all models is 4x5.
OUTDIR -> Name of the directory where the output file will
be written. Default is './'. ;
OUTPUTS:
Writes regridded O3 columns to file.
SUBROUTINES:
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Input filename is hardwired -- change as necessary
EXAMPLE:
REGRID_TOMS_SBUV, OUTMODELNAME='GEOS1', $
OUTRESOLUTION=4, $
OUTDIR='/scratch/'
; Regrids O3 column data to GEOS-1 4 x 5 grid,
; writes output file to /scratch directory
MODIFICATION HISTORY:
bmy, 16 Mar 2001: VERSION 1.00
bmy, 29 Mar 2001: VERSION 1.01
- renamed to REGRID_TOMS_SBUV
- renamed keyword MODELNAME to OUTMODELNAME
- renamed keyword RESOLUTION to OUTRESOLUTION
- now use routine INTERPOLATE_2D
(See /n/home09/ryantosca/IDL/gamap2/regridding/regrid_toms_sbuv.pro)
NAME:
REPLACE_TOKEN (function)
PURPOSE:
Replaces occurrences of tokens with text. Can also
be used to expand wildcards with a name list.
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = REPLACE_TOKEN( STR, TOKEN, TEXT, [, Keywords ] )
INPUTS:
STR -> The string to be searched for tokens. This must be
a scalar string.
TOKEN -> A string or string array containing the token text
*OR* a structure. If TOKEN is a structure, the tag
names will be used as Tokens and the tag values will
be converted to string and used as TEXT. TOKEN is
case-insensitive and will always be used as uppercase.
TEXT -> A string or string array containing the replacement
text. TEXT may be some other type than string on input.
In this case it will be returned as string and formatted
according to the optional FORMAT keyword. If TOKEN is
provided as a structure, TEXT will return the (formatted)
tag values as strings. TOKEN and TEXT must have the same
number of elements with one exception: If TOKEN contains
only one element while TEXT is an array, the result will
be a string array where each string has TOKEN replaced
with the corresponding TEXT value (wildcard replacement).
[see example 7]
KEYWORD PARAMETERS:
DELIMITER -> The delimiter character for TOKEN. Default is
'%'. The delimiter will be automatically appended to the
beginning and end of TOKEN if not already there.
COUNT -> Number of tokens that were replaced. If TOKEN has
more than one element or tag, COUNT will be an integer
array.
VERBOSE -> Will print a warning message if no tokens are found.
FORMAT -> A string or string array containing format
specifications for each element of TEXT or each tag of
the TOKEN structure. If FORMAT contains only one element,
this will be used throughout. For wildcard replacement,
the default format is I14 (number will be trimmed).
TFORMAT -> (type format) If TOKEN is provided as a structure,
it may contain data of various types. You can use TFORMAT
to specify a format code for each data type (see IDL SIZE
function) instead of each tag number as with the FORMAT
keyword. TFORMAT should contain at least 6 elements to
allow formatting of double precision data, or 8 elements
if you want to output complex data.
OUTPUTS:
RESULT -> String with replaced text. If TOKEN is a single
string and TEXT is an array, then the result is an array
with N(text) elements. In case of errors, an empty string
is returned.
SUBROUTINES:
External Subroutines Used:
========================================
CHKSTRU (function) STRRIGHT (function)
REQUIREMENTS:
None
NOTES:
(1) The original input string (STR) is not altered.
(2) REPLACE_TOKEN will search for and replace multiple
occurrences of the same token in the input string (STR).
(3) Use DELIM='' for wildcard replacement.
(4) If no tokens are found in the input string, then
REPLACE_TOKEN returns the original input string (STR)
as the value of the function.
(5) The use of structures for TOKEN allows for different
data types.
EXAMPLE:
(1)
STR = 'Hello, My Name is %NAME% and %NAME%.'
NEWSTR = REPLACE_TOKEN( Str, 'NAME', 'Robert' )
PRINT, NEWSTR
Hello, my name is Robert and Robert.
; Replace multiple tokens in the input string
(2)
STR = 'His name is %NAME% and he lives in %STREET%, %CITY%'
TOKEN = { NAME : 'Henry', $
STREET : '29 Oxford St.', $
CITY : 'Cambridge, MA', $
ZIP : '02138' }
PRINT, REPLACE_TOKEN( STR, TOKEN )
His name is Henry and he lives in
29 Oxford St., Cambridge, MA
; Use a structure to replace several items at once
; (Note: ZIP code is not used!)
(3)
STR = 'His name is NAME and he lives in STREET, CITY'
PRINT, REPLACE_TOKEN( STR, TOKEN, DELIM='' )
His Henry is Henry and he lives in ...
; Use of an empty delimiter (same TOKEN as above)
; (Exercise: what went wrong ?)
(4)
STR = 'The date is 2003/01/01.'
PRINT, REPLACE_TOKEN( STR, '2003', 2005', DELIM='' )
The date is 2005/01/01.
; Another use of an empty delimiter
; (very useful for switching dates/times!!!)
(5)
STR = 'She earns %Salary%.'
FORMAT = '("$",g0.10)'
PRINT, REPLACE_TOKEN( STR, 'Salary', 39000., FORMAT=FORMAT )
She earns $39000.
; Use of FORMAT
(6)
STR = '%Name% earns %Salary%.'
VAL = { NAME : 'Sally', $
SALARY : 39000. }
TFORMAT = [ '(A)','','','','("$",g0.10)','("$",g0.10)' ]
; (format codes for string, float and double)
PRINT, REPLACE_TOKEN( STR, VAL, TFORMAT=TFORMAT )
Sally earns $39000.
; Use of TFORMAT
(7)
FILEMASK = '~/data/cruise$$.dat'
CRUISES = indgen(10)+1
PRINT, REPLACE_TOKEN( FILEMASK, '$$', $
CRUISES, DELIM='', FORMAT='(I2.2)' )
~/data/cruise01.dat
~/data/cruise02.dat ...
~/data/cruise10.dat
; Wildcard replacement
MODIFICATION HISTORY:
bmy, 23 Sep 1998: VERSION 1.00
bmy, 24 Sep 1998: - added VERBOSE keyword and improved comments
mgs, 24 Sep 1998: - improved error handling
- TOKEN and TEXT may now be arrays
- *or* TOKEN may be a structure
- TEXT is trimmed
- added FORMAT and TFORMAT keywords
mgs, 23 Dec 1998: - added wildcard (isarray) functionality
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- updated comments
(See /n/home09/ryantosca/IDL/gamap2/strings/replace_token.pro)
NAME:
RESOLVE_EVERY
PURPOSE:
Resolve (by compiling) all procedures and functions.
This is useful when preparing .sav files containing all the IDL
routines required for an application.
CATEGORY:
General
CALLING SEQUENCE:
RESOLVE_EVERY
INPUTS:
None.
KEYWORD PARAMETERS:
QUIET = if set, produce no messages.
SKIP_ROUTINES = an optional string array containing the names
of routines to NOT resolve. This is useful when a library
file containing the designated routines will be later included.
OUTPUTS:
No explicit outputs.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None
RESTRICTIONS:
Will not resolve procedures or functions that are called via
CALL_PROCEDURE, CALL_FUNCTION, or EXECUTE. Only explicit calls
are resolved.
If an unresolved procedure or function is not in the IDL
search path, an error occurs, and no additional routines
are resolved.
PROCEDURE:
This routine iteratively determines the names of unresolved calls
to user-written or library procedures and functions, and then
compiles them. The process stops when there are no unresolved
routines.
EXAMPLE:
RESOLVE_EVERY.
MODIFICATION HISTORY:
Written by:
DMS, RSI, January, 1995.
DMS, RSI, April, 1997, Added SKIP_ROUTINES keyword.
mgs, Harvard, 21 Apr 1998: use findfile before trying to resolve
a routine
bmy, 28 May 2004: TOOLS VERSION 2.02
- Now use MFINDFILE which will call FILE_SEARCH
for IDL 5.5+ or FINDFILE for IDL 5.4-
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/resolve_every.pro)
NAME:
REVISIONS
PURPOSE:
Extract information about file modifications and create
REVISIONS file for all files w/in a directory.
CATEGORY:
Documentation
CALLING SEQUENCE:
REVISIONS, DIRNAME
INPUTS:
DIRNAME -> directory name to be searched for *.pro files
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================================
ADD_SEPARATOR (function) MFINDFILE
STRDATE (function) STRRIGHT (function)
REQUIREMENTS:
The program files must have a standard header with tag
"MODIFICATION HISTORY" as last item. This must be followed
with a ;- line (!! NOT ;----- !!).
The REVISIONS file will be written in the directory DIRNAME,
thus the user must have write permission.
NOTES:
(1) All *.pro file in the given directory will be analyzed.
(2) Also see IDL routine ADD_TEMPLATE
EXAMPLE:
REVISIONS, '~/IDL/gamap2/doc/'
; Will produce a REVISIONS file for all of the
; *.pro files w/in the '~/IDL/gamap2/doc' directory
MODIFICATION HISTORY:
mgs, 16 Jun 1998: VERSION 1.00
mgs, 25 May 1999: - added caution for tag detection in this
routine itself.
bmy, 24 Oct 2003: TOOLS VERSION 1.53
- Bug fix: EXPAND_PATH strips the directory
separator string from the end of DIRNAME
in IDL 6.0+. Add this back manually.
- use MFINDFILE instead of FINDFILE to fix
file listing bug in IDL 5.2-
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/doc/revisions.pro)
NAME:
REWRITE_AGPROD
PURPOSE:
To rewrite a APROD / GPROD restart file with a different
timestamp TAU0. The correspondence b/w file name and timestamp
is enforced, as required by GEOS-Chem.
CATEGORY:
Date & Time
CALLING SEQUENCE:
REWRITE_AGPROD, INFILE='old_file_name', TAU0=tau | YMD=yyyymmdd
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> initial restart_aprod_gprod file. If not
passed, a dialog window will pop up.
TAU0 (double) -> the new time stamp you want, in Tau units
YMD (long) -> the new time stamp you want, in YYMMDD or YYYYMMDD
HH -> hour for this date (e.g. 6 for 6 a.m.) Default is 0.
Either TAU0 or YMD should be passed. If both are passed,
TAU0 is used.
OUTPUTS:
None.
SIDE EFFECTS:
A file named restart_aprod_gprod.YYYYMMDDHH where YYYYMMDDHH
corresponds with TAU0 in the data blocks is created.
RESTRICTIONS:
The input file must be a restart_aprod_gprod file.
NOTES:
This is not a regridding routine. To regrid a
restart_aprod_gprod file, use :
REGRIDV_RESTART, ..., DIAGN=0
or/and
REGRIDH_RESTART, ..., DIAGN=0
EXAMPLE:
REWRITE_AGPROD, YMD=20010701
MODIFICATION HISTORY:
phs, Jul 2007: version 0.1
phs, 04 Apr 2007: GAMAP VERSION 2.12
- commemts
- clean non_global pointers
- added YMD and HH keywords
ccc, 09 Aug 2010: GAMAP VERSION 2.14
- add automatic definition of outfilename
(See /n/home09/ryantosca/IDL/gamap2/date_time/rewrite_agprod.pro)
NAME:
RH
PURPOSE:
Calculates relative humidity from temperature and
dew/frostpoint
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = RH( DEWPOINT, TEMPERATURE [,/WATER] [,/ICE] )
INPUTS:
DEWPOINT --> dewpoint (or frostpoint) temperature [K]
TEMPERATURE --> dry (or static) air temperature [K]
KEYWORD PARAMETERS:
/WATER --> always calculate dewpoint temperature
/ICE --> always calculate frostpoint temperature
OUTPUTS:
RESULT -> Relative humidity [%]
SUBROUTINES:
External Subroutines Required:
===============================
E_H2O (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, RH( 266., 278. )
41.4736
; Prints the RH for dewpoint=266K and temp=278K.
MODIFICATION HISTORY:
mgs, 23 Feb 1997: VERSION 1.00
mgs, 03 Aug 1997: split e_h2o and rh, renamed, added template
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/rh.pro)
NAME:
ROUTINE_NAME (function)
PURPOSE:
return the name of the routine which calls this function.
CATEGORY
File & I/O
CALLING SEQUENCE:
rname = ROUTINE_NAME()
INPUTS:
none
KEYWORD PARAMETERS:
FILENAME -> returns the file in which the routine can be found
/CALLER -> returns information about the caller of the routine
instead of the routine itself
OUTPUTS:
The name of the caller routine is returned in lowercase
characters (can be used to construct a filename by adding
".pro")
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
From the command line:
PRINT, ROUTINE_NAME()
results in $main$
Very useful in conjunction with USAGE.PRO:
USAGE, ROUTINE_NAME()
displays help information on the current routine.
MODIFICATION HISTORY:
mgs, 27 Mar 1998: VERSION 1.00
mgs, 22 Apr 1998: - added FILENAME and CALLER keywords
mgs, 14 Jan 1998: - needed fix for filename when working on PC:
$MAIN$ allows no str_sep
bmy, 07 Aug 2002: TOOLS VERSION 1.51
- Now use routine STRBREAK to split the line
instead of STR_SEP. STR_SEP has been removed
from the IDL distribution in IDL 5.4+.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/routine_name.pro)
NAME:
RSEARCH
PURPOSE:
Wrapper for routines STRPOS and RSTRPOS.
Needed for backwards compatibility for GAMAP users
who are running versions of IDL prior to 5.2.
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = RSEARCH( STR, PATTERN )
INPUTS:
STR -> The string to be searched.
PATTERN -> The pattern to search for in STR.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Character index where PATTERN is found in STR
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
STR = "This is a test: Hello!"
PRINT, RSEARCH( STR, 'test:' )
10
; Location where PATTERN is found in STR
MODIFICATION HISTORY:
bmy, 17 Jan 2002: TOOLS VERSION 1.50
bmy, 14 Apr 2005: TOOLS VERSION 2.04
- Now uses CALL_FUNCTION to call STRPOS
and RSTRPOS so as to avoid bugs at
compile-time
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/rsearch.pro)
NAME:
RUN_AV (function)
PURPOSE:
Compute running average or running total of a
data vector. Compared to the IDL function TS_SMOOTH,
this function takes into account missing values or
gaps in an optional x vector, and it allows for
even bandwidths. It can also be used to compute cumulative
totals.
CATEGORY:
Math & Units
CALLING SEQUENCE:
result = RUN_AV(Y [,X] [,keywords] )
INPUTS:
Y -> the data vector (a 2-D array will be treated as a vector)
X -> an optional X vector defining e.g. the sample times.
This only has an effect when the DELTAX keyword is specified.
X must be monotonically increasing and have the same
number of elements as Y.
KEYWORD PARAMETERS:
WIDTH -> The number of points to use for the average or total
Default is 1, i.e. Y is returned unchanged.
MINWIDTH -> The minimum number of points that must be valid
in order to return a average or total for the given point.
Default is MINWIDTH=WIDTH, i.e. all points must be valid
(and if X and DELTAX are specified, all points must lie
within WIDTH*DELTAX).
MIN_VALID -> The minimum value for valid data. Data with less than
MIN_VALID will be considered missing. MIN_VALID is also used
to indicate invalid totals or averages (1% is subtracted).
DELTAX -> The maximum gap between two consecutive x values.
Only effective when X is given.
COUNT -> A named variable will return the number of points used
in each average or total.
/TOTAL -> Set this keyword to compute running totals instead
of running averages.
OUTPUTS:
The function returns a vector with running averages or totals.
The number of elements in the result vector always equals the
number of elements in Y (unless an error occurs).
SUBROUTINES:
REQUIREMENTS:
NOTES:
This function can also be used to compute accumulative totals.
Simply set WIDTH to n_elements(Y) and MINWIDTH to 1 and use
the /TOTAL keyword. However, this is very uneffective for large
data vectors!
EXAMPLE:
y = findgen(20)
print,run_av(y,width=4)
; IDL prints: -1E31 -1E31 -1E31 1.5 2.5 3.5 4.5 ...
print,run_av(y,width=4,/TOTAL)
; IDL prints: -1E31 -1E31 -1E31 6 10 14 18 ...
; (cumulative total)
print,run_av(y,width=n_elements(y),minwidth=1,/TOTAL)
; IDL prints: 0 1 3 ... 190
x = [ 0, 2, 4, 6, 16, 20, 24, 25, 26, 27, 28, 29, 30, 32, 33 ]
y = fltarr(n_elements(x)) + 1.
print,run_av(y,x,width=4,count=c)
; IDL prints: -1E31 -1E31 -1E31 1 1 1 1 ...
print,c
; IDL prints: 1 2 3 4 4 4 4 4 4 4 4 4 4 4 4
print,run_av(y,x,deltax=2,width=4,count=c)
; IDL prints: -1E31 -1E31 -1E31 1 -1E31 -1E31 -1E31
; -1E31 -1E31 -1E31 1 1 1 1 1
print,c
; IDL prints: 1 2 3 4 3 2 1 1 2 3 4 4 4 4 4
MODIFICATION HISTORY:
mgs, 21 Oct 1998: VERSION 1.00
mgs, 07 Jun 1999: - changed loop variable to LONG type.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/run_av.pro)
NAME:
SCALEFOSS2BPCH
PURPOSE:
Converts fossil fuel scale factor files from the obsolete
binary format to binary punch format (so that they can be
read by GAMAP).
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
SCALEFOSS2BPCH, [ Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the input file containing fossil
fuel scale factors. If omitted, SCALEFOSS2BPCH
will prompt the user for a filename via a dialog box.
OUTFILENAME -> Name of the binary punch file containing
fossil fuel scale factors. Default is to add a
".bpch" extension to INFILENAME.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required
==================================================
CTM_TYPE (function) CTM_GRID (function)
NYMD2TAU (function) CTM_MAKE_DATAINFO (function)
CTM_WRITEBPCH EXTRACT_FILENAME (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
SCALEFOSS2BPCH, INFILENAME='scalefoss.liq.2x25.1998', $
OUTFILENAME='scalefoss.liq.2x25.1998.bpch'
; Converts scalefoss files to BPCH format.
MODIFICATION HISTORY:
bmy, 15 Jan 2003: VERSION 1.00
bmy, 23 Dec 2003: VERSION 1.01
- rewritten for GAMAP v2-01
bmy, 27 Jun 2006: VERSION 1.02
- Use more robust algorithm for getting
the year out of the file name
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/scalefoss2bpch.pro)
NAME:
SCHMIDT
PURPOSE:
Computes the SCHMIDT number for a given species.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = SCHMIDT( TEMPERATURE, XMV, SEAWATER )
INPUTS:
TEMPERATURE -> Temperature in Kelvin.
XMV -> Molar volume of species
SEAWATER -> set =1 if it is seawater, set =0 otherwise
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The Schmidt number
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, SCHMIDT( 278, 0.75, 1 )
165.55126
; Compute Schmidt # for seawater
MODIFICATION HISTORY:
pip & bmy, 27 Jun 2003: VERSION 1.00
- Written by Paul Palmer
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/schmidt.pro)
NAME:
SCREEN2BMP
PURPOSE:
Captures an image from the X-window or Z-buffer device and
saves the image to a BMP file. Handles 8-bit and TRUE
COLOR displays correctly.
CATEGORY:
Graphics
CALLING SEQUENCE:
SCREEN2BMP, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> Name of the BMP file that will be created.
FILENAME may be omitted if you wish to only return
the image (via the THISFRAME keyword).
KEYWORD PARAMETERS:
THISFRAME -> If FILENAME is not specified, then the byte
image returned from the screen capture will be passed
back to the calling program via THISFRAME.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
TVREAD (function)
REQUIREMENTS:
None
NOTES:
(1) Should work for Unix/Linux, Macintosh, and Windows.
(2) SCREEN2TIFF is just a convenience wrapper for TVREAD.
EXAMPLES:
PLOT, X, Y
SCREEN2TIFF, 'myplot.bmp'
; Creates a simple plot and writes it to a TIFF file
; via capture from the screen (X-window device).
PLOT, X, Y
SCREEN2TIFF, THISFRAME=THISFRAME
; Creates a simple plot and saves the screen
; capture image to the byte array THISFRAME.
OPEN_DEVICE, /Z
PLOT, X, Y
SCREEN2TIFF, 'myplot.bmp'
CLOSE_DEVICE
; Creates a simple plot and writes it to a TIFF file
; via capture from the Z-buffer device.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- adapted from SCREEN2GIF
phs, 3 Feb 2009: GAMAP VERSION 2.13
- Use the NoDialog keyword in call to
TVREAD
(See /n/home09/ryantosca/IDL/gamap2/graphics/screen2bmp.pro)
NAME:
SCREEN2GIF
PURPOSE:
Captures an image from the X-window or Z-buffer device and
saves the image to a GIF file. Handles 8-bit and TRUE
COLOR displays correctly.
CATEGORY:
Graphics
CALLING SEQUENCE:
SCREEN2GIF, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> Name of the GIF file that will be created.
FILENAME may be omitted if you wish to only return
the image (via the THISFRAME keyword).
KEYWORD PARAMETERS:
THISFRAME -> Returns to the calling program the
byte image captured from the screen.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
TVREAD (function)
REQUIREMENTS:
Requires routines from the TOOLS package.
NOTES:
(1) Should work for Unix/Linux, Macintosh, and Windows.
(2) SCREEN2GIF is now a wrapper for TVREAD. David Fanning's
TVREAD function does the screen capture better than
the algorithm in the old SCREEN2GIF.
EXAMPLES:
PLOT, X, Y
SCREEN2GIF, 'myplot.gif'
; Creates a simple plot and writes it to a GIF file
; via capture from the screen (X-window device).
PLOT, X, Y
SCREEN2GIF, THISFRAME=THISFRAME
; Creates a simple plot and saves the screen
; capture image to the byte array THISFRAME.
OPEN_DEVICE, /Z
PLOT, X, Y
SCREEN2GIF, 'myplot.gif'
CLOSE_DEVICE
; Creates a simple plot and writes it to a GIF file
; via capture from the Z-buffer device.
MODIFICATION HISTORY:
bmy, 24 Jul 2001: TOOLS VERSION 1.49
bmy, 02 Dec 2002: TOOLS VERSION 1.52
- now uses TVREAD function from D. Fanning
which works on both PC's & Unix terminals
bmy, 30 Apr 2003: TOOLS VERSION 1.53
- Bug fix in passing file name to TVREAD
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now pass _EXTRA=e to TVREAD
- now call TVREAD correctly if we omit FILENAME
- updated comments
phs, 3 Feb 2009: GAMAP VERSION 2.13
- Use the NoDialog keyword in call to
TVREAD
(See /n/home09/ryantosca/IDL/gamap2/graphics/screen2gif.pro)
NAME:
SCREEN2JPG
PURPOSE:
Captures an image from the X-window or Z-buffer device and
saves the image to a JPEG file. Handles 8-bit and TRUE
COLOR displays correctly.
CATEGORY:
Graphics
CALLING SEQUENCE:
SCREEN2JPG, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> Name of the JPEG file that will be created.
FILENAME may be omitted if you wish to only return
the image (via the THISFRAME keyword).
KEYWORD PARAMETERS:
THISFRAME -> If FILENAME is not specified, then the byte
image returned from the screen capture will be passed
back to the calling program via THISFRAME.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
TVREAD (function)
REQUIREMENTS:
Requires routines from the TOOLS package.
NOTES:
(1) Should work for Unix/Linux, Macintosh, and Windows.
(2) SCREEN2JPG is just a convenience wrapper for TVREAD.
EXAMPLES:
PLOT, X, Y
SCREEN2JPG, 'myplot.jpg'
; Creates a simple plot and writes it to a JPG file
; via capture from the screen (X-window device).
PLOT, X, Y
SCREEN2JPG, THISFRAME=THISFRAME
; Creates a simple plot and saves the screen
; capture image to the byte array THISFRAME.
OPEN_DEVICE, /Z
PLOT, X, Y
SCREEN2JPG, 'myplot.jpg'
CLOSE_DEVICE
; Creates a simple plot and writes it to a JPG file
; via capture from the Z-buffer device.
MODIFICATION HISTORY:
bmy, 25 Sep 2003: TOOLS VERSION 1.53
- Bug fix in passing file name to TVREAD
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now pass _EXTRA=e to TVREAD
- updated comments
phs, 3 Feb 2009: GAMAP VERSION 2.13
- Use the NoDialog keyword in call to
TVREAD
(See /n/home09/ryantosca/IDL/gamap2/graphics/screen2jpg.pro)
NAME:
SCREEN2PNG
PURPOSE:
Captures an image from the X-window or Z-buffer device and
saves the image to a PNG file. Handles 8-bit and TRUE
COLOR displays correctly.
CATEGORY:
Graphics
CALLING SEQUENCE:
SCREEN2PNG, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> Name of the PNG file that will be created.
FILENAME may be omitted if you wish to only return
the image (via the THISFRAME keyword).
KEYWORD PARAMETERS:
THISFRAME -> Returns to the calling program the
byte image captured from the screen.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
TVREAD (function)
REQUIREMENTS:
None
NOTES:
(1) Should work for Unix/Linux, Macintosh, and Windows.
(2) SCREEN2PNG is just a convenience wrapper for TVREAD.
EXAMPLES:
PLOT, X, Y
SCREEN2PNG, 'myplot.png'
; Creates a simple plot and writes it to a PNG file
; via capture from the screen (X-window device).
PLOT, X, Y
SCREEN2PNG, THISFRAME=THISFRAME
; Creates a simple plot and saves the screen
; capture image to the byte array THISFRAME.
OPEN_DEVICE, /Z
PLOT, X, Y
SCREEN2PNG, 'myplot.png'
CLOSE_DEVICE
; Creates a simple plot and writes it to a PNG file
; via capture from the Z-buffer device.
MODIFICATION HISTORY:
bmy, 25 Sep 2003: TOOLS VERSION 1.53
- Bug fix in passing file name to TVREAD
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now pass _EXTRA=e to TVREAD
- updated comments
phs, 3 Feb 2009: GAMAP VERSION 2.13
- Use the NoDialog keyword in call to
TVREAD
(See /n/home09/ryantosca/IDL/gamap2/graphics/screen2png.pro)
NAME:
SCREEN2TIFF
PURPOSE:
Captures an image from the X-window or Z-buffer device and
saves the image to a TIFF file. Handles 8-bit and TRUE
COLOR displays correctly.
CATEGORY:
Graphics
CALLING SEQUENCE:
SCREEN2TIFF, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> Name of the TIFF file that will be created.
FILENAME may be omitted if you wish to only return
the image (via the THISFRAME keyword).
KEYWORD PARAMETERS:
THISFRAME -> If FILENAME is not specified, then the byte
image returned from the screen capture will be passed
back to the calling program via THISFRAME.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
TVREAD (function)
REQUIREMENTS:
None
NOTES:
(1) Should work for Unix/Linux, Macintosh, and Windows.
(2) SCREEN2TIFF is just a convenience wrapper for TVREAD.
EXAMPLES:
PLOT, X, Y
SCREEN2TIFF, 'myplot.tif'
; Creates a simple plot and writes it to a TIFF file
; via capture from the screen (X-window device).
PLOT, X, Y
SCREEN2TIFF, THISFRAME=THISFRAME
; Creates a simple plot and saves the screen
; capture image to the byte array THISFRAME.
OPEN_DEVICE, /Z
PLOT, X, Y
SCREEN2TIFF, 'myplot.tif'
CLOSE_DEVICE
; Creates a simple plot and writes it to a TIFF file
; via capture from the Z-buffer device.
MODIFICATION HISTORY:
bmy, 25 Sep 2003: TOOLS VERSION 1.53
- Bug fix in passing file name to TVREAD
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now pass _EXTRA=e to TVREAD
- updated comments
phs, 3 Feb 2009: GAMAP VERSION 2.13
- Use the NoDialog keyword in call to
TVREAD
(See /n/home09/ryantosca/IDL/gamap2/graphics/screen2tiff.pro)
NAME:
SEARCH (function)
PURPOSE:
Perform a binary search for the data point closest
to a given value. Data must be sorted.
CATEGORY:
Math & Units
CALLING SEQUENCE:
INDEX = SEARCH( DATA, VALUE )
INPUTS:
DATA -> a sorted data vector
VALUE -> the value to look for
KEYWORD PARAMETERS:
None
OUTPUTS:
INDEX -> The function returns the index of the
nearest data point.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
This routine is much faster than WHERE or MIN for
large arrays. It was written in response to a newsgroup
request by K.P. Bowman.
EXAMPLE:
TEST = FINDGEN(10000)
PRINT, SEARCH( TEST, 532.3 )
; prints 532
MODIFICATION HISTORY:
mgs, 21 Sep 1998: VERSION 1.00
bmy, 24 May 2007: TOOLS VERSION 2.06
- updated comments, cosmetic changes
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/search.pro)
NAME:
SELECT_MODEL
PURPOSE:
Primitive function to select a model.
Calls CTM_TYPE and returns the MODELINFO structure.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
MODELINFO = SELECT_MODEL( [ Keywords ] )
INPUTS:
None
KEYWORD PARAMETERS:
DEFAULT -> String containing the default model name,
resolution, and number of levels.
OUTPUTS:
Returns the MODELINFO structure (from CTM_TYPE)
as the value of the function.
SUBROUTINES:
External subroutines required:
------------------------------
CTM_TYPE (function)
REQUIREMENTS:
References routines from GAMAP and TOOLS packages.
NOTES:
Add new model selections as is necessary. Also be sure to
update routines "ctm_type", "ctm_grid", and "getsigma".
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% NOTE: THIS ROUTINE IS MOSTLY OBSOLETE NOW BECAUSE %%%
%%% MOST DATA FILES NOW CONTAIN THE MODEL NAME AND %%%
%%% RESOLUTION INFORMATION. %%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
EXAMPLE:
MODELINFO = SELECT_MODEL( DEFAULT='GISS_II_PRIME 4x5 (23L)' )
; Will return the modelinfo structure for the 23-layer
; GISS-II-PRIME model. We need to specify the number
; of layers here since there is also a 9-layer version
; of the GISS-II-PRIME model.
MODIFICATION HISTORY:
mgs, 13 Aug 1998: VERSION 1.00
mgs, 21 Dec 1998: - added GEOS_STRAT 2x2.5
mgs, 25 Mar 1999: - changed FSU to 4x5 and added 'generic'
bmy, 27 Jul 1999: GAMAP VERSION 1.42
- now add the number of layers to the menu choices
- added GISS-II-PRIME 23-layer model as a choice
- more sophisticated testing for default model
- a few cosmetic changes
bmy, 03 Jan 2000: GAMAP VERSION 1.44
- added GEOS-2 as a model selection
- added standard comment header
bmy, 16 May 2000: GAMAP VERSION 1.45
- now use GEOS-2 47-layer grid
bmy, 28 Jul 2000: GAMAP VERSION 1.46
- added GEOS-3 48-layer grids for 1 x 1,
2 x 2.5, and 4 x 5 horizontal resolution
bmy, 26 Jul 2001: GAMAP VERSION 1.48
- added GEOS-3 30-layer grids for 2 x 2.5
and 4 x 5 horizontal resolution
bmy, 24 Aug 2001: - deleted GEOS-3 30-layer grids, since
we won't be using these soon
bmy, 06 Nov 2001: GAMAP VERSION 1.49
- added GEOS-4/fvDAS grids at 1 x 1.25,
2 x 2.5, and 4 x 5 resolution
clh & bmy, 18 Oct 2002: GAMAP VERSION 1.52
- added MOPITT 7L grid
bmy, 11 Dec 2002 - deleted GEOS-2 47L grid, nobody uses this
bmy, 18 May 2007: GAMAP VERSION 2.06
- added GEOS-4 30L grid
- added GEOS-5 47L and 72L grids
- added quit option
bmy, 11 May 2012: GAMAP VERSION 2.16
- Added MERRA, GEOS-5.7 options
(See /n/home09/ryantosca/IDL/gamap2/internals/select_model.pro)
NAME:
SIGN
PURPOSE:
Return the mathematical sign of the argument.
CATEGORY:
Math & Units
CALLING SEQUENCE:
s = sign(x)
INPUTS:
x = value of array of values.
KEYWORD PARAMETERS:
OUTPUTS:
s = sign of value(s).
COMMON BLOCKS:
None
NOTES:
Note:
s = -1 for x < 0
s = 0 for x = 0
s = 1 for x > 0
MODIFICATION HISTORY:
R. Sterner, 7 May, 1986.
Johns Hopkins University Applied Physics Laboratory.
RES 15 Sep, 1989 --- converted to SUN.
RES 23 Sep, 1991 --- rewrote, reducing 11 lines of code to 1.
(See /n/home09/ryantosca/IDL/gamap2/math_units/sign.pro)
NAME:
SORT_STRU
PURPOSE:
Returns an sort index array a structure data field.
CATEGORY:
Structures
CALLING SEQUENCE:
INDEX = SORT_STRU( STRU, SORT_TAG )
INPUTS:
STRU -> The structure containing the data to be sorted.
SORT_TAG -> A string containing the name of the structure
tag for which to compute the sort index array.
KEYWORD PARAMETERS:
/REVERSE_SORT -> Set this switch to return an sort
index array in reverse order.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
STRU = { DATA : [5,3,2,1,4] }
IND = SORT_STRU( STRU, 'DATA' )
PRINT, STRU.DATA[IND]
1 2 3 4 5
; Returns an sort index array for the DATA
; tag of the structure STRU. STRU.DATA[IND]
; will be in ascending order.
(2)
STRU = { DATA : [5,3,2,1,4] }
IND = SORT_STRU( STRU, 'DATA', /REVERSE_SORT );
PRINT, STRU.DATA[IND]
5 4 3 2 1
; Returns an sort index array for the DATA
; tag of the structure STRU. STRU.DATA[IND]
; will be in descending order.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/structures/sort_stru.pro)
NAME:
STR2BYTE (function)
PURPOSE:
Convert a string into a byte vector of a given length
for output in binary data files.
CATEGORY:
Strings
CALLING SEQUENCE:
BSTR = STR2BYTE( STRING [, LENGTH ] )
INPUTS:
STRING -> The string to be converted
LENGTH -> Length of the byte vector. Default is to use the
length of the string. If LENGTH is shorter, the string
will be truncated, if it is longer, it will be filled
with blanks (32B).
KEYWORD PARAMETERS:
None
OUTPUTS:
BSTR -> A byte vector of the specified length
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
OPENW, LUN, 'TEST.DAT', /F77_UNFORMATTED, /GET_LUN
WRITEU, LUN, STR2BYTE( 'Test string', 80 )
FREE_LUN, LUN
; write a 80 character string into a binary file
MODIFICATION HISTORY:
mgs, 24 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/strings/str2byte.pro)
NAME:
STRAT
PURPOSE:
Creates zonal-mean curtain plots of GEOS-Chem tracers between
100hPa and 0.01 hPa from the GEOS-Chem 1-month benchmark simulations.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
STRAT, FILE, LONS, TAUS, TRACERS, VERSION, [, Keywords ]
INPUTS:
FILE -> The name of the file containing data to be plotted.
LONS -> Longitudes to plot
TAU -> The TAU value (hours GMT from /1/1985) corresponding
to the data to be plotted.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSION -> The model version number corresponding to the
data to be plotted.
KEYWORD PARAMETERS:
/DO_FULLCHEM -> Set this switch to plot the chemically
produced OH in addition to the advected tracers.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Provided:
==================================================
PlotStrat
External Subroutines Required:
==================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA EXTRACT_FILENAME (function)
GETMODELANDGRIDINFO MULTIPANEL
MYCT OPEN_DEVICE
TVMAP CHKSTRU (function)
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILE = 'ctm.bpch.v7-04-11'
LEVELS = [ 1, 1, 13, 13 ]
TAUS = NYMD2TAU( 20010701 )
TRACERS = INDGEN( 43 ) + 1
VERSIONS = 'v7-04-11'
STRAT, FILE, LONS, TAU, TRACERS, VERSION, $
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'
MODIFICATION HISTORY:
mps, 11 Sep 2015: - Initial version, based on zonal.pro
(See /n/home09/ryantosca/IDL/gamap2/benchmark/strat.pro)
NAME:
STRAT_DIFF
PURPOSE:
Creates zonal mean absolute and percent difference plots
of tracers between 100hPa and 0.01 hPa from the GEOS-Chem
1-month benchmark simulations.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
STRAT_DIFF, FILES, TAUS, TRACERS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DO_FULLCHEM -> Set this switch to plot the chemically
produced OH in addition to the advected tracers.
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range to predetermined values as returned
by routine GET_DIFF_RANGE.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
ZDFORMAT -> This keyword passes a colorbar format string
(Fortran-style) to the COLORBAR routine (via TVPLOT).
This keyword is purposely not named CBFORMAT, in order
to avoid passing this quantity to other routines.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
==================================================
PlotStratAbsDiff PlotStratPctDiff
External Subroutines Required:
==================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA GET_DIFF_RANGE (function)
GETMODELANDGRIDINFO EXTRACT_FILENAME (function)
MULTIPANEL CHKSTRU (function)
MYCT OPEN_DEVICE
TVPLOT UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLE:
FILES = [ 'ctm.bpch.v9-01-01', 'ctm.bpch.v9-01-02a' ]
TAUS = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
TRACERS = INDGEN( 43 ) + 1
VERSIONS = [ 'v9-01-01', 'v9-01-02a' ]
STRAT_DIFF, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, $
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'
; Creates zonal mean difference plots of two GEOS-Chem
; versions; (in this case v9-01-01 / v9-01-01a) for
; July 2001. Output is sent to the PostScript file
; "myplot.ps". The min and max of the data on each plot
; panel is restricted to pre-defined values returned by
; function GET_DIFF_RANGE.
STRAT_DIFF, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, $
/DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Same as the above example, but the min & max of
; each plot panel corresponds to the dynamic range
; of the data (centered around zero).
MODIFICATION HISTORY:
mps, 11 Sep 2015: - Initial version, based on zonal_diff.pro
mps, 04 Jan 2016: - Include MERRA2 in the check for equivalent
vertical grids
(See /n/home09/ryantosca/IDL/gamap2/benchmark/strat_diff.pro)
NAME:
STRBREAK
PURPOSE:
Wrapper for routines STRSPLIT and STR_SEP.
Needed for backwards compatibility for GAMAP users
who are running versions of IDL prior to 5.2.
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = STRBREAK( STR, SEPARATOR, _EXTRA=e )
INPUTS:
STR -> The string to be separated.
SEPARATOR -> The separating character.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT = Array of sub-strings, separated by the character
passed as SEPARATOR
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
(1)
Str = 'Hello , My , Name , is , Slim , Shady '
NewStr = StrBreak( Str, ',' )
; Separates the string using the comma as the separator.
MODIFICATION HISTORY:
bmy, 17 Jan 2002: TOOLS VERSION 1.50
bmy, 17 Jan 2003: TOOLS VERSION 1.52
- now use CALL_FUNCTION to call both STRSPLIT
and STR_SEP functions for backwards compatibility
bmy, 14 Oct 2003: TOOLS VERSION 1.53
- deleted obsolete code
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/strbreak.pro)
NAME:
STRCHEM (function)
PURPOSE:
Superscripts or subscripts numbers and special
characters ('x', 'y') found in strings containing
names of chemical species.
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = STRCHEM( STR [,keywords] )
INPUTS:
STR -> The input string containing the name of the
chemical species (e.g. 'NOx', 'H2O', CxO2, etc, )
KEYWORD PARAMETERS:
/SUB -> Will cause numbers and special characters to
be subscripted. This is the default.
/SUPER -> Will cause numbers and special characters to
be superscripted.
SPECIALCHARS -> a string with characters that shall be sub-
or superscripted. Defaults are '0123456789xyXY' for
/SUB and '+-0123456789' for /SUPER
PROTECT -> internal keyword used to protect certain characters
from being super or subscripted. May be useful to
circumvent troubles. See example below.
/TRIM -> perform a strtrim( ,2) on the result
OUTPUTS:
RESULT -> String with formatting characters included
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
(1)
PRINT, STRCHEM( 'C2H5O2 [pptv]' )
C!l2!nH!l5!nO!l2!n [pptv]"
(2)
PRINT, STRCHEM( STRCHEM('NH4+',/sub), /SUPER, SPECIAL='+-' )
NH!l4!n!u+!n.
(3)
S0 = '(H2O2)2' ; supposed to be H2O2 squared
PROTECT = STRLEN( s0 )-1 ; protect last character
S1 = STRCHEM(S0,PROTECT=PROTECT)
S2 = STRCHEM(S1,/SUPER,PROTECT=PROTECT)
PRINT, S1, '->', S2
(H!l2!nO!l2!n)2->(H!l2!nO!l2!n)!u2!n
; without protect the "square" would have been subscripted
MODIFICATION HISTORY:
bmy, 01 Jun 1998: VERSION 1.00
mgs, 02 Jun 1998: VERSION 1.10 - rewritten
mgs, 11 Jun 1998: - removed IS_ION keyword
- changed default specialchars for SUPER
mgs, 22 Sep 1998: - added TRIM keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/strings/strchem.pro)
NAME:
STRDATE (function)
PURPOSE:
Format a "standard form" date string
CATEGORY:
Date & Time, Strings
CALLING SEQUENCE:
RESULT = STRDATE( [ DATE ] [, Keywords ] )
INPUTS:
DATE -> (OPTIONAL) Either a up to 6 element array containing
year, month, day, hour, minute, and secs (i.e. the format
returned from BIN_DATE) or a structure containing year,
month, day, hour, minute, seconds (as returned from
TAU2YYMMDD) or a date string in "standard" format as
returned by SYSTIME(0). If DATE is omitted, STRDATE will
automatically return the current system time.
KEYWORD PARAMETERS:
/SHORT -> omit the time value, return only date
/SORTABLE -> will return 'YYYY/MM/DD HH:MM'
/EUROPEAN -> will return 'DD.MM.YYYY HH:MM'
IS_STRING -> Indicates that DATE is a date string
rather than an integer array. This keyword is now
obsolete but kept for compatibility.
OUTPUTS:
RESULT -> A date string formatted as 'MM/DD/YYYY HH:MM'.
If SHORT flag is set, the format will be 'MM/DD/YYYY'
SUBROUTINES:
External Subroutines Required:
==============================
DATATYPE (function)
REQUIREMENTS:
None
NOTES:
(1) /EUROPEAN and /SORTABLE will have effect of
/SORTABLE but with dots as date Seperators.
EXAMPLES:
(1)
PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ] )
01/01/2001 12:30
; Date string for 2001/01/01 12:30 in USA format
(2)
PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ], /EUROPEAN )
01.01.2001 12:30
; Date string for 2001/01/01 12:30 in European format
(3)
PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ], /SORTABLE )
2001/01/01 12:30
; Date string for 2001/01/01 12:30 in YYYY/MM/DD format
(4)
PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ], /SORTABLE, /SHORT )
2001/01/01
; Date string for 2001/01/01 w/o hours and minutes
(5)
RESULT = TAU2YYMMDD( 144600D )
PRINT, STRDATE( RESULT, /SORTABLE )
2001/07/01 00:00
; Use TAU2YYMMDD to convert a TAU value (in this case
; for July 1, 2001) to a structure. Then pass the
; structure to STRDATE to make a string.
MODIFICATION HISTORY:
mgs, 11 Nov 1997: VERSION 1.00
mgs, 26 Mar 1998: VERSION 1.10
- examines type of DATE parameter
and accepts structure input.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Renamed /GERMAN to /EUROPEAN
- Updated comments, cosmetic changes
- Now uses function DATATYPE
(See /n/home09/ryantosca/IDL/gamap2/date_time/strdate.pro)
NAME:
STRPAD
PURPOSE:
This function returns the source string padded with leading
and/or trailing white-space characters.
CATEGORY:
Strings
CALLING SEQUENCE:
Result = STRPAD( Source, Length [, Pos] )
INPUTS:
Source: A string or number you want padded with white-space
characters.
Length: The total length of the returned padded string.
OPTIONAL INPUTS:
Pos: Position of the Source string within the returned
padded string. [0=Default]
OUTPUTS:
The source parameter is returned as a string with leading
and/or trailing white-space characters.
RESTRICTIONS:
The Length and Pos parameters must be in the range [0-255].
EXAMPLE:
Let's say you want 'bob' to have a length of 10 characters
with spaces padded after 'bob':
bob10 = STRPAD( 'bob', 10 )
Or if you want 'bob' to be at the end:
bobend= STRPAD( 'bob', 10, 7 )
MODIFICATION HISTORY:
Written by: Han Wen, December 1994.
(See /n/home09/ryantosca/IDL/gamap2/strings/strpad.pro)
NAME:
STRREPL (function)
PURPOSE:
Replace all occurences of one character in a string with
another character. The character to be replaced can either
be given as string of length 1 or as an index array
containing the character positions (see strwhere). This
function also works for string arrays.
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = STRREPL( STR, FROMCHAR, TOCHAR [,/IGNORECASE] )
INPUTS:
STR -> the string to be changed
FROMCHAR -> either: a string of length 1 (the character
to be replaced) or: an index array with the character
positions
TOCHAR -> replacement character
KEYWORD PARAMETERS:
IGNORECASE -> if set, fromchar will be treated
case-insensitive (only if fromchar is a character)
FOLD_CASE -> same thing but following IDL naming
(e.g. StrMatch)
OUTPUTS:
RESULT -> A string of same length as the input string
with the text replaced
SUBROUTINES:
REQUIREMENTS:
NOTES:
Uses SIZE(/TYPE) available since IDL 5.2
EXAMPLES:
(1)
UFILE = '/usr/local/idl/lib/test.pro'
WFILE = 'c:' + strrepl(ufile,'/','\')
PRINT, WFILE
; c:\usr\local\idl\lib\test.pro
; Convert a Unix filename to Windows
(2)
A = 'abcdabcdabcd'
INDEX = [ strwhere(a,'a'), strwhere(a,'b') ] > 0
PRINT, STRREPL( a, index, '#' )
##cd##cd##cd
; Use with index (uses strwhere function)
MODIFICATION HISTORY:
mgs, 02 Jun 1998: VERSION 1.00
mgs, 24 Feb 2000: - rewritten
- now accepts character argument
- added IGNORECASE keyword
mgs, 26 Aug 2000: - changed copyright to open source
- added FOLD_CASE keyword
bmy, 28 Oct 2003: VERSION 1.01
- Need to test if FROMCHAR is a character
or a byte type. This will allow STRREPL
to replace non-printable ASCII characters
such as Horizontal TAB ( BYTE(9B) ).
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/strings/strrepl.pro)
NAME:
STRRIGHT
PURPOSE:
Return right subportion from a string
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = STRRIGHT( STRING [,nlast] )
INPUTS:
STRING -> the string to be searched
NLAST -> the number of characters to be returned.
Default is 1. If NLAST is ge strlen(STRING),
the complete string is returned.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> The portion of NLAST characters of STRING
counted from the back.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
IF ( STRRIGHT( PATH ) NE '/' ) THEN PATH = PATH + '/'
; Add a slash to a directory name if necessary
MODIFICATION HISTORY:
mgs, 19 Nov 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/strings/strright.pro)
NAME:
STRSCI (function)
PURPOSE:
Given a number, returns a string of that number in
scientific notation format ( e.g. A x 10 )
CATEGORY:
Strings
CALLING SEQUENCE:
RESULT = STRSCI( DATA [, Keywords ] )
INPUTS:
DATA -> A floating point or integer number to be
converted into a power of 10.
KEYWORD PARAMETERS:
FORMAT -> The format specification used in the string
conversion for the mantissa (i.e. the "A" of
"A x 10^B"). Default is '(f12.2)'.
/POT_ONLY -> Will return only the "power of 10" part of
the string (i.e. the "10^B"). Default is to return
the entire string (e.g. "A x 10^B" )
/MANTISSA_ONLY -> return only mantissa of the string
/SHORT -> return 10^0 as '1' and 10^1 as '10'
/TRIM -> don't insert blanks (i.e. return Ax10^B)
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
This function does not "evaluate" the format statement thoroughly
which can result in somewhat quirky strings. Example:
print,strsci(-9.999) results in -10.0x10^0 instead of -1.0x10^1.
Need a better symbol than the 'x' for the multiplier...
EXAMPLE:
Result = STRSCI( 2000000, format='(i1)' )
print, result
; 6
; prints 2 x 10!u6!n, which gets plotted as 2 x 10
Result = STRSCI( -0.0001 )
print, result
; 4
; prints -1.00 x 10!u-4!n, which gets plotted as 1.00 x 10
Result = STRSCI( 0d0, format='(f13.8)' )
print, result
;
; prints, 0.00000000
MODIFICATION HISTORY:
bmy, 28 May 1998: INITIAL VERSION
- now returns string of the form A x 10
mgs, 29 May 1998: - bug fix: now allows negative numbers
- keyword MANTISSA_ONLY added
- default format changed to f12.2
bmy, 02 Jun 1998: - renamed to STRSCI
("STRing SCIentific notation")
mgs, 03 Jun 1998: - added TRIM keyword
mgs, 22 Sep 1998: - added SHORT keyword
- modified handling of TRIM keyword
mgs, 24 Sep 1998: - bug fix with SHORT flag
bmy & mgs, 02 Jun 1999: - now can handle DATA=0.0 correctly
- updated comments
mgs, 03 Jun 1999: - can now also handle values lt 1 ;-)
- and doesn't choke on arrays
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- updated comments
(See /n/home09/ryantosca/IDL/gamap2/strings/strsci.pro)
NAME:
STRSIZE
PURPOSE:
Given a string argument and the character size, returns the
# of characters that can fit w/in the horizontal or vertical
extent of a plot window.
CATEGORY:
Plotting, Strings
CALLING SEQUENCE:
RESULT = STRSIZE( STRARG, CHARSIZE [, Keywords ] )
INPUTS:
STRARG -> A string of characters.
CHARSIZE -> The size of each character. 1.0 is normal
size, 2.0 is double size, etc.
KEYWORD PARAMETERS:
/Y -> Set this switch to compute the number of characters
that can fit along the vertical extent of the plot.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
OPEN_DEVICE, WINPARAM=[ 0, 800, 600 ]
PRINT, STRSIZE( 'Hello', 3 )
80.0000
; Computes the # of characters of size 3
; that can fit in the plot window
MODIFICATION HISTORY:
bmy, 10 Oct 2006: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/plotting/strsize.pro)
NAME:
STRUADDVAR (function)
PURPOSE:
Add additional variables (tags) to an exisiting
structure. The new variables will be inserted after
the old ones, '__' tags will be appended at the end.
The function renames new tags if they would cause
duplicate names by adding a '_A'.
CATEGORY:
Structures
CALLING SEQUENCE:
NEWSTRU = STRUADDVAR( OLDSTRU, NEWVAR [, NEWNAME, Keywords ] )
INPUTS:
OLDSTRU -> the exisiting structure. This must be a structure,
otherwise the program will complain and exit.
NEWVAR -> A new variable (any type) or a new structure
that shall be incorporated into OLDSTRU. If NEWVAR
is *not* a structure, then NEWNAME must be present.
If you want to add an array with several named columns,
use Arr2Stru first.
NEWNAME -> The name of the new variable. Only used if
NEWVAR is no structure.
KEYWORD PARAMETERS:
/WARNNELEMENTS -> If this flag is set, the program will print out
a warning if the number of elements in the new variable does
not match the number of elements in the last variable of the
old structure.
OUTPUTS:
NEWSTRU -> A structure that combines the information from
OLDSTRU and NEWVAR.
SUBROUTINES:
External Subroutines Required:
==============================
CHKSTRU (function)
REQUIREMENTS:
None
NOTES:
(1) NEWNAME (or the tag names from NEWVAR) will be added to
the __NAMES__ tag if present. __EXTRA__ entries will be
combined only if tags within __EXTRA__ structures are
different. If __EXTRA__ contains a non-structure
variable it will be converted to a structure with tag
name 'EXTRA_N' where N is a number from 1-9, A-Z (the
first tag is just 'EXTRA').
EXAMPLES:
(1)
NSTRU = STRUADDVAR( STRU, FINDGEN(100), 'DUMMY' )
; Adds a 100 element floating-point array
; to structure STRU under the tag name "DUMMY"
; and returns the result as NSTRU.
(2)
X = { A :0L, B:STRARR(10), $
C : FINDGEN(100), __EXTRA__:'TEST' }
OSTRU = STRUADDVAR( NSTRU, X )
; Adds the structure X (with tag names A, B, C, and
; __EXTRA__) to the structure NSTRU and returns
; the result as OSTRU.
MODIFICATION HISTORY:
mgs, 03 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/structures/struaddvar.pro)
NAME:
STRUINFO (function)
PURPOSE:
Return information about structures. This routine is designed
to help handling variable structures of mixed type.
CATEGORY:
Structures
CALLING SEQUENCE:
INFO = STRUINFO( STRU, [, Keywords ] )
INPUTS:
STRU -> a structure
KEYWORD PARAMETERS:
NAMES -> return variable names as spelled in structure tags
ORIGINAL_NAMES -> return variable names as stored in
__NAMES__ tag
EXTRA -> return information stored in __EXTRA__ tag. This
information is always returned as a structure
NVARS -> return number of variables, i.e. tags that do
not begin with '__'
HOMOGENEOUS -> return tag indices of tags with identical '
number of elements (only those can be combined to an
array with Stru2Arr). This keyword honors the RefIndex
keyword.
NUMERIC -> return tag indices of numeric structure tags
TYPE -> return variable type of structure tags. For
non-variable tags (whose name begin with '__') a -1
is returned
REFINDEX -> indicates the tag index to compare the number
of elements to (default is the first variable index).
OUTPUTS:
The desired information (hopefully)
SUBROUTINES:
External Subroutines Required:
================================
CHKSTRU (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, STRUINFO( !p, /names )
BACKGROUND CHARSIZE CHARTHICK CLIP COLOR FONT LINESTYLE
MULTI NOCLIP NOERASE NSUM POSITION PSYM REGION SUBTITLE
SYMSIZE T T3D THICK TITLE TICKLEN CHANNEL
; Print the names from the !P system variable structure
MODIFICATION HISTORY:
mgs, 03 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/structures/struinfo.pro)
NAME:
STRWHERE (function)
PURPOSE:
return position *array* for occurence of a character in
a string
CATEGORY:
Strings
CALLING SEQUENCE:
POS = STRWHERE( STR, SCHAR [,COUNT] )
INPUTS:
STR -> the string
SCHAR -> the character to look for
KEYWORD PARAMETERS:
none.
OUTPUTS:
COUNT -> (optional) The number of matches that were found
POS -> The function returns an index array similar to the
result of the where function
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
IND = STRWHERE( 'abcabcabc', 'a' )
; returns [ 0, 3, 6 ]
MODIFICATION HISTORY:
mgs, 02 Jun 1998: VERSION 1.00
bmy, 30 Jun 1998: - now returns COUNT, the number
of matches that are found (this is
analogous to the WHERE command)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/strings/strwhere.pro)
NAME:
STR_SIZE
PURPOSE:
The purpose of this function is to return the proper
character size to make a specified string a specifed
width in a window. The width is specified in normalized
coordinates. The function is extremely useful for sizing
strings and labels in resizeable graphics windows.
CATEGORY:
Strings, Graphics
CALLING SEQUENCE:
thisCharSize = STR_SIZE(thisSting, targetWidth)
INPUTS:
thisString: This is the string that you want to make a specifed
target size or width.
OPTIONAL INPUTS:
targetWidth: This is the target width of the string in normalized
coordinates in the current graphics window. The character
size of the string (returned as thisCharSize) will be
calculated to get the string width as close as possible to
the target width. The default is 0.25.
KEYWORD PARAMETERS:
INITSIZE: This is the initial size of the string. Default is 1.0.
STEP: This is the amount the string size will change in each step
of the interative process of calculating the string size.
The default value is 0.05.
OUTPUTS:
thisCharSize: This is the size the specified string should be set
to if you want to produce output of the specified target
width. The value is in standard character size units where
1.0 is the standard character size.
EXAMPLE:
To make the string "Happy Holidays" take up 30% of the width of
the current graphics window, type this:
XYOUTS, 0.5, 0.5, ALIGN=0.5, "Happy Holidays", $
CHARSIZE=STR_SIZE("Happy Holidays", 0.3)
MODIFICATION HISTORY:
Written by: David Fanning, 17 DEC 96.
Added a scaling factor to take into account the aspect ratio
of the window in determing the character size. 28 Oct 97. DWF
(See /n/home09/ryantosca/IDL/gamap2/strings/str_size.pro)
NAME:
SYM
PURPOSE:
Define a standard sequence of plotting symbols that can
be used in conjunction with the PLOT command.
CATEGORY:
Plotting
CALLING SEQUENCE:
RESULT = SYM( NUMBER) or also
PLOT, X, Y, PSYM=SYM( NUMBER )
INPUTS:
NUMBER -> symbol number
0 : dot
1 : filled circle
2 : filled upward triangle
3 : filled downward triangle
4 : filled diamond
5 : filled square
6 : open circle
7 : open upward triangle
8 : open downward triangle
9 : open diamond
10 : open square
11 : plus
12 : X
13 : star
14 : filled rightfacing triangle
15 : filled leftfacing triangle
16 : open rightfacing triangle
17 : open leftfacing triangle
18 : greater-than symbol ">"
19 : less-than symbol "<"
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Function returns the symbol number to be
used with PSYM= in the PLOT command.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
This function produces a side effect in that the USERSYM procedure
is used to create a symbol definition. It's meant for usage within
the PLOT, OPLOT, etc. command
EXAMPLE:
PLOT, X, Y, PSYM=SYM(0), SYMSIZE=3
; Produces a plot with dots (standard symbol 3)
FOR I = 0, 17 DO OPLOT, X+1, Y, PSYM=SYM(I), COLOR=I
; overplots 17 curves each with its own symbol
MODIFICATION HISTORY:
mgs, 22 Aug 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 11 Dec 2009: GAMAP VERSION 2.14
- Added ">" as symbol #18
- Added "<" as symbol #19
cdh & bmy, 16 Mar 2011: GAMAP VERSION 2.15
- Now use 13 vertices for circle symbols so that
the PostScript output files will become smaller
(See /n/home09/ryantosca/IDL/gamap2/plotting/sym.pro)
NAME:
TAU2YYMMDD (function)
PURPOSE:
Converts a tau value (elapsed hours between
the current date/time and the beginning of an epoch) into a
calendar date and time value.
CATEGORY:
Date & Time
CALLING SEQUENCE:
RESULT = TAU2YYMMDD( TAU, [ NYMD0, NHMS0 ] )
INPUTS:
TAU -> the tau value to be converted (type long)
NYMD0 (long) -> YY/MM/DD for the start of the epoch
default is {19}850101 which is the GEOS-1 start
NHMS0 (long) -> HH/MM/SS for the start of the epoch
will be defaulted to 000000
KEYWORD PARAMETERS:
/NFORMAT --> produce 2-element vector instead of structure
The result will be NYMD and NHMS with NYMD as YYYYMMDD.
/SHORT --> produce 2-element vector with 2-digit year format.
(implies NFORMAT=1)
/GEOS1 -> use 1985/01/01 as epoch start
/GISS_II -> use 1980/01/01 as epoch start
OUTPUTS:
RESULT -> The function returns the calendar date and time as
either a structure with tags YEAR, MONTH, DAY, HOUR,
MINUTE, SECOND or a 2 element array with NYMD and NHMS
long values.
SUBROUTINES:
NYMD2STRU -> extracts year, month, day, hour, minute
and seconds from NYMD and NHMS values.
REQUIREMENTS:
None
NOTES:
Function NYMD2STRU is also embedded in NYMD2TAU function. This should
be kept in mind when changes are necessary.
Function STRDATE can be used to produce a formatted string from
the structure returned by TAU2YYMMDD.
EXAMPLE:
; get calendar structure from tau value for 1994/01/01 (GEOS)
print,tau2yymmdd(78888,/GEOS1)
result (structure with Year, Month, Day, Hour, Minute, Second):
{ 1994 1 1 0 0 0}
... and in the format of NYMD, NHMS
print,tau2yymmdd(78888,/GEOS1,/NFORMAT)
print,tau2yymmdd(78888,/GEOS1,/NFORMAT,/SHORT)
results (array with 2 elements):
19940101 0
940101 0
MODIFICATION HISTORY:
mgs, 26 Mar 1998: VERSION 1.00
mgs, 16 Mar 1999: - now allows floating point tau values
CAUTION: Use double for second precision !
bmy, 27 Jul 1999: VERSION 1.42
- updated comments
bmy, 03 Jan 2000: VERSION 1.44
- updated comments
bmy, 23 Mar 2005: GAMAP VERSION 2.03
- renamed internal function NYMD2STRU to
T2N_NYMD2STRU to avoid conflict with
similar function in "tau2yymmdd.pro";
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/date_time/tau2yymmdd.pro)
NAME:
TESTPATH
PURPOSE:
Set !PATH variable to a limited set of directories for test
purposes (or restore the initial value)
CATEGORY:
File & I/O
CALLING SEQUENCE:
TESTPATH [,pathstring] [,/restore]
INPUTS:
PATHSTRING -> a string with the test directory name(s)
The !PATH variable will contain this string plus the
standard IDL library search path [which is hardwired
and may have to be changed after future updates].
Note: This parameter is ignored if the /RESTORE keyword
is set.
KEYWORD PARAMETERS:
/RESTORE -> restore initial value of !PATH. This is always
the value before the very first call to testpath! Use
of this keyword overrides the PATHSTRING parameter.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
testpath,'~mgs/IDL/test3d'
; sets !PATH to the given name + standard IDL libraries
testpath,/restore
; resets !PATH variable to original value
MODIFICATION HISTORY:
mgs, 16 Jun 1998: VERSION 1.00
mgs, 02 Nov 1998: - changed IDL path from idl5 to idl
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/testpath.pro)
NAME:
TEST_MET
PURPOSE:
Prints out the name, time, and min/max of data of GMAO or
GISS/GCAP met data files which are used as input to GEOS-Chem.
CATEGORY:
GAMAP Utilities
CALLING SEQUENCE:
TEST_MET, MODELINFO [, Keywords ]
INPUTS:
MODELINFO -> Structure from CTM_TYPE which defines the model
name, resolution, and other parameters. NOTE: If the
met field files contain an IDENT string then TEST_MET
will ignore the MODELINFO structure passed and instead
will parse the IDENT string to obtain the model name
and resolution. (NOTE: GEOS-4, GEOS-5, and GCAP met
fields contain an identification string which is read in
to determine the proper model name. For these met fields
you won't need to supply MODELINFO.)
KEYWORD PARAMETERS:
FILENAME -> Name of the binary met field file to examine. If
FILENAME is not passed, then the user will be prompted
to supply a file name via a dialog box query.
/VERBOSE -> If set, then will echo extra information
to the screen.
XINDEX -> A 2-element vector containing the minimum and
maximum longitude indices (in FORTRAN notation) which
define the nested model grid.
YINDEX -> A 2-element vector containing the minimum and
maximum longitude indices (in FORTRAN notation) which
define the nested model grid.
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 [-90,90].
PLOTLEVEL -> If specified, then TEST_MET will plot a lon-lat
map of the given vertical level of the data. Useful for
debugging purposes.
_EXTRA=e -> Picks up extra keywords for OPEN_FILE.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================
OPEN_FILE CTM_GRID (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
TEST_MET, CTM_TYPE( 'GEOS3', res=2 ), FILE='20010115.i6.2x25'
; Prints out information from the 2 x 2.5
; GEOS-3 I-6 met field file for 2001/01/15.
MODIFICATION HISTORY:
bmy, 24 May 2005: GAMAP VERSION 2.04
- now renamed from "test_dao.pro"
- added fields for GISS/GCAP model
- now looks for an IDENT string
bmy, 12 Dec 2006: GAMAP VERSION 2.06
- Modifications for GEOS-5 met fields
- Added XINDEX, YINDEX keywords
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Added extra GEOS-5 fields
bmy, 21 Feb 2008: GAMAP VERSION 2.12
- Now be sure to swap the endian when
opening the file on little-endian
machines
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Added modifications for MERRA data
bmy, 17 Aug 2010: - Added SEAICE** fields for MERRA
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/test_met.pro)
NAME:
TRIANGLE
PURPOSE:
Converts a vector with corner coordinates into X and Y
vectors for a triangle shape. The output vectors can be
used with PLOTS, POLYFILL, or similar IDL plotting commands.
CATEGORY:
Plotting
CALLING SEQUENCE:
TRIANGLE, CORNERS, XVEC, YVEC [, Keywords ]
INPUTS:
CORNERS -> A 1-D vector with [ X0, Y0, X1, Y1 ] coordinates.
(X0,Y0) is the bottom left corner of the plot region and
(X1,Y1) is the top right corner of the plot region.
KEYWORD PARAMETERS:
EXPAND -> A value that will be used to expand the size
of the triangle by the same amount on all sides.
Default is 0.
OUTPUTS:
XVEC -> A 1-D vector with the X-coordinates listed in the
proper order for the POLYFILL or PLOTS commands.
YVEC -> A 1-D vector with the X-coordinates listed in the
proper order for the POLYFILL or PLOTS commands.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; Get a plot position vector from MULTIPANEL
MULTIPANEL, 2, POSITION=POSITION
PRINT, POSITION
0.112505 0.0874544 0.466255 0.956280
; Convert to X and Y vectors for PLOTS input
TRIANGLE, POSITION, XPOINTS, YPOINTS
PRINT, XPOINTS
0.112505 0.466255 0.466255 0.112505 0.112505
PRINT, YPOINTS
0.0874544 0.0874544 0.956280 0.956280 0.0874544
; Call PLOTS to draw a box
PLOTS, XPOINTS, YPOINTS, THICK=2, COLOR=1, /NORMAL
MODIFICATION HISTORY:
cdh, 19 Nov 2007: GAMAP VERSION 2.11
- Adapted from "rectangles.pro"
(See /n/home09/ryantosca/IDL/gamap2/plotting/triangle.pro)
NAME:
TROP_CUT
PURPOSE:
Reads a CTM data block and then only saves data from the
surface up to the maximum tropopause level. (e.g. the
field MODELINFO.NTROP, returned from function CTM_TYPE).
CATEGORY:
Regridding
CALLING SEQUENCE:
TROP_CUT [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. Default is INFILENAME + '.trop'.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==================================================
CTM_GET_DATA CTM_MAKE_DATAINFO (function)
GETMODELANDGRIDINFO UNDEFINE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages
NOTES:
None
EXAMPLE:
TROP_CUT, INFILENAME='data.geos3.4x5', $
OUTFILENAME='trop_data.geos3.4x5'
; Reads data from "data.geos3.4x5". Saves data
; from the surface up to level MODELINFO.NTROP
; and writes to file trop_data.geos3.4x5".
MODIFICATION HISTORY:
bmy, 31 Oct 2002: VERSION 1.00
bmy, 25 Sep 2003: VERSION 1.01
- Call PTR_FREE to free the pointer heap memory
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
(See /n/home09/ryantosca/IDL/gamap2/regridding/trop_cut.pro)
NAME:
TSDIAG
PURPOSE:
Reads and plots CTM time series (station) data. The
data are returned in a structure together with longitude,
latitude, altitude, and time information. TSDIAG tries to
construct a time vector from the TAU information stored
in the file. This may not always work (e.. it is assumed
that time steps are 1 hour).
While reading, TSDIAG displays a '.' for each new station
encountered, and a '+' if a station is continued. If you want
more detailed output, set the /VERBOSE flag.
%%% NOTE: May need updating %%%
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, GAMAP Plotting
CALLING SEQUENCE:
TSDIAG [,RESULT] [,keywords]
INPUTS:
None
KEYWORD PARAMETERS:
FILENAME -> Path of the input file containing CTM
Data data.
SCALE -> A global scale factor that will be applied to all
data. Default is 1. Note that concentration data is
stored as v/v, hence for ppt you should set
SCALE=1.E-12.
/VERBOSE -> display detailed information on what is being read.
/PLOT -> set this flag to produce quick-and-dirty plots of the
time-series data.
OUTPUTS:
RESULT -> A structure containing LON, LAT, ALT and Data data
together with TRACER and a "global" TIME array.
SUBROUTINES:
OPEN_DEVICE CLOSE_DEVICE
CTM_TRACERINFO FILE_EXIST (function)
STRSCINOT (function)
REQUIREMENTS:
NOTES:
Lines with the Data data (Header = 'TB' or 'DV') will be
read from disk. Statistics are ignored for now.
EXAMPLE:
; read time series data from file and return result structure
; in variable TSDATA
tsdiag, TSDATA, FILENAME='ctm.ts'
MODIFICATION HISTORY:
bmy, 06 May 1998: VERSION 1.00
bmy, 07 May 1998: VERSION 1.01
- added PPBC and INTERVAL keywords
- now calls FILE_EXIST to make sure
the input file exists
bmy, 27 May 1998 - now uses CTM_DIAGINFO to return
the proper tracer offset
bmy, 28 May 1998 - now uses SCALE, UNIT, and MOLC information
as returned by CTM_TRACERINFO.
- now uses EXP_STR to compute a
power-of-ten string for the plot title
bmy, 29 May 1998 - now calls CLEANPLOT to initialize
all system variables
bmy, 02 Jun 1998 - now uses STRSCI and STRCHEM string
formatting functions
mgs, 11 Jun 1998: - couple of bug fixes
mgs, 15 Jun 1998: - default tick interval now 48 h
mgs, 22 Jun 1998: - added Data and CSTEPS keywords
mgs, 20 Nov 1998: - now uses convert_unit
hsu, 22 Mar 1999: - increased MAXSTEPS and changed input format
mgs, 04 May 1999: - added MS as a tracer offset (100*MS)
mgs, 05 May 1999: - ... and a little bug fix
mgs, 19 May 1999: - updated comments
- default SCALE factor now 1 instead of 1.E-12
- CLEANPLOT no longer called
mgs, 24 May 1999: - added VERBOSE keyword
- fixed at least two bugs
- improved output. Now need to say /VERBOSE in
order to get details.
mgs, 25 May 1999: - new format had MS and N swapped.
bmy, 27 Jul 1999: GAMAP VERSION 1.42
- updated comments
bmy, 30 Jan 2002: GAMAP VERSION 1.50
- Now use STRBREAK to split each line into
elements of data
- Also no longer restrict data to be > 0
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tsdiag.pro)
NAME:
TSPLOT
PURPOSE:
Create a plot of station data time series using the
data structure as returned from TSDIAG.PRO. This routine
is a simple outline for how to use this structure and
not meant to produce publisheable plots. Tip: use
MULTIPANEL.PRO to save paper.
%%% THIS MAY NOW BE OBSOLETE %%%
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
TSPLOT, TSSTRU, INDEX, SCALE=SCALE
INPUTS:
TSSTRU -> The data structure as returned from TSDIAG.PRO
INDEX -> A vector with station indices that are to be plotted.
If no index is given, the program will loop through all
records.
KEYWORD PARAMETERS:
SCALE -> A scaling factor to be applied to the dat abefore plotting.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; read station data
TSDIAG,TSSTRU,FILE='ctm.ts'
; set page for 16 panels
MULTIPANEL, 16
; plot data from all stations as pptv
TSPLOT, TSSTRU, SCALE=1.e12
; turn multipanel off
MULTIPANEL, /OFF
MODIFICATION HISTORY:
mgs, 30 Jun 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tsplot.pro)
NAME:
TVIMAGE
PURPOSE:
This purpose of TVIMAGE is to enable the TV command in IDL
to be a completely device-independent and color-decomposition-
state independent command. On 24-bit displays color decomposition
is always turned off for 8-bit images and on for 24-bit images.
The color decomposition state is restored for those versions of
IDL that support it (> 5.2). Moreover, TVIMAGE adds features
that TV lacks. For example, images can be positioned in windows
using the POSITION keyword like other IDL graphics commands.
TVIMAGE also supports the !P.MULTI system variable, unlike the
TV command. TVIMAGE was written to work especially well in
resizeable graphics windows. Note that if you wish to preserve
the aspect ratio of images in resizeable windows, you should set
the KEEP_ASPECT_RATIO keyword, described below. TVIMAGE works
equally well on the display, in the PostScript device, and in
the Printer and Z-Graphics Buffer devices. The TRUE keyword is
set automatically to the correct value for 24-bit images, so you
don't need to specify it when using TVIMAGE.
AUTHOR:
FANNING SOFTWARE CONSULTING:
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
GAMAP Internals, Graphics
CALLING SEQUENCE:
TVIMAGE, image
INPUTS:
image: A 2D or 3D image array. It should be byte data.
x : The X position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
If the Y position is not used, X is taken to be the image
"position" in the window. See the TV command documenation
for details.
y : The Y position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
KEYWORD PARAMETERS:
BACKGROUND: This keyword specifies the background color. Note that
the keyword ONLY has effect if the ERASE keyword is also
set or !P.MULTI is set to multiple plots and TVIMAGE is
used to place the *first* plot.
ERASE: If this keyword is set an ERASE command is issued
before the image is displayed. Note that the ERASE
command puts the image on a new page in PostScript
output.
_EXTRA: This keyword picks up any TV keywords you wish to use.
HALF_HALF: If set, will tell CONGRID to extrapolate a *half* row
and column on either side, rather than the default of
one full row/column at the ends of the array. If you
are interpolating images with few rows, then the
output will be more consistent with this technique.
This keyword is intended as a replacement for
MINUS_ONE, and both keywords probably should not be
used in the same call to CONGRID.
KEEP_ASPECT_RATIO: Normally, the image will be resized to fit the
specified position in the window. If you prefer, you can
force the image to maintain its aspect ratio in the window
(although not its natural size) by setting this keyword.
The image width is fitted first. If, after setting the
image width, the image height is too big for the window,
then the image height is fitted into the window. The
appropriate values of the POSITION keyword are honored
during this fitting process. Once a fit is made, the
POSITION coordiates are re-calculated to center the image
in the window. You can recover these new position coordinates
as the output from the POSITION keyword.
MARGIN: A single value, expressed as a normalized coordinate, that
can easily be used to calculate a position in the window.
The margin is used to calculate a POSITION that gives
the image an equal margin around the edge of the window.
The margin must be a number in the range 0.0 to 0.333. This
keyword is ignored if the POSITION or OVERPLOT keywords are
used. It is also ignored when TVImage is executed in a
multi-plot window, EXCEPT if it's value is zero. In this
special case, the image will be drawn into its position in
the multi-plot window with no margins whatsoever. (The
default is to have a slight margin about the image to separate
it from other images or graphics.
MINUS_ONE: The value of this keyword is passed along to the CONGRID
command. It prevents CONGRID from adding an extra row and
column to the resulting array, which can be a problem with
small image arrays.
NOINTERPOLATION: Setting this keyword disables the default bilinear
interpolation done to the image when it is resized. Nearest
neighbor interpolation is done instead. This is preferred
when you do not wish to change the pixel values of the image.
This keyword must be set, for example, when you are displaying
GIF files that come with their own non-IDL color table vectors.
NORMAL: Setting this keyword means image position coordinates x and y
are interpreted as being in normalized coordinates. This keyword
is only valid if the TV keyword is set.
OVERPLOT: Setting this keyword causes the POSITION keyword to be ignored
and the image is positioned in the location established by the
last graphics command. For example:
Plot, Findgen(11), Position=[0.1, 0.3, 0.8, 0.95]
TVImage, image, /Overplot
POSITION: The location of the image in the output window. This is
a four-element floating array of normalized coordinates of
the type given by !P.POSITION or the POSITION keyword to
other IDL graphics commands. The form is [x0, y0, x1, y1].
The default is [0.0, 0.0, 1.0, 1.0]. Note that this keyword is ALSO
an output keyword. That is to say, upon return from TVIMAGE
this keyword (if passed by reference) contains the actual
position in the window where the image was displayed. This
may be different from the input values if the KEEP_ASPECT_RATIO
keyword is set, or if you are using TVIMAGE with the POSITION
keyword when !P.MULTI is set to something other than a single
plot. One use for the output values might be to position other
graphics (e.g., a colorbar) in relation to the image.
Note that the POSITION keyword should not, normally, be used
when displaying multiple images with !P.MULTI. If it *is* used,
its meaning differs slightly from its normal meaning. !P.MULTI
is responsible for calculating the position of graphics in the
display window. Normally, it would be a mistake to use a POSITION
graphics keyword on a graphics command that was being drawn with
!P.MULTI. But in this special case, TVIMAGE will use the POSITION
coordinates to calculate an image position in the actual position
calculated for the image by !P.MULTI. The main purpose of this
functionality is to allow the user to display images along with
colorbars when using !P.MULTI. See the example below.
TV: Setting this keyword makes the TVIMAGE command work much
like the TV command, although better. That is to say, it
will still set the correct DECOMPOSED state depending upon
the kind of image to be displayed (8-bit or 24-bit). It will
also allow the image to be "positioned" in the window by
specifying the coordinates of the lower-left corner of the
image. The NORMAL keyword is activated when the TV keyword
is set, which will indicate that the position coordinates
are given in normalized coordinates rather than device
coordinates.
Setting this keyword will ensure that the keywords
KEEP_ASPECT_RATIO, MARGIN, MINUS_ONE, MULTI, and POSITION
are ignored.
OUTPUTS:
None.
SIDE EFFECTS:
Unless the KEEP_ASPECT_RATIO keyword is set, the displayed image
may not have the same aspect ratio as the input data set.
RESTRICTIONS:
If the POSITION keyword and the KEEP_ASPECT_RATIO keyword are
used together, there is an excellent chance the POSITION
parameters will change. If the POSITION is passed in as a
variable, the new positions will be returned in the same variable
as an output parameter.
If a 24-bit image is displayed on an 8-bit display, the
24-bit image must be converted to an 8-bit image and the
appropriate color table vectors. This is done with the COLOR_QUAN
function. The TVIMAGE command will load the color table vectors
and set the NOINTERPOLATION keyword if this is done. Note that the
resulting color table vectors are normally incompatible with other
IDL-supplied color tables. Hence, other graphics windows open at
the time the image is display are likely to look strange.
EXAMPLE:
To display an image with a contour plot on top of it, type:
filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
image = BYTARR(360,360)
OPENR, lun, filename, /GET_LUN
READU, lun, image
FREE_LUN, lun
TVIMAGE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO
CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $
YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10
To display four images in a window without spacing between them:
!P.Multi=[0,2,2]
TVImage, image, Margin=0
TVImage, image, Margin=0
TVImage, image, Margin=0
TVImage, image, Margin=0
!P.Multi = 0
To display four image in a window with associated color bars:
!P.Multi=[0,2,2]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 0
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 2
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 3
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 5
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
!P.Multi =0
MODIFICATION HISTORY:
Written by: David Fanning, 20 NOV 1996.
Fixed a small bug with the resizing of the image. 17 Feb 1997. DWF.
Removed BOTTOM and NCOLORS keywords. This reflects my growing belief
that this program should act more like TV and less like a "color
aware" application. I leave "color awareness" to the program
using TVIMAGE. Added 24-bit image capability. 15 April 1997. DWF.
Fixed a small bug that prevented this program from working in the
Z-buffer. 17 April 1997. DWF.
Fixed a subtle bug that caused me to think I was going crazy!
Lession learned: Be sure you know the *current* graphics
window! 17 April 1997. DWF.
Added support for the PRINTER device. 25 June 1997. DWF.
Extensive modifications. 27 Oct 1997. DWF
1) Removed PRINTER support, which didn't work as expected.
2) Modified Keep_Aspect_Ratio code to work with POSITION keyword.
3) Added check for window-able devices (!D.Flags AND 256).
4) Modified PostScript color handling.
Craig Markwart points out that Congrid adds an extra row and column
onto an array. When viewing small images (e.g., 20x20) this can be
a problem. Added a Minus_One keyword whose value can be passed
along to the Congrid keyword of the same name. 28 Oct 1997. DWF
Changed default POSITION to fill entire window. 30 July 1998. DWF.
Made sure color decomposition is OFF for 2D images. 6 Aug 1998. DWF.
Added limited PRINTER portrait mode support. The correct aspect ratio
of the image is always maintained when outputting to the
PRINTER device and POSITION coordinates are ignored. 6 Aug 1998. DWF
Removed 6 August 98 fixes (Device, Decomposed=0) after realizing that
they interfere with operation in the Z-graphics buffer. 9 Oct 1998. DWF
Added a MARGIN keyword. 18 Oct 1998. DWF.
Re-established Device, Decomposed=0 keyword for devices that
support it. 18 Oct 1998. DWF.
Added support for the !P.Multi system variable. 3 March 99. DWF
Added DEVICE, DECOMPOSED=1 command for all 24-bit images. 2 April 99. DWF.
Added ability to preserve DECOMPOSED state for IDL 5.2 and higher. 4 April 99. DWF.
Added TV keyword to allow TVIMAGE to work like the TV command. 11 May 99. DWF.
Added the OVERPLOT keyword to allow plotting on POSITION coordinates
estabished by the preceding graphics command. 11 Oct 99. DWF.
Added automatic recognition of !P.Multi. Setting MULTI keyword is no
longer required. 18 Nov 99. DWF.
Added NOINTERPOLATION keyword so that nearest neighbor interpolation
is performed rather than bilinear. 3 Dec 99. DWF
Changed ON_ERROR condition from 1 to 2. 19 Dec 99. DWF.
Added Craig Markwardt's CMCongrid program and removed RSI's. 24 Feb 2000. DWF.
Added HALF_HALF keyword to support CMCONGRID. 24 Feb 2000. DWF.
Fixed a small problem with image start position by adding ROUND function. 19 March 2000. DWF.
Updated the PRINTER device code to take advantage of available keywords. 2 April 2000. DWF.
Reorganized the code to handle 24-bit images on 8-bit displays better. 2 April 2000. DWF.
Added BACKGROUND keyword. 20 April 2000. DWF.
Fixed a small problem in where the ERASE was occuring. 6 May 2000. DWF.
Rearranged the PLOT part of code to occur before decomposition state
is changed to fix Background color bug in multiple plots. 23 Sept 2000. DWF.
Removed MULTI keyword, which is no longer needed. 23 Sept 2000. DWF.
Fixed a small problem with handling images that are slices from 3D image cubes. 5 Oct 2000. DWF.
Added fix for brain-dead Macs from Ben Tupper that restores Macs ability to
display images. 8 June 2001. DWF.
Fixed small problem with multiple plots and map projections. 29 June 2003. DWF.
Converted all array subscripts to square brackets. 29 June 2003. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Small modification at suggestion of Karsten Rodenacker to increase size of
images in !P.MULTI mode. 8 December 2004. DWF.
Minor modifications on Karsten Rodenacker's own account concerning margination
and TV behaviour. 8 December 2004. KaRo
There was a small inconsistency in how the image was resized for PostScript as
opposed to the display, which could occasionally result in a small black line
to the right of the image. This is now handled consistently. 3 January 2007. DWF.
Made a small change to CMCONGRID to permit nearest-neighbor interpolation for 3D arrays.
Previously, any 24-bit image was interpolated, no matter the setting of the NOINTERP
keyword. 22 April 2007. DWF.
Updated the program for the 24-bit Z-buffer in IDL 6.4. 11 June 2007. DWF.
Added new POSITION keyword functionality for !P.MULTI display. 9 Sept 2007. DWF.
(See /n/home09/ryantosca/IDL/gamap2/internals/tvimage.pro)
NAME:
TVMAP
PURPOSE:
TVMAP produces one of the following plots:
(1) A color-pixel image, overlaid with a world map
(2) A line-contour plot, overlaid with a world map
(3) A filled-contour plot, overlaid with a world map
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
TVMAP, Data, [ Xarr, YArr [ [, keywords ] ]
INPUTS:
DATA -> 2-D array of values to be plotted as a color map.
The first dimension is longitude, the second is latitude.
XARR, YARR -> If plotting a line-contour map or filled-contour map,
then XARR is the array of X-axis values, and YARR is the
array of Y-Axis values that are needed to construct the
the contours. XARR and YARR are not needed to produce a
color-pixel image map; however, if XARR and YARR are
passed, TVMAP will be able to label the longitude and
latitude lines accordingly and set the proper default limits.
KEYWORD PARAMETERS:
BLACK -> The color index corresponding to black.
Default is !MYCT.BLACK.
/CONUS -> a Lambert's azimuthal equal area projection for
CONtiguous U.S., w/ specific LIMIT and P0lat, P0lon, Rot.
MAX_VALID -> maximum valid data value for color-pixel plots
Data above MAX_VALID will be shown in white, unless
TOPOUTOFRANGE is set to another color index.
MIN_VALID -> minimum valid data value for color-pixel plots.
(or minimum contour level for contour plots). Data
below MIN_VALID will be shown in white, unless
BOTOUTOFRANGE is set to another color index.
TOPOUTOFRANGE ( BOTOUTOFRANGE ) -> color index to indicate
data above MAX_VALID (below MIN_VALID). Default is
white. The color is also shown with a box (or TRiangle)
near the colorbar (if any). If negative, the box is not
shown with the colorbar.
/NOERASE -> This keyword prevents erasing the screen (or page)
when setting a multi-panel environment or after a page was
filled. /NOERASE is automatically turned ON when the /OFF
keyword is given. NOTE: On the PostScript device, when
the page is filled, it automatically places the next plot
on the next page. You can use the /NOERASE keyword to
suppress this behavior, especially if you are manually
placing plots on the page.
CSFAC -> Character size for the map labels and X, Y titles.
Default settings for CSFAC vary according to the number
of plots per page and type of plot device.
TCSFAC -> Character size for the top title. Default
settings for TCSFAC vary according to the number
of plots per page and type of plot device.
/NOADVANCE -> Set this switch to prevent TVMAP from advancing
to the next plot panel on the page. This is useful if
you desire to overplot something atop the pixel map or
contour map.
/POLYFILL -> to use IDL POLYFILL routine instead of MAP_IMAGE
to do the pixel plot (see /SAMPLE). Use this keyword
with default cylindrical projection only. Use it also if
you think that MAP_IMAGE does not neatly reproduces the
boxes.
/RECTANGLE -> to plot a rectangle around the map. Default is
to have one for non-polar projection, and none for polar
projection. Set to 0 or 1 to override default. NOTE:
setting the /HORIZON keyword will disable this option.
/SAMPLE -> to do "pixel plot" (ie grid boxes are colored)
instead of contour.
/HORIZON -> Set this switch to call IDL routine MAP_HORIZON
to draw a horizon line around the boundaries of the map.
Use this feature if the map projection you are using is
elliptical or interrupted. NOTE: /HORIZON will override
override the /RECTANGLE keyword setting.
WINDOWPOSITION -> Returns the position of the plot window
in normal coordinates to the calling program. This can
be used by a subsequent call to PLOT if you want to
overplot symbols atop the contour or pixel plot created
by TVMAP.
_EXTRA=e -> Picks up extra keywords (not listed below, unless
noted) for BYTSCL, COLORBAR, TVIMAGE, MAP_SET, MAP_GRID,
MAP_CONTINENTS, MAP_LABELS and CONTOUR.
Keywords passed to both BYTSCL and COLORBAR:
============================================
MAXDATA -> Maximum value of the DATA array to use in the
byte scaling. Default is max( DATA ).
MINDATA -> Minimum value of the DATA array to use in the
byte scaling. Default is min( DATA ).
BOTTOM -> The lowest color index of the colors to be used
for byte-scaling the color map and colorbar. Default
is 20 (or !D.N_COLORS-1 if 20 is too large).
NCOLORS -> This is the maximum color index that will be used.
Default is 120 (or !D.N_COLORS-BOTTOM, if 120 is too large).
/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.
Additional keywords passed to COLORBAR:
=======================================
/CBAR -> If set, will plot a horizontal colorbar below the
map in the position specified by CBPOSITION. Default is
to NOT plot a colorbar.
CBCOLOR -> Color index of the colorbar outline and
characters. Defaults to BLACK (see above).
CBPOSITION -> A four-element array of normalized coordinates
that specifies the location of the colorbar. CBPOSITION
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.
CBFORMAT -> format to use in call to colorbar. Default is I12
if abs(max(data)) < 1e4, else e12.2 (strings get trimmed)
CBMIN, CBMAX -> Explicitly sets the min and max values of
the colorbar range. If not set, TVMAP will set
CBMIN = min( DATA ) and CBMAX = max( DATA ).
CBTICKLEN -> Specifies the color bar tick length as a
fraction of the colorbar height (for horizontal
colorbars) or width (for vertical colorbars).
CBVERTICAL -> If set, will plot a vertical bar on the right
side of the map.
CBSCALE -> If set, then the printed tick labels are scaled by
powers of 10 to minimize overlap.
DIVISIONS -> Number of labels for the colorbar. Default is 4.
/TRIANGLE -> to replace box that indicate Out Of Range data
with a triangle.
TOPLEVELVALUE -> to define the last annotation of the
colorbar when using the C_LEVELS keyword
Keywords passed to MAP_SET:
===========================
COLOR -> Color index of the map outline and title characters.
Defaults to BLACK (see above).
MPARAM -> A 3 element vector containing values for
[ P0Lat, P0Lon, Rot ]. Default is [ 0, 0, 0 ].
Elements not specified are automatically set to zero.
/ISOTROPIC -> If set, will produce a map with the same scale
in the X and Y directions. Default is not to plot an
isotropic-scale map. Note, however, that if TVMAP is
called from CTM_PLOT, the default is to plot a map that
keeps the aspect ratio (which is about the same as
isotropic).
LIMIT -> A four-element vector which specifies the latitude
and longitude extent of the map. The elements of LIMIT
are arranged thus: [ LatMin, LonMin, LatMax, LonMax ].
Default is to set LIMIT = [ -90, -180, 90, 180 ] (i.e.
to include the entire globe). P0Lon will be computed
to fit into the LIMIT range unless it is explicitely
requested in MParam.
POLAR -> Plot a polar stereographic projection. If set and
equal 1 then the plot goes from the pole to a latitude
defined by either the extend of the data or by the user
through the LIMIT keyword. If set and equal to 2, then
the full hemisphere is plot, regardless of the data or
LIMIT settings.
Note that setting the /STEREOGRAPHIC keyword wouldn't
work.
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.0, 0.15, 1.0, 1.0] with Horizontal Color
Bar, and [0., 0., 0.82, 1.0] with Vertical CBar.
MARGIN -> specify a margin around the plot in normalized
coordinates. This keyword does not change any IDL
system variables and will thus only become "visible"
if you use the POSITION returned by MULTIPANEL in
subsequent plot commands. MARGIN can either be one value
which will be applied to all four margins, or a 2-element
vector which results in equal values for the left and
right and equal values for the bottom and top margins,
or a 4-element vector with [left,bottom,right,top]. The
default MARGIN setting is [ 0.05, 0.04, 0.03, 0.07 ].
OMARGIN -> specify a page margin around all panels in normalized
coordinates. Works like MARGIN.
SCALEMAPSET -> To pass the SCALE keyword to MAP_SET.
TITLE -> The title string that is to be placed atop the
plot window. TITLE is passed explicitly to avoid keyword
name duplication in the _EXTRA=e facility.
Keywords passed to MAP_LABELS:
==================================
LATS, LONS -> Array of latitudes (longitudes) used to
construct the map labels. If LATS has one element, the
LATS vector is build with LATS+n*DLAT, with as n as
needed to cover the map range. If it has more than one
element, it is not modified and it is the final grid.
DLAT, DLON -> Latitude (longitude) interval between grid
lines. Passed with _extra.
Keywords passed to MAP_CONTINENTS:
==================================
/CONTINENTS -> If set, will call MAP_CONTINENTS to plot
continent outlines or filled boundaries. Default is 0.
/COUNTRIES -> If set, will call MAP_CONTINENTS to draw the
political boundaries of countries as of 1993.
/COASTS -> If set, will call MAP_CONTINENTS to draw the coast
lines of continental regions.
CCOLOR -> The color index of the continent outline or fill
region. Default is BLACK (see above).
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.
/USA -> Set this switch to turn on US State boundaries.
Keywords passed to MAP_GRID:
============================
/BOX_AXES -> If set, then MAP_GRID will print alternating
light & dark regions with the lon & lat labels around
the border of the plot. This is passed directly to
MAP_GRID. NOTE: BOX_AXES is the default for the CONUS
option.
/GRID -> If set, will call MAP_GRID to plot grid lines and
labels. Labels can be turned off with /NOGLABELS.
Default is _not_ to plot grid lines.
GCOLOR -> The color index of the grid lines. Default is
BLACK (see above).
/NOGXLABELS -> If set, TVMAP will suppress printing longitude
labels for each grid line.
/NOGYLABELS -> If set, TVMAP will suppress printing latitude
labels for each grid line.
Keywords passed to CONTOUR:
===========================
/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.
C_LEVELS -> Vector containing the contour levels. If not
specified, will use preset default levels.
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_COLORS -> Index array of color levels for contour lines or
fill regions. If not specified then will use uniformly
spaced default color levels. If C_COLORS is set to a
scalar value, then all contour lines will have the same
color value.
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.
/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.
Keywords passed to MAP_IMAGE (prior: to REBIN):
==============================================
/SAMPLE -> Used to rebin the byte-scaled image array to a
larger size. If /SAMPLE is set, then MAP_IMAGE will use
nearest-neighbor sampling rather than bilinear
interpolation.
Keyword passed to TVIMAGE:
===============================================
SCALEMAPIMAGE -> Sets the number of pixels per graphic coordinate
in PostScript and other devices with scalable
pixels. Larger values produce better resolution output,
but much larger file sizes. The default value is
0.04. Use a larger number for higher resolution if your
image does not exactly fit on the map projection.
OUTPUTS:
None
SUBROUTINES:
External subroutines required:
------------------------------
COLORBAR ( by Martin Schultz & David Fanning )
TVIMAGE ( by David Fanning )
RECTANGLE ( by Martin Schultz )
CONVERT_LON ( by Martin Schultz )
INV_INDEX ( function, by Martin Schultz )
MAP_LABELS ( by Martin Schultz & Bob Yantosca )
LOGLEVELS ( by Martin Schultz )
GET_DEFAULTFORMAT ( by Martin Schultz )
MYCT_DEFAULTS ( by Bob Yantosca )
REQUIREMENTS:
Assumes that a MYCT colortable has been loaded.
NOTES:
(1) The _EXTRA facility now picks up keywords for multiple
routines (this is a new feature in IDL v. 5.0+!!)
(2) 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.
(4) For contour plots, contour labels will be specified
using the C_ANNOTATION keyword. The downside is that
by using C_ANNOTATION, this disables the C_LABELS keyword
and so one cannot specify which contour lines will get
labels. The solution would be to expand the C_LABELS
vector so that it has the same number of elements as
C_ANNOTATION, and then to individually zero the
corresponding elements of C_ANNOTATION before making
the contour plot. Don't have enough time for this now,
but maybe can deal with this at a later time...
(5) Now references the !MYCT system variable. This should
be defined at the start of your IDL session when "myct.pro"
is called from "idl_startup.pro".
LIMITATIONS:
(1) The case of plot over the dateline is working fine only if
LIMIT[3] is negative and LIMIT[1] is positive. Other cases are
not specifically handled and results may not be reliable.
(2) Since we are using MAP_IMAGE, pixel plots do start and end
at longitude and latitude centers of the grid by default,
like contour plots. More map coverage is done in three cases:
(2a) Data sets that cover the globe will fill the map with
coarse pixel plots.
(2b) Data sets that cover the globe will fill the map only
in the longitude direction with smooth pixel and contour
plot. Plots start and stop at the first and last latitudes
centers.
(2c) Data sets that do not cover the globe will start and
end at grid edges with coarse pixels, only if the limit of
the map is less than half grid size away from the the
first/last latitude and longitude centers. This limitation
is due to the method used to pad the data outside the
domain delimited by X/Y arrays.
(3) MAP_IMAGE assumes that an evenly spaced data set is
passed. If X or Y array is not evenly spaced, pixels plots are
flawed and not reliable. Contour plots are ok.
EXAMPLE:
(1)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC
/SAMPLE, TITLE='O3 at 10 km'
(2)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC
TITLE='O3 at 10 km'
; Plots a 2-D "smooth" pixel map.
(3)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC $
/FCONTOUR, TITLE='O3 at 10 km', $
C_LEVELS=[10,20,30,40,50,60,70,80,90,100]
; Plots a 2-D filled contour map.
(4)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC $
/FCONTOUR, TITLE='O3 at 10 km', $
C_LEVELS=[10,20,30,40,50,60,70,80,90,100], $
/NOGXLABELS, /NOGYLABELS, /BOX_AXES
; Same as Example (3), but prints prints box-style
; axes via the /BOX_AXES feature of MAP_GRID.
MODIFICATION HISTORY:
bmy, 13 Apr 1998: VERSION 1.00
bmy, 11 Jun 1998: - now returns if there is
nothing to plot
mgs, 15 Jun 1998: - bug fix: n_elements instead of
keyword_set
bmy, 22 Sep 1998: VERSION 1.10
- Now use _EXTRA=e to pass keywords to
BYTSCL, TVIMAGE, MAP_SET, and COLORBAR
- added MAPTITLE and UNIT keywords to
avoid keyword name duplication in
_EXTRA=e.
bmy, 25 Sep 1998: VERSION 2.00
- now calls MAP_CONTINENTS and MAP_GRID
- keywords renamed for consistency
- reduced default size for CBPOSITION
bmy, 28 Sep 1998: VERSION 2.01
- MPOSITION renamed to POSITION, MCOLOR to
COLOR, MTITLE to TITLE for consistency
- LONSHIFT renamed to LSHIFT to avoid
problems with ambiguous keyword names
bmy, 07 Sep 1998: VERSION 3.00
- now can plot contour map or color-pixel
map (added CONTOUR and FCONTOUR keywords,
and XARR and YARR parameters)
- The colorbar is now optional, and is
turned on via the /COLORBAR switch.
bmy, 12 Nov 1998: VERSION 3.01
- added ISOTROPIC, SAMPLE, KEEP_ASPECT_RATIO,
C_LABELS, and C_FORMAT keywords
- now isotropic-scale color-image plots
and isotropic-scale contour plots are
handled correctly
- Use mgs-style default levels & colors for
contour and filled-contour maps.
bmy, 13 Nov 1998: - updated comments
- renamed C_LEVELS to C_ANNOTATION to
prevent keyword name confusion
- added NOLINES, NOLABELS, C_LABELS,
and OVERLAYCOLOR keywords
- contour lines and labels can be
suppressed correctly
- added mgs fix so that PostScript
pixel-maps appear smoother
- a border is now plotted around the
map window, without inserting any of that
annoying "cushion" space.
- added LOG keyword for logarithmic
contours and/or pixel colors
- use KEYWORD_SET more often
mgs, 17 Nov 1998: - re-arranged calls to map_set and tvimage
in order to maximize size
- output of title now seperate from map_set
- added CBFormat keyword
mgs, 19 Nov 1998: - CBFormat now handled in colorbar.pro
mgs, 20 Nov 1998: - bug fix for map_set for contour plots
mgs, 03 Dec 1998: - filled continents now added before contours
- CFILL keyword checked for consistency
bmy, 08 Feb 1999: - If /LOG is set, make sure that we don't
take the log of zero and incur a math error
- add call to function INV_INDEX
bmy, 23 Feb 1999: - added /GLABELS keyword to turn on/off printing
of labels for each grid line on the map
- added call to CONVERT_LON for longitudes
that straddle the date line
bmy, 26 Feb 1999: - added LIMIT as an explicit keyword
- now uses MAP_LABELS to construct grid labels
- updated comments
bmy, 04 Mar 1999: - added DEBUG keyword for debug output
mgs, 17 Mar 1999: - some cleaning:
- LSHIFT, DLON, and GLABELS made obsolete
- new keyword NOGLABELS
- P0Lon now computed from LIMIT information.
- Updated call to map_labels
- For contour plots: XArr, YArr no longer
mandatory (although they should be provided)
- much smarter default contour levels
mgs, 22 Mar 1999: - added multi-panel ability through use of
the new MULTIPANEL routine. This alters the
meaning of MPosition and CB_Position: they now
refer to positions in the current plot panel!
mgs, 23 Mar 1999: - fixed a few minor things
- charsize is now adjusted according to number
of panels on page
bmy, 25 Mar 1999: - If CBAR=0, then print unit string below
plot (formerly was done in CTM_PLOT)
- now use updated GET_DEFAULTFORMAT
- updated comments
- if NPANELS >=2 then place the plot title
higher above the window, to allow for
carriage-returned lines
mgs, 23 Apr 1999: - added CBMin and CBMax keywords for
tighter colorbar control
mgs, 19 May 1999: - title shifted a little higher if it has
more than 1 line.
bmy & mgs, 26 May 1999: - added POLAR keyword and respective support.
bmy, 27 May 1999: - bug fix for isotropic contour plots
mgs, 27 May 1999: - added support for discrete colorbars and
changed default behaviour for filled
contour plots: now plots a colorbar and
no lines.
bmy, 03 Jun 1999: - For polar plots, if the latitude range
spans more than 60 degrees, only plot
labels for [ 30, 60, 90 ] degrees.
mgs, 03 Jun 1999: - CFill now also allowed for filled contours
or pixel plots (data will be overplotted)
bmy, 09 Jun 1999: - Set CBUnit to '' if nothing passed
bmy, 21 Jun 1999: - Added MIN_VALID keyword.
bmy, 06 Jul 1999: - bug fix for min_valid: ge replaces gt.
bmy, 07 Jul 1999: - Save C_COLORS in a temp variable. Also
define C_COLORS so that grayscales won't
appear in Postscript plots
- multi-panel plots are now well-separated
from each other (for PostScript output)
bmy, 08 Jul 1999: - more minor fixes
bmy, 18 Nov 1999: - increase default left margin by a little
bmy, 31 Mar 2000: GAMAP VERSION 1.45
- make CSFAC and TITLECSFAC into keywords
bmy, 10 May 2000: - make sure XARR and YARR (if passed) are 1D vectors
- now use XARR, YARR to set default limits
- rearranged keyword settings code for clarity
- added more debug output (when /DEBUG is set)
bmy, 26 May 2000: - updated comments
bmy, 13 Jun 2000: - added /COUNTRIES and /COASTS keywords.
Setting /COUNTRIES, /COASTS, or /CONTINENTS
will now invoke routine MAP_CONTINENTS
bmy, 30 Jan 2001: GAMAP VERSION 1.47
- if NOGLABELS=0 and GRID=0, will print out
grid labels w/o printing out grid lines
- added MARGIN keyword for MULTIPANEL
- also allow coarse plots with /SAMPLE
when using the Z-buffer device
bmy, 07 Jun 2001: - removed some obsolete code & comments
bmy, 02 Jul 2001: GAMAP VERSION 1.48
- added /NOGXLABELS and /NOGYLABELS keywords
to suppress printing either lon or lat
grid labels, if so desired.
bmy, 13 Jul 2001: - bug fix: remove _EXTRA=e from MAP_SET call
when making pixel plots. This prevents extra
grid lines from being drawn on the map.
bmy, 23 Jul 2001: - now call MYCT_DEFAULTS to specify default
values for BLACK, BOTTOM, NCOLORS, etc
if these keywords are not passed explicitly.
bmy, 31 Oct 2001: GAMAP VERSION 1.49
- add /NOADVANCE keyword to prevent advancing
to the next page (in case you want to overplot)
bmy, 08 May 2002: GAMAP VERSION 1.50
- If the data array has more than 100,000 elements,
then assign it a dithering factor of 1, so that
we don't run out of memory when trying to plot it
bmy, 20 Jun 2002: GAMAP VERSION 1.51
- added WINDOWPOSITION keyword to return
the position vector of the plot window
region to the calling program
bmy, 28 Sep 2002: - now gets MYCT default parameters from the
!MYCT system variable
bmy, 10 Oct 2002: - bug fix: MCOLOR=!MYCT.BLACK setting has
now been restored (was left commented out)
bmy, 14 Nov 2002: GAMAP VERSION 1.52
- If GLABELS=0, then this also sets GXLABELS=0
and GYLABELS=0.
- Removed obsolete keywords
- Removed reference to MYCT_DEFAULTS.
bmy, 02 Mar 2004: GAMAP VERSION 2.02
- added OMARGIN keyword so that we can put
an outer margin around all plot panels
bmy, 28 May 2004: - Now returns the modified value of
C_COLORS to the calling program
- added CBTICKLEN keyword to specify the
color bar tick length
bmy, 23 Aug 2005: GAMAP VERSION 2.04
- added MAX_VALID keyword
- now adjust MINDATA to MIN_VALID and
MAXDATA to MAX_VALID internally
- Now pass _EXTRA=e to XYOUTS
tmf & bmy, 04 Oct 2006: GAMAP VERSION 2.05
- Replace /ERASE keyword with /NOERASE
to facilitate manual positioning of
plots. Pass /NOERASE to MULTIPANEL.
bmy & phs, 18 Sep 2007: GAMAP VERSION 2.10
- Don't reset data below MIN_VALID to
MIN_VALID for contour plots
- fix MAX_VALID for contour plots.
- fix CBar behavior when C_LEVELS is passed
cdh/phs/bmy 26 Nov 2007: GAMAP VERSION 2.11
- do not modify input DATA & X/YARR
- add support for VERTICAL COLORBAR
- add support for CONUS projection
- now all map projections are supported for
all 4 types of plots.
- now data Latitudes and Longitudes (X/Yarr)
are taken into account in Pixel
plot: no more need to clip the data
before plotting, TVMAP will do it, like
it already does for Contour plots.
- added Full Hemisphere Polar plot option,
regardless of DATA range and LIMIT keyword
- added RECTANGLE keyword to overwrite
default behavior
- map plotting coordinate system active at
exit, allowing for easy oplot
- default LIMIT for small data set corrected
- various fixes for across-the-dateline plots
- remove obsolete KEEP_ASPECT_RATIO keyword
- add /HORIZON keyword to call MAP_HORIZON
- updated comments
phs, 19 Dec 2007: - new default map limit in case of
non-global smooth pixel and contour
plots.
- plots start and end at box edges in few
new cases.
- replace /CENTER with /MINUS_ONE in call
to CONGRID
phs, 12 Feb 2008: GAMAP VERSION 2.12
- Fixes for MIN_VALID and MAX_VALID
- The test for the LIMIT keyword is now to check
"if ( n_elements(limit) ne 4 )". This allows you
to disable the LIMIT keyword by also setting
LIMIT=0.
phs, 28 Feb 2008: - Couple of small padding improvements
- added SCALEMAPSET and SCALEMAPIMAGE to pass
their respective SCALE keyword to MAP_SET and
MAP_IMAGE.
- LONS and LATS keyword added, so the grid can
be specified. Work with DLAT and DLON, the
grid spacings that can be passed to MAP_LABELS
thru the _extra keyword.
cdh & phs, 21 Mar 2008: - added minimum support for LIMIT input as
8-elements vector
phs, 17 Apr 2008: - Added the TopOutOfRange and BotOutOfRange
keywords, so default color (white) for Out-Of
-Range data can be overwritten.
phs, 6 May 2008: - Added the GXLABELS and GYLABELS keywords
to specify which grid line to label.
phs, 19 Jun 2008: - Set default SCALE value for MapImage
(ScaleMapImage keyword) to 0.04 if PS device.
phs, 25 Mar 2009: GAMAP VERSION 2.13
- Added NAN_COLOR to specify color to use
for NaN and Infinite data
cdh, eml, phs, 19 Sep 2009: - Now C_LEVELS works with pixel plots and
any projection.
- Added LATS, LONS (to specify the grid), and
TOPLEVELVALUE (to specify the last level
in the colorbar when using C_LEVELS)
keywords
- fixed limit of CONUS projection
phs, 29 Oct 2009: GAMAP VERSION 2.14
- added the polyfill keyword
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tvmap.pro)
NAME:
TVPLOT
PURPOSE:
TVPLOT produces one of the following plots:
(1) A color-pixel image, overlaid atop X-Y plot axes
(2) A line-contour plot, overlaid atop X-Y plot axes
(3) A filled-contour plot, overlaid atop X-Y plot axes
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
TVPLOT, Data, Xarr, Yarr, [, keywords ]
INPUTS:
DATA -> 2-D array of values to be plotted.
XARR -> array of X-axis (horizontal axis) values needed to
construct the plot. The number of elements in XARR must
equal the number of elements of the first dimension of DATA.
ZARR -> ZARR is the array of Z-axis (vertical axis) values
needed to construct the plot. The number of elements
in ZARR must equal the number of elements of the second
dimension of DATA. If ZARR[0] > ZARR[N_Elements(ZARR)-1]
then TVPLOT will assume pressure is to be plotted on the
Y-axis.
KEYWORD PARAMETERS:
BLACK -> The color index corresponding to black.
Default is !MYCT.BLACK (from !MYCT system variable.)
/NOERASE -> This keyword prevents erasing the screen (or page)
when setting a multi-panel environment or after a page was
filled. /NOERASE is automatically turned ON when the /OFF
keyword is given. NOTE: On the PostScript device, when
the page is filled, it automatically places the next plot
on the next page. You can use the /NOERASE keyword to
suppress this behavior, especially if you are manually
placing plots on the page.
CSFAC -> Character size for the map labels and plot titles.
Default settings for CSFAC vary according to the number
of plots per page and type of plot device.
/NOADVANCE -> Set this switch to prevent TVMAP from advancing
to the next plot panel on the page. This is useful if
you desire to overplot something atop the pixel plot or
contour plot.
MARGIN -> specify a margin around the plot in normalized
coordinates. This keyword does not change any IDL
system variables and will thus only become "visible"
if you use the POSITION returned by MULTIPANEL in
subsequent plot commands. MARGIN can either be one value
which will be applied to all four margins, or a 2-element
vector which results in equal values for the left and
right and equal values for the bottom and top margins,
or a 4-element vector with [left,bottom,right,top]. The
default MARGIN setting is [ 0.05, 0.04, 0.00, 0.02 ].
-> adds 0.02 to the left margin for Y-axis title
-> adds 0.03 to the bottom margin for X-axis title
-> adds 0.03 to the right margin for vertical color bar
-> adds 0.02 to the top margin for more than 2 plots/page
OMARGIN -> specify a page margin around all panels in normalized
coordinates. Works like MARGIN.
WINDOWPOSITION -> Returns the position of the plot window
in normal coordinates to the calling program. This can
be used by a subsequent call to PLOT if you want to
overplot symbols atop the contour or pixel plot created
by TVPLOT.
_EXTRA=e -> Picks up extra keywords (not listed below) for
BYTSCL, COLORBAR, TVIMAGE, MAP_SET, MAP_GRID,
MAP_CONTINENTS, and CONTOUR.
Keywords for both BYTSCL and COLORBAR:
======================================
MAXDATA -> Maximum value of the DATA array to use in the
byte scaling. Default is max( DATA ).
MINDATA -> Minimum value of the DATA array to use in the
byte scaling. Default is min( DATA ).
BOTTOM -> The lowest color index of the colors to be used
for byte-scaling the color map and colorbar. Default
is !MYCT.BOTTOM (from the !MYCT system variable).
NCOLORS -> This is the maximum color index that will be used.
Default is !MYCT.NCOLOR (from the !MYCT system variable).
/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 logarithmic.
Additional keywords for COLORBAR:
=================================
/CBAR -> If set, will plot the colorbar below the map in the
position specified by CBPOSITION. Default is to NOT
plot a colorbar.
CBCOLOR -> Color index of the colorbar outline and
characters. Defaults to BLACK (see above).
CBPOSITION -> A four-element array of normalized coordinates
that specifies the location of the colorbar. CBPOSITION
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.
CBFORMAT -> format to use in call to colorbar. Default is I12
if abs(max(data)) < 1e4, else e12.2 (strings get trimmed)
CBMIN, CBMAX -> Explicitly sets the min and max values of
the colorbar range. If not set, TVPLOT will set
CBMIN = min( DATA ) and CBMAX = max( DATA ).
CBTICKLEN -> Specifies the color bar tick length as a
fraction of the colorbar height (for horizontal
colorbars) or width (for vertical colorbars).
CBSCALE -> If set, then the printed tick labels are scaled by
powers of 10 to minimize overlap.
DIVISIONS -> Number of labels for the colorbar. Default is 4.
/CBVERTICAL -> Will draw a vertical colorbar instead of
a horizontal one. Default is to draw a horizontal
colorbar.
Keywords for INTERPOLATION:
===========================
/SAMPLE -> Used to get COARSE pixel plot. REBIN is called,
and uses the nearest-neighbor sampling.
Note that REBIN is used even if SAMPLE is not set, when
device is PostScript. It uses the bilinear interpolation
then.
/NOZINTERP -> set to switch off the vertical
interpolation. This can be used only if the ZARR is
evenly spaced.
Keywords for PLOT:
===================
BOTOUTOFRANGE -> Color index for data below
MIN_VALID. Default is white, or last color in color
table if !MYCT is not defined. If set to negative, the
color is used in the plot only, and not in the colorbar.
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
plot window. TITLE is passed explicitly to avoid keyword
name duplication in the _EXTRA=e facility.
COLOR -> Color index for the plot window outline and titles.
Default is BLACK.
XSTYLE, YSTYLE -> Style settings for the X and Y axes. See
the "Graphics Keywords" settings man page for more info.
XSTYLE and YSTYLE are passed as explicit keywords to
avoid keyword name confusion in the _EXTRA=e facility.
XRANGE, YRANGE -> Two-element vectors for the X-axis and Y-axis
plot ranges, of the form [Xmin,Xmax] and [YMin,Ymax].
XRANGE and YRANGE are passed as explicit keywords to
avoid keyword name confusion in the _EXTRA=e facility.
XTITLE, YTITLE -> Titles for the X and Y axes. XTITLE and
YTITLE are passed as explicit keywords to avoid keyword
name confusion in the _EXTRA=e facility.
NOXLABEL, NOYLABEL -> Suppress printing tick labels for X and Y axes.
Keywords for CONTOUR:
=====================
/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.
C_LEVELS -> Vector containing the contour levels. If not
specified, will use preset default levels (see below).
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_COLORS -> Index array of color levels for contour lines or
fill regions. If not specified then will use uniformly
spaced default color levels. If C_COLORS is set to a
scalar value, then all contour lines will have the same
color value.
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.
/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.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==================================================
COLORBAR GET_DEFAULTFORMAT (function)
INV_INDEX (function) LOGLEVELS (function)
TVIMAGE
REQUIREMENTS:
Assumes that a MYCT colortable has been loaded.
NOTES:
(1) The _EXTRA facility picks extra keywords for BYTSCL,
TVIMAGE, PLOT and COLORBAR, etc... This is a new
feature in IDL v. 5.0+!!
(2) For contour plots, contour labels will be specified
using the C_ANNOTATION keyword. The downside is that
by using C_ANNOTATION, this disables the C_LABELS keyword
and so one cannot specify which contour lines will get
labels. The solution would be to expand the C_LABELS
vector so that it has the same number of elements as
C_ANNOTATION, and then to individually zero the
corresponding elements of C_ANNOTATION before making
the contour plot. Don't have enough time for this now,
but maybe can deal with this at a later time...
EXAMPLE:
POSITION = [0.1, 0.1, 0.9, 0.9 ] ; position for map
CBPOSITION = [0.1, 0.05, 0.9, 0.08] ; position for colorbar
TVPLOT, DATA, XARR, YARR, $
MAXDATA=MAXDATA, MINDATA=MINDATA, $
POSITION=POSITION, CBPOSITION=CBPOSITION, $
/ERASE, TITLE='Avg O3', $
XTITLE='Longitude', YTITLE='Altitude', $
DIVISIONS=4, FORMAT='(F6.2)'
MODIFICATION HISTORY:
bmy, 27 Apr 1998: VERSION 1.00
bmy, 04 Jun 1998: - now can plot separate X or Y axes
if [XY]STYLE = 4 or 8
mgs, 15 Jun 1998: - bug fix n_elements instead of keyword_set
- now does spline interpolation in the
vertical in order to get correct
altitudes
bmy, 21 Sep 1998: - Rename EXTRA1, EXTRA2, etc, to names
that have more meaning (e.g. E_BYT for
BytScl, E_TV for TVImage, etc.)
bmy, 22 Sep 1998: VERSION 1.10
- now uses _EXTRA=e facility to pass extra
keywords to BYTSCL, TVIMAGE, PLOT, and
COLORBAR.
- add PLOTTITLE (for PLOT) and UNIT (for
COLORBAR) keywords to prevent keyword
name duplication in _EXTRA=e.
mgs, 11 Nov 1998: - added CBar keyword
bmy, 16 Nov 1998: VERSION 2.00
- now can produce line-contour and filled-
contour plots as well as image plots
- now calls REBIN to rebin the byte-scaled
image array to higher resolution for
PostScript output.
- added the following keywords: /LOG,
/SAMPLE, /CONTOUR, /FCONTOUR, C_ANNOTATION,
C_LEVELS, C_LABELS, /NOLABELS, /NOLINES,
bmy, 17 Nov 1998: - For image plots, now only display plot axes
AFTER the image plot has been made. This
reduces the "apparent" wait time for the
user.
- renamed keywords to XA_TITLE, XA_RANGE,
XA_TICKNAME, etc to avoid keyword name
duplication in the _EXTRA=e facility.
mgs, 17 Nov 1998: - added CBFormat keyword
bmy, 18 Nov 1998: - also added floating point format for
CBFORMAT when abs(max(Data)) < 10
mgs, 19 Nov 1998: - CBFormat no whandled in colorbar.pro
bmy, 27 Jan 1999: - added defaults for XRANGE and YRANGE
bmy, 08 Jan 1999: - If /LOG is set, make sure that we don't
take the log of zero and incur a math error
- add call to function INV_INDEX
mgs, 18 Mar 1999: - cleaned up
- now uses loglevels and has smarter default
contour levels
mgs, 22 Mar 1999: - added multi-panel ability through use of
the new MULTIPANEL routine. This alters the
meaning of MPosition and CB_Position: they now
refer to positions in the current plot panel!
mgs, 23 Mar 1999: - fixed a few minor things
- charsize is now adjusted according to number
of panels on page
bmy, 25 Mar 1999: - now use updated GET_DEFAULTFORMAT
- if NPANELS >=2 then place the plot title
higher above the window, to allow for
carriage-returned lines
- updated comments
bmy, 27 Apr 1999: - commented out !x.charsize=csfac and
!y.charsize=csfac lines...these messed
up the plot window sizes
- updated comments
bmy, 28 Apr 1999: - added CBMin and CBMax keywords for
tighter colorbar control
mgs, 19 May 1999: - title shifted a little higher if it has
more than 1 line.
mgs, 21 May 1999: - variable name for TITLE now MTITLE as in
TVMAP.
mgs, 27 May 1999: - changed default behaviour for filled contours:
now plots "discrete" colorbar and no lines.
Keyword NoLines changed to C_Lines.
bmy, 10 Jun 1999: - CBUnit defaults to '
mgs, 06 Jul 1999: - adjusted charsize for multipanel plots
bmy, 07 Jul 1999: - Save C_COLORS in a temp variable. Also
define C_COLORS so that grayscales won't
appear in Postscript plots
- multi-panel plots are now well-separated
from each other (for PostScript output)
bmy, 08 Jul 1999: - more minor fixes
bmy, 18 Nov 1999: - increase default left margin by a little
bmy, 31 Mar 2000: GAMAP VERSION 1.45
- made CSFAC a keyword
bmy, 23 Jul 2001: GAMAP VERSION 1.48
- now call MYCT_DEFAULTS to specify default
values for BLACK, BOTTOM, NCOLORS, etc
if these keywords are not passed explicitly.
bmy, 07 Jul 2001: - removed obsolete code from 1998 and 1999
bmy, 31 Oct 2001: GAMAP VERSION 1.49
- add /NOADVANCE keyword to prevent advancing
to the next page (in case you want to overplot)
bmy, 28 Sep 2002: GAMAP VERSION 1.51
- now gets MYCT default parameters from the
!MYCT system variable
bmy, 15 Nov 2002: GAMAP VERSION 1.52
- Added MIN_VALID keyword to skip missing
data values for pixel plots
bmy, 18 Dec 2003: - For pixel plots, now linearly interpolate
when creating NDATA instead of using a
cubic spline. This is more accurate.
- Prevent NDATA from being extrapolated wildly
due to the slope at the surface and top level
of the plot.
bmy, 06 Jan 2003: - Now interpolate NDATA correctly when pressure
or altitude is on the Y-axis.
- Removed obsolete keywords XA_TITLE, YA_TITLE,
- XA_RANGE, YA_RANGE, XA_TICKNAME, YA_TICKNAME
- Now define default YRANGE = [ ZBOT, ZTOP ]
to make Y-axis labels correct for both pressure
and altitude on the Y-axis.
- Removed ZBOT, ZTOP from the keyword list;
these are now internal variables.
- updated comments
bmy, 02 Mar 2004: GAMAP VERSION 2.02
- added MARGIN keyword a la TVMAP
- added OMARGIN keyword
bmy, 28 May 2004: - Now returns the modified value of
C_COLORS to the calling program
- added CBTICKLEN keyword to specify the
color bar tick length
bmy, 30 Nov 2004: GAMAP VERSION 2.03
- added WINDOWPOSITION keyword
bmy, 12 Jul 2005: GAMAP VERSION 2.04
- added /ISOTROPIC keyword
- added /NOZINTERP keyword to prevent interpolation
to a fine grid of 100 pts in the vertical dim.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy & phs, 26 Nov 2007: GAMAP VERSION 2.11
- Minor fix for margins w/ for new TVIMAGE
- Also reset !P.MULTI=0 when using TVIMAGE
so that it will use the internally computed
position vector. Reset after TVIMAGE call.
- Make sure to label last colorbar division
for contour plots
- Vertical colorbar options and MIN_VALID,
MAX_VALID keywords are the same as TVMAP
- Extra space is now added to the default
MARGIN values for vertical colorbar
and multiple plots per page.
- Adjust default CBPOSITION values such
that the colorbar will be placed either
0.05 below or 0.02 to the right of the plot
phs, 04 Apr 2008: GAMAP VERSION 2.12
- now produces a better coarse pixel plot
for altitude vs latitude or longitude
plots, even though the initial box size
is not exactly reproduced.
cdh, eml, phs, 24 Sep 2009: GAMAP VERSION 2.13
- fixes for LOG10 plots
- new improved interpolation scheme in Z
direction
- C_LEVELS works with /SAMPLE
- added checks on NAN when looking at
min/max, added NAN_COLOR to specify a
color for NaN
- added BOTOUTOFRANGE to set color of data
below Min_Valid
- check if !MYCT is defined
xyue & bmy, 24 Jan 2011: GAMAP VERSION 2.15
- Replace /ERASE keyword with /NOERASE
to facilitate manual positioning of
plots. Pass /NOERASE to MULTIPANEL.
This is now consistent w/ TVMAP.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tvplot.pro)
NAME:
TVREAD
PURPOSE:
To get accurate screen dumps with the IDL command TVRD on 24-bit
PC and Macintosh computers, you have to be sure to set color
decomposition on. This program adds that capability automatically.
In addition, the program will optionally write BMP, GIF, JPEG,
PICT, PNG, and TIFF color image files of the screen dump.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Graphics
CALLING SEQUENCE:
image = TVREAD(xstart, ystart, ncols, nrows)
The returned image will be a 2D image on 8-bit systems and
a 24-bit pixel interleaved true-color image on 24-bit systems.
A -1 will be returned if a file output keyword is used (e.g.,
JPEG, TIFF, etc.).
OPTIONAL INPUTS:
XSTART -> The starting column index. By default, 0.
YSTART -> The starting row index. By default, 0.
NCOLS -> The number of columns to read. By default, !D.X_Size - XSTART
NROWS -> The number of rows to read. By default, !D.Y_Size - YSTART.
KEYWORD PARAMETERS:
BMP -> Set this keyword to write the screen dump as a color BMP file.
CANCEL -> An output keyword set to 1 if the user cancels out of a
filename dialog. Set to 0 otherwise.
COLORS -- If a 24-bit image has to be quantized, this will set
the number of colors in the output image. Set to 256 by
default. Applies to BMP, GIF, PICT, and PNG formats
written from 24-bit displays. (See the COLOR_QUAN
documentation for details.)
CUBE -> If this keyword is set to a value between 2 and 6 the
color quantization will use a cubic method of
quantization. Applies to BMP, GIF, PICT, and PNG formats
written from 24-bit displays. (See the COLOR_QUAN
documentation for details.)
DITHER -> If this keyword is set the quantized image will be
dithered. Applies to BMP, GIF, PICT, and PNG formats
written from 24-bit displays. (See the COLOR_QUAN
documentation for details.)
FILENAME -> The base name of the output file. (No file extensions;
they will be added automatically.) This name may be
changed by the user.
image = TVREAD(Filename='myfile', /JPEG)
No file will be written unless a file output keyword is
used (e.g., JPEG, TIFF, etc.) in the call. By default
the FILENAME is set to "idl". The file extension will be
set automatically to match the type of file created.
GIF -> Set this keyword to write the screen dump as a color
GIF file.
JPEG -> Set this keyword to write the screen dump as a color
JPEG file.
ORDER -> Set this keyword to determine the image order for
reading the display. Corresponds to !Order and set to such
as the default.
PICT -> Set this keyword to write the screen dump as a color
PICT file.
PNG -> Set this keyword to write the screen dump as a color
PNG file.
TIFF -> Set this keyword to write the screen dump as a color
TIFF file.
TRUE -> Set this keyword to the type of interleaving you
want. 1 = Pixel interleaved, 2 = row interleaved,
3 = band interleaved.
TYPE -> Can be set to the type of file to write. Use this
instead of setting BMP, GIF, JPEG, PICT, PNG, or TIFF
keywords: TYPE='JPEG'. The primary purpose of this is to
make event handlers easier to write.
QUALITY -> This keyword sets the amount of compression for
JPEG images. It should be set to a value between 0 and
100. It is set to 75 by default. (See the WRITE_JPEG
documentation for details.)
WID -> The index number of the window to read from. The
current graphics window (!D.Window) is selected by
default. An error is issued if no windows are
currently open on a device that supports windows.
_EXTRA -> Any keywords that are appropriate for the
WRITE_*** routines are also accepted via keyword
inheritance.
COMMON BLOCKS:
None
RESTRICTIONS: Requires IDL 5.2 and higher.
MODIFICATION HISTORY:
Written by David W. Fanning, 9 AUG 2000.
Added changes to make the program more device independent. 16 SEP 2000. DWF.
Removed GIF file support for IDL 5.4 and above. 18 JAN 2001. DWF.
Added NODIALOG keyword. 28 MAR 2001. DWF.
Added an output CANCEL keyword. 29 AUG 2001. DWF.
Added ERROR_MESSAGE code to file. 17 DEC 2001. DWF.
Added ORDER keyword. 25 March 2002. DWF.
Now create 24-bit PNG files if reading from a 24-bit display. 11 May 2002. DWF.
Now create 24-bit BMP files if reading from a 24-bit display. 23 May 2002. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Unleashed the GIF code for IDL 6.2 and above. 10 Nov 2005. DWF.
Rolled back previous change to IDL 6.1. 24 Jan 2006. DWF.
Fixed a problem in which 16-bit displays were treated as 24-bit displays,
and as a result could not produce WHITE colors. Now all 16-bit displays
are treated as 8-bit displays. It is an ugly trade-off. 24 Jan 2006. DWF.
Added TYPE keyword 27 Sep 2006. DWF.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Removed /NODIALOG keyword
- Only pop up a dialog box if FILENAME
isn't passed and we are writing a file
- Updated comments, cosmetic changes
phs, 13 Feb 2009: GAMAP VERSION 2.13
- Restored the /NODIALOG keyword
(See /n/home09/ryantosca/IDL/gamap2/graphics/tvread.pro)
NAME:
UNDEFINE
PURPOSE:
The purpose of this program is to delete or undefine
an IDL program variable from within an IDL program or
at the IDL command line. It is a more powerful DELVAR.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1642 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
General
CALLING SEQUENCE:
UNDEFINE, variable
REQUIRED INPUTS:
variable: The variable to be deleted. Up to 10 variables may be specified as arguments.
SIDE EFFECTS:
The variable no longer exists.
EXAMPLE:
To delete the variable "info", type:
IDL> Undefine, info
MODIFICATION HISTORY:
Written by David Fanning, 8 June 97, from an original program
given to me by Andrew Cool, DSTO, Adelaide, Australia.
Simplified program so you can pass it an undefined variable. :-) 17 May 2000. DWF
Simplified it even more by removing the unnecessary SIZE function. 28 June 2002. DWF.
Added capability to delete up to 10 variables at suggestion of Craig Markwardt. 10 Jan 2008. DWF.
(See /n/home09/ryantosca/IDL/gamap2/general/undefine.pro)
NAME:
UPDATE_LIBRARY
PURPOSE:
automatic update of IDL WWW library
CATEGORY:
Documentation
CALLING SEQUENCE:
UPDATE_LIBRARY,TARGETDIR,TARNAME [,keywords]
INPUTS:
TARGETDIR --> directory where WWW library resides
Usually a local directory, the contents of which is then
ftp'd to the www site (default: '~/IDL/lib-tools/').
TARNAME --> after copying all the required files, the library
is tar'd and compressed. TARNAME is the name of the uncompressed
file (default 'idl_lib.tar').
KEYWORD PARAMETERS:
DIRS --> directories to search for files with SEARCHPATTERN.
This will only come to effect if no LISTFILE is given
(default ['~/IDL/tools/','~/IDL/tools3d']).
SEARCHPATTERN --> string array of filemasks which may contain
wildcards and determine the files to be included in the
library (default ['*.pro', '*.doc']). This
parameter is also used to obtain a list of files that are
already in the library and to determine the files to delete
if the PACKAGE option is set.
LISTFILE --> Name of a file that contains the names of all the
files to be included in the library (E.g. output from the
DISTRIBUTE routine, although this cannot be used directly).
In this case, no search for matching files is performed.
PACKAGE --> Normally, the individual files of the library will
remain in TARGETDIR together with the compressed tar file.
If the PACKAGE option is set, all individual files will be
deleted after creation of a new tar file. In order to retain
information about files once included in the library, the
file 'dirlist.old' is created before deleting the files.
Normally this file is created at the beginning of program
execution.
NO_ACTION --> DO not copy any files, create a tar file or compress
this. This will only produce a list of all the files that
would be included in the library together with their status
label ('NEW' or 'UPDATE', 'OLD' is represented byu blanks)
OUTPUTS:
Unless the NO_ACTION keyword is set, the TARGETDIR will contain
a compressed tar file and unless the PACKAGE option is set, it
will also contain a copy of all individual files that make up the
library.
SUBROUTINES:
REQUIREMENTS:
Requires function STRRIGHT.
NOTES:
This routine uses SPAWN extensively. The spawned commands are
UNIX specific.
The file status 'UPDATED' is obtained by comparing the filedate
of all files that are not 'NEW' with the date of the compressed
tar file using the Unix find command.
EXAMPLE:
UPDATE_LIBRARY
will collect all '*.pro', and '*.doc' files in the directories
'~/IDL/tools', and '~/IDL/tools3d' , copy them into the
default target directory '~/IDL/lib-tools', tar them and compress
the tar file 'idl-lib.tar'.
In order to create a library with all '*.pro' and '*.sav' files
of all subdirectories of '~/IDL/' in the target directory 'lib-all'
type:
DIRS = STR_SEP(EXPAND_PATH('+~/IDL'),':')
SEARCH = ['*.pro','*.sav']
UPDATE_LIBRARY,'~/lib-all/','all_idl.tar',dirs=DIRS, $
searchpattern=SEARCH
In order to pack together all the files needed to run program
TEST.PRO, proceed as follows:
(if you are in IDL, exit and come back in)
JOURNAL,'test.files'
DISTRIBUTE,'test'
JOURNAL
(now edit your journal file 'test.files', keeping only the
names of the files that belong to the test.pro package, and
maybe add documentation and/or example files that you would
like to include in the library and create directory ~/lib-test)
UPDATE_LIBRARY,'~/lib-test','test.tar',listfile='test.files', $
SEARCHPATTERN=['*.pro','*.doc','*.data'],/PACKAGE
Note, that the filemasks in SEARCHPATTERN will be used to
obtain the file status, and to find the files to be deleted after
updating the library. They are not necessary to include these
files in the library. This is completely controlled by the entries
of listfile.
If you want to collect all '*.data' files from a list of directories
in a library without keeping a copy of the individual files try:
dirlist=['~/data/','~/data/aircraft/','~/data/surface/']
UPDATE_LIBRARY,dirlist,'all_data.tar',/package, $
searchpattern='*.data'
MODIFICATION HISTORY:
mgs, 19 Nov 1997: VERSION 1.00
mgs, 22 Feb 1999: replaced findfile with mfindfile for SGI
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/doc/update_library.pro)
NAME:
USAGE
PURPOSE:
Display help information on any routine in the IDL path
that has a (more or less) standard header.
CATEGORY:
Documentation
CALLING SEQUENCE:
USAGE, ROUTINENAME
INPUTS:
ROUTINENAME -> (string) name of the routine for which help
information shall be provided. Tip: to get help for the
current routine use function ROUTINE_NAME().
KEYWORD PARAMETERS:
/PRINTALL -> prints complete header information. Normally, only
"user relevant" information is displayed.
OUTPUTS:
Prints usage information on the screen.
SUBROUTINES:
External Subroutines Referenced:
================================
DATATYPE (function)
FILE_EXIST (function)
REQUIREMENTS:
None
NOTES:
This routine is meant to replace /HELP constructs etc.
EXAMPLES:
(1)
IF ( N_PARAMS() NE 2 ) THEN BEGIN
PRINT,'Invalid number of arguments!'
USAGE, routine_name()
ENDIF
; Put this error check IF block at the top of
; an IDL routine to display the doc header
; info if the wrong # of arguments are passed
(2)
USAGE, 'MY_ROUTINE', /PRINTALL
; Print complete doc header information from
; the IDL routine "my_routine.pro".
MODIFICATION HISTORY:
mgs, 27 Mar 1998: VERSION 1.00
mgs, 16 Jun 1998: - replaced close by free_lun
bmy, 09 May 2002: TOOLS VERSION 1.50
- test RNAME to see if it's a string
- updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/doc/usage.pro)
NAME:
USSA_ALT (function)
PURPOSE:
Return the altitude for a given pressure corresponding
to the US Standard Atmosphere.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
ALT = USSA_ALT( PRESSURE )
INPUTS:
PRESSURE -> a floating point value, variable or vector
for which temperatures shall be returned. Pressure must
correspond to an altitude of less than 100 km.
KEYWORD PARAMETERS:
OUTPUTS:
ALT -> An altitude value or vector [in km]
SUBROUTINES:
External Subroutines Required:
===============================
USSA_PRESS (function)
REQUIREMENTS:
None
NOTES:
Computes approx. altitudes (logp fit to US Standard Atmosphere)
tested vs. interpolated values, 5th degree polynomial gives good
results (ca. 1% for 0-100 km, ca. 0.5% below 30 km)
EXAMPLE:
PRINT, USSA_ALT( [ 1000, 800, 600, 400, 200] )
0.106510 1.95628 4.20607 7.16799 11.8405
; Prints altitudes corresponding to 1000, 800,
; 600, 400, 200 hPa based on the US Std Atmosphere.
MODIFICATION HISTORY:
bmy, 17 Jun 1998: VERSION 1.00
- removed section of code from
CTM_GRID.PRO by mgs
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/ussa_alt.pro)
NAME:
USSA_PRESS (function)
PURPOSE:
Return the pressure for a given altitude corresponding
to the US Standard Atmosphere
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = USSA_PRESS( ALTITUDE )
INPUTS:
ALTITUDE -> a floating point value, variable or vector
for which temperatures shall be returned.
Altitude must lie in the range of 0-50 km.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> A pressure value or vector [in mbar]
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The function evaluates a 5th order polynomial which had
been fitted to USSA data from 0-100 km. Accuracy is on the
order of 0.5% below 30 km, and 1% above.
EXAMPLE:
PRINT, USSA_PRESS( [ 0, 10, 20, 30 ] )
998.965 264.659 55.2812 11.9484
; Returns pressures corresponding to 0, 10, 20,
; and 30 km, as based on the US Std Atmosphere
MODIFICATION HISTORY:
mgs, 23 May 1998: VERSION 1.00
(designed from USSA_TEMP.PRO)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/ussa_press.pro)
NAME:
USSA_TEMP (function)
PURPOSE:
Return the temperature for a given altitude corresponding
to the US Standard Atmosphere
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = USSA_TEMP( ALTITUDE )
INPUTS:
ALTITUDE -> a floating point value, variable or vector
for which temperatures shall be returned. Altitude must lie
in the range of 0-50 km.
KEYWORD PARAMETERS:
OUTPUTS:
RESULT -> A temperature value or vector [in K]
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The function evaluates a 6th order polynomial which had
been fitted to USSA data from 0-50 km. Accuracy is on the
order of 2 K below 8 km, and 5 K from 8-50 km. Note that
this is less than the actual variation in atmospheric
temperatures.
USSA_TEMP was designed to assign a temperature value to
CTM grid boxes in order to allow conversion from mixing
ratios to concentrations and vice versa.
EXAMPLE:
PRINT, USSA_TEMP( [ 0, 10, 20, 30 ] )
288.283 226.094 216.860 229.344
; Returns the temperature [K] at 0, 10, 20, 30 km
; corresponding to the US Standard Atmosphere
MODIFICATION HISTORY:
mgs, 16 May 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/ussa_temp.pro)
NAME:
VELOCITY_FIELD
PURPOSE:
Overplots a 2-D velocity field atop a map or plot window.
CATEGORY:
Plotting
CALLING SEQUENCE:
VELOCITY_FIELD, U, V, X, Y [, keywords ]
INPUTS:
U -> The X component of the two-dimensional field.
U must be a two-dimensional array.
V -> The Y component of the two dimensional field. V must have
the same dimensions as U. The vector at point (i,j) has a
magnitude of:
[ U(i,j)^2 + V(i,j)^2 ]^0.5
and a direction of:
ATAN2( V(i,j), U(i,j) ).
X -> Abcissae values. X must be a vector with a length
equal to the first dimension of U and V.
Y -> Ordinate values. Y must be a vector with a length
equal to the second dimension of U and V.
KEYWORD PARAMETERS:
MISSING -> Missing data high-cutoff value. Vectors with a
magnitude greater than MISSING are ignored.
/DOTS -> If set, will place a dot at each missing data point.
Otherwise, will draw nothing for missing data points.
/DOTS only has effect if MISSING is specified.
X_STEP -> The X-extent of a cell in data coordinates. If
X_STEP is not specified, then a VELOCITY_FIELD will
compute it as:
X_STEP = ( Max(X) - Min(X) ) / ( N_Elements(X) - 1 )
Where X is the array of abscissae as described above.
Y_STEP -> The X-extent of a cell in data coordinates. If
X_STEP is not specified, then a VELOCITY_FIELD will
compute it as:
Y_STEP = ( Max(Y) - Min(Y) ) / ( N_Elements(Y) - 1 )
Where X is the array of ordinates as described above.
COLOR -> Specifies the color of the arrows. Default is black.
/DATELINE -> Will skip points for which an arrow cannot
be drawn (usually across the date line).
HSIZE -> The length of the lines used to draw the arrowhead.
If HSIZE is positive, then the arrow head will be the
same regardless of the length of each vector. (Default
size is !D.X_SIZE / 100). If HSIZE is negative, then
the arrowhead will be 1/HSIZEth of the total arrow
length.
LEGENDLEN -> Specify an arrow of a given length in DATA
coordinates displayed as a legend in the calling
routine. Default is LONGEST.
LEGENDNORM -> Returns to the calling program the length of
LEGENDLEN in NORMAL coordinates. This is needed in
order to plot a legend arrow in the calling program.
LEGENDMAG -> Returns to the calling program the magnitude of
the vector of size LEGENDLEN. Default is LONGEST.
_EXTRA=e -> Picks up all other keywords for PLOT, PLOTS, etc.
OUTPUTS:
None.
SUBROUTINES:
Internal Subroutines:
=====================
VF_MAGNITUDE (function)
NOTES:
(1) You need to call MAP_SET or PLOT first, to establish the
coordinate system. VELOCITY_FIELD can only overplot
vectors atop of an existing map or plot window.
(2) If you are calling VELOCITY_FIELD to overplot vectors
atop a world map, then in the calling program you must
make sure that the longitude values contained in the X
vector are in the range 0 - 360.
(3) If you do not explicitly specify Y_STEP, and your grid
has half-size boxes at the poles, then the value of
Y_STEP computed by VELOCITY_FIELD might be different from
the actual latitude interval.
(4) VELOCITY_FIELD assumes that U, V, X, and Y are on a
regularly-spaced grid (e.g. longitude & latitude).
(5) Now uses the IDL ARROW command to draw the arrow heads.
RESTRICTIONS:
None.
CALLING SEQUENCE:
VELOCITY_FIELD, U, V, X, Y, Thick=3, HSize=0.1
; produces a velocity field plot with an arrow
; thickness of 3 and a arrow head size of 10% of
; the arrow body size.
MODIFICATION HISTORY:
DMS, RSI, Oct., 1983.
For Sun, DMS, RSI, April, 1989.
Added TITLE, Oct, 1990.
Added POSITION, NOERASE, COLOR, Feb 91, RES.
August, 1993. Vince Patrick, Adv. Visualization Lab, U. of Maryland,
fixed errors in math.
August, 1993. DMS, Added _EXTRA keyword inheritance.
bmy, 03 Dec 1999: GAMAP VERSION 1.44
- renamed to VELOCITY_FIELD
- added ARRLEN, HSIZE, HANGLE, THICK keywords
- cleaned up some things
bmy, 26 May 2000: GAMAP VERSION 1.45
- updated comments, minor cleanup
bey, bmy, 24 Jul 2000: GAMAP VERSION 1.46
- several bug fixes
- added internal routine MAGNITUDE
- added X_STEP, Y_STEP, MAXMAG keywords
sjg, bmy, 01 Aug 2000: - added error check on index array GOOD
- now compare magnitudes to abs( MISSING )
- now error check for MAXLEN: prevent div by 0
- updated comments
bmy, 23 Jul 2002: GAMAP VERSION 1.51
- now use IDL ARROW procedure to draw arrows
- HSIZE is now defaulted to device coordinates
- removed HANGLE keyword -- it's obsolete
- now specify legend vector w/ LEGENDLEN
- renamed ARRLEN to LEGENDNORM
bmy, 02 Jun 2005: GAMAP VERSION 2.04
- Added /DATELINE keyword to perform a quick
test to skip over points which will choke
at the date line
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 20 Mar 2008: GAMAP VERSION 2.12
- Now test if the vector position is in
the plot window
- Added the PLOTPOSITION keyword
(See /n/home09/ryantosca/IDL/gamap2/plotting/velocity_field.pro)
NAME:
WRITEDATA
PURPOSE:
write a 2 dimensional data array and header information to a file
CATEGORY:
File & I/O
CALLING SEQUENCE:
WRITEDATA,FILENAME,DATA [,HEADER,UNITS,CFACT,MCODE] [,keywords]
INPUTS:
FILENAME --> the name of the output file. If the output file
exists, the user will be prompted for a new name unless
keyword NO_WARN is set.
DATA --> The data array to be written.
HEADER --> An optional string array containing variable names.
These will be composed to a string using the DELIM delimiter.
Note that the HEADER information can also be passed in the
pre-formatted COMMENTS keyword parameter.
UNITS, CFACT, MCODE --> string arrays that will be added to the
file header concatenated with blank delimiters. These parameters
are optional and merely there to facilitate creating chem1d
model input files.
KEYWORD PARAMETERS:
TITLE --> A title string that will be the first header line.
It is also possible to pass a string array here, although for
more complicate file headers it is recommended to pre-format
the file header and pass it in the COMMENTS keyword.
DELIM --> A delimiter character for the HEADER (variable name)
items. Default is a blank ' '.
COMMENTS --> A string array containing all the lines of the file
header. Note that COMMENTS overrules the input of HEADER, UNITS,
CFACT, and MCODE as well as TITLE.
/NO_WARN --> Suppress warning message and user prompt for a new
filename if the file already exists.
OUTPUTS:
A file containing a file header and the data array written
line by line.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
DATA = findgen(3,10)
HEADER = ['A','B','C']
writedata,'test.out',DATA,HEADER,TITLE='test file',DELIM=';'
This will create a file like:
test file
A;B;C
0.00000 1.00000 2.00000
3.00000 4.00000 5.00000
...
MODIFICATION HISTORY:
mgs, 25 Nov 1997: VERSION 1.00
mgs, 05 Apr 1999: - now uses formatted write statement
(looks like a bug in IDL for windows: sometimes no space
is printed between numbers if you simply print,data)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/writedata.pro)
NAME:
WRITE_BDT0001
PURPOSE:
Write a binary data file with size information and
variable names and units
CATEGORY:
File & I/O
CALLING SEQUENCE:
WRITE_BDT0001,filename,data,vardesc[,keywords]
INPUTS:
FILENAME -> Name of the file to write or a file mask
which will be used in the PICKFILE dialog. If the
filemask is a named variable, it will return the
actual filename.
DATA -> a 2D data array with dimensions LINES,VARIABLES
VARDESC -> A variable descriptor structure array (see
GTE_VARDESC). This array must contain one structure
for each variable and the structure must have the
tags NAME and UNIT. Alternatively, you can use the
NAMES and UNITS keywords to pass string arrays.
KEYWORD PARAMETERS:
NAMES -> A string array containing variable names. This
will only be used if no VARDESC structure array is
given.
UNITS -> A string array with physical units for each
variable. (see NAMES)
COMMENTS -> A string (or string array) with comment lines.
Only the first 80 characters of each line will be stored.
SELECTION -> An index array to select only a subset of
variables from the data set. Indices are truncated
to lie in the range 0..n_elements(names), which can
lead to multiple output of the same variable!
_EXTRA keywords are passed on to OPEN_FILE
Flags to determine the data type:
Default is to store the data in its current type. Use the
TYPE keyword to convert it to any other (numeric) type
or use one of the following keywords. The type information
is saved in the file, so READ_BDT0001 can automatically
read the data regardless of the format.
/BYTE -> convert data to byte format
/INT -> convert data to (2 byte) integer format
/LONG -> convert data to (4 byte) integer format
/FLOAT -> convert data to (4 byte) real format
/DOUBLE -> convert data to (8 byte) double prec. real format
/COMPLEX -> convert data to (8 byte) complex
/DCOMPLEX -> convert data to (16 byte) double complex
OUTPUTS:
None
SUBROUTINES:
Uses OPEN_FILE, STR2BYTE
REQUIREMENTS:
None
NOTES:
Format specification:
file_ID : 80 byte character string
NVARS, NLINES, NCOMMENTS, TYPE : 4 byte integer (long)
NAMES : NVARS*40 byte character string
UNITS : NVARS*40 byte character string
COMMENTS : NCOMMENTS records with 80 characters each
DATA : 8 byte float (double) array NLINES*NVARS
EXAMPLE:
WRITE_BDT0001,'~/tmp/*.bdt',data,vardesc
MODIFICATION HISTORY:
mgs, 24 Aug 1998: VERSION 1.00
mgs, 28 Aug 1998: - changed specs to allow comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now write data as big-endian
(See /n/home09/ryantosca/IDL/gamap2/file_io/write_bdt0001.pro)
NAME:
WRITE_BIN
PURPOSE:
Save a 2-D data array into a binary file together with
its size info. Use read_bin.pro to read it.;
CATEGORY:
File & I/O
CALLING SEQUENCE:
WRITE_BIN, data, filename, _EXTRA=e
INPUTS:
DATA -> Array to save to binary file format.
FILENAME -> Name of the output binary file.
KEYWORD PARAMETERS:
_EXTRA=e -> Passes extra keywords to OPEN_FILE
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
OPEN_FILE
REQUIREMENTS:
None
NOTES:
Use READ_BIN to read the data file.
EXAMPLES:
(1)
WRITE_BIN, DIST(20,20), 'myfile.bin'
; Writes a data array to a binary file.
(2)
WRITE_BIN, DIST(20,20), 'myfile.bin', /SWAP_ENDIAN
; Writes a data array to a binary file
; converts to BIG-ENDIAN (i.e. use this if
; you are running IDL on a PC.)
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now write data as big-endian
(See /n/home09/ryantosca/IDL/gamap2/file_io/write_bin.pro)
NAME:
XCOLORS
PURPOSE:
The purpose of this routine is to interactively change color tables
in a manner similar to XLOADCT. No common blocks are used so
multiple copies of XCOLORS can be on the display at the same
time (if each has a different TITLE). XCOLORS has the ability
to notify a widget event handler, an object method, or an IDL
procedure if and when a new color table has been loaded. The
event handler, object method, or IDL procedure is then responsibe
for updating the program's display on 16- or 24-bit display systems.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Color
CALLING SEQUENCE:
XCOLORS
INPUTS:
None.
KEYWORD PARAMETERS:
BLOCK: If this keyword is set, the program will try to block the
IDL command line. Note that this is only possible if no other
widget program is currently blocking the IDL command line. It
is much more reliable to make XCOLORS a modal widget (see the MODAL
keyword), although this can generally only be done when XCOLORS
is called from another widget program.
BOTTOM: The lowest color index of the colors to be changed.
COLORINFO: This output keyword will return either a pointer to
a color information structure (if the program is called in
a non-modal fashion) or a color information structure (if the program
is called in modal or blocking fashion). The color information
structure is an anonymous structure defined like this:
struct = { R: BytArr(!D.Table_Size), $ ; The current R color vector.
G: BytArr(!D.Table_Size), $ ; The current G color vector.
B: BytArr(!D.Table_Size), $ ; The current B color vector.
NAME: "", $ ; The name of the current color table.
INDEX: 0 } ; The index number of the current color table.
If a pointer to the structure is obtained, you will be responsible
for freeing it to prevent memory leakage:
XColors, ColorInfo=colorInfoPtr
Print, "Color Table Name: ", (*colorInfoPtr).Name
Ptr_Free, colorInfoPtr
Note that that Name field will be "Unknown" and the Index field will
be -1 until a color table is actually selected by the user. You are
responsible for checking this value before you use it.
When called in modal or blocking fashion, you don't have to worry about freeing
the pointer, since no pointer is involved:
XColors, /Block, ColorInfo=colorInfoData
Help, colorInfoData, /Structure
Print, "Color Table Name: ", colorInfoData.Name
DATA: This keyword can be set to any valid IDL variable. If
the variable is defined, the specified object method or notify
procedure will be passed this variable via a DATA keyword. This
keyword is defined primarily so that Notify Procedures are compatible
with the XLOADCT way of passing data. It is not strictly required,
since the _EXTRA keyword inheritance mechanism will allow passing
of *any* keyword parameter defined for the object or procedure that is
to be notified.
DRAG: Set this keyword if you want colors loaded as you drag
the sliders. Default is to update colors only when you release
the sliders.
_EXTRA: This keyword inheritance mechanism will pick up and
pass along to any method or procedure to be notified and keywords
that are defined for that procedure. Note that you should be sure
that keywords are spelled correctly. Any mis-spelled keyword will
be ignored.
FILE: A string variable pointing to a file that holds the
color tables to load. The normal colors1.tbl file is used by default.
GROUP_LEADER: The group leader for this program. When the group
leader is destroyed, this program will be destroyed.
INDEX: The index of the color table to start up. If provided, a color
table of this index number is loaded prior to display. Otherwise,
the current color table is used. Set this keyword if you wish
to have the index number of the event structure correct when
the user CANCELs out of the progam.
MODAL: Set this keyword (along with the GROUP_LEADER keyword) to
make the XCOLORS dialog a modal widget dialog. Note that NO
other events can occur until the XCOLORS program is destroyed
when in modal mode.
NCOLORS: This is the number of colors to load when a color table
is selected.
NOSLIDERS: If this keyword is set, the color stretch and color gamma
sliders are not displayed. This would be appropriate, for example,
for programs that just load pre-defined color tables.
NOTIFYID: A 2-column by n-row array that contains the IDs of widgets
that should be notified when XCOLORS loads a color table. The first
column of the array is the widgets that should be notified. The
second column contains IDs of widgets that are at the top of the
hierarchy in which the corresponding widgets in the first column
are located. (The purpose of the top widget IDs is to make it
possible for the widget in the first column to get the "info"
structure of the widget program.) An XCOLORS_LOAD event will be
sent to the widget identified in the first column. The event
structure is defined like this:
event = {XCOLORS_LOAD, ID:0L, TOP:0L, HANDLER:0L, $
R:BytArr(!D.TABLE_SIZE < 256), G:BytArr(!D.TABLE_SIZE < 256), $
B:BytArr(!D.TABLE_SIZE < 256), INDEX:0, NAME:""}
The ID field will be filled out with NOTIFYID[0, n] and the TOP
field will be filled out with NOTIFYID[1, n]. The R, G, and B
fields will have the current color table vectors, obtained by
exectuing the command TVLCT, r, g, b, /Get. The INDEX field will
have the index number of the just-loaded color table. The name
field will have the name of the currently loaded color table.
Note that XCOLORS can't initially tell *which* color table is
loaded, since it just uses whatever colors are available when it
is called. Thus, it stores a -1 in the INDEX field to indicate
this "default" value. Programs that rely on the INDEX field of
the event structure should normally do nothing if the value is
set to -1. This value is also set to -1 if the user hits the
CANCEL button. (Note the NAME field will initially be "Unknown").
Typically the XCOLORS button will be defined like this:
xcolorsID = Widget_Button(parentID, Value='Load New Color Table...', $
Event_Pro='Program_Change_Colors_Event')
The event handler will be written something like this:
PRO Program_Change_Colors_Event, event
; Handles color table loading events. Allows colors be to changed.
Widget_Control, event.top, Get_UValue=info, /No_Copy
thisEvent = Tag_Names(event, /Structure_Name)
CASE thisEvent OF
'WIDGET_BUTTON': BEGIN
; Color table tool.
XColors, NColors=info.ncolors, Bottom=info.bottom, $
Group_Leader=event.top, NotifyID=[event.id, event.top]
ENDCASE
'XCOLORS_LOAD': BEGIN
; Update the display for 24-bit displays.
Device, Get_Visual_Depth=thisDepth
IF thisDepth GT 8 THEN BEGIN
WSet, info.wid
...Whatever display commands are required go here. For example...
TV, info.image
ENDIF
ENDCASE
ENDCASE
Widget_Control, event.top, Set_UValue=info, /No_Copy
END
NOTIFYOBJ: A vector of structures (or a single structure), with
each element of the vector defined as follows:
struct = {XCOLORS_NOTIFYOBJ, object:Obj_New(), method:''}
where the Object field is an object reference, and the Method field
is the name of the object method that should be called when XCOLORS
loads its color tables.
ainfo = {XCOLORS_NOTIFYOBJ, a, 'Draw'}
binfo = {XCOLORS_NOTIFYOBJ, b, 'Display'}
XColors, NotifyObj=[ainfo, binfo]
Note that the XColors program must be compiled before these structures
are used. Alternatively, you can put this program, named
"xcolors_notifyobj__define.pro" (*three* underscore characters in this
name!) in your PATH:
PRO XCOLORS_NOTIFYOBJ__DEFINE
struct = {XCOLORS_NOTIFYOBJ, OBJECT:Obj_New(), METHOD:''}
END
Or, you can simply define this structure as it is shown here in your code.
"Extra" keywords added to the XCOLORS call are passed along to
the object method, which makes this an alternative way to get information
to your methods. If you expect such keywords, your methods should be defined
with an _Extra keyword.
NOTIFYPRO: The name of a procedure to notify or call when the color
tables are loaded. If the DATA keyword is also defined, it will
be passed to this program via an DATA keyword. But note that *any*
keyword appropriate for the procedure can be used in the call to
XCOLORS. For example, here is a procedure that re-displays and image
in the current graphics window:
PRO REFRESH_IMAGE, Image=image, _Extra=extra, WID=wid
IF N_Elements(wid) NE 0 THEN WSet, wid
TVIMAGE, image, _Extra=extra
END
This program can be invoked with this series of commands:
IDL> Window, /Free
IDL> TVImage, image, Position=[0.2, 0.2, 0.8, 0.8]
IDL> XColors, NotifyPro='Refresh_Image', Image=image, WID=!D.Window
Note that "extra" keywords added to the XCOLORS call are passed along to
your procedure, which makes this an alternative way to get information
to your procedure. If you expect such keywords, your procedure should
be defined with an _Extra keyword as illustrated above.
TITLE: This is the window title. It is "Load Color Tables" by
default. The program is registered with the name 'XCOLORS:' plus
the TITLE string. The "register name" is checked before the widgets
are defined. If a program with that name has already been registered
you cannot register another with that name. This means that you can
have several versions of XCOLORS open simultaneously as long as each
has a unique title or name. For example, like this:
IDL> XColors, NColors=100, Bottom=0, Title='First 100 Colors'
IDL> XColors, NColors=100, Bottom=100, Title='Second 100 Colors'
XOFFSET: This is the X offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
YOFFSET: This is the Y offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Colors are changed. Events are sent to widgets if the NOTIFYID
keyword is used. Object methods are called if the NOTIFYOBJ keyword
is used. This program is a non-blocking widget.
RESTRICTIONS:
None.
EXAMPLE:
To load a color table into 100 colors, starting at color index
50 and send an event to the widget identified at info.drawID
in the widget heirarchy of the top-level base event.top, type:
XCOLORS, NCOLORS=100, BOTTOM=50, NOTIFYID=[info.drawID, event.top]
MODIFICATION HISTORY:
Written by: David W. Fanning, 15 April 97. Extensive modification
of an older XCOLORS program with excellent suggestions for
improvement by Liam Gumley. Now works on 8-bit and 24-bit
systems. Subroutines renamed to avoid ambiguity. Cancel
button restores original color table.
23 April 1997, added color protection for the program. DWF
24 April 1997, fixed a window initialization bug. DWF
18 June 1997, fixed a bug with the color protection handler. DWF
18 June 1997, Turned tracking on for draw widget to fix a bug
in TLB Tracking Events for WindowsNT machines in IDL 5.0. DWF
20 Oct 1997, Changed GROUP keyword to GROUP_LEADER. DWF
19 Dec 1997, Fixed bug with TOP/BOTTOM reversals and CANCEL. DWF.
9 Jun 1998, Fixed bug when using BOTTOM keyword on 24-bit devices. DWF
9 Jun 1998, Added Device, Decomposed=0 for TrueColor visual classes. DWF
9 Jun 1998, Removed all IDL 4 compatibility.
21 Oct 1998, Fixed problem with gamma not being reset on CANCEL. DWF
5 Nov 1998. Added the NotifyObj keyword, so that XCOLORS would work
interactively with objects. DWF.
9 Nov 1998. Made slider reporting only at the end of the drag. If you
want continuous updating, set the DRAG keyword. DWF.
9 Nov 1998. Fixed problem with TOP and BOTTOM sliders not being reset
on CANCEL. DWF.
10 Nov 1998. Fixed fixes. Sigh... DWF.
5 Dec 1998. Added INDEX field to the XCOLORS_LOAD event structure. This
field holds the current color table index number. DWF.
5 Dec 1998. Modified the way the colorbar image was created. Results in
greatly improved display for low number of colors. DWF.
6 Dec 1998. Added the ability to notify an unlimited number of objects. DWF.
12 Dec 1998. Removed obsolete Just_Reg keyword and improved documetation. DWF.
30 Dec 1998. Fixed the way the color table index was working. DWF.
4 Jan 1999. Added slightly modified CONGRID program to fix floating divide
by zero problem. DWF
2 May 1999. Added code to work around a Macintosh bug in IDL through version
5.2 that tries to redraw the graphics window after a TVLCT command. DWF.
5 May 1999. Restore the current window index number after drawing graphics.
Not supported on Macs. DWF.
9 Jul 1999. Fixed a couple of bugs I introduced with the 5 May changes. Sigh... DWF.
13 Jul 1999. Scheesh! That May 5th change was a BAD idea! Fixed more bugs. DWF.
31 Jul 1999. Substituted !D.Table_Size for !D.N_Colors. DWF.
1 Sep 1999. Got rid of the May 5th fixes and replaced with something MUCH simpler. DWF.
14 Feb 2000. Removed the window index field from the object notify structure. DWF.
14 Feb 2000. Added NOTIFYPRO, DATA, and _EXTRA keywords. DWF.
20 Mar 2000. Added MODAL, BLOCK, and COLORINFO keywords. DWF
20 Mar 2000. Fixed a slight problem with color protection events triggering
notification events. DWF.
31 Mar 2000. Fixed a problem with pointer leakage on Cancel events, and improved
program documentation. DWF.
17 Aug 2000. Fixed a problem with CANCEL that occurred only if you first
changed the gamma settings before loading a color table. DWF.
10 Sep 2000. Removed the requirement that procedures and object methods must
be written with an _Extra keyword. DWF.
5 Oct 2000. Added the File keyword to LOADCT command, as I was suppose to. DWF.
5 Oct 2000. Now properly freeing program pointers upon early exit from program. DWF.
7 Mar 2001. Fixed a problem with the BLOCK keyword. DWF.
12 Nov 2001. Renamed Congrid to XColors_Congrid. DWF.
14 Aug 2002. Moved the calculation of NCOLORS to after the draw widget creation
to fix a problem with !D.TABLE_SIZE having a correct value when no windows had
been opened in the current IDL session. DWF.
14 Aug 2002. Fixed a documentation problem in the NOTIFYID keyword documentation
that still referred to !D.N_COLORS instead of the current !D.TABLE_SIZE. DWF.
27 Oct 2003. Added INDEX keyword. DWF.
29 July 2004. Fixed a problem with freeing colorInfoPtr if it didn't exist. DWF.
5 December 2005. Added NOSLIDERS keyword and performed some small cosmetic changes. DWF.
27 Sep 2006. Fixed a problem in which XCOLORS set device to indexed color mode. DWF.
bmy, 21 Apr 2008: GAMAP VERSION 2.12
- Added XCOLORS into GAMAP v2-12 unmodified,
except for minor comment header changes, e.g.:
* added ID tag for CVS repository
* also changed category to "Color" for
compatibility w/ GAMAP documentation
(See /n/home09/ryantosca/IDL/gamap2/color/xcolors.pro)
NAME:
YBOXPLOT
PURPOSE:
Produce a box and whisker plot of a data vector
categories displayed on the Y axis as opposed to boxplot
CATEGORY:
Plotting
CALLING SEQUENCE:
YBOXPLOT, DATA [,keywords]
INPUTS:
DATA -> the data vector
KEYWORD PARAMETERS:
GROUP -> array of the same dimension as DATA which contains
grouping information. One box is plotted for each group.
If MINGROUP or MAXGROUP are given, boxes and whiskers are
only plotted for group values within this range.
GROUP may not contain more than 28 different values.
Group can also be a string array. In this case MINGROUP
and MAXGROUP make no sense of course.
MINGROUP -> the minimum group value for which a box shall be
plotted
MAXGROUP -> the maximum group value for which a box shall be
plotted
LABEL -> string array containing labels for *different* groups.
NOTE: The user must take care that one label is passed for
each group to be plotted. If label is not specified, the
group values will be used as axis labels
COLOR -> plotting color for axis (default : 1, i.e. black in MYCT
color scheme). Will also be used as default for BOXCOLOR.
BOXCOLOR -> color of the boxes (frames). Default is the COLOR
value, i.e. 1 if not specified. This color will also be used as
default for MEDIANCOLOR and MEANCOLOR. If you want boxes that
are only filled but have no frame, you must specify BOXCOLOR=-1.
In this case the default for MEDIANCOLOR and MEANCOLOR will
be the COLOR value.
BOXWIDTH -> relative width of boxes (default: 0.8).
BOXPOSITION -> relative position of box on x axis (default: 0.).
This parameter can be used together with the OVERPLOT keyword
to plot multiple groups of boxes in one graph.
MEDIANCOLOR -> a color value for the median bar
(default: value of BOXCOLOR)
MEANSYMBOL -> symbol to be used for mean values. If no symbol
is given, no mean values will be drawn.
MEANCOLOR -> color for mean symbols (default: value of BOXCOLOR)
FILLCOLOR -> a value or an array containing the colorindex for all
boxes or each box, respectively. If a single value is given,
*all* boxes will be filled with this color. If an array is
passed that has less elements than there are groups to plot,
the remaining colors will be filled with 15 (grey in MYCT
standard-scheme). If no FILLCOLOR is specified, the boxes will
be empty.
MISSING -> a value that represents missing data. If given, any data
with a value of missing will be filtered out before plotting.
PRINTN -> print number of elements on top of each box/whisker
CHARSIZE -> character size of the PRINTN labels (default: 0.8)
/OVERPLOT -> do not draw a new coordinate system but overlay new
data. For 2 sets of data you should use BOXWIDTH=0.4 and
BOXPOSITION=-0.25 and 0.25, respectively.
ORIENTATION -> orientation for axis labels (see XYOUTS procedure)
/IS_PERCENTILE -> data are already processed percentiles. In this
case data must be an array with dimensions 5,N. The GROUP keyword
is ignored, and each set of the N percentiles will be treated as
one group.
PERCVAL -> float array with 5 elements denoting the percentile
values (default: 0.05, 0.25, 0.5, 0.75, 0.95)
Further keywords are passed to the PLOT routine and can be used
to determine the appearance of the plot (e.g. XTITLE,YTITLE,
YSTYLE,YRANGE,/YLOG,COLOR,THICK)
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================
PERCENTILES (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
O3 = DATA( where( header eq 'O3' ), * )
ALT = DATA( WHERE( HEADER EQ 'ALT' ), * )
IALT = 2.0 * FIX( ALT / 2.0 )
YBOXPLOT, O3, GROUP=IALT
; produces a boxplot with ozone percentiles in
; altitude bins of 2 (km). Axis, box frames and
; labels will be black, boxes are not color filled.
(2)
YBOXPLOT, O3, GROUP=IALT, FILLC=15, MEANSYM=SYM(1), $
MEANCOL=!MYCT.RED, BOXWIDTH=0.6, YTITLE='O3', $
XTITLE='ALT. BIN', MISSING=-999.99, /PRINTN
; produces boxes that are filled with light grey and
; have a black frame and median line. A red filled
; circle denotes the mean value, titles are assigned
; to the x and y axis. The number of valid observations
; is printed on top of each box. The boxes are reduced
; in size.
(3)
CO = DATA( WHERE( HEADER EQ 'CO' ), * )
YBOXPLOT, O3, GROUP=IALT, MISSING=-999.99, $
BOXCOL=!MYCT.BLUE, BOXWIDTH=0.4, BOXPOS=-0.25
YBOXPLOT, CO, GROUP=IALT, MISSING=-999.99, $
BOXCOL=!MYCT.RED, BOXWIDTH=0.4, BOXPOS=+0.25, /OVERPLOT
; produces a plot with blue box frames for ozone
; and red frames for CO data.
MODIFICATION HISTORY:
mgs, 30 Jul 1997: VERSION 1.00
mgs, 03 Aug 1997: added template
mgs, 27 Nov 1997: some revisions and suggested changes by T.Brauers:
- better color handling (NOTE: meaning of BOXCOLOR has changed)
- optional overlay of mean value
- box frames
- variable boxwidth
- error fixing lower upper boundaries in log plots
- bug fix with label keyword
- added OVERPLOT and BOXPOSITION keywords
mgs, 22 Jan 1998: added IS_PERCENTILE keyword to allow
plotting of data that has been processed already
mgs, 17 Apr 1998:
- x-axis handling improved (now uses axis command and xyouts)
- orientation and medianthick keywords added
- CREATED as yboxplot
mgs, 06 May 1998:
- added percval keyword
mgs, 21 May 1998:
- percval defaults changed from min,max to 5%, 95%
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/plotting/yboxplot.pro)
NAME:
YESNO
PURPOSE:
Query user for decisions with only two possible answers.
CATEGORY:
General
CALLING SEQUENCE:
ANSWER = YESNO( QUESTION [,DEFAULT=DEFAULT ,/STRING ] )
INPUTS:
QUESTION -> A string containing the query. The following
will automatically be added to QUESTION: ' (Y/N) [x] : '
where x is replaced by the default selection.
KEYWORD PARAMETERS:
DEFAULT -> either 0 (for 'NO') or 1 (for 'YES'). Default is 0.
/QUIT_OPTION -> if set, the user can quit with 'Q'. This
option is appended to the (Y/N) string. YesNo returns
-1 if quit was selected.
/STRING -> set this keyword to return a 'Y' or 'N' instead
of the numerical values 0 or 1.
OUTPUTS:
ANSWER -> An integer 0 or 1 that can be used in boolean
expressions, or a 1 character string if /STRING is set.
-1 is returned if /QUIT was allowed and used.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
'0' or '1' are also accepted as input. Everything but
'y', 'Y', '1' is treated as 'N'. 'Q' or 'C' can both
be used to quit.
EXAMPLES:
(1)
IF ( YESNO( 'Shall we meet today?', DEFAULT=1) ) $
THEN GOTO, MEETING
(2)
ANS = YESNO( 'Do you really want to quit?' )
if ( ans ) then return
(3)
ANS = YESNO( 'Save data ?', /QUIT, default=1 )
IF ( ANS LT 0 ) THEN RETURN
MODIFICATION HISTORY:
mgs, 22 Jan 1999: VERSION 1.00
mgs, 23 Mar 1999: - added /QUIT option
- bug fix: '0' was recognized as 'Y'
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/yesno.pro)
NAME:
YMD2DATE
PURPOSE:
Given year, month, day (or hour, minute, second) values,
returns a variable in YYYYMMDD (or HHMMSS) format.
CATEGORY:
Date & Time
CALLING SEQUENCE:
RESULT = YMD2DATE( YEAR, MONTH, DAY )
INPUTS:
YEAR -> Year (or hour ) value
MONTH -> Month (or minute) value
DAY -> Day (or second) value
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, YMD2DATE( 2006, 1, 1 )
20060101
; Takes separate Y, M, D values and creates a date variable.
PRINT, YMD2DATE( 12, 30, 0 )
123000
; Takes separate H, Mi, S values and creates a time variable.
MODIFICATION HISTORY:
bmy, 06 Jun 2006: TOOLS VERSION 2.05
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/date_time/ymd2date.pro)
NAME:
ZMID (function)
PURPOSE:
Given a vector of altitudes at vertical edges of a model grid
computes the altitudes at the grid centers.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = ZMID( EDGE )
INPUTS:
EDGE -> Vector of altitude edges that defines the grid.
EDGE will be sorted in ascending order.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Altitudes at grid centers [m, km, etc]
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The relationship between altitude centers and edges is:
ZMID[N] = ( ZEDGE[N] + ZEDGE[N+1] ) / 2.0
EXAMPLE:
PRINT, ZMID( [ 0.0, 2.0, 4.0, 6.0, 8.0 ] )
1.00000 3.00000 5.00000 7.00000
; Given the altitude at grid edges at 0, 2, 4, 6, 8 km
; returns the altitude at grid centers.
;
MODIFICATION HISTORY:
bmy, 21 Jun 1999: VERSION 1.00
bmy, 22 Oct 1999: VERSION 1.44
- Now use SHIFT to compute the average
between successive edges
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/zmid.pro)
NAME:
ZONAL
PURPOSE:
Creates zonal-mean curtain plots of GEOS-Chem tracers
CATEGORY:
Benchmarking
CALLING SEQUENCE:
ZONAL, FILE, LONS, TAUS, TRACERS, VERSION, [, Keywords ]
INPUTS:
FILE -> The name of the file containing data to be plotted.
LONS -> Longitudes to plot
TAU -> The TAU value (hours GMT from /1/1985) corresponding
to the data to be plotted.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSION -> The model version number corresponding to the
data to be plotted.
KEYWORD PARAMETERS:
/DO_FULLCHEM -> Set this switch to plot the chemically
produced OH in addition to the advected tracers.
/PRESSURE -> Set this switch to plot pressure on the Y-axis.
The default is to plot altitude on the Y-axis.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Provided:
==================================================
PlotZonal
External Subroutines Required:
==================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA EXTRACT_FILENAME (function)
GETMODELANDGRIDINFO MULTIPANEL
MYCT OPEN_DEVICE
TVMAP CHKSTRU (function)
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILE = 'ctm.bpch.v7-04-11'
LEVELS = [ 1, 1, 13, 13 ]
TAUS = NYMD2TAU( 20010701 )
TRACERS = INDGEN( 43 ) + 1
VERSIONS = 'v7-04-11'
ZONAL, FILE, LONS, TAU, TRACERS, VERSION, $
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'
MODIFICATION HISTORY:
cdh, 01 May 2012: Created zonal.pro based on maps.pro
bmy, 29 May 2013: GAMAP VERSION 2.17
- Remove reference to MEAN2 function
mps, 07 Aug 2013: - Now plot chemically produced HO2
mps, 10 Sep 2015: - Added /PRESSURE keyword to plot pressure
on the Y-axis (instead of altitude)
(See /n/home09/ryantosca/IDL/gamap2/benchmark/zonal.pro)
NAME:
ZONAL_DIFF
PURPOSE:
Creates zonal mean absolute and percent difference plots
of tracers from the GEOS-Chem 1-month benchmark simulations.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
ZONAL_DIFF, FILES, TAUS, TRACERS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "old" and "new" GEOS-Chem model versions
that are to be compared.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSIONS -> A 2-element vector containing the version
numbers for the "old" and "new" GEOS-Chem model
versions.
KEYWORD PARAMETERS:
/DO_FULLCHEM -> Set this switch to plot the chemically
produced OH in addition to the advected tracers.
/DYNRANGE -> Set this switch to create plots using the whole
dynamic range of the data. Default is to restrict
the plot range to predetermined values as returned
by routine GET_DIFF_RANGE.
/PRESSURE -> Set this switch to plot pressure on the Y-axis.
The default is to plot altitude on the Y-axis.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
ZDFORMAT -> This keyword passes a colorbar format string
(Fortran-style) to the COLORBAR routine (via TVPLOT).
This keyword is purposely not named CBFORMAT, in order
to avoid passing this quantity to other routines.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Included:
==================================================
PlotZonalAbsDiff PlotZonalPctDiff
External Subroutines Required:
==================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA GET_DIFF_RANGE (function)
GETMODELANDGRIDINFO EXTRACT_FILENAME (function)
MULTIPANEL CHKSTRU (function)
MYCT OPEN_DEVICE
TVPLOT UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLE:
FILES = [ 'ctm.bpch.v9-01-01', 'ctm.bpch.v9-01-02a' ]
TAUS = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
TRACERS = INDGEN( 43 ) + 1
VERSIONS = [ 'v9-01-01', 'v9-01-02a' ]
ZONAL_DIFFS, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, $
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'
; Creates zonal mean difference plots of two GEOS-Chem
; versions; (in this case v9-01-01 / v9-01-01a) for
; July 2001. Output is sent to the PostScript file
; "myplot.ps". The min and max of the data on each plot
; panel is restricted to pre-defined values returned by
; function GET_DIFF_RANGE.
ZONAL_DIFFS, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, $
/DYNRANGE, /PS, OUTFILENAME='myplot.ps'
; Same as the above example, but the min & max of
; each plot panel corresponds to the dynamic range
; of the data (centered around zero).
MODIFICATION HISTORY:
bmy, 21 Jun 2011: VERSION 1.01
- Initial version, based on profiles.pro
bmy, 18 Jul 2011: - Added /PRESSURE keyword to plot pressure
on the Y-axis (instead of altitude)
bmy, 11 May 2012: GAMAP VERSION 2.16
- Now allow comparision of equivalent model
grids, even if the model names differ
(e.g. GEOS5_47L, MERRA_47L, GEOSFP_47L)
mps, 29 Mar 2013: - Now plot HO2 difference profiles
mps, 07 Aug 2013: - Now plot OH differences everywhere to fix bug
- Pre-defined range for ratio plots is now set to
+/- 30, so that we only plot ratios > 10%
- Cap dynamic range ratio plots at 1000% to avoid
going beyong max number of digits for colorbar
mps, 01 Oct 2015: - Include MERRA2 in the check for equivalent
vertical grids
(See /n/home09/ryantosca/IDL/gamap2/benchmark/zonal_diff.pro)
NAME:
ZSTAR (function)
PURPOSE:
Computes pressure-altitudes from pressures.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = ZSTAR( PRESS )
INPUTS:
PRESS -> The input pressure value, in [hPa].
PRESS can be either a scalar or a vector.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Computed pressure altitude(s) [km]
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
Pressure-altitude is defined as:
Z* = 16 * log10[ 1000 / P(mb) ]
which, by the Laws of Logarithms, is equivalent to
Z* = 48 - ( 16 * log10[ P(mb) ] ).
EXAMPLE:
PRINT, ZSTAR( [ 900, 700, 500 ] )
0.732121 2.47843 4.81648
; Returns pressure-altitudes at 900, 700, 500 hPa
MODIFICATION HISTORY:
bmy, 21 Jun 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/zstar.pro)