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:
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)