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)