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