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:
COMPARE_FLIGHT
PURPOSE:
Compare observations from aircraft campaigns to
high time-resolution CTM output (bpch files).
This routine reads aircraft data in binary (bdt) format
and produces an unlabeld plot and returns all the data
you might ask for. If an aircraft mission extends beyond
midnight GMT, the program will ask for a second model file
which should be from the following day.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
COMPARE_FLIGHT, keywords
INPUTS:
None
KEYWORD PARAMETERS:
DATAFILE -> Name of the aircraft data file or file mask
MODELFILE -> Name of the (first) model output file or file mask
TRACER -> tracer number in model output (default=71)
PSURF -> surface pressure for model grid (default=1013, because most
aircraft data was sampled over oceans)
FLIGHTDATA -> returns the observational data array as read
with gte_readbin. Can also be used to pass flight data if you
set the USE_DATA flag.
FLIGHTVARS -> returns the variable names of the observational data.
Must accompany FLIGHTDATA if you use USE_DATA.
SPECIES -> the name of the observed species to plot (default CH3I).
MODELDATA -> returns a time series of model data along the flight
track and a couple of min/max values:
MODELDATA[*,0] = model value in corresponding grid box
[*,1] = min of neighbouring grid boxes at same level
[*,2] = max ...
[*,3] = min of neighbouring grid boxes at level below
[*,4] = max ...
[*,5] = min of neighbouring grid boxes at level above
[*,6] = max ...
Note that the min/max arrays may contain values from the same
grid boxes at the edges (i.e. there is no level below the first
one, hence 3,4 will be identical to 1,2).
TIME -> returns the time vector of the observations and modeldata
/USE_DATA -> set this flag if you provide the aircraft data in the
FLIGHTDATA array and the variable names in FLIGHTVARS. The data
must contain variables named 'LON', 'LAT', 'ALTP' and SPECIES
(for SPECIES see above). You must also provide a TIME vector
which specifies UTC seconds.
OUTPUTS:
The extracted data is returned in MODELDATA, several other keywords
return things read or computed in the process.
SUBROUTINES:
EXTRACT__FLIGHT : actual workhorse that does the extraction
REQUIREMENTS:
chkstru, ctm_get_data (GAMAP), gte_readbin (GTE)
NOTES:
Some hardwiring of default directories.
EXAMPLE:
simply COMPARE_FLIGHT,tracer=1 if all you want is a plot
CONVERT_FLIGHT,tracer=1,modeldata=md,time=time
plot,time,md[*,0],color=1
MODIFICATION HISTORY:
mgs, 21 Apr 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/compare_flight.pro)
NAME:
CTM_LABEL (function)
PURPOSE:
Returns strings for several CTM quantities.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
RESULT = CTM_LABEL( DATAINFO, MODELINFO [, Keywords ] )
INPUTS:
DATAINFO -> Structure returned from CTM_GET_DATA, which
contains information about one data block
MODELINFO -> Structure returned from CTM_TYPE, which
contains information about the particular model
KEYWORD PARAMETERS:
AVERAGE -> Bit flag indicating the dimensions over which
to average the data:
1 : longitudinal
2 : latitudinal
4 : vertical
These values can be combined. E.g., to average over
longitude and latitude use 3. A bit set in AVERAGE
supersedes the corresponding bit in TOTAL (see below).
LAT -> Scalar value or array of latitudes used in the plot.
LON -> Scalar value or array of longitudes used in the plot.
LEV -> Scalar value or array of latitudes used in the plot.
ALT -> Scalar value or array of altitudes used in the plot.
PRS -> Scalar value or array of pressures used in the plot.
TOTAL -> Bit flag indicating the dimensions over which
to sum the data:
1 : longitudinal
2 : latitudinal
4 : vertical
These values can be combined. E.g., to integrate over
longitude and latitude use 3. A bit set in AVERAGE
supersedes the corresponding bit in TOTAL (see above).
FORMAT -> Specifies format for converting numeric values into
string values, for selected fields (such as LAT and LON).
Default is I14 (strings are trimmed).
/NO_SPECIAL -> If set, will not place any special superscript
or subscript characters into the strings returned in
LABELSTRU.
OUTPUTS:
LABELSTRU -> Structure containing the following label fields:
LAT: String for latitude(s)
LON: String for longitude(s)
LEV: String for vertical level(s)
ALT: String for altitude level(s)
PRS: String for pressure level(s)
LATLON: String that has format "(Lat,Lon)"
TRACERNAME: String for the tracer name
SCALE: String for the tracer's scale factor
UNIT: String for the tracer's unit
TAU0: String representation of TAU0
TAU1: String representation of TAU1
YMD0: String representation of (YY)YYMMDD
corresponding to TAU0
YMD1: String representation of (YY)YYMMDD
corresponding to TAU1
HMS0: String representation of HHMMSS
corresponding to TAU0
HMS1: String representation of HHMMSS
corresponding to TAU1
YEAR0: String for the starting year (e.g. 1994)
YEAR1: String for the ending year
MONTH0: String for the starting month name
(e.g. "Jan", "Feb", "Mar", etc..)
MONTH1: String for the ending month name
DAY0: String for the starting day number (1-31)
DAY1: String for the ending day number (1-31)
DATE: String for the date (see below)
MODEL: String for the model name
FAMILY String for the model's family
RES: String for the resolution of the model
SUBROUTINES:
External Subroutines Required:
==============================================
CHKSTRU (function) STRCHEM (function)
STRSCI (function) TAU2YYMMDD (function)
REQUIREMENTS:
DATAINFO and MODELINFO must be passed to CTM_LABEL. These
structures are computed by the GAMAP package subroutines.
NOTES:
DATAINFO is created e.g. by CTM_GET_DATA (or CTM_GET_DATABLOCK)
MODELINFO is created by CTM_TYPE
EXAMPLE:
CTM_LABEL, DataInfo, ModelInfo, LabelStru, Lat=10, Lon=48
print, LabelStru.LAT
'Lat=10!UN!N'
MODIFICATION HISTORY:
bmy, 23 Sep 1998: VERSION 1.00
bmy, 24 Sep 1998: - now ensure that RES is a scalar string
- place TAU2YYMMDD in FORWARD_FUNCTION call
bmy, 28 Sep 1998: VERSION 1.01
- formats for LatStr, LonStr, LevStr
changed to be more consistent.
mgs, 29 Sep 1998: - changed a few comments and fixed bug in
MinLon/MaxLon
bmy, 03 Nov 1998: - changed NAME to TRACERNAME for
the sake of consistency
bmy, 12 Nov 1998: - added LABELSTRU structure tags: YEAR0,
YEAR1, MONTH0, MONTH1, DAY0, DAY1, and DATE
- now reports lats as S/N instead of -/+
and reports lons as W/E instead of -/+
bmy, 17 Nov 1998: - now use function N_UNIQ to test for
the number of unique elements in
LAT, LON, LEV, ALT, PRS
- Added FORMAT keyword to specify
format for LAT and LON strings
- updated comments
bmy, 15 Jan 1999: - added NO_SPECIAL keyword
bmy, 17 Feb 1999: - Now add GMT to date string for timeseries
animation plots (interval < 1 day)
- make sure that HMS0STR and HMS1STR have
string lengths of 6 characters
bmy, 18 Feb 1999: - fix default DATE string for February
mgs, 16 Mar 1999: - cosmetic changes
- removed SUBTRACT_ONE keyword and improved
choice of date format
bmy, 13 Jul 2001: GAMAP VERSION 1.48
- Use updated version of STRREPL.PRO from mgs
bmy, 07 Nov 2001: GAMAP VERSION 1.49
- now use 8-digit YYYYMMDD format for
date variables YMD0, YMD1
bmy, 02 Oct 2002: GAMAP VERSION 1.53
- now write GEOS3 instead of GEOS3_30L
bmy, 05 Nov 2003: GAMAP VERSION 2.01
- now write GEOS4 instead of GEOS3_30L
- now use the proper time epoch for each
model family in call to TAU2YYMMDD
- updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_label.pro)
NAME:
CTM_OVERLAY
PURPOSE:
Calls TVMAP to plot a pixel or contour map and then overplots
either an aircraft flight track or individual station data
atop it.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_OVERLAY, DATA, XMID, YMID, $
TRACKD, TRACKX, TRACKY [, Keywords ]
INPUTS:
DATA -> Data array (e.g. from CTM_GET_DATA or CTM_GET_DATABLOCK)
from which a pixel plot or contour plot will be generated.
XMID -> Vector of longitudes corresponding to DATA.
YMID -> Vector of latitudes corresponding to DATA
TRACKD -> Vector of data values corresponding to the aircraft
flight track or station data points.
TRACKX -> Vector of longitudes corresponding to the aircraft
flight track or station data points. Should be in the
range [-180,180].
TRACKY -> Vector of longitudes corresponding to the aircraft
flight track or station data points. Should be in the
range [-90,90].
KEYWORD PARAMETERS:
C_COLORS -> Vector to specify the color levels for filled
contour plots. If not passed, then C_COLORS will return
to the calling program the default color level values
generated internally by TVMAP.
C_LEVELS -> Vector containing contour levels for filled
contour plots. Used in conjunction with /FCONTOUR.
COLOR -> Color of the map outline. Passed to TVMAP.
/FCONTOUR -> Set this switch to generate a filled-contour
plot instead of a pixel plot.
/LOG -> Set this switch to use a logarithmic color table.
MINDATA -> Minimum value of DATA. If omitted, then MINDATA
will be automatically set to the minimum value of DATA.
MAXDATA -> Minimum value of DATA. If omitted, then MINDATA
will be automatically set to the minimum value of DATA.
/OVERPLOT -> Set this keyword to overplot a flight track
atop a map previously drawn by TVMAP.
T_COLOR -> (1) If plotting aircraft flight track data, then
T_COLOR will be used to define the color of the line.
(2) If plotting symbol data, then T_COLOR will be used to
describe the color of the border around the symbol.
To suppress printing a border around the symbol, use
any negative value for T_COLOR (e.g. T_COLOR = -1).
T_LINESTYLE -> IDL linestyle for the aircraft flight track.
Takes same values as the LINESTYLE graphic keyword
(see help pages).
T_SYMBOL -> Argument to the SYM keyword, which will be used
to define the individual data points if you are plotting
station data. Recommended value: 1 (filled circle).
T_THICK -> Thickness of the aircraft flight track, in pixels.
_EXTRA=e -> Passes extra keywords to TVMAP and OPLOT.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
==========================================
SCALETRACK (function)
External Subroutines Required:
=========================================
MULTIPANEL MYCT_DEFAULTS (function)
TVMAP RECTANGLE
SYM (function)
REQUIREMENTS:
None
NOTES:
You can pass all of the same keywords to CTM_OVERLAY_FLIGHT
as you do to TVMAP.
EXAMPLE:
(1) Plot flight tracks atop a pixel or contour map
--------------------------------------------------
; Read the data -- in this case, CO concentrations
SUCCESS = CTM_Get_DataBlock( Data, 'IJ-AVG-$', $
File='ctm.bpch.1995', $
Tra=4, $
/First, $
Lon=[-180, 180], $
Lat=[-88, 88], $
Lev=1, $
XMid=XXmid, Ymid=YYMid )
; Make a "fake" aircraft track
; Here we'll use MAP_2POINTS to create a "fake" flight
; track of constant longitude (30 deg E meridian)
nPts = 101
a = MAP_2POINTS( 30, -90, 30, 90, NPATH=NPTS )
TrackX = A[0,*]
TrackY = A[1,*]
TrackD = FltArr( nPts )
; Plot a pixel map w/ countries, continents, grid lines,
; and overlay a red, dashed-line flight track atop it.
CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
/Sample, /Countries, /Coasts, /CBar, $
Div=4, Min_Val=1e-20, /Isotropic, /Grid, $
Title='Pixel map overlaid /w contour map', $
T_Color=!MYCT.RED, T_Thick=2, T_LineStyle=2
; Make a second "fake" aircraft track
; (of course, if you have a real flight track, use it...)
TrackX = Replicate( 72, 100 )
TrackY = Findgen( 100 ) - 50
TrackD = Fltarr( 100 )
; Call CTM_OVERLAY again with /OVERPLOT to
; overplot the second flight track
CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
T_Color=!MYCT.BLUE, T_Thick=2, T_LineStyle=2, /OVERPLOT
(2) Draw Boxes for Tagged Tracer regions
----------------------------------------
; Define (X,Y) coordinates of first tagged tracer region
TrackX = [ 0, 60, 60, 0, 0 ]
TrackY = [ 0, 0, 30, 30, 0 ]
TrackD = [ 0, 0, 0, 0, 0 ]
; Call CTM_OVERLAY with all TVMAP keywords to
; plot the map and to initialize the map dataspace
CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
/Sample, /Countries, /Coasts, /CBar, $
Div=4, Min_Val=1e-20, /Isotropic, /Grid, $
Title='Test pixel map w/ overlay boxes', $
T_Thick=3, T_Color=!MYCT.BLACK, T_LineStyle=0
; Define second tagged tracer region
TrackX = [ 0, 120, 120, 0, 0 ]
TrackY = [ 0, 0, -30, -30, 0 ]
; Call CTM_OVERLAY with /OVERPLOT to overplot
; atop the previously defined map
CTM_OverLay, Data, XXMid, YYMid, TrackX, TrackY, $
/OVERPLOT, T_Thick=3, T_Color=!MYCT.RED, T_LineStyle=0
(3) Plot individual station data points
----------------------------------------
; Define "fake" station data for demo
; (along the equator between 60W and 60E)
Ind = Where( XMid ge -60 AND XMid le 60, N )
TrackD = Findgen(N) + 20
TrackY = Fltarr(N) + 0
TrackX = Xmid[Ind]
; Call CTM_OVERLAY with all TVMAP keywords to
; plot the map and to initialize the map dataspace
CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
/Sample, /Countries, /Coasts, /CBar, $
Div=4, Min_Val=1e-20, /Isotropic, /Grid, $
T_Symbol=1, SymSize=2, $
Title='Test pixel map w/ station data',
MODIFICATION HISTORY:
bmy, 05 Oct 2006: GAMAP VERSION 2.05
- Modified from CTM_OVERLAY_FLIGHT and
renamed to CTM_OVERLAY
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
dbm & bmy, 06 Nov 2007: - Modified to allow filled contour plots
cdh & bmy, 18 Feb 2009: GAMAP VERSION 2.13
- Now pass LOG=LOG to TVMAP call to ensure
that TVMAP gets the /LOG keyword OK
bmy & cph, 14 Jan 2010: GAMAP VERSION 2.14
- Remove the call to the PLOT command after
TVMAP. This does set up the approropriate
coordinates for map projections other
than /CYLINDRICAL.
- Now use PLOTS to plot symbols or lines
rather than OPLOT.
- Updated comments
cdh, 24 Feb 2010: - Added /NOADVANCE keyword
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Now set default values for C_COLORS
for filled contour plots if not specified
bf & bmy, 18 Oct 2010: - Bug fix submitted by Bonne Ford to allow
more than one overlay on the same plot
bmy, 10 Feb 2016: GAMAP VERSION 2.19
- If plotting symbols, suppress symbol borders
if T_COLOR is negative (e.g. T_COLOR=-1).
- Now require adding /NOADVANCE before each
successive call to CTM_OVERLAY with /OVERPLOT
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_overlay.pro)
NAME:
CTM_OVERLAY_WIND
PURPOSE:
Calls TVMAP to plot a pixel or contour map and then overplots
wind data atop it.
%%%% NOTE: Still in BETA testing! %%%%
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_OVERLAY, DATA, XMID, YMID, U, V, [, Keywords ]
INPUTS:
DATA -> Data array (e.g. from CTM_GET_DATA or CTM_GET_DATABLOCK)
from which a pixel plot or contour plot will be generated.
XMID -> Vector of longitudes corresponding to DATA.
YMID -> Vector of latitudes corresponding to DATA
U -> Array of U-wind values
V -> Array of V-wind values
KEYWORD PARAMETERS:
COLOR -> Color of the map outline. Passed to TVMAP.
/LOG -> Set this switch to use a logarithmic color table.
MINDATA -> Minimum value of DATA. If omitted, then MINDATA
will be automatically set to the minimum value of DATA.
MAXDATA -> Minimum value of DATA. If omitted, then MINDATA
will be automatically set to the minimum value of DATA.
/OVERPLOT -> Set this keyword to overplot the wind
atop a map previously drawn by TVMAP.
_EXTRA=e -> Passes extra keywords to TVMAP and VELOCITY_FIELD.
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
==========================================
SCALETRACK (function)
External Subroutines Required
=========================================
MULTIPANEL MYCT_DEFAULTS (function)
TVMAP RECTANGLE
SYM (function)
REQUIREMENTS:
Uses routines from both GAMAP and TOOLS packages.
NOTES:
You can pass all of the same keywords to CTM_OVERLAY_FLIGHT
as you do to TVMAP.
EXAMPLE:
(1) Plot flight tracks atop a pixel or contour map
--------------------------------------------------
; Read the data -- in this case, CO concentrations
SUCCESS = CTM_Get_DataBlock( Data, 'IJ-AVG-$', $
File='ctm.bpch.1995', $
Tra=4, $
/First, $
Lon=[-180, 180], $
Lat=[-88, 88], $
Lev=1, $
XMid=XXmid, Ymid=YYMid )
; Make a "fake" wind [TO DOCUMENT]
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 20 Mar 2008: GAMAP VERSION 2.12
- cleanup, updated for new TVMAP
- now pass Map Position to velocity_field
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_overlay_wind.pro)
NAME:
CTM_PLOT
PURPOSE:
General plotting tool for CTM data that is stored in the
GAMAP datainfo and fileinfo structures. CTM_PLOT can
handle everything from 0-D to 3-D and has many different
plot options, especially for 2-D plots for which it was
originally designed. E.g. full map support.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_PLOT, [ Diagn [ [ ,Keywords ] ]
INPUTS:
DIAGN -> The diagnostic number (e.g. ND22, ND45, etc or
category name (e.g. "JV-MAP", "IJ-AVG") for which to
read data from the punch file.
KEYWORD PARAMETERS:
Keyword parameters passed to CTM_GET_DATABLOCK:
===============================================
FILENAME -> Name of the punch file to read data from.
FILENAME is passed to CTM_GET_DATABLOCK. You can also
use a file mask, in which case FILENAME will return the
full filename if it is a named variable. If an empty
filename is provided, the default search mask from
gamap.defaults (see gamap.cmn) will be used. If no
filename is given, ctm_plot will try
to find the records from data already loaded.
TRACER -> Number of tracer to read from the punch file.
TAU0, /FIRST, /LAST -> time step to be plotted
LON -> If /INDEX is set, LON denotes the CTM longitude index
of the box to plot. Otherwise, LON denotes the actual
longitude value of that box. (that is at box CENTER, phs
4/2/08)
LAT -> If /INDEX is set, LAT denotes the CTM latitude index
of the box to plot. Otherwise, LAT denotes the actual
latitude value of that box. (that is at box CENTER, phs
4/2/08)
LEV -> An index array of sigma levels *OR* a two-element
vector specifying the min and max sigma levels to be
included in the plot. Default is [ 1, GRIDINFO.LMX ].
ALTRANGE -> A vector specifying the min and max altitude
values to be included in the extracted data block.
PRANGE -> A vector specifying the min and max pressure
levels to be included in the extracted data block.
/INDEX -> If set, will interpret LAT, LEV, and LON as CTM
indices. If not set, will interpret LAT, LEV, and LON
as the actual values of latitude, level, and longitude.
NOTE: If /INDEX is set, then GAMAP cannot create plots
for longitude ranges that span the date line!!!
AVERAGE -> If = 0, will not average the data
= 1, will average data longitudinally
= 2, will average data latitudinally
= 4, will average data vertically
These are cumulative (e.g. AVERAGE=3 will average over
both lat and lon, and AVERAGE=7 will average over lat,
lon, and vertical levels to produce 1 data point).
TOTAL -> If = 0, will not total data
= 1, will total data longitudinally
= 2, will total data latitudinally
= 4, will total data vertically
These are cumulative (e.g. TOTAL=3 will total over both
lat and lon, and TOTAL=7 will total over lat, lon, and
vertical levels to produce 1 data point).
USE_FILEINFO -> (optional) If provided, CTM_GET_DATABLOCK will
restrict its search to only the files that are
contained in USE_FILEINFO which must be a FILEINFO
structure array. Default is to use the global information
(see gamap_cmn.pro).
If an undefined named variable is provided in USE_FILEINFO,
it will either contain the global FILEINFO structure array
or the FILEINFO record of the specified file.
USE_FILEINFO and USE_DATAINFO must be consistent, and should
either both be used or omitted. However, it is
possible to provide the global FILEINFO structure
(or nothing) with a local subset of DATAINFO.
USE_DATAINFO -> (optional) Restrict search to records contained
in USE_DATAINFO which must be a DATAINFO structure array.
If an undefined named variable is provided in USE_DATAINFO,
it will either contain the global DATAINFO structure array
or all DATAINFO records of the specified file.
See also USE_FILEINFO.
Keywords passed to CTM_CONVERT_UNIT:
====================================
UNIT -> Name of the unit that the DATA array will be converted
to. If not specified, then no unit conversion will be done.
Keywords passed to TVMAP or TVPLOT:
===================================
NOERASE -> Do not erase previous plot.
POSITION -> A four-element array of normalized coordinates
that specifies the location of map on the plot. POSITION
has the same form as the POSITION keyword on a plot.
Default is [0.1, 0.05, 0.9, 0.08]. (Passed to TVMAP).
NCOLORS -> This is the maximum color index that will be used.
BOTTOM -> The lowest color index of the colors to be loaded
used in the color map and color bar.
/NOCBAR -> If set, will not plot the colorbar below the map
in the position specified by CBPOSITION. Default is to
plot a colorbar.
CBCOLOR -> Color index of the colorbar outline and
characters. Defaults to BLACK (from colors_default.pro).
CBPOSITION -> A four-element array of normalized coordinates
that specifies the location of the colorbar. BARPOSITION
has the same form as the POSITION keyword on a plot.
Default is [0.1, 0.05, 0.9, 0.08].
CBUNIT -> Passes the Unit string to COLORBAR, which will be
plotted to the right of the color bar. NOTE: For black
& white contour plots, the string specified by CBUNIT
will be plotted below the X-axis.
CBFORMAT -> format to use in call to colorbar. Default is I12
if abs(max(data)) < 1e4, else e12.2 (strings get trimmed)
COLOR -> Color index of the map outline and title characters.
Defaults to BLACK (from colors_default.pro). Also used as
plot color for 1-D (line) plots.
MPARAM -> A 3 element vector containing values for
[ P0Lat, P0Lon, Rot ]. Default is [ 0, 0, 0 ].
POSITION -> A four-element array of normalized coordinates
that specifies the location of the map. POSITION has
the same form as the POSITION keyword on a plot.
Default is [0.1, 0.1, 0.9, 0.9].
TITLE -> The title string that is to be placed atop the
map window.
/NOCONTINENTS -> If set, will suppress adding continent lines
to the map. Default is to call MAP_CONTINENTS to plot
continent outlines or filled boundaries.
CCOLOR -> The color index of the continent outline or fill
region. Default is BLACK (from colors_default.pro).
CFILL -> Value passed to FILL_CONTINENTS keyword of
MAP_CONTINENTS. If CFILL=1 then will fill continents
with a solid color (as specified in CCOLOR above).
If CFILL=2 then will fill continents with hatching.
/NOGRID -> If set, will suppress printing of grid lines.
Default is to call MAP_GRID to overlay grid lines.
GCOLOR -> The color index of the grid lines.
Default is BLACK (from colors_default.pro)
/NOGLABELS -> Will suppres printing of labels for each grid
line in TVMAP.PRO. Default is to print grid labels
for each grid line.
/NOISOTROPIC -> Will suppress plotting of an isotropic map
(i.e. one with the same X and Y scale). Default is to
print an isotropic map.
/CONTOUR -> Will produce a line-contour map instead of the
default color-pixel image map.
/FCONTOUR -> Will produce a filled contour map instead
of the default color-pixel image map. If you find
that one or more color bands are not filled properly,
try the /CELL_FILL keyword. This is a known IDL precularity.
C_LEVELS -> Vector containing the contour levels. If not
specified, TVMAP will use quasi-logarithmic levels.
C_COLORS -> Index array of color levels for each line (or
each fill section) of the contour map. If not
specified, TVMAP will select default colors from the
colortable.
C_ANNOTATION -> Vector containing the contour labels.
Default is to use string representations of C_LEVELS.
C_FORMAT -> Format string used in converting C_LEVELS to
the default C_ANNOTATION values. Default is '(f8.1)'.
C_LABELS -> Specifies which contour levels should be labeled.
By default, every other contour level is labeled. C_LABELS
allows you to override this default and explicitly
specify the levels to label. This parameter is a vector,
converted to integer type if necessary. If the LEVELS
keyword is specified, the elements of C_LABELS
correspond directly to the levels specified, otherwise,
they correspond to the default levels chosen by the
CONTOUR procedure. Setting an element of the vector to
zero causes that contour label to not be labeled. A
nonzero value forces labeling.
NOTE: If C_LABELS is given as a scalar, then it will be
expanded to a vector with all elements having the same value.
/C_LINES -> Will overplot a filled-contour map with contour lines
and labels instead of plotting a colorbar. This was the old
default behaviour but has been changed with the advent of
"discrete" colorbars. The old NOLINES keyword is kept
for compatibility reasons but doesn't do anything.
/NOLABELS -> Will suppress printing contour labels on both
line-contour and filled-contour maps.
OVERLAYCOLOR -> Color of the solid lines that will be
overlaid atop a filled contour map. Default is BLACK.
/OVERPLOT -> Add an additional line plot to an existing one.
You should specify LINE=n and/or COLOR=n to distinguish
between curves in this case. You can manually add a legend
with legend.pro after the plot(s) are produced.
Note that the title string will contain information on
your first selection only. Use an explicit TITLE for
best results.
/SAMPLE -> Will cause REBIN (in TVMAP) to use nearest-
neighbor sampling rather than bilinear interpolation.
/LOG -> Will create a color-pixel plot with logarithmic
scaling. /LOG has no effect on line-contour or
filled-contour plots, since the default contour levels
are quasi-logarithmic.
/POLAR -> Create a polar plot. Note that the longitude range must
be -180..180 and the latitude range must extend to one pole
but not straddle the equator.
Keywords passed to ISOPLETH_MAP:
================================
ISOPLETH -> Value for which a 3-D isosurface will be computed.
ISOPLETH_MAP assigns a default value of 35.0.
Other Keywords:
===============
USTR -> Unit string to be plotted to the right of the colorbar.
If not specified, then CTM_PLOT will construct a unit
string based on the value of TRACERINFO.UNIT.
NOTE: USTR is a synonym for the keyword CBUNIT, which
specifies the color bar unit string.
THISDATAINFO -> Returns to the calling program the THISDATAINFO
structure obtained by CTM_GET_DATABLOCK.
LABELSTRU -> Returns to the calling program the structure
of label information obtained by CTM_LABEL.
YRANGE -> range of y values for color scaling (default:
scale each plot seperately with data min and max)
X_FORMAT, Y_FORMAT (optional) -> Specifies the format string
(e.g. '(f10.3)', '(e14.2)' ) for the X and Y axes, when
making line plots. If omitted, CTM_PLOT will call
GET_DEFAULTFORMAT to compute default format strings.
RESULT -> A named variable will contain the data subset that was
plotted together with the X and/or Y coordinates in a structure.
For 1D plots, either X or Y are -1. 3D visualization returns
a structure including the Z coordinate.
_EXTRA=e -> Picks up extra keywords for CTM_GET_DATABLOCK,
CTM_LABEL, TVMAP, and TVPLOT.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===========================================================
CTM_DRAW_CUBE CONVERT_LON
CTM_TRACERINFO CTM_CONVERT_UNIT
TVMAP TVPLOT
CHKSTRU (function) MYCT_DEFAULTS (function)
CTM_GET_DATABLOCK (function) CTM_LABEL (function)
REPLACE_TOKEN (function) CTM_BOXSIZE (function)
GET_DEFAULTFORMAT (function) GAMAP_CMN (include file)
REQUIREMENTS:
Also assumes colortable has been loaded with "myct.pro".
NOTES:
(1) Some keywords are saved in local variables with
slightly different names (e.g. MCONTOUR for /CONTOUR)
to prevent confusion with routine names and/or keywords
that are picked up by the _EXTRA=e facility.
(2) Not every possible combination of keywords has been thoroghly
tested. *PLEASE* report reproducible errors to mgs@io.harvard.edu!!
(3) As of 11/17/98, CTM_PLOT can only produce X-Y plots with
either PRESSURE or ALTITUDE along the left Y-Axis. The right
Y-Axis is left disabled (but will fix that later on...)
(4) Now define X-axis labels for longitude. The labels are
defined correctly for data blocks that span the date line.
EXAMPLE:
(0)
CTM_PLOT
; To plot an ozone surface map (default) of a
; user-selected file
(1)
FileName = '~/terra/CTM4/run_code/ctm.pch.sep1'
CTM_PLOT, 22, 1, FileName=FileName, Lev=[1,14], $
Total=4, /NoErase
; Plots vertically-summed map for tracer 1 of ND22
; (J-Values map). Will erase screen before plotting map.
(2)
CTM_PLOT, 'JV-MAP-$', 1, FileName=FileName, Lev=[1,14], $
Total=4, /NoErase
; Same as above, but uses category name instead of
; diagnostic number.
MODIFICATION HISTORY:
bmy, 21 Sep 1998: VERSION 1.00
bmy, 22 Sep 1998: VERSION 1.01
- added AVERAGE and TOTAL keywords
bmy, 22 Sep 1998: VERSION 1.10
- Modified for use with new versions of
CTM_GET_DATABLOCK, CTM_EXTRACT,
CTM_LABEL, REPLACE_TOKEN, and TVMAP
bmy, 25 Sep 1998: VERSION 1.11
- modified for TVMAP v. 2.0
bmy, 28 Sep 1998: VERSION 2.00
- modified for TVMAP v. 2.01
- renamed LONSHIFT to LSHIFT
bmy, 29 Sep 1998: - added ALTRANGE and PRANGE keywords
(which had been previously omitted)
bmy, 30 Sep 1998: VERSION 2.01
- added call to CTM_CONVERT_UNIT
- added LABELSTRU keyword
bmy, 07 Oct 1998 VERSION 2.02
- now works with TVMAP 3.0
- added /CONTOUR, /FCONTOUR, and
/COLORBAR keywords
- removed I/O error handling (that
is already done in CTM_GET_DATABLOCK)
bmy, 08 Oct 1998: VERSION 2.03
- now works with CTM_GET_DATABLOCK v. 1.03
and CTM_EXTRACT v. 1.04
- added DATA and THISDATAINFO keywords so
that an external data block can be
passed.
- another bug fix for UNITSTR
bmy, 03 Nov 1998: VERSION 2.04
- works with new CTM_GET_DATA,
CTM_GET_DATABLOCK and CTM_LABEL routines
- Now pass the FILEINFO and DATAINFO
structures via USE_FILEINFO and
USE_DATAINFO keywords
- removed DATA keyword
- changed %NAME% token to %TRACERNAME%
- Now can pass an explicit unit string
via the USTR keyword
mgs, 10 Nov 1998: - adapted for use with new CTM_GET_DATABLOCK
- changed keyword Erase to NoErase
- defaults set to produce an OX surface map
from IJ-AVG-$ diagnostics
- allow for vertical cross section plots
(interface to TVPLOT) : ** still needs work! **
- changed CBAR to NOCBAR
bmy, 12 Nov 1998: - TRACER is now a keyword instead of
an argument
- Changed keyword CONTINENTS to
NOCONTINENTS and GRID to NOGRID
- added NOISOTROPIC, SAMPLE and
keywords
bmy, 13 Nov 1998: - VERSION 3.00
- ***** RENAMED to CTM_PLOT *****
- updated documentation header
- renamed C_LABELS to C_ANNOTATION to
prevent keyword name confusion
- added NOLINES, NOLABELS, C_LABELS,
and OVERLAYCOLOR keywords for tvmap
- now gets default colors from
DEFAULT_COLORS.PRO
- Error checking for LIMIT keyword
(OK for now...fix this later on...)
bmy, 16 Nov 1998: - Now use %DATE% instead of %YMD1% for
all default plot titles
- now enhanced for TVPLOT v. 2.0
- now only convert units for a tracer
if the default unit is different from
the desired unit!!
bmy, 17 Nov 1998: - added /PRESSURE keyword to plot pressure
instead of altitude on the left Y-axis
mgs, 17 Nov 1998: - messed around quite a bit, because of
(unfortunate) changes in default_range !@#$!@
- added CBFormat keyword
bmy, 23 Nov 1998: - eliminated %SCALE% token from UNITSTR,
to be consistent with the latest
upgrade to COLORBAR.PRO.
- now pass SECONDS to CTM_CONVERT_UNIT
bmy, 13 Jan 1999: - add support for line plots. Also, if
the DATA array is averaged down to a
single point, will print the value of
that point and exit.
- use NEWXTITLE and NEWYTITLE as token-replaced
strings for XTITLE and YTITLE
bmy, 15 Jan 1999: - add support for 3-D visualization plots
- added unit string for contour plots
- now place CTM_LABEL call after the case
statement for PLOTTYPE, so that we can
suppress printing of special characters
in plot titles.
bmy, 19 Jan 1999: - improve 0-D output
- fixed [XY]Titles for line plots
- "unitless" is now a unit string option
- now use new default color names from
DEFAULT_COLORS.PRO
bmy, 20 Jan 1999: - Updated comments
mgs, 22 Jan 1999: - couple bug fixes, some code cleaning
- added OverPlot keyword to allow multiple
line plots
bmy, 19 Feb 1999: - now pass DEBUG (from GAMAP_CMN) to
CTM_GET_DATABLOCK via DEBUG keyword
- Rename XIND, YIND, ZIND keywords to
XMID, YMID, ZMID, in call to CTM_GET_DATABLOCK
bmy, 23 Feb 1999: - Add XTICKNAME, XTICKS, XTICKV in call to
TVPLOT...fix for map regions smaller than
the globe
- bug fix.../NOGRID was listed as GRID!!!
- added keyword /NOGLABELS, which
suppresses grid line labels in MAP_SET
- updated comments
bmy, 26 Feb 1999: - now calls MAP_LABELS to get latitude labels
for X, XZ, Y, YZ plot types.
- updated comments
bmy, 04 Mar 1999: - now pass DEBUG keyword to TVMAP
- now use GRIDINFO.XEDGE, GRIDINFO.YEDGE
to compute the LIMIT keyword for MAP_SET
mgs, 18 Mar 1999: - minor cleaning
mgs, 23 Mar 1999: - added ILun to keyword list to prevent retrieval
of two otherwise identical records from two
different files
bmy, 25 Mar 1999: - now line plots use MULTIPANEL
- if NPANELS >=2 then place the plot title
higher above the window, to allow for
carriage-returned lines
for X, Y, Z, XY, XZ, YZ plots
mgs, 25 Mar 1999: - no unit conversion if not necessary
- small fix to allow for 2D fields (e.g. EPTOMS)
bmy, 14 Apr 1999: - now prints unit string at lower right of
XZ or YZ plots, if the colorbar is not
plotted
bmy, 26 Apr 1999: - rename YRANGE to YYRANGE internally, so as
to avoid confusion with YRANGE plot keywords
mgs, 19 May 1999: - removed a few too explicit keyword settings
for 1D plots and fixed OverPlot option.
Now stores !X, !Y, and !P from last 1D plot
in a local common block.
mgs, 21 May 1999: - restore !X, !Y, and !P at the end of each
1-D plot to allow overplotting of data.
mgs, 25 May 1999: - needed to mess around with lonrange to get
it right.
mgs & bmy, 26 May 1999: - added POLAR keyword
bmy, 27 May 1999: - bug fix: CBUnit keyword wasn't honored
- neither was NoIsotropic
mgs, 27 May 1999: - changed default behaviour for filled contours:
now plots no lines and colorbar. Keyword
NoLines changed to C_Lines.
mgs, 28 May 1999: - added RESULT keyword to return data as plotted
- bug fix with wrapping round data: shouldn't be
done for vertical cross sections.
mgs, 02 Jun 1999: - small bug fix for 0D results.
mgs, bmy 03 Jun 1999: - removed "Unit:" from output
bmy, 07 Jul 1999: - added PLOTCSFAC scale factor for multipanel
plots
- small fixes for line plots
bmy, 02 Nov 1999: GAMAP VERSION 1.44
- return if THISDATAINFO contains
information for more than one data block
bmy, 24 Nov 1999: - now pass _EXTRA=e to CTM_TRACERINFO
so that /SMALLCHEM will be passed
bmy, 13 Dec 1999: - if GRIDINFO is undefined after returning from
CTM_GET_DATABLOCK, rebuild it w/ CTM_TYPE
bmy, 03 Feb 2000: GAMAP VERSION 1.45
- NOTE: /INDEX does not work with lon range
shifting anymore. Will fix later.
- also make sure LON, LAT have two elements
- added X_FORMAT, Y_FORMAT keywords for line plots
- updated comments
bmy, 06 Apr 2000: - bug fix: restrict X or Y axis range for line
plots using the value passed from YYRANGE.
- cosmetic changes, updated comments
bmy, 23 Jan 2001: GAMAP VERSION 1.47
- now call "isopleth_map.pro" to plot a 3-D
isosurface. 3-D visualization via
routine "ctm_draw_cube.pro" is obsolete.
- added ISOPLETH keyword as pass-thru to
ISOPLETH_MAP
bmy, 23 Jul 2001: GAMAP VERSION 1.48
- replaced call to DEFAULT_COLORS with
call to MYCT_DEFAULTS() to specify
MYCT color table information
- deleted obsolete code from 1998 and 1999
bmy, 09 Aug 2001: - bug fix: remove reference to BLACK from
the old "default_colors.pro"
bmy, 24 May 2002: GAMAP VERSION 1.50
- Now use SI unit hPa instead of mb in axis titles
- delete obsolete, commented-out code
bmy, 28 Sep 2002: GAMAP VERSION 1.51
- now get default NCOLORS, BOTTOM, BLACK values
from !MYCT system variable instead of from
the MYCT_DEFAULTS function
bmy, 16 Apr 2004: GAMAP VERSION 2.02
- Also need to convert the units of YYRANGE
accordingly so that /AUTORANGE will work
bmy, 16 Jun 2004: - Bug fix: if we do unit conversion, do not
let the converted value of YRANGE get
passed back to the main program
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Modified for GEOS-5 fields that are
defined on level edges
phs, 19 Mar 2008: GAMAP VERSION 2.12
- Bug fix for working with new map_labels
phs, 02 Apr 2008: - Bug fix for XZ and YZ pixel plots
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plot.pro)
NAME:
CTM_PLOTDIFF
PURPOSE:
Prints a lat-lon map of 2 CTM fields, their absolute difference,
and their percent difference. This is a quick way of ensuring
that two model versions are producing identical results.
The page will contain the following plot panels:
Panel #1 Panel #2
Data Block D1 Data Block D2
Panel #3 Panel #4
Abs Diff (D2 - D1) % Diff (D2 - D1)
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_PLOTDIFF, DIAGN, FILE1, FILE2 [, Keywords ]
INPUTS:
DIAGN -> A diagnostic number or category to restrict
the record selection (default is: "IJ-AVG-$").
FILE1 -> Name of the first CTM output file. If FILE1
is not given, or if it contains wildcard characters
(e.g. "*"), then the user will be prompted to supply
a file name via a pickfile dialog box.
FILE2 -> Name of the second CTM output file. If FILE2
is not given, or if it contains wildcard characters
(e.g. "*"), then the user will be prompted to supply
a file name via a pickfile dialog box.
KEYWORD PARAMETERS:
LON -> A 2-element vector specifying the longitude range that
will be used to make the plot. Default is [-180,180].
LAT -> A 2-element vector specifying the latitude range that
will be used to make the plot. Default is [-88,88].
LEV -> A scalar or 2-element vector which specifies the
level(s) that will be used to make the plot. Default
is [ 1, 1 ].
/PS -> Set this switch to print to a PostScript file.
OUTFILENAME -> Name of the PostScript file if the /PS option
is set. Default is "idl.ps".
TRACER -> Tracer number(s) for which differences will be plotted.
TAU0 -> TAU value(s) (hours since 0 GMT 1 Jan 1985) at the start
of the diagnostic data block to plot.
DIVISIONS -> Specifies the number of colorbar divisions for
the quantity plot (Panels #1 and #2). Default is 5.
NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.
DATARANGE -> Allows you to manually specify the min and max
values of the data that will appear on the plot (Panels
# 1 and #2). The default is to automatically compute
the overall min and max of both data blocks.
MIN_VALID -> Specifies the minimum valid data for the plot.
Data lower than MIN_VALID will be rendered with color
!MYCT.WHITE. For example, MIN_VALID is useful for
plotting emissions which only occur on land.
DIFFDIV -> Specifies the number of colorbar divisions for
the difference plots (Panels #3 and #4). Default is 8.
NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.
DIFFNCOLORS -> Sets the # of colors used to create the
difference plots (Panels #3 and #4). Default is 13.
DIFFRANGE -> Allows you to manually specify the min and max
values that will appear on the absolute difference
plot (Panel #3). Default is to use the dynamic range of
the absolute difference data (symmetric around zero).
/NODEVICE -> set to not call open_device, so you can do it
from outside
/NOMULTIPANEL -> set to not call multipanel, so you can do it
from outside
PCRANGE -> Allows you to manually specify the min and max
values that will appear on the percentage difference
plot (Panel #4). Default is to use the dynamic range of
the percentage difference data (symmetric around zero).
PCDIV -> number of ticks in the %-Diff colorbar
PCNCOLORS -> number of colors for the %-Diff plot
T1, T2, DIFFTITLE -> allows you to overwrite the default
title for the 1st, 2nd and DIff plots.
_EXTRA=e -> Picks up extra keywords for CTM_DIFF,
OPEN_DEVICE, and MYCT
Keywords for the MASK feature:
------------------------------
/MASK -> set to mask with a green color boxes where %-diff
and/or diff are below some threshold. The absolute value
of the % is plot.
PC_THR, DIFF_THR : the %-Diff and Diff THResholds to mask data in the
4th plot if /MASK is set. Boxes with %-Diff or/and Diff
below the THResholds are masked. Default values are 1%
and 1e4.
/ZAP -> set to skip all plots if /MASK is set and all boxes
are masked.
OUTPUTS:
none
SUBROUTINES:
External Subroutines Required:
=======================================================
CHKSTRU (function) CLOSE_DEVICE
CTM_CLEANUP COLORBAR_NDIV (function)
CTM_DIFF CTM_GET_DATABLOCK (function)
IS_DEFINED (function) EXTRACT_FILENAME (function)
MULTIPANEL OPEN_DEVICE
REQUIREMENTS:
None
NOTES:
(1) CTM_PLOTDIFF calls CTM_CLEANUP each time to remove
previously read datablock info from the GAMAP common
block.
(2) The default TAU0 value is 0, and is not suitable if your
run has no output for 0 GMT 1 Jan 1985! You may have to
gather tau0 before running and crashing CTM_PLOTDIFF.
EXAMPLE:
FILE1 = 'ctm.bpch.v4-30'
FILE2 = 'ctm.bpch.v4-31'
CTM_PLOTDIFF, 'IJ-AVG-$', FILE1, FILE2, TRACER=1
; Creates 4-panel plot w/ old data, new data,
; new - old (abs diff), and new - old (% diff).
MODIFICATION HISTORY:
bmy, 17 Apr 2002: GAMAP VERSION 1.50
bmy, 17 Jul 2002: GAMAP VERSION 1.51
- added TAU0 keyword
bmy, 16 Dec 2002: GAMAP VERSION 1.52
- now can handle 2 different tracer numbers
- now can handle 2 different TAU0 values
bmy, 29 Jan 2004: GAMAP VERSION 2.01
- Now pass LEV keyword to CTM_DIFF
- Now plot both DATA1 and DATA2 on
the same scale for easier comparison
bmy, 16 Feb 2005: GAMAP VERSION 2.03
- Now use /QUIET and /NOPRINT keywords in
CTM_GET_DATA and CTM_GET_DATABLOCK to
suppress screen output
phs, 24 Oct 2006: GAMAP VERSION 2.05
- Now use YRANGE if it is passed.
- Also use DIFFRANGE (for range of the
abs difference plot) if it is passed.
- Now use PCRANGE (for range of the
%age difference plot) if it is passed.
bmy, 15 Nov 2006: GAMAP VERSION 2.06
- Now use blue-white-red color table
for abs diff and % diff plots
bmy & phs, 04 Oct 2007: GAMAP VERSION 2.10
- Added DIVISIONS keyword (default=5)
- Now make the default DIFFRANGE and
PCRANGE symmetric around zero
- Added DIFFDIV, DIFFNCOLORS keywords
- Also restore original !MYCT structure
- restore initial Color Table and !MyCt,
and return, when crashes.
- Now skip plotting % difference if
DATA1 is zero everywhere
- Add error trapping with CATCH
bmy, 16 Jan 2008: GAMAP VERSION 2.12
- add _EXTRA=e to calls to CTM_PLOT, in order
to pass extra variables to that routine
phs, 31 Jan 2008: - Add NODEVICE keyword, so device (like PS
file) can be open outside this routine,
allowing for multiple pages in a PS file
for example.
- Clipping of percentage difference range
is indicated with triangle.
phs, 25 Feb 2008: - Improved error catcher
bmy, 05 Nov 2008: GAMAP VERSION 2.13
- Renamed YRANGE keyword to DATARANGE in
order to avoid confusion with nested grids
phs, 22 Sep 2009: - more flexible call to MYCT for diff
plots, so it can be overwriten from
caller
- Can select number of colors and divisions
for %-diff plot
- Can overwrite titles
- Can set Multipanel from outside in caller
- Can MASK data according to both Diff and
%-Diff values, in the 4th plot
bmy, 29 Jan 2010: GAMAP VERSION 2.14
- Minor fix in IF statement to prevent code
from dying after call to CTM_DIFF.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plotdiff.pro)
NAME:
CTM_PLOTDIFF4
PURPOSE:
Prints a lat-lon map of 2 CTM fields, their absolute difference,
and their percent difference. This is a quick way of ensuring
that two model versions are producing identical results.
The page will contain the following plot panels:
Panel #1 Panel #2
Data Block D1 Data Block D2
Panel #3 Panel #4
Abs Diff (D2 - D1) % Diff (D2 - D1) / D1
CTM_PLOTDIFF4 is a lighter version of CTM_PLOTDIFF, and does
not use CTM_DIFF as an intermediary routine.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_PLOTDIFF4, DIAGN, FILE2, FILE2 [, Keywords ]
INPUTS:
DIAGN -> A diagnostic number or category to restrict
the record selection (default is: "IJ-AVG-$").
FILE1 -> Name of the first CTM output file. If FILE1
is not given, or if it contains wildcard characters
(e.g. "*"), then the user will be prompted to supply
a file name via a pickfile dialog box.
FILE2 -> Name of the second CTM output file. If FILE2
is not given, or if it contains wildcard characters
(e.g. "*"), then the user will be prompted to supply
a file name via a pickfile dialog box.
KEYWORD PARAMETERS:
LON -> A 2-element vector specifying the longitude range that
will be used to make the plot. Default is [-180,180].
LAT -> A 2-element vector specifying the latitude range that
will be used to make the plot. Default is [-88,88].
LEV -> A scalar or 2-element vector which specifies the
level(s) that will be used to make the plot. Default
is [ 1, 1 ].
/PS -> Set this switch to print to a PostScript file.
OUTFILENAME -> Name of the PostScript file if the /PS option
is set. Default is "idl.ps".
TRACER -> A scalar or 2-element vector which specifies the
tracer number(s) for each data block.
TAU0 -> A scalar or 2-element vector which specifies the
TAU value(s) (hours since 0 GMT 1 Jan 1985) by which
each data block is timestamped.
DIVISIONS -> Specifies the number of colorbar divisions for
the quantity plot (Panels #1 and #2). Default is 5.
NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.
DATARANGE -> Allows you to manually specify the min and max
values of the data that will appear on the plot (Panels
# 1 and #2). The default is to automatically compute
the overall min and max of both data blocks.
MIN_VALID -> Specifies the minimum valid data for the plot.
Data lower than MIN_VALID will be rendered with color
!MYCT.WHITE. For example, MIN_VALID is useful for
plotting emissions which only occur on land.
DIFFDIV -> Specifies the number of colorbar divisions for
the difference plots (Panels #3 and #4). Default is 8.
NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.
DIFFNCOLORS -> Sets the # of colors used to create the
difference plots (Panels #3 and #4). Default is 13.
DIFFRANGE -> Allows you to manually specify the min and max
values that will appear on the absolute difference
plot (Panel #3). Default is to use the dynamic range of
the absolute difference data (symmetric around zero).
/NODEVICE -> set to not call open_device, so you can do it
from outside
/NOMULTIPANEL -> set to not call multipanel, so you can do it
from outside
PCRANGE -> Allows you to manually specify the min and max
values that will appear on the percentage difference
plot (Panel #4). Default is to use the dynamic range of
the percentage difference data (symmetric around zero).
PCDIV -> number of ticks in the %-Diff colorbar
PCNCOLORS -> number of colors for the %-Diff plot
TITLE_1 -> Allows you to override the default plot title for
the first data block (1st plot panel).
TITLE_1 -> Allows you to override the default plot title for
the 2nd data block (2nd plot panel).
DIFFTITLE -> Allows you to override the default plot title for
the absolute difference plot (3rd plot panel).
PCTITLE -> Allows you to override the default plot title for
the percent difference plot (4th plot panel).
_EXTRA=e -> Picks up extra keywords for CTM_DIFF,
OPEN_DEVICE, and MYCT
Keywords for the MASK feature:
------------------------------
/MASK -> set to mask with a green color boxes where %-diff
and/or diff are below some threshold. The absolute value
of the % is plot.
PC_THR, DIFF_THR : the %-Diff and Diff THResholds to mask
data in the 4th plot (percent difference) if /MASK is
set. Boxes with %-Diff or/and Diff below the THResholds
are masked. Default values are 1% and 1e4.
/ZAP -> set to skip all plots if /MASK is set and all boxes
are masked.;
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==========================================================
CHKSTRU (function) CLOSE_DEVICE
COLORBAR_NDIV (function) CTM_GET_DATABLOCK (function)
EXTRACT_FILENAME (function) MULTIPANEL
MYCT OPEN_DEVICE
TVMAP UNDEFINE
REQUIREMENTS:
Requires routines from the GAMAP package.
NOTES:
(1) When plotting a subset of the globe, CTM_PLOTDIFF4
properly sets the colorbar ranges for the abs diff
and percent diff plots. This was an issue in the
older CTM_PLOTDIFF.
(2) Longitude and latitude ranges specified by LON and LAT
will be applied to both data blocks.
EXAMPLE:
CTM_PLOTDIFF4, 'IJ-AVG-$', $
'v8-03-02.bpch', 'v9-01-01.bpch, $
TRACER=6, LEVEL=1, $
LON=[-90,-30], LAT=[30,15]
; Creates a 4-panel difference plot for ISOPRENE
; (IJ-AVG-$, tracer #6) at the surface for the Amazon
; basin region from data in 2 different model versions.
MODIFICATION HISTORY:
bmy, 16 May 2011: VERSION 1.00
bmy, 13 Jan 2014: GAMAP VERSION 2.17
- Bug fix: For 2-D data blocks that lack the
GRIDINFO.ZMID tag name, display the altitude
of the data as 0.0 km.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plotdiff4.pro)
NAME:
CTM_PLOTRATIO
PURPOSE:
Plots the ratio of two CTM data fields. This is one way
to see if two model versions produce identical results.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_PLOTRATIO, DIAGN [, Keywords ]
INPUTS:
DIAGN -> A diagnostic number or category to restrict
the record selection. Default is "IJ-AVG-$".
KEYWORD PARAMETERS:
FILE1 -> Name of the first CTM output file (containing the
"old" data). If FILE1 is not given, or if it contains
wildcard characters (e.g. "*"), then the user will be
prompted to supply a file name via a pickfile dialog box.
FILE2 -> Name of the second CTM output file. If FILE2
is not given, or if it contains wildcard characters
(e.g. "*"), then the user will be prompted to supply
a file name via a pickfile dialog box.
LON -> A 2-element vector specifying the longitude range that
will be used to make the plot. Default is [-180,180].
LAT -> A 2-element vector specifying the latitude range that
will be used to make the plot. Default is [-88,88].
LEV -> Vertical level for which to plot data. Default is 1.
TITLE -> Title string for the plot. If not specified, a
generic title string will be generated.
TRACER -> Number of the tracer for which differences
will be plotted. Default is 1.
_EXTRA=e -> Picks up extra keywords for CTM_DIFF.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==========================================
CTM_CLEANUP CTM_GET_DATABLOCK (function)
CTM_DIFF EXTRACT_FILENAME (function)
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL
REQUIREMENTS:
None
NOTES:
(1) The ratio plotted will be DATA2 / DATA1, where DATA2
is contained in FILE2, and DATA1 is contained in FILE1.
(2) For places where DATA1 = 0, DATA2 will also be set to 0.
This avoids division by zero errors.
(3) CTM_PLOTRATIO calls CTM_CLEANUP each time to remove
previously read datablock info from the GAMAP common
block.
EXAMPLE:
FILE1 = 'ctm.bpch.v4-30'
FILE2 = 'ctm.bpch.v4-31'
CTM_PLOTRATIO, 'IJ-AVG-$', $
FILE1=FILE1, FILE2=FILE2, TRACER=1, LEV=1
; Plots the ratio of NOx data at the surface:
; ctm.bpch.v4-31 / ctm.bpch.v4-30
MODIFICATION HISTORY:
bmy, 24 Apr 2002: GAMAP VERSION 1.50
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plotratio.pro)
NAME:
CTM_PLOT_TIMESERIES
PURPOSE:
Plots station timeseries data (e.g. from the GEOS-CHEM
ND48 diagnostic) contained in binary punch file format.
%%%% MAY NEED UPDATING %%%%%
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
CTM_PLOT_TIMESERIES, CATEGORY [ , Keywords ]
INPUTS:
CATEGORY -> The diagnostic number (e.g. ND22, ND45, etc or
category name (e.g. "JV-MAP-$", "IJ-AVG-$") for which to
read data from the punch file.
KEYWORD PARAMETERS:
BOTTOM -> The lowest color index of the colors to be loaded
used in the color map and color bar. The default is
to use the value in system variable !MYCT.BOTTOM.
COLOR -> Color of the plot window and/or data. The default
is to use the system variable !MYCT.BLACK.
LABELSTRU -> Returns to the calling program the structure
of label information obtained by CTM_LABEL.
LEV -> An index array of sigma levels *OR* a two-element
vector specifying the min and max sigma levels to be
included in the plot. Default is [ 1, GRIDINFO.LMX ].
OVERPLOT -> Plot data atop the previous plot window, instead
of erasing the screen and plotting in a new window.
RESULT -> A named variable will contain the data subset that
was plotted together with the X and/or Y coordinates in
a structure.
TITLE -> Top title string for the plot. If not passed,
then a default title string will be printed.
UNIT -> Name of the unit that the DATA array will be converted
to. If not specified, then no unit conversion will be done.
XTITLE -> X-Axis title string for the plot. If not passed,
then a default title string will be printed.
YTITLE -> Y-Axis title string for the plot. If not passed,
then a default title string will be printed.
YRANGE -> range of y values for color scaling (default:
scale each plot seperately with data min and max)
_EXTRA=e -> Picks up extra keywords for routines called
by CTM_PLOT_TIMESERIES.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===========================================================
CTM_GET_DATA CTM_INDEX (function)
CTM_LABEL (function) GETMODELANDGRIDINFO (function)
UNDEFINE REPLACE_TOKEN (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
MODIFICATION HISTORY:
bmy, 16 Apr 2004: GAMAP VERSION 2.03
- Initial version
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plot_timeseries.pro)
NAME:
GAMAP
PURPOSE:
Menu-driven user interface for creating plots with
the GAMAP package subroutines. The actual data retrieval
and plotting is done with ctm_plot.pro. This routine
mainly collects all user requests and passes them on to
CTM_PLOT.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
GAMAP, [ DiagN [, Keywords ] ]
INPUTS:
DIAGN -> A diagnostic number or category to restrict
the record selection (default is: use all).
KEYWORD PARAMETERS:
General keywords:
-----------------------------------------------------------------
FILENAME -> CTM output file name. Default is to display a
pickfile dialog and let the user select. You can have
wildcards ('*', '?') in your filename which restricts
the file selection.
/NOFILE -> Don't query for filename but display all records that
have already been loaded. This can save you a couple of
mouse clicks when you want to create several plots with
data from one file, and it also useful when you want
to plot data from 'external' files that were converted
with ctm_make_datainfo. If a filename is given or no
data were loaded, the file selection dialog will appear
anyhow.
/RESETDEFAULTS -> If set, will reset all GAMAP values to their
defaults.
/HELP -> Displays a help page.
RESULT -> Returns a structure with the data subset as plotted and
the respective X and Y coordinates. Returns only one data
record though.
TOPTITLE -> Add a specific title centered on top of each page
of output.
Keywords to restrict the number of records displayed for selection:
-----------------------------------------------------------------
TRACER -> A tracer number to restrict record selection
TAU0 -> Time value (at beginning of record)
DATE -> 6 digit date (e.g. 940101) at the beginning of the
output record (this gets translated into a TAU0
value via the function nymd2tau). You can specify more
than one date at a time using a vector (e.g. [940101, 940301]).
For the GISS model(s), you also have to specify /GISS_Date in
order to get correct tau values. The time is assumed to
be 00 GMT. For other times use the TAU0 keyword as
TAU0=nymd2tau(dates,times).
/GISS_Date -> set this flag if you are using the DATE keyword
with GISS model output.
Keywords defining output options (these override defaults in
gamap.defaults)
-----------------------------------------------------------------
/PS -> If set, will directly send output to the 'idl.ps' file.
If not set, GAMAP will prompt the user whether to create
the 'idl.ps' file.
OUTFILENAME -> Name of file to send PostScript output to.
/NOTIMESTAMP -> Do not include a user ID and time stamp
on the postscript plot. Unnecessary if the TIMESTAMP value
in gamap.defaults is set to 0.
XSIZE, YSIZE, XOFFSET, YOFFSET -> GAMAP will pass these
keywords to routine OPEN_DEVICE, for setting the size
and margins of PostScript output.
/DO_BMP -> If set, GAMAP will save animation frames as BMP
files. If not set, GAMAP will prompt the user whether
to save animation frames to BMP files. DO_BMP overrides
the default setting in "gamap.defaults".
BMPFILENAME -> Name of BMP file to save animation frames to.
If the token %N% is used in BMPFILENAME, then GAMAP
will replace %N% with the actual frame number. If
BMPFILENAME is not set, or if DO_BMP is set to *QUERY in
"gamap.defaults", GAMAP will prompt user to supply
BMPFILENAME.
/DO_GIF -> If set, GAMAP will save animation frames as GIF
files. If not set, GAMAP will prompt the user whether
to save animation frames to GIF files. DO_GIF overrides
the default setting in "gamap.defaults".
GIFFILENAME -> Name of GIF file to save animation frames to.
If the token %N% is used in GIFFILENAME, then GAMAP
will replace %N% with the actual frame number. If
GIFFILENAME is not set, or if DO_GIF is set to *QUERY in
"gamap.defaults", GAMAP will prompt user to supply
GIFFILENAME.
/DO_JPEG -> If set, GAMAP will save animation frames as BMP
files. If not set, GAMAP will prompt the user whether
to save animation frames to JPEG files. DO_JPEG overrides
the default setting in "gamap.defaults".
JPEGFILENAME -> Name of JPEG file to save animation frames to.
If the token %N% is used in JPEGFILENAME, then GAMAP
will replace %N% with the actual frame number. If
JPEGFILENAME is not set, or if DO_JPEG is set to *QUERY in
"gamap.defaults", GAMAP will prompt user to supply
JPEGFILENAME.
/DO_PNG -> If set, GAMAP will save animation frames as PNG
files. If not set, GAMAP will prompt the user whether
to save animation frames to PNG files. DO_PNG overrides
the default setting in "gamap.defaults".
PNGFILENAME -> Name of PNG file to save animation frames to.
If the token %N% is used in PNGFILENAME, then GAMAP
will replace %N% with the actual frame number. If
PNGFILENAME is not set, or if DO_PNG is set to *QUERY in
"gamap.defaults", GAMAP will prompt user to supply
PNGFILENAME.
/DO_TIFF -> If set, GAMAP will save animation frames as TIFF
files. If not set, GAMAP will prompt the user whether
to save animation frames to TIFF files. DO_TIFF overrides
the default setting in "gamap.defaults".
TIFFFILENAME -> Name of TIFF file to save animation frames to.
If the token %N% is used in TIFFFILENAME, then GAMAP
will replace %N% with the actual frame number. If
TIFFFILENAME is not set, or if DO_PNG is set to *QUERY in
"gamap.defaults", GAMAP will prompt user to supply
TIFFFILENAME.
/POLAR -> Set this keyword for polar pots. This forces latitude
ranges to extend to one pole and longitude ranges to span
the globe. Polar plots only work for global (at least
longitudinally) data sets. Currently, polar plots are
supported only for contour plots.
_EXTRA=e -> Picks up extra keywords for CTM_PLOT, etc...
OUTPUTS:
SUBROUTINES:
Internal subroutines:
------------------------------------------------------
GAMAP_CheckDataBlockConsistency (function)
GAMAP_FindNearestCenters (function)
GAMAP_GetDataBlockRanges (function)
GAMAP_GetDefaultRanges
GAMAP_AutoYRange (function)
GAMAP_PrintDimInfo
GAMAP_QueryAnimationOptions
GAMAP_QueryAverageOrTotal
GAMAP_QueryPostScriptOptions
GAMAP_SelectDataBlocks (function)
GAMAP_SelectPlotType
GAMAP_QueryIsoPleth
GAMAP_StoreGridInfo
GAMAP_UserRangeEntry (function)
GAMAP_GetFrameFileName (function)
Also uses external subroutines:
------------------------------------------------------
CHOICE (function) CLOSE_DEVICE
CTM_PLOT OPEN_DEVICE
STRREPL (function) STRWHERE (function)
DEFAULT_RANGE (function) CHKSTRU (function)
REPLACE_TOKEN (function) CTM_GRID (function)
MAKE_SELECTION(function) TVREAD (function)
REQUIREMENTS:
None
NOTES:
(1) GAMAP can read ASCII punch files with GEOS or GISS, model II
diagnostics, binary punch files (as defined in Jan 1999),
and GEOS-CTM binary restart files. Binary punch files
are processed much faster and allow "windowing" of output.
(2) For pixel plots, GAMAP can only plot cylindrical maps
with rectangular projections. Arbitrary map projections
should be possible with any type of contour plot. For
polar plots, use the /POLAR keyword. Other projections
have not been tested and may lead to unexpected results.
(3) GAMAP forces map ranges to coincide with the grid box
edges, so that the map and pixel plot will be aligned.
Each "pixel" size corresponds to one full grid box.
For grids with half-polar boxes, it is therefore recommended
not to plot the polar latitudes, since those boxes will
show up as full-size boxes and shift the rest of the plot
accordingly.
(4) When the user selects multiple data blocks, GAMAP will produce
a multi-panel plot if !p.multi indicates more than one panel
on the screen (use the MULTIPANEL procedure to turn it on).
If you plot only one panel per screen, GAMAP will automatically
start XInterAnimate to present your own movie to you. Be
aware that XInterAnimate is limited by your system resources.
With default window sizes, we can usually display at least
30 frames. ADDENDUM: 3-D isopleth maps will not be
animated. (bmy, 1/22/01)
(5) Animation frames can also be written to GIF or MPEG
files. Defaults can be set in "gamap.defaults", or
specified via the command line. You can also save individual
GAMAP plots as GIF files. If you want to animate them later
(e.g. using ULead's GIF-Animator), make sure to specify the
RANGE keyword to get identical color schemes (or use contours).
(6) The GAMAP authors wish to point out that it is still relatively
expensive to produce color plots on the printer. We encourage
you to try out contour plots and make a test print on a black
and white printer before you make a color print.
(7) The 3-D isopleth maps do not quite work with MULTIPANEL, since
they are produced with screen capture in the Z-Buffer. Hence
Hence, the X window device has to be re-initialized each time,
which negates the MULTIPANEL utility. PostScript plots of 3-D
isopleth maps will print one plot per page. We can live with
this for the time being. Isopleth maps can also be written
to GIF files.
(8) Now uses D. Fanning's TVREAD function to perform better
device-independent screen capture. (cf. www.dfanning.com)
EXAMPLES:
(1)
GAMAP
; operates fully interactively
MULTIPANEL,nplots=6 ; turn on multi-panel environment
GAMAP
; same as above, but produce multi-panel plots with
; 6 plots per page
(2)
GAMAP, 'IJ-AVG-$', tra=4
; Will create a CO (tracer=4) plot for the ND45 diagnostic.
; GAMAP will display dialog pickfile box and will scan the
; file for all records with ND45 and tracer 4. Those will be
; displayed and the user can then select a record to be plotted.
(3)
GAMAP, [ 'IJ-AVG-$', 'BIOBSRCE' ], tra=[2,4], $
date=[19940601, 19940801], $
FileName='~bmy/terra/CTM4/ctm.pch',/ps
; In this example the file is fully specified, hence no file
; selection dialog will be displayed. GAMAP scans the file
; for all records of 'IJ-AVG-$' and 'BIOBSRCE' and tracers
; 2 (OX) and 4 (NOX) and it seelcts only those records that
; begin on the first of JUNE or AUGUST 1994. Because the ps
; flag is set, the output will be directed to the postscript
; file 'idl.ps' without first being displayed on the screen.
MODIFICATION HISTORY:
mgs, 12 Nov 1998: VERSION 1.00
bmy, 16 Nov 1998: - added defaults for LAT, LEV, LON, PTYPE
- now prompts for PS
- now prompts user for /PS output
bmy, 17 Nov 1998: - now call DEFAULT_RANGE to ensure that
that LAT, LON, LEVEL have two elements,
even if there is only one unique value.
- now uses N_UNIQ.PRO to test for the number
of unique elements in LON, LAT, and LEVEL.
mgs, 17 Nov 1998: - finishing touches for first release.
- added NOFILE keyword
- added plot type b/w contours
mgs, 18 Nov 1998: - added timestamp as default when closing
postscript files
bmy, 08 Jan 1999: - Will also prompt for totaling (if
averaging is not selected)
bmy, 13 Jan 1999: - now prompt user for OUTFILENAME
bmy, 15 Jan 1999: VERSION 1.02
- add support for 3-D data slices
- clean up user interface so that the user
menu of plotting options is only invoked
when plotting a 2-D map.
bmy, 19 Jan 1999: - added binary flag masking
- added defaults for averaging and selection
- improved echoback of information to user
bmy, 20 Jan 1999: - prompts user again if data block selection
or averaging selection is out of range
- fixed bug: now default data block
selection is saved.
- Reset PS to 0 and OUTFILENAME to '' if we
are plotting a 0-D or 3-D data block
- updated comments
mgs, 21 Jan 1999: - dimensional information now in subroutine
- improved binary masking
- added several Quit options
- Postscript options now controlled from
gamap.defaults
- removed NoTimeStamp keyword (now set in
gamap.defaults)
bmy, 12 Feb 1999: VERSION 1.03
- now works with data blocks that are
sub-regions of the globe
- added functions GAMAP_GetDataBlockRanges
GAMAP_SelectDataBlock, and
GAMAP_QueryAverageOrTotal
- updated comments
bmy, 17 Feb 1999: VERSION 1.20
- Replace DATAINFO.OFFSET by DATAINFO.FIRST,
which contains the I, J, L indices of
the first grid box
- Animation facility added
- added functions GAMAP_GetModelInfo,
GAMAP_CheckDataBlockConsistency,
GAMAP_SelectPlotType, and
GAMAP_QueryPostScriptOptions.
- Also renamed function GAMAP_SelectDataBlock to
GAMAP_SelectDataBlocks, since one can now
select multiple data blocks
bmy, 18 Feb 1999: - added /RESETDEFAULTS keyword
- removed /ANIMATE keyword
bmy, 19 Feb 1999: - added NOAUTOYRANGE keyword
- added function GAMAP_AutoYRange
- added GIFFILENAME keyword
- added GIF_SAV to common block SAVEVALUES
- call REPLACE_TOKEN to replace token text
in DEFAULTGIFFILENAME
bmy, 22 Feb 1999: - added more animation options
- added DO_GIF, DO_MPEG, DO_ANIMATE, and
MPEGFILENAME keywords
- added GAMAP_QueryAnimationOptions routine
bmy, 23 Feb 1999: - small bug fixes
bmy, 04 Mar 1999: - added internal routines GAMAP_FindNearestEdges
and GAMAP_GetDefaultRanges
- now force lat/lon ranges to coincide with
grid box edges
- warn user if lat range contains half-polar
boxes, since TVIMAGE will treat them as
whole boxes and the map overlay will be
inaccurate!
bmy, 05 Mar 1999: - Clean up FILEINFO/DATAINFO matching process
- renamed/reorganized internal functions\
bmy, 20 Mar 1999: - bug fix for default ranges (may need more
fixing later on)
mgs, 22 Mar 1999: - added ALREADY_PS flag for multi-panel use
- animation now only if !p.multi does not
have more than 1 panel to display
mgs, 23 Mar 1999: - improved comments and examples
- removed unnecessary function MatchFileInfo...
(easier with make_selection)
- changed all "string booleans" to booleans
- Do_Animation now an entirely local variable
mgs, 25 Mar 1999: - few minor bug fixes
- improved handling of default ranges
- detect out of range in record selection
- now allows for 2D field plots
bmy, 17 May 1999: - now resolve DEFAULT_RANGE explicitly and
call DEFRANGE_STR2NUM separately
- few minor fixes in GAMAP_UserRangeEntry for
data blocks that straddle the date line.
mgs, 19 May 1999: - some more cleaning
- implemented SAVE option after data record
selection
- user selection for longitudes greatly improved
- some adjustments in FindNearestEdges, notably
for range 0..360. Unfortunately, the 0 meridian
gridline will be omitted in such plots. If we
wanted to include it we would need to carry
an extra GLOBAL flag because lower and upper
edges (grid box indices) are identical.
mgs, 20 May 1999: - added option to save record seelction to file.
mgs, 24 May 1999: - yet more work had to be done to make lon/lat
selection as user would expect it to work.
- renamed FindNearestEdges to ..Centers
mgs, 25 May 1999: - still more fiddling. Yuck!
RELEASE OF GAMAP VERSION 1.40
bmy, 26 May 1999: - Added polar plot capabilities
- fixed reset of plot ranges when latitude is +-90
mgs, 27 May 1999: - already_ps flag now also prevents user query.
- default lat range for global fields now back
to -88..88 only for "reset" conditions. Otherwise
-90..90 is recognized and remembered.
mgs, 28 May 1999: - added RESULT keyword.
- added TOPTITLE keyword.
bmy, 28 May 1999: - restrict plot type menu for polar plots
bmy & mgs, 02 Jun 1999: - add /NOERASE to MULTIPANEL call when
testing for last plot on page
- updated some comments
mgs, 30 Jun 1999: - make sure to return only one lat/lon box
if user enters single value (even on edges).
bmy, 07 Jul 1999: - small bug fixes
bmy, 15 Sep 1999: GAMAP VERSION 1.43
- changes for 23L GISS-II-PRIME model
- minor bug fixes
bmy, 25 Oct 1999: GAMAP VERSION 1.44
- added /MULTIPLE keyword -- option to
write to a GIF file w/ multiple frames
bmy, 23 Nov 1999: - /SMALLCHEM now works correctly!
bmy, 26 Apr 2000: GAMAP VERSION 1.45
- now make sure tracer numbers are mod 100L
when saving data blocks to disk
bmy, 19 Jun 2000: - now create NS string array by concatenating
smaller arrays of < 1024 elements
bmy, 20 Jun 2000: - bug fix -- set NS[0] blank for string output
bmy, 03 Oct 2000: GAMAP VERSION 1.46
bmy, 22 Jan 2001: GAMAP VERSION 1.47
- removed obsolete code
- now produce a 3-D isopleth map instead of
calling the volume slicer routine
- added ISOPLETH keyword
- added internal subroutine GAMAP_QueryIsopleth
- allow PostScript output for 3-D maps, and
suppress animation for 3-D maps.
bmy, 13 Mar 2001: - remove a couple more instances of the
obsolete STR_SEP routine. Replaced with
STRSPLIT( /EXTRACT ).
bmy, 28 Jun 2001: GAMAP VERSION 1.48
- bug fix in GAMAP_StoreDataInfo: for
GENERIC grids with NLAYERS=0, be sure to
call CTM_GRID with the /NO_VERTICAL flag.
bmy, 29 Aug 2001: - added XSIZE, YSIZE, XOFFSET, YOFFSET
keywords to pass to OPEN_DEVICE
mje & bmy, 17 Dec 2001: GAMAP VERSION 1.49
- add _EXTRA=e in call to CTM_WRITEBPCH,
so that we can pass the /APPEND keyword
bmy, 17 Jan 2002: GAMAP VERSION 1.50
- now call STRBREAK wrapper routine from
the TOOLS subdirectory for backwards
compatiblity for string-splitting
- use FORWARD_FUNCTION to declare STRBREAK
bmy, 24 Jan 2002: - deleted obsolete code
bmy, 06 Dec 2002: GAMAP VERSION 1.52
- removed /DO_MPEG and MPEGFILENAME keywords
- now use D. Fanning's TVREAD for better
device-independent screen capture
- removed /MULTIPLE keyword for GIF output
- added /DO_PNG, /DO_BMP, /DO_JPEG,
/DO_TIFF keywords
- added internal function GAMAP_GetFrameFileName
bmy, 13 Nov 2003: GAMAP VERSION 2.01
- comment out XINTERANIMATE options
bmy, 27 Aug 2004: GAMAP VERSION 2.03
- now call CTM_PLOT_TIMESERIES to plot data
from bpch files containing GEOS-CHEM station
timeseries output (e.g. ND48 diagnostic)
bmy, 27 Oct 2004: - now pass /QUIET keyword to GAMAP_AUTOYRANGE,
CTM_PLOT_TIMESERIES, and CTM_PLOT
- hardwire QUIET=1 in to suppress extra printing
bmy, 28 Jun 2005: GAMAP VERSION 2.04
- Strip white spaces in FILENAME, if present
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy & phs, 20 Nov 2007: GAMAP VERSION 2.11
- If any 4D data blocks are encountered,
then only use the first 3 dimensions
phs, 22 Sep 2009: GAMAP VERSION 2.13
- Added /NoDialog to all call to TVRead
bmy, 26 Feb 2010: GAMAP VERSION 2.14
- Now allow polar maps to use pixel plots
bmy, 11 Feb 2011: GAMAP VERSION 2.15
- Updated welcome screen
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/gamap.pro)
NAME:
PLANE_PLOT
PURPOSE:
Plots data from the GEOS-CHEM plane following diagnostic
atop a world map. Multiple flights can be plotted.
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
PLANE_PLOT, VAR, FLTID [, Keywords ]
INPUTS:
VAR -> Variable name for which to plot data. VAR should
match the variable names in the GEOS-CHEM input file
"Planeflight.dat" (e.g. TRA_001, GMAO_TEMP, REA_O1D, etc.)
FLTID -> Flight ID(s) for which to plot data. These should
match the flight ID's in the GEOS-CHEM input file
"Planeflight.dat" (e.g. P3B01, DC801, etc.)
KEYWORD PARAMETERS:
FILENAME -> Name of the file containing GEOS-CHEM plane
following diagnostic output. If FILENAME is omitted,
then a dialog box will prompt the user to supply a file
name.
LIMIT -> A 4-element vector with [MINLAT,MINLON,MAXLAT,MAXLON],
which will specify the bottom left and top right corners
of the map plot in degrees. Default is to plot the
entire Northern Hemisphere [0,-180,90,180].
MPARAM -> A 3 element vector which specifies the LAT0, LON0,
and ROT values to be passed to MAP_SET. Default is
[0,0,0].
SYMBOL -> Number of the symbol used to plot each data point.
SYMBOL corresponds to the types of symbols defined with
the routine "sym.pro" in the TOOLS package. Default is
1 (filled circle).
SYMSIZE -> Size of the plot symbol. Default is 1.5
_EXTRA=e -> Passes extra keywords to MAP_SET, MAP_GRID,
and MAP_CONTINENTS.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================
COLORBAR
CTM_READ_PLANEFLIGHT (function)
UNDEFINE
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
PLANE_PLOT, 'O3', 'P3B04', $
LIMIT=[20,-120,50,-60], $
FILENAME='plane.log'
; Plots GEOS-CHEM O3 data (stored in "plane.log) from
; the model grid boxes corresponding to flight P3BO4
; over the USA.
PLANE_PLOT, 'O3', ['P3B04','DC801'], $
LIMIT=[20,-120,50,-60], $
FILENAME='plane.log'
; Plots GEOS-CHEM O3 data (stored in "plane.log) from
; the model grid boxes corresponding to flights P3BO4
; and DC801 over the USA.
MODIFICATION HISTORY:
bmy, 23 Apr 2004: GAMAP VERSION 2.03
bmy, 13 Mar 2006: GAMAP VERSION 2.05
- Slight modifications for new version
of ctm_read_planeflight.pro
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/plane_plot.pro)
NAME:
TSDIAG
PURPOSE:
Reads and plots CTM time series (station) data. The
data are returned in a structure together with longitude,
latitude, altitude, and time information. TSDIAG tries to
construct a time vector from the TAU information stored
in the file. This may not always work (e.. it is assumed
that time steps are 1 hour).
While reading, TSDIAG displays a '.' for each new station
encountered, and a '+' if a station is continued. If you want
more detailed output, set the /VERBOSE flag.
%%% NOTE: May need updating %%%
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, GAMAP Plotting
CALLING SEQUENCE:
TSDIAG [,RESULT] [,keywords]
INPUTS:
None
KEYWORD PARAMETERS:
FILENAME -> Path of the input file containing CTM
Data data.
SCALE -> A global scale factor that will be applied to all
data. Default is 1. Note that concentration data is
stored as v/v, hence for ppt you should set
SCALE=1.E-12.
/VERBOSE -> display detailed information on what is being read.
/PLOT -> set this flag to produce quick-and-dirty plots of the
time-series data.
OUTPUTS:
RESULT -> A structure containing LON, LAT, ALT and Data data
together with TRACER and a "global" TIME array.
SUBROUTINES:
OPEN_DEVICE CLOSE_DEVICE
CTM_TRACERINFO FILE_EXIST (function)
STRSCINOT (function)
REQUIREMENTS:
NOTES:
Lines with the Data data (Header = 'TB' or 'DV') will be
read from disk. Statistics are ignored for now.
EXAMPLE:
; read time series data from file and return result structure
; in variable TSDATA
tsdiag, TSDATA, FILENAME='ctm.ts'
MODIFICATION HISTORY:
bmy, 06 May 1998: VERSION 1.00
bmy, 07 May 1998: VERSION 1.01
- added PPBC and INTERVAL keywords
- now calls FILE_EXIST to make sure
the input file exists
bmy, 27 May 1998 - now uses CTM_DIAGINFO to return
the proper tracer offset
bmy, 28 May 1998 - now uses SCALE, UNIT, and MOLC information
as returned by CTM_TRACERINFO.
- now uses EXP_STR to compute a
power-of-ten string for the plot title
bmy, 29 May 1998 - now calls CLEANPLOT to initialize
all system variables
bmy, 02 Jun 1998 - now uses STRSCI and STRCHEM string
formatting functions
mgs, 11 Jun 1998: - couple of bug fixes
mgs, 15 Jun 1998: - default tick interval now 48 h
mgs, 22 Jun 1998: - added Data and CSTEPS keywords
mgs, 20 Nov 1998: - now uses convert_unit
hsu, 22 Mar 1999: - increased MAXSTEPS and changed input format
mgs, 04 May 1999: - added MS as a tracer offset (100*MS)
mgs, 05 May 1999: - ... and a little bug fix
mgs, 19 May 1999: - updated comments
- default SCALE factor now 1 instead of 1.E-12
- CLEANPLOT no longer called
mgs, 24 May 1999: - added VERBOSE keyword
- fixed at least two bugs
- improved output. Now need to say /VERBOSE in
order to get details.
mgs, 25 May 1999: - new format had MS and N swapped.
bmy, 27 Jul 1999: GAMAP VERSION 1.42
- updated comments
bmy, 30 Jan 2002: GAMAP VERSION 1.50
- Now use STRBREAK to split each line into
elements of data
- Also no longer restrict data to be > 0
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tsdiag.pro)
NAME:
TSPLOT
PURPOSE:
Create a plot of station data time series using the
data structure as returned from TSDIAG.PRO. This routine
is a simple outline for how to use this structure and
not meant to produce publisheable plots. Tip: use
MULTIPANEL.PRO to save paper.
%%% THIS MAY NOW BE OBSOLETE %%%
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
TSPLOT, TSSTRU, INDEX, SCALE=SCALE
INPUTS:
TSSTRU -> The data structure as returned from TSDIAG.PRO
INDEX -> A vector with station indices that are to be plotted.
If no index is given, the program will loop through all
records.
KEYWORD PARAMETERS:
SCALE -> A scaling factor to be applied to the dat abefore plotting.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; read station data
TSDIAG,TSSTRU,FILE='ctm.ts'
; set page for 16 panels
MULTIPANEL, 16
; plot data from all stations as pptv
TSPLOT, TSSTRU, SCALE=1.e12
; turn multipanel off
MULTIPANEL, /OFF
MODIFICATION HISTORY:
mgs, 30 Jun 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tsplot.pro)
NAME:
TVMAP
PURPOSE:
TVMAP produces one of the following plots:
(1) A color-pixel image, overlaid with a world map
(2) A line-contour plot, overlaid with a world map
(3) A filled-contour plot, overlaid with a world map
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
TVMAP, Data, [ Xarr, YArr [ [, keywords ] ]
INPUTS:
DATA -> 2-D array of values to be plotted as a color map.
The first dimension is longitude, the second is latitude.
XARR, YARR -> If plotting a line-contour map or filled-contour map,
then XARR is the array of X-axis values, and YARR is the
array of Y-Axis values that are needed to construct the
the contours. XARR and YARR are not needed to produce a
color-pixel image map; however, if XARR and YARR are
passed, TVMAP will be able to label the longitude and
latitude lines accordingly and set the proper default limits.
KEYWORD PARAMETERS:
BLACK -> The color index corresponding to black.
Default is !MYCT.BLACK.
/CONUS -> a Lambert's azimuthal equal area projection for
CONtiguous U.S., w/ specific LIMIT and P0lat, P0lon, Rot.
MAX_VALID -> maximum valid data value for color-pixel plots
Data above MAX_VALID will be shown in white, unless
TOPOUTOFRANGE is set to another color index.
MIN_VALID -> minimum valid data value for color-pixel plots.
(or minimum contour level for contour plots). Data
below MIN_VALID will be shown in white, unless
BOTOUTOFRANGE is set to another color index.
TOPOUTOFRANGE ( BOTOUTOFRANGE ) -> color index to indicate
data above MAX_VALID (below MIN_VALID). Default is
white. The color is also shown with a box (or TRiangle)
near the colorbar (if any). If negative, the box is not
shown with the colorbar.
/NOERASE -> This keyword prevents erasing the screen (or page)
when setting a multi-panel environment or after a page was
filled. /NOERASE is automatically turned ON when the /OFF
keyword is given. NOTE: On the PostScript device, when
the page is filled, it automatically places the next plot
on the next page. You can use the /NOERASE keyword to
suppress this behavior, especially if you are manually
placing plots on the page.
CSFAC -> Character size for the map labels and X, Y titles.
Default settings for CSFAC vary according to the number
of plots per page and type of plot device.
TCSFAC -> Character size for the top title. Default
settings for TCSFAC vary according to the number
of plots per page and type of plot device.
/NOADVANCE -> Set this switch to prevent TVMAP from advancing
to the next plot panel on the page. This is useful if
you desire to overplot something atop the pixel map or
contour map.
/POLYFILL -> to use IDL POLYFILL routine instead of MAP_IMAGE
to do the pixel plot (see /SAMPLE). Use this keyword
with default cylindrical projection only. Use it also if
you think that MAP_IMAGE does not neatly reproduces the
boxes.
/RECTANGLE -> to plot a rectangle around the map. Default is
to have one for non-polar projection, and none for polar
projection. Set to 0 or 1 to override default. NOTE:
setting the /HORIZON keyword will disable this option.
/SAMPLE -> to do "pixel plot" (ie grid boxes are colored)
instead of contour.
/HORIZON -> Set this switch to call IDL routine MAP_HORIZON
to draw a horizon line around the boundaries of the map.
Use this feature if the map projection you are using is
elliptical or interrupted. NOTE: /HORIZON will override
override the /RECTANGLE keyword setting.
WINDOWPOSITION -> Returns the position of the plot window
in normal coordinates to the calling program. This can
be used by a subsequent call to PLOT if you want to
overplot symbols atop the contour or pixel plot created
by TVMAP.
_EXTRA=e -> Picks up extra keywords (not listed below, unless
noted) for BYTSCL, COLORBAR, TVIMAGE, MAP_SET, MAP_GRID,
MAP_CONTINENTS, MAP_LABELS and CONTOUR.
Keywords passed to both BYTSCL and COLORBAR:
============================================
MAXDATA -> Maximum value of the DATA array to use in the
byte scaling. Default is max( DATA ).
MINDATA -> Minimum value of the DATA array to use in the
byte scaling. Default is min( DATA ).
BOTTOM -> The lowest color index of the colors to be used
for byte-scaling the color map and colorbar. Default
is 20 (or !D.N_COLORS-1 if 20 is too large).
NCOLORS -> This is the maximum color index that will be used.
Default is 120 (or !D.N_COLORS-BOTTOM, if 120 is too large).
/LOG -> Will create a color-pixel plot with logarithmic
scaling. /LOG has no effect on line-contour or
filled-contour plots, since the default contour levels
are quasi-logarithmic.
Additional keywords passed to COLORBAR:
=======================================
/CBAR -> If set, will plot a horizontal colorbar below the
map in the position specified by CBPOSITION. Default is
to NOT plot a colorbar.
CBCOLOR -> Color index of the colorbar outline and
characters. Defaults to BLACK (see above).
CBPOSITION -> A four-element array of normalized coordinates
that specifies the location of the colorbar. CBPOSITION
has the same form as the POSITION keyword on a plot.
Default is [0.1, 0.05, 0.9, 0.08].
CBUNIT -> Passes the Unit string to COLORBAR, which will be
plotted to the right of the color bar.
CBFORMAT -> format to use in call to colorbar. Default is I12
if abs(max(data)) < 1e4, else e12.2 (strings get trimmed)
CBMIN, CBMAX -> Explicitly sets the min and max values of
the colorbar range. If not set, TVMAP will set
CBMIN = min( DATA ) and CBMAX = max( DATA ).
CBTICKLEN -> Specifies the color bar tick length as a
fraction of the colorbar height (for horizontal
colorbars) or width (for vertical colorbars).
CBVERTICAL -> If set, will plot a vertical bar on the right
side of the map.
CBSCALE -> If set, then the printed tick labels are scaled by
powers of 10 to minimize overlap.
DIVISIONS -> Number of labels for the colorbar. Default is 4.
/TRIANGLE -> to replace box that indicate Out Of Range data
with a triangle.
TOPLEVELVALUE -> to define the last annotation of the
colorbar when using the C_LEVELS keyword
Keywords passed to MAP_SET:
===========================
COLOR -> Color index of the map outline and title characters.
Defaults to BLACK (see above).
MPARAM -> A 3 element vector containing values for
[ P0Lat, P0Lon, Rot ]. Default is [ 0, 0, 0 ].
Elements not specified are automatically set to zero.
/ISOTROPIC -> If set, will produce a map with the same scale
in the X and Y directions. Default is not to plot an
isotropic-scale map. Note, however, that if TVMAP is
called from CTM_PLOT, the default is to plot a map that
keeps the aspect ratio (which is about the same as
isotropic).
LIMIT -> A four-element vector which specifies the latitude
and longitude extent of the map. The elements of LIMIT
are arranged thus: [ LatMin, LonMin, LatMax, LonMax ].
Default is to set LIMIT = [ -90, -180, 90, 180 ] (i.e.
to include the entire globe). P0Lon will be computed
to fit into the LIMIT range unless it is explicitely
requested in MParam.
POLAR -> Plot a polar stereographic projection. If set and
equal 1 then the plot goes from the pole to a latitude
defined by either the extend of the data or by the user
through the LIMIT keyword. If set and equal to 2, then
the full hemisphere is plot, regardless of the data or
LIMIT settings.
Note that setting the /STEREOGRAPHIC keyword wouldn't
work.
POSITION -> A four-element array of normalized coordinates
that specifies the location of the map. POSITION has
the same form as the POSITION keyword on a plot.
Default is [0.0, 0.15, 1.0, 1.0] with Horizontal Color
Bar, and [0., 0., 0.82, 1.0] with Vertical CBar.
MARGIN -> specify a margin around the plot in normalized
coordinates. This keyword does not change any IDL
system variables and will thus only become "visible"
if you use the POSITION returned by MULTIPANEL in
subsequent plot commands. MARGIN can either be one value
which will be applied to all four margins, or a 2-element
vector which results in equal values for the left and
right and equal values for the bottom and top margins,
or a 4-element vector with [left,bottom,right,top]. The
default MARGIN setting is [ 0.05, 0.04, 0.03, 0.07 ].
OMARGIN -> specify a page margin around all panels in normalized
coordinates. Works like MARGIN.
SCALEMAPSET -> To pass the SCALE keyword to MAP_SET.
TITLE -> The title string that is to be placed atop the
plot window. TITLE is passed explicitly to avoid keyword
name duplication in the _EXTRA=e facility.
Keywords passed to MAP_LABELS:
==================================
LATS, LONS -> Array of latitudes (longitudes) used to
construct the map labels. If LATS has one element, the
LATS vector is build with LATS+n*DLAT, with as n as
needed to cover the map range. If it has more than one
element, it is not modified and it is the final grid.
DLAT, DLON -> Latitude (longitude) interval between grid
lines. Passed with _extra.
Keywords passed to MAP_CONTINENTS:
==================================
/CONTINENTS -> If set, will call MAP_CONTINENTS to plot
continent outlines or filled boundaries. Default is 0.
/COUNTRIES -> If set, will call MAP_CONTINENTS to draw the
political boundaries of countries as of 1993.
/COASTS -> If set, will call MAP_CONTINENTS to draw the coast
lines of continental regions.
CCOLOR -> The color index of the continent outline or fill
region. Default is BLACK (see above).
CFILL -> Value passed to FILL_CONTINENTS keyword of MAP_CONTINENTS.
If CFILL=1 then will fill continents with a solid color
(as specified in CCOLOR above). If CFILL=2 then will fill
continents with hatching.
/USA -> Set this switch to turn on US State boundaries.
Keywords passed to MAP_GRID:
============================
/BOX_AXES -> If set, then MAP_GRID will print alternating
light & dark regions with the lon & lat labels around
the border of the plot. This is passed directly to
MAP_GRID. NOTE: BOX_AXES is the default for the CONUS
option.
/GRID -> If set, will call MAP_GRID to plot grid lines and
labels. Labels can be turned off with /NOGLABELS.
Default is _not_ to plot grid lines.
GCOLOR -> The color index of the grid lines. Default is
BLACK (see above).
/NOGXLABELS -> If set, TVMAP will suppress printing longitude
labels for each grid line.
/NOGYLABELS -> If set, TVMAP will suppress printing latitude
labels for each grid line.
Keywords passed to CONTOUR:
===========================
/CONTOUR -> Will produce a line-contour map instead of the
default color-pixel image map.
/FCONTOUR -> Will produce a filled-contour map instead
of the default color-pixel image map.
C_LEVELS -> Vector containing the contour levels. If not
specified, will use preset default levels.
C_ANNOTATION -> Vector containing the contour labels.
Default is to use string representations of C_LEVELS.
C_FORMAT -> Format string used in converting C_LEVELS to
the default C_ANNOTATION values. Default is '(f8.1)'.
C_COLORS -> Index array of color levels for contour lines or
fill regions. If not specified then will use uniformly
spaced default color levels. If C_COLORS is set to a
scalar value, then all contour lines will have the same
color value.
C_LABELS -> Specifies which contour levels should be labeled.
By default, every other contour level is labeled. C_LABELS
allows you to override this default and explicitly
specify the levels to label. This parameter is a vector,
converted to integer type if necessary. If the LEVELS
keyword is specified, the elements of C_LABELS
correspond directly to the levels specified, otherwise,
they correspond to the default levels chosen by the
CONTOUR procedure. Setting an element of the vector to
zero causes that contour label to not be labeled. A
nonzero value forces labeling.
/C_LINES -> Will overplot a filled-contour map with contour lines
and labels instead of plotting a colorbar. This was the old
default behaviour but has been changed with the advent of
"discrete" colorbars. The old NOLINES keyword is kept
for compatibility reasons but doesn't do anything.
/NOLABELS -> Will suppress printing contour labels on both
line-contour and filled-contour maps.
OVERLAYCOLOR -> Color of the solid lines that will be
overlaid atop a filled contour map. Default is BLACK.
Keywords passed to MAP_IMAGE (prior: to REBIN):
==============================================
/SAMPLE -> Used to rebin the byte-scaled image array to a
larger size. If /SAMPLE is set, then MAP_IMAGE will use
nearest-neighbor sampling rather than bilinear
interpolation.
Keyword passed to TVIMAGE:
===============================================
SCALEMAPIMAGE -> Sets the number of pixels per graphic coordinate
in PostScript and other devices with scalable
pixels. Larger values produce better resolution output,
but much larger file sizes. The default value is
0.04. Use a larger number for higher resolution if your
image does not exactly fit on the map projection.
OUTPUTS:
None
SUBROUTINES:
External subroutines required:
------------------------------
COLORBAR ( by Martin Schultz & David Fanning )
TVIMAGE ( by David Fanning )
RECTANGLE ( by Martin Schultz )
CONVERT_LON ( by Martin Schultz )
INV_INDEX ( function, by Martin Schultz )
MAP_LABELS ( by Martin Schultz & Bob Yantosca )
LOGLEVELS ( by Martin Schultz )
GET_DEFAULTFORMAT ( by Martin Schultz )
MYCT_DEFAULTS ( by Bob Yantosca )
REQUIREMENTS:
Assumes that a MYCT colortable has been loaded.
NOTES:
(1) The _EXTRA facility now picks up keywords for multiple
routines (this is a new feature in IDL v. 5.0+!!)
(2) Some keywords are saved in local variables with
slightly different names (e.g. MCONTOUR for /CONTOUR)
to prevent confusion with routine names and/or keywords
that are picked up by the _EXTRA=e facility.
(4) For contour plots, contour labels will be specified
using the C_ANNOTATION keyword. The downside is that
by using C_ANNOTATION, this disables the C_LABELS keyword
and so one cannot specify which contour lines will get
labels. The solution would be to expand the C_LABELS
vector so that it has the same number of elements as
C_ANNOTATION, and then to individually zero the
corresponding elements of C_ANNOTATION before making
the contour plot. Don't have enough time for this now,
but maybe can deal with this at a later time...
(5) Now references the !MYCT system variable. This should
be defined at the start of your IDL session when "myct.pro"
is called from "idl_startup.pro".
LIMITATIONS:
(1) The case of plot over the dateline is working fine only if
LIMIT[3] is negative and LIMIT[1] is positive. Other cases are
not specifically handled and results may not be reliable.
(2) Since we are using MAP_IMAGE, pixel plots do start and end
at longitude and latitude centers of the grid by default,
like contour plots. More map coverage is done in three cases:
(2a) Data sets that cover the globe will fill the map with
coarse pixel plots.
(2b) Data sets that cover the globe will fill the map only
in the longitude direction with smooth pixel and contour
plot. Plots start and stop at the first and last latitudes
centers.
(2c) Data sets that do not cover the globe will start and
end at grid edges with coarse pixels, only if the limit of
the map is less than half grid size away from the the
first/last latitude and longitude centers. This limitation
is due to the method used to pad the data outside the
domain delimited by X/Y arrays.
(3) MAP_IMAGE assumes that an evenly spaced data set is
passed. If X or Y array is not evenly spaced, pixels plots are
flawed and not reliable. Contour plots are ok.
EXAMPLE:
(1)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC
/SAMPLE, TITLE='O3 at 10 km'
(2)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC
TITLE='O3 at 10 km'
; Plots a 2-D "smooth" pixel map.
(3)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC $
/FCONTOUR, TITLE='O3 at 10 km', $
C_LEVELS=[10,20,30,40,50,60,70,80,90,100]
; Plots a 2-D filled contour map.
(4)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC $
/FCONTOUR, TITLE='O3 at 10 km', $
C_LEVELS=[10,20,30,40,50,60,70,80,90,100], $
/NOGXLABELS, /NOGYLABELS, /BOX_AXES
; Same as Example (3), but prints prints box-style
; axes via the /BOX_AXES feature of MAP_GRID.
MODIFICATION HISTORY:
bmy, 13 Apr 1998: VERSION 1.00
bmy, 11 Jun 1998: - now returns if there is
nothing to plot
mgs, 15 Jun 1998: - bug fix: n_elements instead of
keyword_set
bmy, 22 Sep 1998: VERSION 1.10
- Now use _EXTRA=e to pass keywords to
BYTSCL, TVIMAGE, MAP_SET, and COLORBAR
- added MAPTITLE and UNIT keywords to
avoid keyword name duplication in
_EXTRA=e.
bmy, 25 Sep 1998: VERSION 2.00
- now calls MAP_CONTINENTS and MAP_GRID
- keywords renamed for consistency
- reduced default size for CBPOSITION
bmy, 28 Sep 1998: VERSION 2.01
- MPOSITION renamed to POSITION, MCOLOR to
COLOR, MTITLE to TITLE for consistency
- LONSHIFT renamed to LSHIFT to avoid
problems with ambiguous keyword names
bmy, 07 Sep 1998: VERSION 3.00
- now can plot contour map or color-pixel
map (added CONTOUR and FCONTOUR keywords,
and XARR and YARR parameters)
- The colorbar is now optional, and is
turned on via the /COLORBAR switch.
bmy, 12 Nov 1998: VERSION 3.01
- added ISOTROPIC, SAMPLE, KEEP_ASPECT_RATIO,
C_LABELS, and C_FORMAT keywords
- now isotropic-scale color-image plots
and isotropic-scale contour plots are
handled correctly
- Use mgs-style default levels & colors for
contour and filled-contour maps.
bmy, 13 Nov 1998: - updated comments
- renamed C_LEVELS to C_ANNOTATION to
prevent keyword name confusion
- added NOLINES, NOLABELS, C_LABELS,
and OVERLAYCOLOR keywords
- contour lines and labels can be
suppressed correctly
- added mgs fix so that PostScript
pixel-maps appear smoother
- a border is now plotted around the
map window, without inserting any of that
annoying "cushion" space.
- added LOG keyword for logarithmic
contours and/or pixel colors
- use KEYWORD_SET more often
mgs, 17 Nov 1998: - re-arranged calls to map_set and tvimage
in order to maximize size
- output of title now seperate from map_set
- added CBFormat keyword
mgs, 19 Nov 1998: - CBFormat now handled in colorbar.pro
mgs, 20 Nov 1998: - bug fix for map_set for contour plots
mgs, 03 Dec 1998: - filled continents now added before contours
- CFILL keyword checked for consistency
bmy, 08 Feb 1999: - If /LOG is set, make sure that we don't
take the log of zero and incur a math error
- add call to function INV_INDEX
bmy, 23 Feb 1999: - added /GLABELS keyword to turn on/off printing
of labels for each grid line on the map
- added call to CONVERT_LON for longitudes
that straddle the date line
bmy, 26 Feb 1999: - added LIMIT as an explicit keyword
- now uses MAP_LABELS to construct grid labels
- updated comments
bmy, 04 Mar 1999: - added DEBUG keyword for debug output
mgs, 17 Mar 1999: - some cleaning:
- LSHIFT, DLON, and GLABELS made obsolete
- new keyword NOGLABELS
- P0Lon now computed from LIMIT information.
- Updated call to map_labels
- For contour plots: XArr, YArr no longer
mandatory (although they should be provided)
- much smarter default contour levels
mgs, 22 Mar 1999: - added multi-panel ability through use of
the new MULTIPANEL routine. This alters the
meaning of MPosition and CB_Position: they now
refer to positions in the current plot panel!
mgs, 23 Mar 1999: - fixed a few minor things
- charsize is now adjusted according to number
of panels on page
bmy, 25 Mar 1999: - If CBAR=0, then print unit string below
plot (formerly was done in CTM_PLOT)
- now use updated GET_DEFAULTFORMAT
- updated comments
- if NPANELS >=2 then place the plot title
higher above the window, to allow for
carriage-returned lines
mgs, 23 Apr 1999: - added CBMin and CBMax keywords for
tighter colorbar control
mgs, 19 May 1999: - title shifted a little higher if it has
more than 1 line.
bmy & mgs, 26 May 1999: - added POLAR keyword and respective support.
bmy, 27 May 1999: - bug fix for isotropic contour plots
mgs, 27 May 1999: - added support for discrete colorbars and
changed default behaviour for filled
contour plots: now plots a colorbar and
no lines.
bmy, 03 Jun 1999: - For polar plots, if the latitude range
spans more than 60 degrees, only plot
labels for [ 30, 60, 90 ] degrees.
mgs, 03 Jun 1999: - CFill now also allowed for filled contours
or pixel plots (data will be overplotted)
bmy, 09 Jun 1999: - Set CBUnit to '' if nothing passed
bmy, 21 Jun 1999: - Added MIN_VALID keyword.
bmy, 06 Jul 1999: - bug fix for min_valid: ge replaces gt.
bmy, 07 Jul 1999: - Save C_COLORS in a temp variable. Also
define C_COLORS so that grayscales won't
appear in Postscript plots
- multi-panel plots are now well-separated
from each other (for PostScript output)
bmy, 08 Jul 1999: - more minor fixes
bmy, 18 Nov 1999: - increase default left margin by a little
bmy, 31 Mar 2000: GAMAP VERSION 1.45
- make CSFAC and TITLECSFAC into keywords
bmy, 10 May 2000: - make sure XARR and YARR (if passed) are 1D vectors
- now use XARR, YARR to set default limits
- rearranged keyword settings code for clarity
- added more debug output (when /DEBUG is set)
bmy, 26 May 2000: - updated comments
bmy, 13 Jun 2000: - added /COUNTRIES and /COASTS keywords.
Setting /COUNTRIES, /COASTS, or /CONTINENTS
will now invoke routine MAP_CONTINENTS
bmy, 30 Jan 2001: GAMAP VERSION 1.47
- if NOGLABELS=0 and GRID=0, will print out
grid labels w/o printing out grid lines
- added MARGIN keyword for MULTIPANEL
- also allow coarse plots with /SAMPLE
when using the Z-buffer device
bmy, 07 Jun 2001: - removed some obsolete code & comments
bmy, 02 Jul 2001: GAMAP VERSION 1.48
- added /NOGXLABELS and /NOGYLABELS keywords
to suppress printing either lon or lat
grid labels, if so desired.
bmy, 13 Jul 2001: - bug fix: remove _EXTRA=e from MAP_SET call
when making pixel plots. This prevents extra
grid lines from being drawn on the map.
bmy, 23 Jul 2001: - now call MYCT_DEFAULTS to specify default
values for BLACK, BOTTOM, NCOLORS, etc
if these keywords are not passed explicitly.
bmy, 31 Oct 2001: GAMAP VERSION 1.49
- add /NOADVANCE keyword to prevent advancing
to the next page (in case you want to overplot)
bmy, 08 May 2002: GAMAP VERSION 1.50
- If the data array has more than 100,000 elements,
then assign it a dithering factor of 1, so that
we don't run out of memory when trying to plot it
bmy, 20 Jun 2002: GAMAP VERSION 1.51
- added WINDOWPOSITION keyword to return
the position vector of the plot window
region to the calling program
bmy, 28 Sep 2002: - now gets MYCT default parameters from the
!MYCT system variable
bmy, 10 Oct 2002: - bug fix: MCOLOR=!MYCT.BLACK setting has
now been restored (was left commented out)
bmy, 14 Nov 2002: GAMAP VERSION 1.52
- If GLABELS=0, then this also sets GXLABELS=0
and GYLABELS=0.
- Removed obsolete keywords
- Removed reference to MYCT_DEFAULTS.
bmy, 02 Mar 2004: GAMAP VERSION 2.02
- added OMARGIN keyword so that we can put
an outer margin around all plot panels
bmy, 28 May 2004: - Now returns the modified value of
C_COLORS to the calling program
- added CBTICKLEN keyword to specify the
color bar tick length
bmy, 23 Aug 2005: GAMAP VERSION 2.04
- added MAX_VALID keyword
- now adjust MINDATA to MIN_VALID and
MAXDATA to MAX_VALID internally
- Now pass _EXTRA=e to XYOUTS
tmf & bmy, 04 Oct 2006: GAMAP VERSION 2.05
- Replace /ERASE keyword with /NOERASE
to facilitate manual positioning of
plots. Pass /NOERASE to MULTIPANEL.
bmy & phs, 18 Sep 2007: GAMAP VERSION 2.10
- Don't reset data below MIN_VALID to
MIN_VALID for contour plots
- fix MAX_VALID for contour plots.
- fix CBar behavior when C_LEVELS is passed
cdh/phs/bmy 26 Nov 2007: GAMAP VERSION 2.11
- do not modify input DATA & X/YARR
- add support for VERTICAL COLORBAR
- add support for CONUS projection
- now all map projections are supported for
all 4 types of plots.
- now data Latitudes and Longitudes (X/Yarr)
are taken into account in Pixel
plot: no more need to clip the data
before plotting, TVMAP will do it, like
it already does for Contour plots.
- added Full Hemisphere Polar plot option,
regardless of DATA range and LIMIT keyword
- added RECTANGLE keyword to overwrite
default behavior
- map plotting coordinate system active at
exit, allowing for easy oplot
- default LIMIT for small data set corrected
- various fixes for across-the-dateline plots
- remove obsolete KEEP_ASPECT_RATIO keyword
- add /HORIZON keyword to call MAP_HORIZON
- updated comments
phs, 19 Dec 2007: - new default map limit in case of
non-global smooth pixel and contour
plots.
- plots start and end at box edges in few
new cases.
- replace /CENTER with /MINUS_ONE in call
to CONGRID
phs, 12 Feb 2008: GAMAP VERSION 2.12
- Fixes for MIN_VALID and MAX_VALID
- The test for the LIMIT keyword is now to check
"if ( n_elements(limit) ne 4 )". This allows you
to disable the LIMIT keyword by also setting
LIMIT=0.
phs, 28 Feb 2008: - Couple of small padding improvements
- added SCALEMAPSET and SCALEMAPIMAGE to pass
their respective SCALE keyword to MAP_SET and
MAP_IMAGE.
- LONS and LATS keyword added, so the grid can
be specified. Work with DLAT and DLON, the
grid spacings that can be passed to MAP_LABELS
thru the _extra keyword.
cdh & phs, 21 Mar 2008: - added minimum support for LIMIT input as
8-elements vector
phs, 17 Apr 2008: - Added the TopOutOfRange and BotOutOfRange
keywords, so default color (white) for Out-Of
-Range data can be overwritten.
phs, 6 May 2008: - Added the GXLABELS and GYLABELS keywords
to specify which grid line to label.
phs, 19 Jun 2008: - Set default SCALE value for MapImage
(ScaleMapImage keyword) to 0.04 if PS device.
phs, 25 Mar 2009: GAMAP VERSION 2.13
- Added NAN_COLOR to specify color to use
for NaN and Infinite data
cdh, eml, phs, 19 Sep 2009: - Now C_LEVELS works with pixel plots and
any projection.
- Added LATS, LONS (to specify the grid), and
TOPLEVELVALUE (to specify the last level
in the colorbar when using C_LEVELS)
keywords
- fixed limit of CONUS projection
phs, 29 Oct 2009: GAMAP VERSION 2.14
- added the polyfill keyword
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tvmap.pro)
NAME:
TVPLOT
PURPOSE:
TVPLOT produces one of the following plots:
(1) A color-pixel image, overlaid atop X-Y plot axes
(2) A line-contour plot, overlaid atop X-Y plot axes
(3) A filled-contour plot, overlaid atop X-Y plot axes
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
TVPLOT, Data, Xarr, Yarr, [, keywords ]
INPUTS:
DATA -> 2-D array of values to be plotted.
XARR -> array of X-axis (horizontal axis) values needed to
construct the plot. The number of elements in XARR must
equal the number of elements of the first dimension of DATA.
ZARR -> ZARR is the array of Z-axis (vertical axis) values
needed to construct the plot. The number of elements
in ZARR must equal the number of elements of the second
dimension of DATA. If ZARR[0] > ZARR[N_Elements(ZARR)-1]
then TVPLOT will assume pressure is to be plotted on the
Y-axis.
KEYWORD PARAMETERS:
BLACK -> The color index corresponding to black.
Default is !MYCT.BLACK (from !MYCT system variable.)
/NOERASE -> This keyword prevents erasing the screen (or page)
when setting a multi-panel environment or after a page was
filled. /NOERASE is automatically turned ON when the /OFF
keyword is given. NOTE: On the PostScript device, when
the page is filled, it automatically places the next plot
on the next page. You can use the /NOERASE keyword to
suppress this behavior, especially if you are manually
placing plots on the page.
CSFAC -> Character size for the map labels and plot titles.
Default settings for CSFAC vary according to the number
of plots per page and type of plot device.
/NOADVANCE -> Set this switch to prevent TVMAP from advancing
to the next plot panel on the page. This is useful if
you desire to overplot something atop the pixel plot or
contour plot.
MARGIN -> specify a margin around the plot in normalized
coordinates. This keyword does not change any IDL
system variables and will thus only become "visible"
if you use the POSITION returned by MULTIPANEL in
subsequent plot commands. MARGIN can either be one value
which will be applied to all four margins, or a 2-element
vector which results in equal values for the left and
right and equal values for the bottom and top margins,
or a 4-element vector with [left,bottom,right,top]. The
default MARGIN setting is [ 0.05, 0.04, 0.00, 0.02 ].
-> adds 0.02 to the left margin for Y-axis title
-> adds 0.03 to the bottom margin for X-axis title
-> adds 0.03 to the right margin for vertical color bar
-> adds 0.02 to the top margin for more than 2 plots/page
OMARGIN -> specify a page margin around all panels in normalized
coordinates. Works like MARGIN.
WINDOWPOSITION -> Returns the position of the plot window
in normal coordinates to the calling program. This can
be used by a subsequent call to PLOT if you want to
overplot symbols atop the contour or pixel plot created
by TVPLOT.
_EXTRA=e -> Picks up extra keywords (not listed below) for
BYTSCL, COLORBAR, TVIMAGE, MAP_SET, MAP_GRID,
MAP_CONTINENTS, and CONTOUR.
Keywords for both BYTSCL and COLORBAR:
======================================
MAXDATA -> Maximum value of the DATA array to use in the
byte scaling. Default is max( DATA ).
MINDATA -> Minimum value of the DATA array to use in the
byte scaling. Default is min( DATA ).
BOTTOM -> The lowest color index of the colors to be used
for byte-scaling the color map and colorbar. Default
is !MYCT.BOTTOM (from the !MYCT system variable).
NCOLORS -> This is the maximum color index that will be used.
Default is !MYCT.NCOLOR (from the !MYCT system variable).
/LOG -> Will create a color-pixel plot with logarithmic
scaling. /LOG has no effect on line-contour or
filled-contour plots, since the default contour levels
are logarithmic.
Additional keywords for COLORBAR:
=================================
/CBAR -> If set, will plot the colorbar below the map in the
position specified by CBPOSITION. Default is to NOT
plot a colorbar.
CBCOLOR -> Color index of the colorbar outline and
characters. Defaults to BLACK (see above).
CBPOSITION -> A four-element array of normalized coordinates
that specifies the location of the colorbar. CBPOSITION
has the same form as the POSITION keyword on a plot.
Default is [0.1, 0.05, 0.9, 0.08].
CBUNIT -> Passes the Unit string to COLORBAR, which will be
plotted to the right of the color bar.
CBFORMAT -> format to use in call to colorbar. Default is I12
if abs(max(data)) < 1e4, else e12.2 (strings get trimmed)
CBMIN, CBMAX -> Explicitly sets the min and max values of
the colorbar range. If not set, TVPLOT will set
CBMIN = min( DATA ) and CBMAX = max( DATA ).
CBTICKLEN -> Specifies the color bar tick length as a
fraction of the colorbar height (for horizontal
colorbars) or width (for vertical colorbars).
CBSCALE -> If set, then the printed tick labels are scaled by
powers of 10 to minimize overlap.
DIVISIONS -> Number of labels for the colorbar. Default is 4.
/CBVERTICAL -> Will draw a vertical colorbar instead of
a horizontal one. Default is to draw a horizontal
colorbar.
Keywords for INTERPOLATION:
===========================
/SAMPLE -> Used to get COARSE pixel plot. REBIN is called,
and uses the nearest-neighbor sampling.
Note that REBIN is used even if SAMPLE is not set, when
device is PostScript. It uses the bilinear interpolation
then.
/NOZINTERP -> set to switch off the vertical
interpolation. This can be used only if the ZARR is
evenly spaced.
Keywords for PLOT:
===================
BOTOUTOFRANGE -> Color index for data below
MIN_VALID. Default is white, or last color in color
table if !MYCT is not defined. If set to negative, the
color is used in the plot only, and not in the colorbar.
POSITION -> A four-element array of normalized coordinates
that specifies the location of the map. POSITION has
the same form as the POSITION keyword on a plot.
Default is [0.1, 0.1, 0.9, 0.9].
TITLE -> The title string that is to be placed atop the
plot window. TITLE is passed explicitly to avoid keyword
name duplication in the _EXTRA=e facility.
COLOR -> Color index for the plot window outline and titles.
Default is BLACK.
XSTYLE, YSTYLE -> Style settings for the X and Y axes. See
the "Graphics Keywords" settings man page for more info.
XSTYLE and YSTYLE are passed as explicit keywords to
avoid keyword name confusion in the _EXTRA=e facility.
XRANGE, YRANGE -> Two-element vectors for the X-axis and Y-axis
plot ranges, of the form [Xmin,Xmax] and [YMin,Ymax].
XRANGE and YRANGE are passed as explicit keywords to
avoid keyword name confusion in the _EXTRA=e facility.
XTITLE, YTITLE -> Titles for the X and Y axes. XTITLE and
YTITLE are passed as explicit keywords to avoid keyword
name confusion in the _EXTRA=e facility.
NOXLABEL, NOYLABEL -> Suppress printing tick labels for X and Y axes.
Keywords for CONTOUR:
=====================
/CONTOUR -> Will produce a line-contour map instead of the
default color-pixel image map.
/FCONTOUR -> Will produce a filled-contour map instead
of the default color-pixel image map.
C_LEVELS -> Vector containing the contour levels. If not
specified, will use preset default levels (see below).
C_ANNOTATION -> Vector containing the contour labels.
Default is to use string representations of C_LEVELS.
C_FORMAT -> Format string used in converting C_LEVELS to
the default C_ANNOTATION values. Default is '(f8.1)'.
C_COLORS -> Index array of color levels for contour lines or
fill regions. If not specified then will use uniformly
spaced default color levels. If C_COLORS is set to a
scalar value, then all contour lines will have the same
color value.
C_LABELS -> Specifies which contour levels should be labeled.
By default, every other contour level is labeled. C_LABELS
allows you to override this default and explicitly
specify the levels to label. This parameter is a vector,
converted to integer type if necessary. If the LEVELS
keyword is specified, the elements of C_LABELS
correspond directly to the levels specified, otherwise,
they correspond to the default levels chosen by the
CONTOUR procedure. Setting an element of the vector to
zero causes that contour label to not be labeled. A
nonzero value forces labeling.
/C_LINES -> Will overplot a filled-contour map with contour lines
and labels instead of plotting a colorbar. This was the old
default behaviour but has been changed with the advent of
"discrete" colorbars. The old NOLINES keyword is kept
for compatibility reasons but doesn't do anything.
/NOLABELS -> Will suppress printing contour labels on both
line-contour and filled-contour maps.
OVERLAYCOLOR -> Color of the solid lines that will be
overlaid atop a filled contour map. Default is BLACK.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==================================================
COLORBAR GET_DEFAULTFORMAT (function)
INV_INDEX (function) LOGLEVELS (function)
TVIMAGE
REQUIREMENTS:
Assumes that a MYCT colortable has been loaded.
NOTES:
(1) The _EXTRA facility picks extra keywords for BYTSCL,
TVIMAGE, PLOT and COLORBAR, etc... This is a new
feature in IDL v. 5.0+!!
(2) For contour plots, contour labels will be specified
using the C_ANNOTATION keyword. The downside is that
by using C_ANNOTATION, this disables the C_LABELS keyword
and so one cannot specify which contour lines will get
labels. The solution would be to expand the C_LABELS
vector so that it has the same number of elements as
C_ANNOTATION, and then to individually zero the
corresponding elements of C_ANNOTATION before making
the contour plot. Don't have enough time for this now,
but maybe can deal with this at a later time...
EXAMPLE:
POSITION = [0.1, 0.1, 0.9, 0.9 ] ; position for map
CBPOSITION = [0.1, 0.05, 0.9, 0.08] ; position for colorbar
TVPLOT, DATA, XARR, YARR, $
MAXDATA=MAXDATA, MINDATA=MINDATA, $
POSITION=POSITION, CBPOSITION=CBPOSITION, $
/ERASE, TITLE='Avg O3', $
XTITLE='Longitude', YTITLE='Altitude', $
DIVISIONS=4, FORMAT='(F6.2)'
MODIFICATION HISTORY:
bmy, 27 Apr 1998: VERSION 1.00
bmy, 04 Jun 1998: - now can plot separate X or Y axes
if [XY]STYLE = 4 or 8
mgs, 15 Jun 1998: - bug fix n_elements instead of keyword_set
- now does spline interpolation in the
vertical in order to get correct
altitudes
bmy, 21 Sep 1998: - Rename EXTRA1, EXTRA2, etc, to names
that have more meaning (e.g. E_BYT for
BytScl, E_TV for TVImage, etc.)
bmy, 22 Sep 1998: VERSION 1.10
- now uses _EXTRA=e facility to pass extra
keywords to BYTSCL, TVIMAGE, PLOT, and
COLORBAR.
- add PLOTTITLE (for PLOT) and UNIT (for
COLORBAR) keywords to prevent keyword
name duplication in _EXTRA=e.
mgs, 11 Nov 1998: - added CBar keyword
bmy, 16 Nov 1998: VERSION 2.00
- now can produce line-contour and filled-
contour plots as well as image plots
- now calls REBIN to rebin the byte-scaled
image array to higher resolution for
PostScript output.
- added the following keywords: /LOG,
/SAMPLE, /CONTOUR, /FCONTOUR, C_ANNOTATION,
C_LEVELS, C_LABELS, /NOLABELS, /NOLINES,
bmy, 17 Nov 1998: - For image plots, now only display plot axes
AFTER the image plot has been made. This
reduces the "apparent" wait time for the
user.
- renamed keywords to XA_TITLE, XA_RANGE,
XA_TICKNAME, etc to avoid keyword name
duplication in the _EXTRA=e facility.
mgs, 17 Nov 1998: - added CBFormat keyword
bmy, 18 Nov 1998: - also added floating point format for
CBFORMAT when abs(max(Data)) < 10
mgs, 19 Nov 1998: - CBFormat no whandled in colorbar.pro
bmy, 27 Jan 1999: - added defaults for XRANGE and YRANGE
bmy, 08 Jan 1999: - If /LOG is set, make sure that we don't
take the log of zero and incur a math error
- add call to function INV_INDEX
mgs, 18 Mar 1999: - cleaned up
- now uses loglevels and has smarter default
contour levels
mgs, 22 Mar 1999: - added multi-panel ability through use of
the new MULTIPANEL routine. This alters the
meaning of MPosition and CB_Position: they now
refer to positions in the current plot panel!
mgs, 23 Mar 1999: - fixed a few minor things
- charsize is now adjusted according to number
of panels on page
bmy, 25 Mar 1999: - now use updated GET_DEFAULTFORMAT
- if NPANELS >=2 then place the plot title
higher above the window, to allow for
carriage-returned lines
- updated comments
bmy, 27 Apr 1999: - commented out !x.charsize=csfac and
!y.charsize=csfac lines...these messed
up the plot window sizes
- updated comments
bmy, 28 Apr 1999: - added CBMin and CBMax keywords for
tighter colorbar control
mgs, 19 May 1999: - title shifted a little higher if it has
more than 1 line.
mgs, 21 May 1999: - variable name for TITLE now MTITLE as in
TVMAP.
mgs, 27 May 1999: - changed default behaviour for filled contours:
now plots "discrete" colorbar and no lines.
Keyword NoLines changed to C_Lines.
bmy, 10 Jun 1999: - CBUnit defaults to '
mgs, 06 Jul 1999: - adjusted charsize for multipanel plots
bmy, 07 Jul 1999: - Save C_COLORS in a temp variable. Also
define C_COLORS so that grayscales won't
appear in Postscript plots
- multi-panel plots are now well-separated
from each other (for PostScript output)
bmy, 08 Jul 1999: - more minor fixes
bmy, 18 Nov 1999: - increase default left margin by a little
bmy, 31 Mar 2000: GAMAP VERSION 1.45
- made CSFAC a keyword
bmy, 23 Jul 2001: GAMAP VERSION 1.48
- now call MYCT_DEFAULTS to specify default
values for BLACK, BOTTOM, NCOLORS, etc
if these keywords are not passed explicitly.
bmy, 07 Jul 2001: - removed obsolete code from 1998 and 1999
bmy, 31 Oct 2001: GAMAP VERSION 1.49
- add /NOADVANCE keyword to prevent advancing
to the next page (in case you want to overplot)
bmy, 28 Sep 2002: GAMAP VERSION 1.51
- now gets MYCT default parameters from the
!MYCT system variable
bmy, 15 Nov 2002: GAMAP VERSION 1.52
- Added MIN_VALID keyword to skip missing
data values for pixel plots
bmy, 18 Dec 2003: - For pixel plots, now linearly interpolate
when creating NDATA instead of using a
cubic spline. This is more accurate.
- Prevent NDATA from being extrapolated wildly
due to the slope at the surface and top level
of the plot.
bmy, 06 Jan 2003: - Now interpolate NDATA correctly when pressure
or altitude is on the Y-axis.
- Removed obsolete keywords XA_TITLE, YA_TITLE,
- XA_RANGE, YA_RANGE, XA_TICKNAME, YA_TICKNAME
- Now define default YRANGE = [ ZBOT, ZTOP ]
to make Y-axis labels correct for both pressure
and altitude on the Y-axis.
- Removed ZBOT, ZTOP from the keyword list;
these are now internal variables.
- updated comments
bmy, 02 Mar 2004: GAMAP VERSION 2.02
- added MARGIN keyword a la TVMAP
- added OMARGIN keyword
bmy, 28 May 2004: - Now returns the modified value of
C_COLORS to the calling program
- added CBTICKLEN keyword to specify the
color bar tick length
bmy, 30 Nov 2004: GAMAP VERSION 2.03
- added WINDOWPOSITION keyword
bmy, 12 Jul 2005: GAMAP VERSION 2.04
- added /ISOTROPIC keyword
- added /NOZINTERP keyword to prevent interpolation
to a fine grid of 100 pts in the vertical dim.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy & phs, 26 Nov 2007: GAMAP VERSION 2.11
- Minor fix for margins w/ for new TVIMAGE
- Also reset !P.MULTI=0 when using TVIMAGE
so that it will use the internally computed
position vector. Reset after TVIMAGE call.
- Make sure to label last colorbar division
for contour plots
- Vertical colorbar options and MIN_VALID,
MAX_VALID keywords are the same as TVMAP
- Extra space is now added to the default
MARGIN values for vertical colorbar
and multiple plots per page.
- Adjust default CBPOSITION values such
that the colorbar will be placed either
0.05 below or 0.02 to the right of the plot
phs, 04 Apr 2008: GAMAP VERSION 2.12
- now produces a better coarse pixel plot
for altitude vs latitude or longitude
plots, even though the initial box size
is not exactly reproduced.
cdh, eml, phs, 24 Sep 2009: GAMAP VERSION 2.13
- fixes for LOG10 plots
- new improved interpolation scheme in Z
direction
- C_LEVELS works with /SAMPLE
- added checks on NAN when looking at
min/max, added NAN_COLOR to specify a
color for NaN
- added BOTOUTOFRANGE to set color of data
below Min_Valid
- check if !MYCT is defined
xyue & bmy, 24 Jan 2011: GAMAP VERSION 2.15
- Replace /ERASE keyword with /NOERASE
to facilitate manual positioning of
plots. Pass /NOERASE to MULTIPANEL.
This is now consistent w/ TVMAP.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tvplot.pro)