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:
MAKE_CH_DATA
PURPOSE:
Driver program for CREATE_NESTED_DATA. Hardwired to
the North-America nested-grid of Qinbin Li.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_CH_DATA
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
None
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_CH_MET
MODIFICATION HISTORY:
bmy, 10 Apr 2003: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/make_ch_data.pro)
NAME:
MAKE_CH_MET
PURPOSE:
Driver program for CREATE_NESTED_MET. Hardwired to
the China/SE Asia nested-grid of Yuxuan Wang.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_CH_MET [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
MONYR -> Specifies the month & year (e.g. '2001/06/' )
FMASK -> File mask (default is '*')
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
None
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_NA_MET
MODIFICATION HISTORY:
bmy, 10 Apr 2003: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/make_ch_met.pro)
NAME:
MAKE_EUR_DATA
PURPOSE:
Driver program for CREATE_NESTED_DATA. Hardwired to
the North-America nested-grid of Qinbin Li.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_EUR_DATA
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_EUR_DATA
MODIFICATION HISTORY:
bmy, 15 May 2003: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/make_eur_data.pro)
NAME:
MAKE_EUR_MET
PURPOSE:
Driver program for CREATE_NESTED_MET. Hardwired to
the European nested-grid of Isabelle Bey.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_EUR_MET
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
None
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_EUR_MET
MODIFICATION HISTORY:
bmy, 10 Apr 2003: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/make_eur_met.pro)
NAME:
MAKE_MULTI_NC
PURPOSE:
Convert bpch files (matching a mask) to netCDF format.
The routine can work recursively : files in subdirectories
are also searched for.
This is a convenient generic wrapper for GAMAP routine
Bpch2coards.pro, to work on several files and directories at
once.
When working recursively, the directory tree in the input
directory is recreated as needed in the output directory.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
MAKE_MULTI_NC
INPUTS:
none
KEYWORD PARAMETERS:
MASK -> string, default is '*', that is all files
INPUT_PARENT_DIR -> top directory of files to convert, if
not specified, a dialog window pops up
OUTPUT_PARENT_DIR -> top directory destination for netCDF
files, if not specified, a dialog window pops up.
RECURSION -> to search subdirectories. Default is 0
(OFF). Set to 1 to turn it on.
TOKEN -> set if you want to replace 'bpch' with 'nc' in all
part of the full name. Default is to have extension
".nc" added to file name only.
OUTPUTS:
None
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
To work recursively on the directories, I use FILE_SEARCH
with 2 arguments. This is not possible with MFINDFILE, and
works only with IDL 5.5 and above.
EXAMPLES:
indir = '/as/data/geos/GEOS_1x1/EDGAR_200607/'
outdir = '/home/phs/data/EDGAR_200607/nc/'
mask = '*1x1'
make_multi_nc, input_parent_dir=indir, out=outdir, mask=mask, /r
MODIFICATION HISTORY:
Thu Oct 29 16:40:28 2009, Philippe Le Sager
now pass _extra keyword to BPCH2COARDS (eg /NAMER
needed for nested data)
Thu Feb 19 11:12:16 2009, Philippe Le Sager
renamed MAKE_MULTI_NC. Added recursion keyword
(default is OFF). Now **AUTOMATICALLY** creates missing
subdirectory in output directory tree, when in
recursive mode.
Tue Jan 27 10:40:49 2009, Philippe Le Sager
v1, based on make_c_nc.pro to work on several
directories at once.
bmy, 30 Nov 2010: GAMAP VERSION 2.15
- Updated comments and category in header
bmy, 01 Feb 2012: GAMAP VERSION 2.16
- Skip processing ASCII text files
mps, 04 Mar 2015: - Bug fix: Now assign InFileName before checking
file type
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_multi_nc.pro)
NAME:
MAKE_NA_DATA
PURPOSE:
Driver program for CREATE_NESTED_DATA. Hardwired to
the North-America nested-grid of Qinbin Li.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_NA_DATA
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
None
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_NA_MET
MODIFICATION HISTORY:
bmy, 10 Apr 2003: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/make_na_data.pro)
NAME:
MAKE_NA_MET
PURPOSE:
Driver program for CREATE_NESTED_MET. Hardwired to
the North-America nested-grid of Qinbin Li.
CATEGORY:
Regridding
CALLING SEQUENCE:
MAKE_NA_MET
INPUTS:
None
KEYWORD PARAMETERS:
MONYR -> Specifies the month & year (e.g. '2001/06/' )
FMASK -> File mask (default is '*')
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MFINDFILE (function)
EXTRACT_FILENAME (function)
CREATE_NESTED_MET
REQUIREMENTS:
None
NOTES:
For simplicity, input & output dirs, and X and Y
ranges have been hardwired. Change as necessary.
EXAMPLE:
MAKE_NA_MET
MODIFICATION HISTORY:
bmy, 10 Apr 2003: VERSION 1.00
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/make_na_met.pro)
NAME:
MAKE_NC_RECURSIVE
PURPOSE:
Converts files matching a mask to netCDF format.
The routine works recursively. This is a convenience
wrapper for GAMAP routine bpch2coards.pro, to work on
several directories at once.
You just need to (1) create the same directory tree in the
output location, then (2) run the routine once.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
MAKE_NC_RECURSIVE
INPUTS:
none
KEYWORD PARAMETERS:
MASK -> string, default is '*', that is all files
INPUT_PARENT_DIR -> top directory of files to convert, if
not specified, a dialog window pops up
NEW_PARENT_DIR -> top directory destination for netCDF
files, if not specified, a dialog window pops up
TOKEN -> set if you want to replace 'bpch' with 'nc' in all
part of the full name
OUTPUTS:
None
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
To work recursively on the directories, I use FILE_SEARCH
with 2 arguments. This is not possible with MFINDFILE, and
works only with IDL 5.5 and above.
EXAMPLE:
; after creating a subdirectories tree in outdir similar to the
; one in indir:
indir = '/as/data/geos/GEOS_1x1/EDGAR_200607/'
outdir = '/home/phs/data/EDGAR_200607/nc/'
mask = '*1x1'
make_nc_recursive, input_parent_dir=indir, new=outdir, mask=mask
MODIFICATION HISTORY:
Tue Jan 27 10:40:49 2009, Philippe Le Sager
v1, based on make_c_nc.pro to work on several
directories at once.
bmy, 30 Nov 2010: GAMAP VERSION 2.15
- Updated comments and categories in header
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_nc_recursive.pro)
NAME:
MAKE_PDF
PURPOSE:
Wrapper program for the Unix utility "ps2pdf". Creates
a PDF file for each PostScript file located in the
a user-specified directory.
CATEGORY:
File & I/O
CALLING SEQUENCE:
MAKE_PDF, DIR
INPUTS:
DIR -> Directory where PostScript files reside.
PDF files will be written out to this directory.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
ADD_SEPARATOR (function)
MFINDFILE (function)
REPLACE_TOKEN (function)
REQUIREMENTS:
You need "ps2pdf" installed on your system. This ships
with most versions of Unix or Linux.
Also requires routines from the GAMAP package.
NOTES:
PDF files will have the same names as the PostScript files
but with the *.pdf extension.
EXAMPLES:
MAKE_PDF, 'output'
; Create *.pdf Files from all *.ps files
; in the "output" directory.
MODIFICATION HISTORY:
bmy, 30 Nov 2010: GAMAP VERSION 2.15
- Initial version
bmy, 08 Jun 2011: - Make sure that the directory ends with a
path separator
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_pdf.pro)
NAME:
MAKE_RESTART
PURPOSE:
Creates a restart file for GEOS-Chem.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
MAKE_RESTART [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is "GEOS4_30L".
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
can be either a 2 element vector with [ DI, DJ ] or
a scalar (DJxDI: 8=8x10, 4=4x5, 2=2x2.5, 1=1x1,
0.5=0.5x0.5). Default for all models is 4x5.
OUTFILENAME -> Name of the restart file that will be created.
Default is "restart.bpch".
TAU0 -> TAU value (hours from 0 GMT on 01 Jan 1985) that
that will be used to timestamp the restart file.
The default TAU0 value 140256.00 (corresponds to
0 GMT on 01 Jan 2001).
TRACERLIST -> A scalar value (or vector) of tracer numbers
to write to the restart file. Default is 1.
DATAVALUE -> Specifies the data value that will be assigned
to all grid boxes in the restart file. Default is 0e0.
DIAGN -> Specifies the diagnostic category name that will
be used to index data fields in the restart file.
Default is "IJ-AVG-$".
UNIT -> Use this keyword to overwrite the default unit
string (as specified in the "tracerinfo.dat" file)
for each data block in the restart file.
/NO_VERTICAL -> Set this switch to create a restart file
with 2-D data blocks (e.g. lon x lat) instead of 3-D
data blocks (e.g. lon x lat x alt).
DIM -> Allows you to manually set the dimensions of the
data blocks (for nested grids). DIM is passed to
CTM_MAKE_DATAINFO.
FIRST -> Allows you to manually set the starting indices
(in Fortran notation, starting from 1) of the data
block. FIRST is passed to CTM_MAKE_DATAINFO.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===================================================
CTM_GET_DATABLOCK (function) CTM_GRID (function)
CTM_MAKE_DATAINFO (function) CTM_TYPE (function)
CTM_WRITEBPCH NYMD2TAU
REQUIREMENTS:
None
NOTES:
(1) You must make sure that your "diaginfo.dat" and
"tracerinfo.dat" file lists the diagnostic categories
and tracers that you wish to save to the restart file.
EXAMPLE:
MAKE_RESTART, OUTMODELNAME='GEOS4_30L', $
OUTRESOLUTION=2, $
OUTFILENAME='restart.2x25.2005010100', $
TAU0=NYMD2TAU( 20050101L ), $
DATAVALUE=100e0, $
TRACERLIST=[1,2,3,4,5,6], $
UNIT='ppbv', $
DIAGN='IJ-AVG-$'
; Create a GEOS-4 30-level 2x25 restart file for
; CO2 tracers 1-6, setting all tracers equal to
; 100 ppbv.
MODIFICATION HISTORY:
bmy, 19 Jul 2007: VERSION 1.00
bmy, 27 Oct 2010: GAMAP VERSION 2.15
- Added DIM and FIRST for setting the
region properly for nested grids
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_restart.pro)
NAME:
MAKE_SELECTION (function)
PURPOSE:
Convert an array of selected values to an index array that
identifies the selected values in a list or data array.
CATEGORY:
General
CALLING SEQUENCE:
INDEX = MAKE_SELECTION( NAMES, SELNAMES [,keywords] )
INPUTS:
NAMES -> A list or array of values to choose from
SELNAMES -> A list of selected values
KEYWORD PARAMETERS:
ONLY_VALID -> Return only indices of found values. Values not
found are skipped. Default is to return 1 index value for
each SELNAME, which is -1 if SELNAME is not contained in
NAMES. If ONLY_VALID is set, the -1 values will be deleted,
and a value of -1 indicates that no SELNAME has been found
at all.
REQUIRED -> Normally, MAKE_SELECTION will return indices for
all values that are found, simply ignoring the selected
values that are not in the NAMES array (although an error
message is displayed). Set this keyword to return with
-1 as soon as a selected value is not found.
QUIET -> Suppress printing of the error message if a
selected value is not found (the error condition will
still be set).
OUTPUTS:
INDEX -> A (long) array with indices to reference the
selected values in the NAMES array.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
If the NAMES array contains multiple entries of the same value,
only the index to the first entry will be returned.
A selection can contain multiple instances of the same value.
The index array will contain one entry per selected item
(See example below)
EXAMPLES:
(1)
NAMES = [ 'Alfred','Anton','Peter','John','Mary']
INDEX = MAKE_SELECTION( NAMES, ['Peter','Mary'] )
PRINT, INDEX
2 4
(2)
VALS = INDGEN(20)
INDEX = MAKE_SELECTION( VALS, [9,-5,8,7,7,8,9] )
PRINT, INDEX
9 -1 8 7 7 8 9
(3)
INDEX = MAKE_SELECTION( VALS,[9,-5,8,7,7,8,9], /ONLY_VALID )
PRINT, INDEX
9 8 7 7 8 9
(4)
INDEX = MAKE_SELECTION( vals, [9,-5,8,7,7,8,9], /REQUIRED )
PRINT, INDEX
-1
MODIFICATION HISTORY:
mgs, 28 Aug 1998: VERSION 1.00
mgs, 29 Aug 1998: - changed behaviour and added ONLY_VALID keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/make_selection.pro)
NAME:
MAPS
PURPOSE:
Creates lon-lat maps of GEOS-Chem tracers at the
surface and 500 hPa levels.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
MAPS, FILE, LEVELS, TAUS, TRACERS, VERSION, [, Keywords ]
INPUTS:
FILE -> The name of the file containing data to be plotted.
LEVELS -> A 4-element vector containing the level indices
for the GEOS-Chem surface layer and 500 hPa layer.
for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
NOTE: This is in Fortran notation (starting from 1!)
TAU -> The TAU value (hours GMT from /1/1985) corresponding
to the data to be plotted.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$").
VERSION -> The model version number corresponding to the
data to be plotted.
KEYWORD PARAMETERS:
/DO_FULLCHEM -> Set this switch to plot the chemically
produced OH in addition to the advected tracers.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Provided:
==================================================
PlotMap
External Subroutines Required:
==================================================
CLOSE_DEVICE COLORBAR_NDIV (function)
CTM_GET_DATA EXTRACT_FILENAME (function)
GETMODELANDGRIDINFO MULTIPANEL
MYCT OPEN_DEVICE
TVMAP CHKSTRU (function)
UNDEFINE
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLES:
FILE = 'ctm.bpch.v7-04-11'
LEVELS = [ 1, 1, 13, 13 ]
TAUS = NYMD2TAU( 20010701 )
TRACERS = INDGEN( 43 ) + 1
VERSIONS = 'v7-04-11'
MAPS, FILE, LEVELS, TAU, TRACERS, VERSION, $
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'
; Creates tracer maps of GEOS-CHEM v7-04-11 for July 2001.
; Output is sent to PostScript file "myplot.ps".
MODIFICATION HISTORY:
bmy, 14 Nov 2007: VERSION 1.01
- Based on "tracer_map.pro"
bmy, 07 May 2008: VERSION 1.06
- Now allow for comparing models on 2
bmy, 08 Jun 2011: VERSION 1.07
- Added /DO_FULLCHEM keyword
- Now restore !MYCT sysvar to previous
settings upon exiting the program
mps, 29 Mar 2013: - Now plot chemically produced HO2
(See /n/home09/ryantosca/IDL/gamap2/benchmark/maps.pro)
NAME:
MAPS_AOD
PURPOSE:
Creates column maps of aerosol optical depths from 1-month
GEOS-Chem benchmark simulation output.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
MAPS_AOD_1YR, FILES, TRACERS, VERSIONS, [, Keywords ]
INPUTS:
FILES -> A 2-element vector containing the names of files
from the "red", 'green", and "blue" GEOS-Chem model
versions that are to be compared.
TAUS -> A 2-element vector contaning TAU values (hours GMT
from /1/1985) corresponding to the "old" and "new"
GEOS-Chem model versions.
TRACERS -> The list of transported tracers (i.e. diagnostic
category "IJ-AVG-$") to be plotted.
VERSIONS -> A 2-element vector containing the model version
names from the "red", 'green", and "blue" simulations.
KEYWORD PARAMETERS:
/DYNRANGE -> Set this switch to create plots using the entire
dynamic range of the data (centered around zero). The
default is to use pre-defined data ranges.
/PS -> Set this switch to generate PostScript output.
OUTFILENAME -> If /PS is set, will write PostScript output
to a file whose name is specified by this keyword.
Default is "tracer_ratio.pro".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Provided:
=========================================
PLOTDIFF
External Subroutines Required:
=========================================
OPEN_DEVICE CLOSE_DEVICE
MULTIPANEL COLORBAR_NDIV (function)
CTM_PLOT CHKSTRU (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Meant to be called from BENCHMARK_1MON.
EXAMPLE:
FILES = [ 'ctm.bpch.v9-02p', 'ctm.bpch.v9-02q' ]
TAUS = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
TRACERS = [ 1, 2, 4 ]
VERSIONS = [ 'v9-02p', 'v9-02q' ]
DIFFERENCES_1YR, FILES, TAUS, TRACERS, VERSIONS, $
/PS, OUTFILENAME=myplot.ps'
; Creates maps from 2 different model versions
; using output from GEOS-Chem 1-month benchmark simulations.
DIFFERENCES_1YR, FILES, TAUS, TRACERS, VERSIONS, /DYNRANGE, $
/PS, OUTFILENAME=PSNAME
; Same as above, but will create difference maps using
; the full dynamic range of the data (centered around zero)
; instead of using pre-defined min & max values.
MODIFICATION HISTORY:
bmy, 05 Sep 2012: VERSION 1.01
- Initial version
mps, 16 Sep 2013: - Modified for 1-month benchmark output
bmy, 24 Jan 2014: GAMAP VERSION 2.17
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/benchmark/maps_aod.pro)
NAME:
MAP_LABELS
PURPOSE:
Constructs map labels from numerical values, in either
numerical format (e.g. "-90", "0", "90" ), or in
directional format ( e.g. "90S, "0", "90N" ).
CATEGORY:
Plotting
CALLING SEQUENCE:
MAP_LABELS, LATLABEL, LONLABEL [ , Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
LATRANGE, LONRANGE -> The range of latitudes (longitudes)
for the map or plot area.
LATS, LONS -> Returns to the calling program the array of
latitudes (longitudes) used to construct the map labels.
Can also be use as input: if LATS has one element, the
LATS vector is build with LATS+n*DLAT; if it has more
than one element, it is not modified and is the final
grid.
DLAT, DLON -> Returns to the calling program the latitude
(longitude) interval between grid lines.
Now, can also be used as input so the user can specify
the grid spacing.
/MAPGRID -> If set, will assume that latitude and longitude
labels are for grid lines on a world map. Also compute
normal coordinates which can be used for placing the
labels next to the map.
NORMLATS -> 2D Array containing normal X and Y
coordinates for placing latitude labels outside map
boundaries. These are computed only if /MAPGRID is set.
NORMLONS -> 2D-Array containing normal X and Y
coordinates for placing latitude labels outside map
boundaries. These are computed only if /MAPGRID is set.
Keywords Passed to CONSTRUCT_MAP_LABELS:
========================================
FORMAT -> Format descriptor string used in converting the
values from DATA into string representation. The
default value is '(i10)'.
/NUMERIC -> If set, will return latitude or longitude
labels in numerical format (e.g. "-90", "0", "+90").
If not set, will return latitude or longitude labels
in directional format (e.g. "90S, "0", "90N")
/NODEGREE -> If set, will prevent the raised degree symbol
from being appended to MAPLABEL. Default is to add the
raised degree symbol to MAPLABEL.
OUTPUTS:
LATLABEL -> String array of latitude labels
LONLABEL -> String array of longitude labels
SUBROUTINES:
Internal Subroutines Used:
=================================
CONSTRUCT_MAP_LABELS (function)
GET_GRIDSPACING
External Subroutines Required:
=================================
STRREPL (function)
REQUIREMENTS:
None
NOTES:
(1) LATLABEL and LONLABEL are in the range of -180..180 degrees.
(2) We should at some point allow the user to supply individual values
that override the default spacing.
EXAMPLES:
(1) For use in conjunction with the PLOT command...
MAP_LABELS, YTICKNAME, XTICKNAME, $ ; Call MAP_LABELS
LATRANGE=[ -90,90], LONRANGE=[-180,180], $ ; to get the
LATS=LATS, LONS=XTICKV, $ ; lat and lon
_EXTRA=e ; tick labels
PLOT, XARR, YARR, XTICKV=XTICKV, $ ; call PLOT,
XTICKNAME=XTICKNAME, $ ; using the
XTICKS=N_ELEMENTS( XTICKV )-1, $ ; labels as
_EXTRA=e ; tick names
(2) For use in conjunction with MAP_SET and MAP_GRID
LIMIT = [ -90, -180, 90, 180 ] ; set up the
MAP_SET, LIMIT=Limit, _EXTRA=e ; world map
LATRANGE = [ Limit[0], Limit[2] ] ; define lat and
LONRANGE = [ Limit[1], Limit[3] ] ; lon ranges
MAP_LABELS, LATLABEL, LONLABEL, $ ; call MAP_LABELS
LATS=LATS, LATRANGE=LATRANGE, $ ; to return
LONS=LONS, LONRANGE=LONRANGE, $ ; the lat/lon
NORMLATS=NORMLATS, NORMLONS=NORMLONS, $ ; values, labels
/MAPGRID, _EXTRA=e ; normal coordinates
MAP_GRID, LATS=LATS, LONS=LONS, _EXTRA=e
; Plots the grid lines on the map
XYOUTS, NORMLATS[0,*], NORMLATS[1,*], $
LATLABEL, ALIGN=1.0, /NORMAL
; Plots latitude labels using normal coordinates
XYOUTS, NORMLONS[0,*], NORMLONS[1,*], $
LONLABEL, ALIGN=0.5, /NORMAL
; Plots longitude labels using normal coordinates
(2) For use in conjunction with TVMAP to control grid
TVMAP, DIST(42)
MODIFICATION HISTORY:
mgs, 19 Feb 1999: VERSION 1.00
bmy, 26 Feg 1999: VERSION 1.10
- now works for maps that are smaller
than global size.
bmy, 04 Mar 1999: VERSION 1.11
- added DEBUG keyword for output
- now computes NORM_XLAT correctly for
grids that are centered on -180 degrees
mgs, 17 Mar 1999: - cleaned up
- replaced Norm[XY]... by two dimensional
NormLons and NormLats
- Longitude conversion now done in CONSTRUCT_...
- calls MAP_SET if /MAPGRID is set and no
map has been established.
bmy, 25 Mar 1999: - double default DLON if more than 2 plots
per page
mgs, 23 Apr 1999: - bug fix for LON labels in Pacific mode
mgs & bmy, 03 Jun 1999: - fix for Pacific ranges in GET_GRIDSPACING
bmy, 17 Nov 2005: GAMAP VERSION 2.04
- Now allows for a spacing of 1 degree
if the plot range is smaller or equal to
10 degrees
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 29 Feb 2008: GAMAP VERSION 2.12
- Grid spacing can be set by user with
DLON and DLAT
- LONS/LATS can be use as input to specify
the start (if 1 element) or the entire
grid (more than 1 element)
- GET_GRIDSPACING is now a procedure
phs, 14 Mar 2008: - Added a new method to find the Labels
position. This can be used to overwrite
the old position with two new keywords,
NEWLONLAB and NEWLATLAB. Useful for map
projection defined with SCALE instead
of LIMIT. Need to pass MapPosition to work.
(See /n/home09/ryantosca/IDL/gamap2/plotting/map_labels.pro)
NAME:
MCF_LIFETIME
PURPOSE:
Computes the methylchloroform (CH3CCl3, aka "MCF") lifetime
w/r/t tropospheric OH from monthly-mean GEOS-Chem archived
fields.
CATEGORY:
Benchmarking
CALLING SEQUENCE:
MCF_LIFETIME, FILE, [ Keywords ]
INPUTS:
FILE -> Specifies the name of the file with GEOS-Chem
diagnostic output (bpch format or otherwise).
KEYWORD PARAMETERS:
LON -> A 2-element vector containing the minimum and maximum
longitude values to include in the computation of the MCF
lifetime. Default is [ -180, 180 ].
LAT -> A 2-element vector containing the minimum and maximum
latitude values to include in the computation of the MCF
lifetime. Default is [ -90, 90 ].
LEV_a -> A 2-element vector containing the minimum and maximum
levels (i.e. all vertical levels) to include in the
computation of the MCF lifetime. Default is [ 1, 47 ]
(corresponding to the GEOS-5 47-level simulation).
LEV_t -> a 2-element vector containing the minimum and
maximum tropospheric levels to include in the
computation of the MCF lifetime. Default is [ 1, 38 ]
(corresponding to the value of the max tropospheric
level LLTROP for a GEOS-5 47-level simulation.)
TAU0 -> TAU value (hours from 0 GMT on 1985/01/01) with which
the GEOS-Chem diagnostic data blocks are timestamped.
Default is 179664.00 (corresponding to 0 GMT on
2005/07/01).
/VERBOSE -> Will cause MCF_LIFETIME to print the methyl
chlofororm lifetime to the screen. The default is to
suppress printing.
OUTPUTS:
LIFE_YEARS -> Returns the MCF lifetime w/r/t tropopsheric
OH in years.
SUBROUTINES:
External subroutines required:
==============================
CTM_BoxSize (function)
CTM_Get_DataBlock (function)
Nymd2Tau (function)
REQUIREMENTS:
MCF_LIFETIME requires that the following GEOS-Chem
diagnostics be present in the input file:
(a) Grid box surface area [m2 ] (DXYP, tracer #1)
(b) Grid box heights [m ] (BXHGHT-$, tracer #1)
(c) Air number density [molec/m3 ] (BXHGHT-$, tracer #4)
(d) Chemically produced OH [molec/cm3] (CHEM-L=$, tracer #1)
(e) Time spent in tropopause [fraction ] (TIME-TPS, tracer #1)
(f) Temperature [K ] (DAO-3D-$, tracer #5)
Requires routines from the GAMAP package.
NOTES:
Derivation of MCF lifetime w/r/t tropospheric OH
----------------------------------------------------------
We assume that MCF has a uniform mixing ratio in air (=1).
Thus the density of air can be substituted for the density
of MCF in the equations below.
The lifetime of MCF w/ respect to tropospheric OH is:
T_OH = Atmospheric Burden / Tropospheric loss rate
The atmospheric burden of MCF is:
SUM{ AIRDEN(I,J,L) * VOLUME(I,J,L) }
where:
I = longitudes
J = latitudes
L = levels from the surface to top of atmosphere
AIRDEN = Air density at ([I,J,L) in molec/cm3
VOLUME = Grid box volume at (I,J,L) in cm3
The tropospheric loss rate of MCF is:
SUM{ K(I,J,X) * OH(I,J,X) * AIRDEN(I,J,X) * VOLUME(I,J,X) }
where
I = longitudes
J = latitudes
X = levels from the surface to the
location of the tropopause at (I,J)
(we only count boxes fully in the tropopause)
K(I,J,X) = 1.64e-12 * EXP( -1520 / T(I,J,X) )
T(I,J,X) = Temperature at grid box (I,J,X)
T_OH has several reported values in the literature:
(a) Spivakovsky et al (2000) : 5.7 years
(b) Prinn et al (2001) : 6.0 years
Derivation of total MCF lifetime:
----------------------------------------------------------
Once you have obtained the MCF lifetime w/r/t tropospheric
OH, you can compute the total lifetime of MCF as:
1/T_total = 1/T_OH + 1/T_strat + 1/T_ocean
where
T_total = total lifetime of MCF in atmosphere
T_OH = the output of this function
T_strat = 43 years (cf. Spivakovsky et al)
T_ocean = 94 years (range 81-145 years, cf WMO/UNEP)
References:
----------------------------------------------------------
(1) Prather, M. and C. Spivakovsky, "Tropospheric OH and
the lifetimes of hydrochlorofluorocarbons", JGR,
Vol 95, No. D11, 18723-18729, 1990.
(2) Lawrence, M.G, Joeckel, P, and von Kuhlmann, R., "What
does the global mean OH concentraton tell us?",
Atm. Chem. Phys, 1, 37-49, 2001.
(3) WMO/UNEP Scientific Assessment of Ozone Depletion: 2010
EXAMPLE:
LIFE = MCF_LIFETIME( 'ctm.bpch', $
LON=[-180,-180], $
LAT=[ -90, 90], $
LEV_A=[ 1, 47 ], $
LEV_T=[ 1, 38 ], $
TAU0=NYMD2TAU( 20050101 ) )
; Will return the MCF lifetime w/r/t tropospheric OH
; (in years) based on GEOS-Chem diagnostic output at
; model date 2005/01/01.
MODIFICATION HISTORY:
bmy, 08 Jun 2011: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/benchmark/mcf_lifetime.pro)
NAME:
MEAN
PURPOSE:
Computes the mean value of an array, along a given dimension.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = MEAN( X, DIM, _EXTRA=e )
INPUTS:
X -> The input vector or array.
DIM -> The dimension along which to compute the mean of X.
DIM may be omitted if the X is 1-dimensional.
KEYWORD PARAMETERS:
_EXTRA=e -> Passes extra keywords to the TOTAL command.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
Multidimensional version from Kevin Ivory (04/03/1997)
EXAMPLES:
(1)
PRINT, MEAN( FINDGEN(10) )
IDL prints:
4.50000
; Prints the mean of a 1-D array
(2)
ARRAY = MEAN( DIST(10,10), 2 )
HELP, ARRAY
PRINT, ARRAY
IDL prints:
ARRAY FLOAT = Array[10]
2.50000 2.79703 3.36695 4.08519 4.89073
5.75076 4.89073 4.08519 3.36695 2.79703
; Prints the mean of a 2-D array along
; the second dimension.
MODIFICATION HISTORY:
ivory, 04 Mar 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Cosmetic changes, added comments
(See /n/home09/ryantosca/IDL/gamap2/math_units/mean.pro)
NAME:
MERGE_FERT_SOILPREC
PURPOSE:
Merges nonzero soil fertilizer and soil precipitation
data onto the same indexing scheme. Also computes
NLAND, the number of land boxes used in "commsoil.h".
CATEGORY:
Regridding
CALLING SEQUENCE:
MERGE_FERT_SOILPREC [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
FERTFILE -> Name of the binary punch file containing soil
fertilizer data to be merged. The default file name
is hardwired (change as necessary).
SOILPRECFILE -> Name of the binary punch file containing soil
precipitation data to be merged. The default file name
is hardwired (change as necessary).
OUTDIR -> Name of the directory where the output file will
be written. Default is './'.
OUTPUTS:
Writes to ASCII output files:
fert_scale.dat.{MODELNAME}.{RESOLUTION}
climatprep{RESOLUTION}.dat.{MODELNAME}
SUBROUTINES:
External Subroutines Required:
==============================================
CTM_TYPE (function) CTM_GRID (function)
CTM_NAMEXT (function) CTM_RESEXT (function)
REQUIREMENTS:
None
NOTES:
(1) Input files must be binary punch files, created with
routines REGRID_FERT and REGRID_SOILPREC.
(2) Output files are in ASCII format and are compatible
with the existing Harvard CTM routines.
EXAMPLE:
MERGE_FERT_PRECIP, FERTFILE='nox_fert.geos1.2x25', $
PRECIPFILE='soil_precip.geos1.2x25', $
OUTDIR='/scratch/bmy'
; Will merge the soil fertilizer data contained in
; "nox_fert.geos1.2x25" and the soil precip data
; contained in soil_precip.geos1.2x25". Output files
; will be sent to the /scratch/bmy directory.
MODIFICATION HISTORY:
bmy, 04 Aug 2000: VERSION 1.00
- adapted from older IDL code
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/merge_fert_soilprec.pro)
NAME:
MERGE_OH
PURPOSE:
Creates a "Merged OH" file, with OH from the GEOS-CHEM
model in the troposphere and zonal mean OH from a 2-D
model in the stratosphere.
CATEGORY:
Regridding
CALLING SEQUENCE:
MERGE_OH, MODELNAME
INPUTS:
None
KEYWORD PARAMETERS:
MODELNAME -> Name of the model (e.g. GEOS1, GEOS-STRAT)
for which we are going to merge tropospheric OH with
stratospheric OH.
RESOLUTION -> Horizontal latitude resolution of the grid.
RESOLUTION=2 specifies 2 x 2.5 grid and
RESOLUTION=4 specifies 4 x 5 grid.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
====================================================
CTM_TYPE (function) CTM_GET_DATABLOCK (function)
CTM_GRID (function) CTM_MAKE_DATAINFO
REQUIREMENTS:
None
NOTES:
(1) The output file name has the form:
OH_3Dglobal.{MODELNAME}.{RESOLUTION}
(2) Filenames are currently hardwired for 4x5,
EXAMPLE:
MERGE_OH, MODELNAME='GEOS3', RESOLUTION=4
; Will merge stratospheric and tropospheric OH
; at the GEOS-1 4 x 5 resolution into a single
; binary punch file.
MODIFICATION HISTORY:
bey, 21 Jul 2000: VERSION 1.00
bmy, 11 Aug 2000: VERSION 1.01
- added standard header, updated comments
- renamed to "merge_oh.pro"
bmy, 04 Feb 2002: VERSION 1.02
- rewrote for expediency
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/regridding/merge_oh.pro)
NAME:
MFINDFILE
PURPOSE:
Find all the files that match a given specification.
MFINDFILE is a wrapper for IDL routines FILE_SEARCH
(v5.5 and higher) and FINDFILE (v5.4 and lower).
CATEGORY:
File & I/O
CALLING SEQUENCE:
LISTING = MFINDFILE( MASK )
INPUTS:
FILEMASK -> a path and filename specification to look for.
KEYWORD PARAMETERS:
none
OUTPUTS:
A string list containing all the files that match the
specification.
SUBROUTINES:
External Routines Required:
===========================
ADD_SEPARATOR (function)
REQUIREMENTS:
None
NOTES:
(1) For IDL 5.5+, use FILE_SEARCH to return a listing of
files with the given path name specified by MASK. This
should work regardless of platform.
(2) For IDL 5.4- running under Unix, The built-in FINDFILE()
function has problems on whenever a lot of files are
matching the file specification. This is due to the fact
that filename expansion is done by the shell before
interpreting a command. Too many files cause too long
commands which are not accepted. This causes FINDFILE()
to return an empty list of candidates. (cf. www.dfanning.com)
Therefore, we implement a workaround where we issue a
"ls -1" command under the Unix shell. This isn't 100%
foolproof either but it's better than nothing.
(3) For IDL 5.5- running under other operating systems,
call the built-in IDL FINDFILE routine as usual.
EXAMPLE:
LIST = MFINDFILE( '~mgs/terra/chem1d/code/*.f' )
; returns all fortran files in Martin's chem1d directory.
MODIFICATION HISTORY:
mgs, 14 Sep 1998: VERSION 1.00
bmy, 14 Oct 2003: TOOLS VERSION 1.53
- Now use built-in FINDFILE() routine to
return file listing for IDL 5.3 and higher
bmy, 06 Nov 2003: TOOLS VERSION 2.01
- return to pre v1-53 algorithm
bmy, 28 May 2004: TOOLS VERSION 2.02
- For IDL 5.5+, now use FILE_SEARCH to return
a list of files corresponding to MASK
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/mfindfile.pro)
NAME:
MODEL2AIRNUMDENS
PURPOSE:
Returns the monthly averaged Air Number Density in
each grid box for one GEOS-Chem model.
This let you get the Number Density from the average monthly
pressure of the model.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
airNumDens = Model2AirNumDens( Model [, tau] )
INPUTS:
Model : string for model name ("GEOS4_30L", "GEOS5_47L", ...)
OPTIONAL INPUTS:
Tau : tau0 for which Air Numb density is look for. The year
does not matter, the month value is extracted. Default
is 0D0, which selects January.
OUTPUTS:
A 3D array (same size as the model 3D grid) with Air
Density Number in [molec/cm3].
PROCEDURE:
GetModelAndGridInfo, DataInfo, Model, Grid
airnumden = Model2AirNumDens( CTM_NamExt( Model ), DataInfo.tau0 )
MODIFICATION HISTORY:
Wed Sep 2 10:54:41 2009, Philippe Le Sager
Gamap v2.13 - Init version
bmy, 30 Nov 2010: GAMAP VERSION 2.15
- Updated comments and category in header
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/model2airnumdens.pro)
NAME:
MULTIPANEL
PURPOSE:
This routine provides an easy-to-use interface to
IDL's !p.multi mechanism and it can be used
to retrieve the position vector of the next plot
in line (even if !p.multi is not set). You can
specify plot margins and a page margin in normalized
coordinates.
For multi-panel plots, multipanel works in three
stages (somewhat similar to XInterAnimate):
1) set up a multi-panel page by specifying the number
of rows and columns or the maximum number of plots
on the page.
2) advance to the next plot position and return that
position. If the page was filled (i.e. the maximum
number of plots (advance steps) has been made, it
will be erased (unless /NOERASE is set).
3) turn the multi-panel environment off and reset margin
values.
Subsequent PLOT, MAP_SET, etc. commands should use the
POSITION vector returned from this routine and they should
use the /NOERASE keyword.
CATEGORY:
Plotting
CALLING SEQUENCE:
Get position of next plot
MULTIPANEL,position=p
Setting up multi-panel pots
MULTIPANEL,[rows=r,cols=c | nplots=n] [,options]
Advance to the next panel (and get its position)
MULTIPANEL,/advance [,position=p] [,options]
Reset multi-panel environment to start over at the first panel
MULTIPANEL,/reset [,options]
Turn multi-panel environment off (reset !p.multi and some other
parameters)
MULTIPANEL,/OFF
INPUTS:
Optionally you can give the number of plots (keyword NPLOTS) as
a parameter instead. Th euse of a parameter will override the
keyword.
KEYWORD PARAMETERS:
General keywords (honored under all circumstances)
-------------------------------------------------------------------
POSITION -> Returns a 4-element vector with the position of
the next plot in the line. As always this vector contains
[X0,Y0,X1,Y1].
MARGIN -> specify a margin around the plot in normalized
coordinates. This keyword does not change any IDL
system variables and will thus only become "visible"
if you use the POSITION returned by MULTIPANEL in subsequent plot
commands.
MARGIN can either be one value which will be applied to
all four margins, or a 2-element vector which results in
equal values for the left and right and equal values for
the bottom and top margins, or a 4-element vector with
[left,bottom,right,top].
OMARGIN -> specify a page margin around all panels in normalized
coordinates. Works like MARGIN.
Note that you can change the values of MARGIN and OMARGIN after
you set up your plot page. The values given with MARGIN and OMARGIN
remain active until you specify a new one or use the /OFF keyword.
/NOERASE -> This keyword prevents erasing the screen (or page)
when setting a multi-panel environment or after a page was
filled. NOERASE is automatically turned ON when the /OFF
keyword is given.
Informational keywords:
-------------------------------------------------------------------
FIRSTPANEL -> returns 1 if the current plotting panel is
the first one on a page
LASTPANEL -> returns 1 if the current plotting panel is the last
on a page
Setting up a multi-panel page:
-------------------------------------------------------------------
ROWS, COLS -> specify the number of rows and columns
you want on your page. If one is specified, the
other one must be given as well. Alternatively,
you can use the NPLOTS keyword.
NPLOTS -> maximum number of plots on one page. The
number of rows and columns is automatically computed
so that the plots "approach a square" and they are
returned in the ROWS and COLS keywords. Setting
NPLOTS to a ROWS*COLS value is equivalent to using
ROWS and COLS. If you specify an "uneven" number
(e.g. 5), multipanel,/advance will erase the page
after 5 plots instead of 6.
/PORTRAIT -> Normally, ROWS tends to be larger than COLS
when NPLOTS is used (e.g. 12 gives 4 rows and 3 cols).
Use this keyword to revert this behaviour.
/LANDSCAPE -> Make ROWS larger than COLS if necessary. This
is the default. Thi skeyword is actually unnecessary and
was introduced for purely aesthetic reasons (symmetry).
Advance to the next plot:
-------------------------------------------------------------------
/ADVANCE -> this keyword issues a hidden plot command to find
out the position of the next plot to be made. The position
is then returned in the POSITION keyword. The value of
!P.MULTI[0] is increased afterwards so that you can issue
your plot command without explicitely specifying the
position or /NOERASE. When the maximum number of plots set
with NPLOTS is reached, MULTIPANEL,/ADVANCE will erase the
screen and reset the plot position to the upper left corner.
CURPLOT -> use this keyword to advance to a specific plot position
on the page. If you specify 0, the screen will be erased.
CURPLOT also returns the current plot number. If you don't
want to set the plot number but just query it, you must pass
an undefined variable (see procedure UNDEFINE.PRO).
Reset the plot position (and erase the screen)
-------------------------------------------------------------------
/RESET -> does just this.
Turn multi-panel environment off
-------------------------------------------------------------------
/OFF -> Overrides all other keywords. Resets !p.multi to 0.
OUTPUTS:
none.
SUBROUTINES:
function GET__PLOTPOSITION() issues a dummy plot command
and returns the plot position from the ![xy].window
variables.
REQUIREMENTS:
none. (example uses RECTANGLE.PRO)
NOTES:
Side effect: Opens a window in standard size if none was open
before. This happens because the next plot position is
determined by issuing a hidden (or dummy) plot command with
no visible output.
Make sure to use POSITION=P,/NOERASE with all your PLOT, MAP_SET
CONTOUR, etc. commands. In fact, you don't _need_ /NOERASE for
PLOT, but it guarantees consistent behaviour with MAP_SET etc.)
A PLOT command without /NOERASE will advance to the next panel
and thereby interfere with MULTIPANEL's plot counter.
If you don't use MARGIN and OMARGIN, the values in ![XY].margin
![XY].omargin will take effect.
A common block is used to store the current plot number and
margin information. This limits the use to one window at a time
(although you can save all parameters elsewhere and supply them
to the routine on a window-by-window basis).
EXAMPLES:
(1)
MULTIPANEL, position=p
PLOT, findgen(10), color=1, position=p, /noerase
; Just retrieve the position of the next plot
(2)
MULTIPANEL, MARGIN=[0.1,0.05], POSITION=P
PLOT, FINDGEN(10), COLOR=1, POSITION=P, /NOERASE
; same thing but use a specific margin (2-element form)
;
; If you want to see both previous plots together use
; /NOERASE with MULTIPANEL
(3)
; Set up for 5 plots
MULTIPANEL, NPLOTS=5
FOR I = 0, 4 DO BEGIN
; Get current plot position
MULTIPANEL, POSITION=P, MARGIN=0.04
; Do the plot
PLOT, FINDGEN(10), COLOR=!MYCT.BLACK,$
POSITION=P, /NOERASE
; Go to the next panel
; Note that the screen would be erased after the last plot
; without the /NoErase keyword.;
MULTIPANEL, /ADVANCE, /NOERASE
ENDFOR
; Multi-panel example
(4)
MULTIPANEL, /OFF, OMARGIN=0.01, MARGIN=0., $
POSITION=P, /NOERASE
RECTANGLE, P, XVEC, YVEC
PLOTS, XVEC, YVEC, COLOR=!MYCT.BLACK, /NORM
; Now let's draw a frame around everything
MODIFICATION HISTORY:
mgs, 19 Mar 1999: VERSION 1.00
mgs, 22 Mar 1999: - improved documentation, changed OMARGIN
to accept normalized coordinates.
- position now also returned if turned OFF
- added FIRSTPANEL and LASTPANEL keywords
- allow NPLOTS to be specified as parameter
mgs, 02 Jun 1999: - now saves old values of !X, !Y, and !P
and restores them when turned OFF.
mgs, 03 Jun 1999: - save !X, !Y, and !P only if !p.multi was
really off
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/plotting/multipanel.pro)
NAME:
MULTISORT
PURPOSE:
hierarchical sorting of a data set, each column can be sorted
reversely. Works well together with W_SORT, a widget interface
that handles up to three sort levels/columns. COLUMNS are defined
as first array index (e.g. DATA=FLTARR(5,20) has 5 columns).
CATEGORY:
Math & Units
CALLING SEQUENCE:
multisort,data,index=index,revert=revert
INPUTS:
DATA --> a 2D array to be sorted
KEYWORD PARAMETERS:
INDEX --> an integer or integer array containing the indices for
which the array shall be sorted (e.g. [ 3,1,0 ] will sort DATA
first by column 3, then within groups of same values for column
3 values will be sorted by column 1, and finally by column 0.
Default is to sort by the first column.
REVERT --> an integer or integer array indicating which columns shall
be sorted in reverse order. REVERT=1 reverts all sorting,
REVERT=[0,1,0] reverts the sort order only for the 2nd column.
Default is 0, i.e. do not revert.
OUTPUTS:
The DATA array will be sorted according to the specifications.
SUBROUTINES:
testsort : little test program (historic debugging purposes)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
MULTISORT, DATA, INDEX=[3,1,0], REVERT=[0,1,0]
; Sort data first in column 3, then in reverse order
; for column 1, and finally ascending order for column 0.
MODIFICATION HISTORY:
mgs, 30 Jun 1997: VERSION 1.00
mgs, 08 Apr 1998: - now stand-alone routine and documentation
mgs, 22 Dec 1998: - bug fix (startindex must be -1)
mgs, 17 Mar 1999: - bug fix: now has default 0 for revert
(thanks to G. Fireman)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/multisort.pro)
NAME:
MYCT
PURPOSE:
Define a set of standard drawing colors and load a colortable
on top of these. The color table can be manipulated in various
ways (see KEYWORD PARAMETERS).
The standard MYCT drawing colors are as follows. These
were implemented by Chris Holmes, based on the ColorBrewer
definitions. These colors are less saturated than the
traditional MYCT drawing colors, and are easier to read
on the screen:
0 : white 9 : lightblue
1 : black 10 : lightorange
2 : red 11 : lightpurple
3 : green 12 : 85% grey
4 : blue 13 : 67% grey
5 : orange 14 : 50% grey
6 : purple 15 : 33% grey
7 : lightred 16 : 15% grey
8 : lightgreen 17 : white
However, if you use the /BRIGHT_COLORS keyword to MYCT, you
may still use the traditional MYCT drawing colors (which were
created by Martin Schultz). These are defined as follows:
0 : white 9 : lightgreen
1 : black 10 : lightblue
2 : red 11 : black
3 : green 12 : 85% grey
4 : blue 13 : 67% grey
5 : yellow 14 : 50% grey
6 : magenta 15 : 33% grey
7 : cyan 16 : 15% grey
8 : lightred 17 : white
With MYCT, you may load any of the standard IDL color tables
or any of the ColorBrewer color tables. For backwards
compatibility, MYCT also supports several customized color
tables that used to be defined with the CUSTOM_COLORTABLE
routine.
MYCT reads color table definitions from an IDL *.tbl file.
The default file name is "gamap_colors.tbl". You may specify
a different file with the CTFILE keyword (see below). Also,
if you wish to add a custom color table, the best way to
proceed is to create your own *.tbl file with your custom
color table definitions. See the routine GAMAP_COLORS for
more information.
CATEGORY:
Color
CALLING SEQUENCE:
MYCT, [ TABLE ] [ , keywords ]
INPUTS:
TABLE (optional) -> Number or name of the IDL color table
to be used. If no number or name is provided, the
routine will default to color table 0 (which for the
"gamap_colors.tbl" file is B-W LINEAR). The MYCT
drawing colors will be loaded first, and the color
table will be loaded on top of that. You can choose
the bottom color index for the color table with the
BOTTOM keyword. MYCT will ensures that the system
variable !D.N_COLORS is set correctly.
KEYWORD PARAMETERS:
/BRIGHT_COLORS -> Selects the older set of MYCT drawing colors
to be loaded at the bottom of the colortable. Default is
to select the newer set of MYCT drawing colors, which
are less saturated and easier to read on the screen.
BOTTOM -> specify where to start color table (see BOTTOM keyword
in LOADCT). Default is number of standard drawing colors+1
or 0 (if NO_STD is set). If BOTTOM is less than the number
of standard drawing colors (17), no standard colors will be
defined (equivalent to setting NO_STD). RANGE has no
effect on the DIAL/LIDAR colortable. Default is 18.
NOTE: You should not normally have to change this value.
CTFILE -> Specify a file containing the color table
definitions. Default is "gamap_colors.tbl", which is
a combination of the standard IDL color tables plus
the ColorBrewer color tables. (See routine GAMAP_COLORS.)
NCOLORS -> number of color indices to be used by the color table.
Default is !D.N_COLORS-BOTTOM.
/NO_STD -> prevents definition of standard drawing colors.
RANGE -> a two element vector which specifies the range of colors
from the color table to be used (fraction 0-1). The colortable
is first loaded into the complete available space, then
the selected portion is interpolated in order to achieve the
desired number of colors. RANGE is only effective when
a TABLE parameter is given. RANGE has no effect on the
customized colortables.
/REVERSE -> Set this switch to reverse the color table.
/REVERSE works for both IDL and custom color tables.
SATURATION -> factor to scale saturation values of the extra
color table. Saturation ranges from 0..1 (but the factor
is free choice as long as positive). SATURATION has no
effect on the customized colortables. Default is 1.
USERDEF -> set to load the user defined colortable. The table
is defined in the Define_UserDef routine. It can be
loaded in three different ways:
MyCt, -1
MyCt, /user
MyCt, 'user'
In the later version, the string is not case sensitive,
and can be any string that contains the word "user".
VALUE -> factor to scale the "value" of the added colortable.
(i.e. this is like the contrast knobon a TV set). Value
ranges from 0..1; 0 = black, 1 = white. Default is 1.
/USE_CURRENT -> By default, MYCT will reset the color table
to all white before loading a new colortable. Set
/USE_CURRENT to prevent this from happening.
/VERBOSE -> Set this switch to print out information about
the color table that has just been selected.
/XINTERACTIVE -> to call XLOADCT instead of LOADCT for
interactivity. Has no effect if a custom colortable is
loaded.
The following keywords are kept for backwards compatibility.
These will replicate the color tables that used to be defined
with the now obsolete CUSTOM_COLORTABLE routine.
/BuWhRd -> Loads 19-color BLUE-WHITE-RED color table
/BuWhWhRd -> Loads 20-color BLUE-WHITE-WHITE-RED color table
/BuYlRd -> Loads 11-color BLUE-YELLOW-RED color table
/BuYlYlRd -> Loads 12-color BLUE-YELLOW-YELLOW-RED color table
/DIAL -> Loads the 26-color DIAL/LIDAR color table
(cf. E. Browell)
/DIFF -> Synonym for /BuWhRd.
/ModSpec -> Loads the 11 color MODIFIED SPECTRUM color table
/WhBu -> Loads the 10-color WHITE-BLUE color table
/WhGrYlRd -> Loads the 20-color WHITE_GREEN-YELLOW-RED color table
(cf. Aaron van Donkelaar)
/WhGyBk -> Loads the 10-color the WHITE-GRAY-BLACK color
/WhRd -> Loads the 10-color the WHITE-RED color table
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Provided:
===============================
MYCT_Drawing_Colors
External Subroutines Required:
===============================
COMPRESS_DIV_CT
DATATYPE (function)
XCOLORS
REQUIREMENTS:
None
NOTES:
(1) It is recommended to use the COLOR keyword in all PLOT
commands. This will ensure correct colors on (hopefully)
all devices. In order to get 256 colors on a postscript
printer use DEVICE,/COLOR,BITS_PER_PIXEL=8
(2) MYCT will also save several parameters in the MYCT system
variable, so that graphics programs can access them.
(3) MYCT uses the "gamap_colors.tbl" file. This file
contains all of the IDL standard color table definitions
all of the olorBrewer color table definitions, and some
extra colortables. If you wish to add a color table
you should probably use routine GAMAP_COLORS to create
a new *.tbl file. Then call MYCT and specify the name
of the new *.tbl file with the CTFILE keyword.
(4) We will use the ColorBrewer color abbreviations:
Bk = Black Br = Brown Bu = Blue
Gr = Green Gy = Gray Or = Orange
Pi = Pink Pu = Purple Rd = Red
Wh = White Yl = Yellow
(5) An MS Excel spreadsheet with all ColorBrewer color tables
is available for download from:
www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_RGB.html
(6) NOTE: Use a temporary hack to center the ColorBrewer
diverging color tables. (phs, 4/23/08)
EXAMPLES:
MYCT, 8, /NO_STD
; load IDL colortable green-white (#8)
; identical result as loadct,3
MYCT, 'EOS B', NCOLORS=20
; change first 17 colors to standard drawing colors
; and add EOS-B (#27) color table in indices 18-36
MYCT, 0, NCOLORS=20, /REVERSE, /NO_STD, /Use_Current
; add reversed grey scale table on top
MYCT, 'EOS B', NCOLORS=40, /NO_STD, /Use_Current, $
RANGE=[0.1,0.7], SATURATION=0.7
; add a less saturated version of a fraction
; of the EOS-B color table in the next 40 indices
; NOTE that color indices above 97 will still contain
; the upper portion of the green-white color table.
MYCT, 0 /REVERSE
; On b/w terminals MYCT can be used to reverse
; the IDL black & white (#0) colortable
MYCT, /DIAL, NCOLORS=120
; Loads the DIAL LIDAR color table with 120 colors
MYCT, /BuYlYlRd
MYCT, 'RdBu', /MIDCOLORPRESENT, /YELLOW, NCOLORS=20
; Both of these commands do the same thing: loads
; the ColorBrewer "RdBu" colortable and inserts yellow
; into the 2 middle colors. This is a good choice
; if you are creating an absolute or % difference plot.
MODIFICATION HISTORY:
mgs, 06 Feb 1997: VERSION 1.00
mgs, 03 Aug 1997: - added input parameter and template
mgs, 26 Mar 1998: - added NCOLORS keyword
mgs, 06 Apr 1998: - added BOTTOM, RANGE, and RGB keywords
mgs, 04 May 1998: - added test for null device
mgs, 03 Jun 1998: - return if !D.N_COLORS is less than 3 (b/w)
mgs, 16 Jun 1998: - bug fix: range check now after tvlct
mgs, 18 Jul 1998: - bug re-visited, added HLS keyword and changed
default to HSV. Also added SATURATION and
VALUE keywords.
mgs, 12 Aug 1998: - re-written with bug fixes and more concise.
removed RGB and HLS keywords, added REVERSE
and NO_STD keywords.
mgs, 14 Jan 1999: - limit oldcolors and ncolors to MaxColors (256)
on PC with TrueColor Graphics to ensure
compatibility with Unix.
bmy, 26 Sep 2002: TOOLS VERSION 1.51
- added /DIAL keyword to specify the DIAL/LIDAR
colortable from Ed Browell et al.
- now save MYCT parameters into a system variable
so that plotting routines can access them.
bmy, 22 Oct 2002: TOOLS VERSION 1.52
- fixed minor bugs in defining the !MYCT variable
bmy, 28 May 2004: TOOLS VERSION 2.02
- removed TESTMYCT routine, it's obsolete
- Bug fix: make sure RANGE is defined before
saving it to the !MYCT variable
bmy, 09 Jun 2005: TOOLS VERSION 2.04
- Added default value for RANGE keyword
bmy, 05 Oct 2006: TOOLS VERSION 2.05
- Now also define the DIFFERENCE color table
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now calls CUSTOM_COLORTABLE to define
several custom colortables
- Now allow /REVERSE to reverse custom
color table indices
- Added /VERBOSE keyword for printing info
about the selected color table
- Added /BuWhWhRd keyword for the
BLUE-WHITE-WHITE-RED colortable
- Added /BuYlYlRd keyword for the
BLUE-YELLOW-YELLOW-RED colortable
- Added /UserDef keyword to select
a user-defined color table.
cdh & bmy, 19 Nov 2007: GAMAP VERSION 2.11
- Now implement newer, less-saturated MYCT
drawing colors as defaults
- Added /BRIGHT_COLORS keyword to use
the older drawing colors for backwards
compatibility.
phs, 17 Apr 2008: GAMAP VERSION 2.12
- Now passes _extra to LOADCT, so a different
table file (*.tbl) can be used for example.
- bug fix: ncolors is correctly passed to
LOADCT if RANGE is not set.
- Added the XINTERACTIVE keyword to use
XCOLORS instead of LOADCT when no custom
table is loaded.
- Now use extra !MYCT tags: NAME, INDEX, FILE
- Added MIDCOLORPRESENT, USE_CURRENT keywords
phs, 22 Sep 2008: GAMAP VERSION 2.13
- Re-Added UserDef keyword. Users can define
(and then load) their own color table in the
Define_UserDef subroutine.
(See /n/home09/ryantosca/IDL/gamap2/color/myct.pro)
NAME:
MYCT_DEFAULTS (function)
PURPOSE:
Returns a structure associating the names of MYCT
drawing colors with their numeric values, plus
the default bottom and number of colors.
CATEGORY:
Color
CALLING SEQUENCE:
C = MYCT_DEFAULTS()
INPUTS:
None
KEYWORD PARAMETERS:
/GRAYSCALE -> If set, will define a grayscale colortable
such that the lowest color is white, and the highest
color is dark grey. Otherwise the standard "TRACE-P"
colortable (based on Mac Style #25) will be defined.
NCOLORS -> Specifies the number of colors for MYCT. The
default is 120, but if your terminal can support more,
you may specify a higher value.
OUTPUTS:
C -> Structure with the following tag names:
WHITE : Color index for "drawing color" WHITE
BLACK : Color index for "drawing color" BLACK
RED : Color index for "drawing color" RED
GREEN : Color index for "drawing color" GREEN
BLUE : Color index for "drawing color" BLUE
ORANGE : Color index for "drawing color" ORANGE
PURPLE : Color index for "drawing color" PURPLE
LIGHTRED : Color index for "drawing color" LIGHTRED
LIGHTGREEN : Color index for "drawing color" LIGHTGREEN
LIGHTBLUE : Color index for "drawing color" LIGHTBLUE
LIGHTORANGE : Color index for "drawing color" LIGHTORANGE
LIGHTPURPLE : Color index for "drawing color" LIGHTPURPLE
YELLOW : Color index for "drawing color" YELLOW
MAGENTA : Color index for "drawing color" MAGENTA
CYAN : Color index for "drawing color" CYAN
GRAY85 : Color index for "drawing color" 85% GRAY
GRAY67 : Color index for "drawing color" 67% GRAY
DARKGRAY : Color index for "drawing color" 67% GRAY
GRAY50 : Color index for "drawing color" 50% GRAY
MEDIUMGRAY : Color index for "drawing color" 50% GRAY
GRAY33 : Color index for "drawing color" 33% GRAY
GRAY : Color index for "drawing color" 33% GRAY
LIGHTGRAY : Color index for "drawing color" 33% GRAY
GRAY15 : Color index for "drawing color" 15% GRAY
FILE : Name of the color table (*.tbl) file
NAME : Color table name
INDEX : Color table index
BOTTOM : Color table starts at this index
NCOLORS : Number of colors
RANGE : Range of IDL color table to be used
SAT : Saturation value for MYCT
VALUE : Hue value for MYCT
REVERSE : REVERSE=1 means light --> dark
REVERSE=0 means dark --> light
SUBROUTINES:
None
REQUIREMENTS:
Designed to be used by the GAMAP routine "myct.pro".
NOTES:
(1) This routine is designed to be called by MYCT_DEFINE.
You should not normally have to call MYCT_DEFAULTS.
(2) MYCT defines a colortable such that the first 17
colors are "drawing" colors, or pure colors intended
for use with the PLOT, CONTOUR, MAP_SET, etc. commands.
MYCT then loads a standard IDL colortable (with NCOLORS
specifying the number of individual colors) into color
indices 18 and higher.
(3) New drawing colors (that are less saturated and
easier to read on the screen) are now the defaults.
See the documentation to the MYCT routine for more info.
EXAMPLE:
C = MYCT_DEFAULTS()
; Defines a grayscale colortable for use w/ MYCT.
MODIFICATION HISTORY:
bmy, 23 Jul 2001: TOOLS VERSION 1.48
- adapted from "default_colors.pro"
bmy, 04 Feb 2004: TOOLS VERSION 2.01
- Increased grayscale color range slightly
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- renamed DIAL to CUSTOM, to reflect that
we have other custom colortables in use
cdh & bmy, 19 Nov 2007: GAMAP VERSION 2.11
- Added names for the new MYCT drawing colors
bmy, 21 Apr 2008: GAMAP VERSION 2.12
- Removed obsolete settings and keywords
- Removed IS_CUSTOM tag name from !MYCT
- Added INDEX, FILE tag names to !MYCT
(See /n/home09/ryantosca/IDL/gamap2/color/myct_defaults.pro)
NAME:
MYCT_DEFINE
PURPOSE:
Defines the !MYCT system variable with default values.
!MYCT is used to make colortable parameters available to
plotting programs.
CATEGORY:
Color
CALLING SEQUENCE:
MYCT_DEFINE
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MYCT_DEFAULTS (function)
REQUIREMENTS:
None
NOTES:
This routine should be called from your "idl_startup.pro"
batch file, so that !MYCT will be defined and ready for
use by all other routines that need it.
EXAMPLE:
MYCT_DEFINE
; Defines the !MYCT system variable
MODIFICATION HISTORY:
bmy, 30 Sep 2002: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/color/myct_define.pro)