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:
ADJ_INDEX
PURPOSE:
Adjusts CTM global index arrays for a particular
data-block dimension from global size to window size.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
NEWINDEX = ADJ_INDEX( OLDINDEX, N_SUBTRACT, MAXINDEX )
INPUTS:
OLDINDEX -> The globally sized CTM index array to be adjusted.
N_SUBTRACT -> The number to subtract from each element
of OLDINDEX.
MAXINDEX -> The maximum number of elements that OLDINDEX
can have.
KEYWORD PARAMETERS:
None
OUTPUTS:
ADJ_INDEX returns the window-sized index array as
the value of the function.
SUBROUTINES:
None
REQUIREMENTS:
None.
NOTES:
Designed for use with GAMAP, but can be used for more
general purpose applications as well.
EXAMPLE:
WE = [ 69, 70, 71, 0, 1, 2 ] ; WE straddles the date line
WE_ADJ = ADJ_INDEX( WE, 69, 72 )
print, WE_ADJ
0 1 2 3 4 5
NEWDATA = DATA[ WE_ADJ, *, * ]
; WE has a possible maximum of 72 elements. Convert WE
; from global size to window size by subtracting 69
; from each element of WE. Use WE_ADJ to reference
; elements of the DATA array.
MODIFICATION HISTORY:
bmy, 19 Feb 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/adj_index.pro)
NAME:
CREATE3DFSTRU
PURPOSE:
Creates an empty GAMAP fileinfo structure or an array
of such structures. These are used to hold information
about CTM data files.
CATEGORY:
GAMAP Internals, Structures
CALLING SEQUENCE:
FILEINFO = CREATE3DHSTRU( [Elements] )
INPUTS:
ELEMENTS -> Number of individual structures to
be contained in the array of structures. Default
is 1, i.e. return a single structure.
KEYWORD PARAMETERS:
None
OUTPUTS:
A fileinfo structure or an array of fileinfo structures.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
See comments in code below for structure field descriptions.
EXAMPLES:
FILEINFO = CREATE3DFSTRU()
; returns a single structure which will hold
; info about CTM punch file data.
FILEINFO = CREATE3DFSTRU( 20 )
; returns an 20 element array of structures
; which will hold info about 20 records from a
; CTM data file
MODIFICATION HISTORY:
mgs, 14 Aug 1998: VERSION 1.00
bmy, 18 May 2007: GAMAP VERSION 2.06
- added standard doc header
- updated comments, cosmetic changes
MODIFICATION HISTORY:
bmy, 19 Feb 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/create3dfstru.pro)
NAME:
CREATE3DHSTRU
PURPOSE:
Creates an empty GAMAP datainfo structure or an array
of such structures. These are used to hold information
about individual data blocks from CTM data files.
CATEGORY:
GAMAP Internals, Structures
CALLING SEQUENCE:
DATAINFO = CREATE3DHSTRU( [Elements] )
INPUTS:
ELEMENTS -> Number of individual structures to be contained
in the array of structures. Default is 1, (i.e. return
a single structure).
KEYWORD PARAMETERS:
None
OUTPUTS:
A datainfo structure or an array of datainfo structures.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
See comments in code below for structure field descriptions.
EXAMPLES:
DATAINFO = CREATE3DHSTRU()
; returns a single structure which will hold
; info about CTM punch file data.
DATAINFO = CREATE3DHSTRU( 20 )
; returns an 20 element array of structures
; which will hold info about 20 records from a
; CTM data file
MODIFICATION HISTORY:
mgs, 14 Aug 1998: VERSION 1.00
mgs, 10 Nov 1998: - changed default filepos to -1L and scale to 1
bmy, 08 Feb 1999: VERSION 1.10
- changed TAU0, TAU1 from longword to double
- added OFFSET field for I0, J0, L0
bmy, 17 Feb 1999: VERSION 1.20
- changed OFFSET field to FIRST since we
are storing the I, J, L indices of the
first
mgs, 16 Mar 1999: - cosmetic changes
bmy, 03 Jan 2000: VERSION 1.44
- updated comments
bmy, 26 Apr 2000: VERSION 1.45
- TRACER now carries a longword variable
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 02 Dec 2008: GAMAP VERSION 2.13
- DIM tag is 32-bit integer (LONG) now
bmy, 23 Feb 2012: GAMAP VERSION 2.16
- Now make FILEPOS a LONG64 variable, in
order to read files larger than 2.4 GB
- Now make FIRST an array of LONG variables
(See /n/home09/ryantosca/IDL/gamap2/internals/create3dhstru.pro)
NAME:
CTM_DOSELECT_DATA (function)
PURPOSE:
Return indices for data blocks that match specific
criteria. This is an internal routine which is called
by CTM_GET_DATA.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
INDEX = CTM_DOSELECT_DATA( DIAGN, USE_DATAINFO [, keywords ] )
INPUTS:
CATEGORY -> A string or string array with category names
to search for. Multilevel categories can be expanded to
a string array with the EXPAND_CATEGORY function.
Usually, CTM_DOSELECT_DATA should be called with only
one "logical" category at the time, i.e. only for
multilevel diagnostics should it contain more than one
element. Otherwise, the tracer offset may be wrong.
USE_DATAINFO -> A valid DataInfo structure. No error checking
is performed.
Both parameters are mandatory.
KEYWORD PARAMETERS:
ILUN -> A logical unit value or an array of logical unit
values. Only records from corresponding files will be
returned. If ILUN is an undefined variable, information
about all previously opened files will be returned,
and ILUN will contain all logical unit numbers that
match the selection criteria.
TRACER -> A tracer number or an array of tracer numbers to
restrict the selection of data records. Default is to
return information about all tracers.
Tracer numbers less than 100 are automatically expanded
to include the offset of certain diagnostics (see
keyword TRCOFFSET and routine CTM_DIAGINFO). If TRACER is
an undefined variable, all tracers that match the selection
criteria are returned.
TRCOFFSET -> A tracer offset (multiple of 100) that will be
added to TRACER. The search is performed for both,
TRACER and TRACER+TRCOFFSET. (for tracer offsets see
routine CTM_DIAGINFO and file diaginfo.dat)
TAU -> A time value (tau0 !) or an array of time values
to restrict the selection of data records. Default is to
return information about all time steps. If TAU is an
undefined variable, it will return all time steps that
match the selection criteria.
STATUS -> Restricts the data selection to
Data that has not been read (STATUS = 0)
Data that has been read (STATUS = 1)
All data blocks (STATUS = 2, default)
If STATUS is 1, all pointers returned in DATA are tested
for validity. Status will automatically be restricted
to range 0..1
COUNT -> A named variable that will return the number of
data blocks found with the given selection criteria
MISSING -> If no records were found that match the selection
criteria, MISSING will return a string array with the
items that could not be matched (e.g. ['TRACER','ILUN']).
If records were found, MISSING returns an empty string.
SPACING -> Passes to CTM_DOSELECT_DATA the spacing between
diagnostic offsets listed in "diaginfo.dat".
OUTPUTS:
The function returns an (long) integer array that contains
index values to all the data blocks that match the selection
criteria. If no data is found, -1L is returned.
SUBROUTINES:
Uses IS_SELECTED function
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
See CTM_SELECT_DATA and CTM_READ_DATA source codes.
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 07 Oct 1998: - added DEBUG keyword
mgs, 22 Oct 1998: - now filters ilun, tracer, and tau
after finding matching records. This
was necessary to find the correct first
or last time step in CTM_GET_DATA.
Needs some more testing whether there are
side effects when TAU0 and ILUN or TRACER
are specified.
mgs, 09 Nov 1998: - improved documentation
- default status now 2
- uses status field in use_datainfo instead of
ptr_valid function
- ILUN, TRACER and TAU only overwritten
if they are undefined variables
- added MISSING keyword
mgs, 10 Nov 1998: - minor bug fix for status=1
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- added SPACING keyword to pass the
diagnostic spacing from CTM_DIAGINFO
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_doselect_data.pro)
NAME:
CTM_GETDEFAULTSTRUCTURES
PURPOSE:
Return default values for FileInfo and DataInfo for
subsequent analysis. The defaults are taken from the
global common block defined in gamap_cmn.pro
CATEGORY:
GAMAP Internals, Structures
CALLING SEQUENCE:
CTM_GETDEFAULTSTRUCTURES, FileInfo, DataInfo, result=result
INPUTS:
FILEINFO -> A named variable that will contain the global
FileInfo structure array, i.e. information about all
files that have been opened.
DATAINFO -> A named variable that will contain the global
DataInfo structure array, i.e. information about all
data records that have been read from the headers of
all opened CTM files.
KEYWORD PARAMETERS:
RESULT -> returns 1 if assignment was successful, 0 otherwise.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required
==============================
GAMAP_CMN
REQUIREMENTS:
Requires routines from the GAMAP package.
NOTES:
None
EXAMPLE:
CTM_GETDEFAULTSTRUCTURES, $
FileInfo, DataInfo, result=result
if (not result) then return
; the current state of the global FileInfo and DataInfo
; structures will be copied into FileInfo and DataInfo
MODIFICATION HISTORY:
mgs, 20 Aug 1998: VERSION 1.00
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_getdefaultstructures.pro)
NAME:
CTM_OPEN_FILE
PURPOSE:
Open a CTM output (punch) file and reads the complete
header information from that file. The file may be either
ASCII or binary type, and is only opened if not already
parsed. It is re-opened if it was parsed but closed in the
meantime. CTM_OPEN_FILE can also be used to read GEOS-CTM
restart files. However, since it is not possible to
point randomly at these data, the complete set of tracers
in a restart file will be read at once.
While in general files are opened automatically when
CTM_GET_DATA is used, there are several circumstances where
direct use of CTM_OPEN_FILE advantageous:
* if a read error occurs, use CTM_OPEN_FILE with the /PRINT
keyword to diagnose the error
* to compare two model runs, it is simpler to first open
the two files, then call CTM_GET_DATA without the filename
keyword. All operations will then be done on both files
in parallel.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_OPEN_FILE, FILENAME, THISFILEINFO, THISDATAINFO
INPUTS:
FILENAME -> The name of the file to be opened or a
file mask. If the file was not found or the file
mask contains wild cards, a pickfile dialog is
opened for interactive selection. The default
search mask can be set in gamap.defaults (see
GAMAP_INIT).
KEYWORD PARAMETERS:
CANCELLED -> Returns 1 if the CANCEL button was pressed
during DIALOG PICKFILE filename selection.
_EXTRA keywords are passed to the various routines which
read the file headers.
OUTPUTS:
THISFILEINFO -> A named variable that will contain a
fileinfo structure (see CREATE3DFSTRU).
THISDATAINFO -> A named variable that will contain an
array of datainfo structures (see CREATE3DHSTRU)
associated with this file.
THISFILEINFO and THISDATAINFO are also appended to the
global pointer variables pGlobalFileInfo and pGlobalDataInfo
(see gamap_cmn.pro and GAMAP_INIT).
SUBROUTINES:
Internal Subroutines:
============================================================
Get_Free_Lun (function) Test_For_NCDF (function)
Test_For_HDF (function) Test_For_HDFEOS (function)
Test_For_GMAO (function) Test_For_Binary (function)
File_Parse (function) File_Opened_Previously (function)
Handle_Prev_Opened_File
External Subroutines Required:
==============================================================
GAMAP_CMN (incl file) OPEN_FILE
CTM_READ3DB_HEADER (function ) CTM_READ3DB_HEADER (function)
CTM_READ_GMAO (function ) CTM_READ_NCDF (function)
CTM_READ_GMI (function ) LITTLE_ENDIAN (function)
STRRIGHT (function )
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) In internal function "test_for_dao", add additional met
field names as is necessary to the FIELDNAMES array. The
first met field name in a file is tested against FIELDNAMES.
If there is a match, then the file is declared to be a DAO
met field file, and it is assigned a file type of 4.
(2) You must also add additional met field names to routine
"ctm_read_dao" as is necessary. The DAO met field files do
not carry tracer numbers, so the name of each met field must
be checked in "ctm_read_dao" before a corresponding DATAINFO
structure can be assigned.
(3) If a binary file is the wrong endian, we will get a
"Corrupted F77 file error" when we try to read data from it.
We now test for this error in routines TEST_FOR_BINARY and
TEST_FOR_DAO. If this error condition occurs, the file is
re-opened with the /SWAP_ENDIAN command.
EXAMPLE:
CTM_OPEN_FILE
; queries the user for a filename and stores the analyzed
; header information in the global common block
; If an ASCII punch file is read, the user is prompted for
; a model name
CTM_OPEN_FILE,'',fileinfo,datainfo
; opens a CTM punch file after selection from a pickfile
; dialog
CTM_OPEN_FILE,'~/amalthea/CTM4/run/ctm.pch',fileinfo,datainfo
; opens the specified punch file
MODIFICATION HISTORY:
mgs, 14 Aug 1998: VERSION 1.00
mgs, 17 Sep 1998: - file units now starting from 20, so
they do not interfere with GET_LUN
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 05 Oct 1998: - added function file_parse
- can now handle GEOS restart files as well.
mgs, 10 Nov 1998: - no message after Cancel on Pickfile dialog
bmy, 20 Jan 1999: - explicitly set binary type to 2 for
GEOS-CTM restart files
- accept bey's personal GEOS CTM timeseries label
mgs, 19 May 1999: - added SWAP_ENDIAN keyword to open_file if
binary files are read on PC
mgs, 24 May 1999: - added support for 'CTM bin 02' files
(involved changing filetype numbers)
bmy, 12 Apr 2000: GAMAP VERSION 1.45
- added test for DAO binary met field files
bmy, 12 Jun 2000: - added CLDFRC to list of recognized DAO fields
bmy, 28 Jul 2000: GAMAP VERSION 1.46
- added GEOS-3 names to list of recognized fields
- deleted a couple of field names woe don't use
bmy, 25 Sep 2000: - added new field: SLP (sea level pressure)
bmy, 05 Dec 2000: GAMAP VERSION 1.47
- added new fields: TKE, RH, KH
bmy, 07 Mar 2001: - added new fields: CLDTMP, TPW
bmy, 25 Apr 2001: - added new fields: TAULOW, TAUMID, TAUHI
bmy, 26 Jul 2001: GAMAP VERSION 1.48
- added new field: T2M
bmy, 15 Aug 2001: - added new field: OPTDEPTH
bmy, 27 Sep 2001: GAMAP VERSION 1.49
- reference LITTLE_ENDIAN in internal
subroutine "handle_prev_opened_file"
- swap endian if LITTLE_ENDIAN() returns true
in internal subroutine "handle_prev_opened_file"
bmy, 29 Jan 2002: GAMAP VERSION 1.50
- added new field: GWET
bmy, 03 Mar 2003: GAMAP VERSION 1.52:
- added new fvDAS fields: CMFDTR, CMFETR,
ZMDU, ZMED, ZMEU, ZMMD, ZMMU, HKETA, HKBETA
bmy, 18 Jun 2003: GAMAP VERSION 1.53
- added new fields: EVAP, LAI, PARDF, PARDR
bmy, 30 Jul 2003: - added new field: TSKIN
lyj & tdf, 22 Oct 2003: - added SWAP_BINARY keyword to TEST_FOR_BINARY
- Call TEST_FOR_BINARY with /SWAP_BINARY
as a last-ditch effort if the file type
cannot be classified. This will open the
file and swap the endian.
bmy, 12 Dec 2003: GAMAP VERSION 2.01
- Now also test for netCDF file format
- Added internal routines TEST_FOR_NETCDF,
TEST_FOR_HDF (stub), TEST_FOR_HDFEOS
- FILETYPE for ASCII files range from 0-99
- FILETYPE for BINARY files range from 100-199
- FILETYPE for netCDF files range from 200-299
- FILETYPE for HDF-EOS files range from 300-399
- Routine TEST_FOR_GMAO now looks for met
field tracer names from "tracerinfo.dat",
instead of using a hardwired string array
- rewritten for clarity; updated comments
- Now looks for the GEOS-4 met field ident string
bmy, 11 Feb 2004: GAMAP VERSION 2.01a
- Now prevents infinite loops when testing
for file type
bmy, 24 Aug 2004: GAMAP VERSION 2.03
- now recognizes GEOS-CHEM station timeseries
file in bpch file format by the FTI string
bmy, 21 Mar 2005: - Added COARDS-compliant netCDF as FILETYPE=203
bmy, 24 May 2005: GAMAP VERSION 2.04
- Now test properly for GCAP met fields
bmy, 06 Feb 2006: - Activate file type tests for HDF-EOS4
swath and point file types
- Add new function TEST_FOR_HDF5 to test if
the file is in HDF5 format
- Use the absolute path name internally when
testing for HDF5 or HDF-EOS files
bmy, 31 May 2006: GAMAP VERSION 2.05
- Now expand the filename when calling NCDF_OPEN
- Skip test for HDF5 for IDL versions
earlier than 6.0
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now modified for GEOS-5
- Added FILETYPE=106 for files that
contain 4-D data blocks
- Use FILETYPE=202 for netCDF files
created by BPCH2GMI
phs, 30 Jun 2008: GAMAP VERSION 2.12
- warning if too many files are opened
- completly rewrite handling of endian swapping
bmy, 23 Jan 2017: GAMAP VERSION 2.19
- Add a better test for netCDF files. This
removes the restriction of the file having
to end with *.nc or *.nc4.
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_open_file.pro)
NAME:
CTM_PRINT_DATAINFO
PURPOSE:
Create and print a formatted list of DATAINFO records.
This procedure can be used for direct printing, but it
can also return a string array of the formatted output
e.g. for use in a widget list.
CATEGORY:
GAMAP Internals, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_PRINT_DATAINFO,DATAINFO [,keywords]
INPUTS:
DATAINFO -> One or more DATAINFO records, e.g. the result
from CTM_GET_DATA.
KEYWORD PARAMETERS:
FIELDS -> (*** not yet implemented ***) A list of fields
(structure tag names) to be printed. Default is
CATEGORY, ILUN, TRACERNAME, TRACERNUMBER,
UNIT, TAU0, STATUS, DIMENSIONS
FIELDS can also include tags from the (global) FILEINFO
structure (e.g. FILENAME).
OUTPUT -> A named variable that will contain a string array
with the formatted output including the title line but
without the seperating lines. The title is not included
if keyword /NOTITLE is set.
/NOPRINT -> Don't print, only return formatted strings
/NOTITLE -> Do not generate title line (will neither be printed
nor included in OUTPUT.
OUTPUTS:
None
SUBROUTINES:
External subroutines required:
------------------------------
GAMAP_CMN (include file)
TAU2YYMMDD (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
For GISS, FSU family of models, TAU0 = 0 occurs on date 1/1/1980.
For GEOS family of models, TAU0 = 0 occurs on date 1/1/1985.
Therefore, the model family must be obtained from the global
FILEINFO structure in order to display the YYMMDD
corresponding to TAU0.
EXAMPLE:
CTM_GET_DATA,DataInfo,File='',tracer=2
CTM_PRINT_DATAINFO,DataInfo
; *or*
CTM_PRINT_DATAINFO,DataInfo,Output=r,/NOPRINT
MODIFICATION HISTORY:
mgs, 10 Nov 1998: VERSION 1.00
bmy, 11 Feb 1999: VERSION 1.01
- adjust format for double-precision TAU0
mgs, 16 Mar 1999: - added tracer number and removed STATUS
- made cosmetic changes
mgs, 23 Mar 1999: - print dimension as NA if not yet available
bmy, 27 Apr 1999: - widen tracer number field to 6 chars
mgs, 22 Jun 1999: - widen unit field to 12 chars and add DATE field
bmy, 27 Jul 1999: VERSION 1.42
- GISS/FSU YYMMDD values are now correct
- cosmetic changes
bmy, 10 Aug 1999: - change I6 format for date to I6.6
so that leading zeroes are printed
bmy, 03 Jan 2000: VERSION 1.44
- change I6.6 format to I8.8 and print the
date in YYYYMMDD format for Y2K compliance
- declare TAU2YYMMDD as external with the
FORWARD_FUNCTION command
bmy, 14 Feb 2001: GAMAP VERSION 1.47
- decrease tracer name from 10 to 7 chars
- Now use 10-digit date string YYYYMMDDHH
bmy, 02 Jul 2001: GAMAP VERSION 1.48
- now assume that GENERIC grids use GEOS
time epoch for NYMD2TAU
bmy, 21 Oct 2002: GAMAP VERSION 1.52
- now assume MOPITT grid uses GEOS epoch
- deleted obsolete code
bmy, 03 May 2005: GAMAP VERSION 2.04
- wrap tracer number into 5 digits
- GCAP uses the same TAU values as GEOS models
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy 24 Jan 2014: GAMAP VERSION 2.17
- Adjust output format string to allow for
a few extra spaces in UNIT and TRACER #.
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_print_datainfo.pro)
NAME:
CTM_READ3DB_HEADER
PURPOSE:
retrieve header information and file positions of data
blocks from binary global 3D model output. This is a
twin of CTM_READ3DP_HEADER which digests the header
information from ASCII punch files.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
test = CTM_READ3DB_HEADER(LUN,FILEINFO,DATAINFO [,keywords])
INPUTS:
LUN --> logical file unit of the binary punch file. The file
must be open (see CTM_OPEN_FILE or OPEN_FILE)
FILEINFO --> a (single) fileinfo structure containing information
about the (open) file (see CREATE3DFSTRU). FILEINFO also
contains information about the model which generated
the output (see CTM_TYPE)
DATAINFO --> a named variable that will contain an array of
structures describing the file content (see
CREATE3DHSTRU)
KEYWORD PARAMETERS:
PRINT -> if activated, print all headers found in the file
OUTPUTS:
The function returns 1 if successful, and 0 otherwise.
FILEINFO --> toptitle and modelinfo tags will be set
DATAINFO --> contains an array of named structures
(see CREATE3DHSTRU) with all relevant information
from the punch file header and what is needed to find
and load the data.
SUBROUTINES:
REQUIREMENTS:
uses CREATE3DHSTRU function to create header structure
uses CHKSTRU to test FILEINFO structure
uses CTM_TYPE to create modelinfo structure
needs gamap_cmn.pro to access global common block
NOTES:
This routine uses the new binary file format introduced
first to the GEOS/Harvard CTM.
EXAMPLE:
fileinfo = create3dfstru() ; not required !
fname = '~bmy/terra/CTM4/results/ctm.bpch'
open_file,fname,ilun,/F77_UNFORMATTED ; <=== !!
if (ilun gt 0) then $
result = CTM_READ3DB_HEADER(ilun,fileinfo,datainfo)
print,result
To get e.g. all scaling factors, type
print,datainfo[*].scale
To retrieve the header structure for one data block, type
blocki = datainfo[i]
MODIFICATION HISTORY:
mgs, 15 Aug 1998: VERSION 1.00
- derived from CTM_READ3DP_HEADER
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 14 Jan 1999: - now expects diag category name instead
of number
bmy, 11 Feb 1999: - change TAU0, TAU1 to double-precision,
in accordance w/ new binary file format
- clean up some POINT_LUN calls
bmy, 22 Feb 1999: VERSION 1.01
- now store I0, J0, L0 from binary file
in new FIRST field from CREATE3DHSTRU
- comment out assignment statement for
SKIP; now use value from binary file
mgs, 16 Mar 1999: - cosmetic changes
mgs, 24 May 1999: - now supports 'CTM bin 02' files
- added a filetype check
- now defaults to 512 records (former 4096)
mgs, 27 May 1999: - fixed bug with new record default: new
records were never added as they were
supposed to.
bmy, 26 Jul 1999: - also print out SKIP field in debug output
bmy, 10 Jul 2003: GAMAP VERSION 1.53
- added kludge so that GEOS-3 reduced grid
w/ 30 layers will be added to FILEINFO
correctly
bmy, 21 Nov 2003: GAMAP VERSION 2.01
- BPCH file v1 now has FILETYPE=101
- BPCH file v2 now has FILETYPE=102
- Now define separate DATAINFO.FORMAT values
for BPCH v1 and BPCH v2 type files
- removed kludge for GEOS3_30L, since the
bug in CTM_TYPE has now been fixed
bmy, 24 Aug 2004: GAMAP VERSION 2.03
- now assign FORMAT string for Filetype 105
which is BPCH file for GEOS-CHEM station
timeseries (e.g. ND48 diagnostic)
phs & bmy, 13 Jul 2007: GAMAP VERSION 2.10
- Now account for FILETYPE=106, which
denotes CTM bpch files w/ 4-D data.
bmy, 23 Feb 2012: GAMAP VERSION 2.16
- Now make FILEPOS and NEWPOS LONG64
variables, in order to read bpch files
larger than 2.4 GB.
bmy, 20 Jan 2016: GAMAP VERSION 2.19
- Bug fix: cast SKIP variable to LONG64
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read3db_header.pro)
NAME:
CTM_READ3DP_HEADER
PURPOSE:
retrieve header information and file positions of data
blocks from global 3D model punch file output.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
test = CTM_READ3DP_HEADER(LUN,FILEINFO,DATAINFO [,keywords])
INPUTS:
LUN --> logical file unit of the punch file. The file
must be open (see CTM_OPEN_FILE or OPEN_FILE)
FILEINFO --> a (single) fileinfo structure containing information
about the (open) file (see CREATE3DFSTRU). FILEINFO also
contains information about the model that generated the
data, which is queried interactively.
DATAINFO --> a named variable that will contain an array of
structures describing the file content (see
CREATE3DHSTRU)
KEYWORD PARAMETERS:
/NO_TOPTITLE --> do not interprete first line of file as
header line. Only one header line will be skipped
(as normally only one header line is read in).
/EXTRA_SPACE -> digests output from GISS_II_PRIME model with
extra spaces in the punch file. This keyword is optional
in the following sense: If CTM_READ3DP_HEADER detects
an error reading a header line, it is called again
automatically with this option set.
PRINT -> if activated, print all headers found in the file
OUTPUTS:
The function returns 1 if successful, and 0 otherwise.
FILEINFO --> toptitle and modelinfo tags will be set
DATAINFO --> contains an array of named structures
(see CREATE3DHSTRU) with all relevant information
from the punch file header and what is needed to find
and load the data.
SUBROUTINES:
REQUIREMENTS:
uses CREATE3DHSTRU function to create header structure
uses CHKSTRU to test FILEINFO structure
uses CTM_TYPE to set modelinfo
needs gamap_cmn.pro to set default in query for model type
NOTES:
This routine does rely on the output format from the global GCM
as specified first for the GEOS/Harvard CTM. However, it is
designed to digest the output from all models currently used
in DJJ's group.
It uses the NL parameter to skip blocks between headers.
The window offsets (I0, J0, L0) are set to
zero, since the ASCII punch file is not set up to save
a sub-region of the globe (bmy, 2/11/99)
EXAMPLE:
fileinfo = create3dfstru() ; not required !
fname = '~bmy/terra/CTM4/results/ctm.pch.m2'
open_file,fname,ilun
if (ilun gt 0) then $
result = ctm_read3dp_header(ilun,fileinfo,datainfo)
print,result
To get e.g. all scaling factors, type
print,datainfo[*].scale
To retrieve the header structure for one data block, type
blocki = datainfo[i]
MODIFICATION HISTORY:
mgs, 21 Aug 1997: VERSION 1.00
mgs, 02 Mar 1998: VERSION 1.10
- can handle GEOS output now
- reads in file header
- returns structure instead of string array
- always returns all entries, filtering must be done later
mgs, 03 Mar 1998: - now returns a structure and is a function
mgs, 04 Mar 1998: - toptitle is now default, changed keyword to
NO_TOPTITLE ; eliminated search for '!' or '%'
mgs, 10 Mar 1998: - rewritten again, now with named structure
returned as DATAINFO. Skipping of data blocks
drastically improved by setting the file pointer
instead of reading the lines.
mgs, 16 May 1998: - removed DATATYPE3DP function, set type tag to -1
- added EXTRA_SPACE option for GISS_II_PRIME output and
LINELENGTH keyword for full flexibility
- now ignores time series ('TS...') data
mgs, 13 Aug 1998: - format string now composed here, not in
read3dp_data
mgs, 14 Aug 1998: VERSION 2.00 - major changes!
- now requires open file and uses ILUN parameter
- automatic EXTRA_SPACE detection
- fileinfo structure not created any more, and only
extended if present (chkstru)
- error messages as dialog box
- LINELENGTH keyword removed
mgs, 15 Aug 1998: - now calls select_model and inserts model
information in fileinfo structure
- gamap_cmn.pro included for default model name
- had to change DEBUG keyword into PRINT
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 26 Oct 1998: - now resets error state in no_dim
mgs, 14 Jan 1998: - new lcount for line counting in error report
- linelength adjusted for working in Windows (CR/LF)
bmy, 11 Feb 1999: VERSION 2.01
- Add window offsets (I0,J0,L0) to DATAINFO
- save DATAINFO.TAU0 and DATAINFO.TAU1 as double precision
bmy, 17 Feb 1999: VERSION 2.02
- changed to accommodate the FIRST field (instead of OFFSET)
of the DATAINFO structure, which contains
the I, J, L indices of the first grid box
bmy, 01 Mar 1999:
- bug fix! NL needs to be a longword, so that
we can read 2 x 2.5 punch files correctly!!
mgs, 23 Mar 1999:
- cleaned up reading of dimensions from label a little
mgs, 27 May 1999:
- new default number of records is 512 instead of 4096.
- bug fix: new records were never appended.
mgs, 22 Jun 1999:
- bug fix: "title" needed to be trimmed.
bmy, 20 Jan 2000: FOR GAMAP VERSION 1.44
- !ERR is now replaced by !ERROR_STATE.CODE
- !ERR_STRING is now replaced by !ERROR_STATE.MSG
- I/O error trapping is now done by testing error
messages instead of testing for error numbers
- cosmetic changes, updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read3dp_header.pro)
NAME:
CTM_READ_COARDS
PURPOSE:
Reads data blocks from a COARDS-compliant netCDF file (such
as created by routine BPCH2COARDS) into GAMAP. CTM_READ_COARDS
is is an internal routine which is called by CTM_OPEN_FILE.
NOTE: COARDS is a formatting standard for netCDF files which
is widely used in both the atmospheric & climate communities.
COARDS-compliant netCDF files can be read by GAMAP, GrADS and
other plotting packages.
See http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html
for more information about the COARDS standard.
CATEGORY:
GAMAP Internals, Scientific Data Formats
CALLING SEQUENCE:
CTM_READ_COARDS, [, Keywords ]
INPUTS:
ILUN -> GAMAP file unit which will denote the netCDF file.
FILENAME -> Name of the netCDF grid file to be read.
FILEINFO -> Array of FILEINFO structures which will be
returned to CTM_OPEN_FILE. CTM_OPEN_FILE will
append FILEINFO to the GAMAP global common block.
DATAINFO -> Array of DATAINFO structures (each element
specifies a GAMAP data block) which will be returned
to CTM_OPEN_FILE. CTM_OPEN_FILE will append FILEINFO
to the GAMAP global common block.
KEYWORD PARAMETERS:
_EXTRA=e -> Picks up extra keywords
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
====================================================
CRC_Get_DimInfo CRC_Get_IndexVars
CRC_Read_Global_Atts CRC_Get_Tracer
CRC_Get_Data CRC_Save_Data
External Subroutines Required:
====================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_MAKE_DATAINFO (function) STRRIGHT (function)
STRREPL (function)
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) Assumes that data blocks have the following dimensions:
(a) longitude, latitude, time
(b) longitude, latitude, levels, time
(2) Assumes that times are given in GMT.
(3) If information about each tracer in the COARDS-compliant
netCDF file is stored in the GAMAP "tracerinfo.dat" file,
then CTM_READ_COARDS will be able to read the file without
having to ask the user to supply a GAMAP category and
tracer name.
EXAMPLE:
ILUN = 21
FILENAME = 'coards.20010101.nc'
CTM_READ_COARDS, ILUN, FILENAME, FILEINFO, DATAINFO
; Reads data from the COARDS-compliant netCDF file
; coards.20010101.nc and stores it the FILEINFO and
; DATAINFO arrays of structures. If you are calling
; CTM_READ_COARDS from CTM_OPEN_FILE, then CTM_OPEN_FILE
; will append FILEINFO and DATAINFO to the GAMAP global
; common block.
MODIFICATION HISTORY:
bmy, 21 Mar 2005: GAMAP VERSION 2.03
bmy, 21 Jul 2005: GAMAP VERSION 2.04
- bug fix in CRC_SAVE_DATA
bmy, 06 Mar 2006: GAMAP VERSION 2.05
- minor bug fix in CRC_READ_GLOBAL_ATTS
- bug fix in CRC_SAVE_DATA: add a fake 4th
dim to DATA array if needed
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 16 Sep 2008: GAMAP VERSION 2.13
- Convert some global attributes to number
types in case attributes were initially
saved to the netCDF file as strings
phs, 15 Sep 2009: - Added check on reading tracerinfo.dat
- Convert some tracer names created by
BPCH2COARDS to their original value.
bmy, 14 Dec 2011: GAMAP VERSION 2.16
- Updated to read the GAMAP category value
from a netCDF variable attribute (if present)
bmy, 19 Dec 2011: - Generalized to handle several different
vertical levels
bmy, 21 Dec 2011: - Now will interpret netCDF attributes
"begin_date" and "begin_time" in the same
way as "start_date" and "start_time"
bmy, 22 Dec 2011: - Now compute FIRST (nested datablock offsets)
properly for nested grids. For now assume
that the data will always start on the first
vertical level.
- Bug fix: test for Latrev gt 0 to avoid
INADVERTENTLY reversing latitudes
bmy, 03 Jan 2012: - Skip over Ap and Bp index arrays
- Now use better error checks for
the time and vertical level dimensions
for each tracer in the netCDF file.
bmy, 05 Jan 2012: - Now interpret DELTA_TIME attribute
correctly when specified in hhmmss format.
bmy, 10 Jan 2012: - Fix to interpret data blocks with multiple
vertical dimensions in the same file
bmy, 13 Jan 2012: - When the time dimension in the netCDF
file is 1 (esp. when time is an UNLIMITED
variable, we need to add a fake dimension
of 1 back onto the data block to avoid
crashes. This is a quirk in how the IDL
NCDF_VARGET function works.
bmy, 23 Jan 2017: GAMAP VERSION 2.19
- Add modifications to read netCDF restart files
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_coards.pro)
NAME:
CTM_READ_DATA
PURPOSE:
read in one data block from a global model punch file output
(ASCII or binary)
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_READ_DATA,data,datainfo
or:
CTM_READ_DATA,data,ilun,filepos,xsize,ysize[,zsize,keywords]
INPUTS:
DATAINFO -> a datainfo structure as retrieved from
CTM_OPEN_FILE. This is the easiest way to read 3D
model output. Alternatively, the individual parameters
can be specified as follows.
ILUN -> logical file unit of input file (must be opened before)
FILEPOS -> a long word containing the start position of the data
block to be read (normally retrieved by CTM_OPEN_FILE)
XSIZE -> 1st dimension of the data array
YSIZE -> 2nd dimension of the data array
ZSIZE -> optional 3rd dimension of the data array
KEYWORD PARAMETERS:
Note: These keywords are ineffective when parameters are passed
via the DATAINFO structure!
SCALE -> apply scaling factor to data (default = 1.0)
FORMAT -> string with format identifier for data block
Default is '(12f6.2)'. Use '(8e10.3)' for BUDGETS output and
'(12(f6.2,1x))' for "extra_space" output. Format='BINARY'
indicates a binary file with REAL*4 data. (As long as the
dimensions are specified correctly ANY binary file can
be read this way, i.e. there is no need for additional
routines to read in e.g. gridded emission data files)
RESULT -> will return 1 if successful, 0 otherwise
OUTPUTS:
DATA -> a float array containing the block of data which is
either a 2D or a 3D array.
SUBROUTINES:
REQUIREMENTS:
file must have been opened and file positions of the data block
must be known (see CTM_OPEN_FILE)
NOTES:
The data array is *not* added to the datainfo structure!
EXAMPLE:
; Open a punch file interactively
CTM_OPEN_FILE,'',fileinfo,datainfo
; Test if successful
IF (not chkstru(datainfo)) then return
; Read in data of first data block
CTM_READ_DATA,data,datainfo[0]
; This is equivalent to:
CTM_READ_DATA,data,fileinfo.ilun,datainfo[0].filepos, $
datainfo[0].dim[0],datainfo[0].dim[1],datainfo[0].dim[2], $
scale=datainfo[0].scale,format=datainfo[0].format
MODIFICATION HISTORY:
mgs, 13 Aug 1998: VERSION 1.00 (from CTM_READ3DP_DATA)
- replaced EFORMAT keyword by more flexible
FORMAT keyword (involves changes in
CTM_READ3DP_HEADER and CREATE_3DHSTRU)
mgs, 17 Aug 1998: VERSION 2.00
- now possible to pass DATAINFO structure
- made it necessary to place DATA argument
as first parameter
mgs, 19 Aug 1998: - added RESULT keyword
mgs, 26 Oct 1998: - changed print statements to message
- user is now prompted when dimensions
are not given
bmy, 07 Apr 2000: - Added DAO keyword for reading in DAO met fields
bmy, 11 Apr 2001: - now uses DATA = TEMPORARY( DATA ) * SCALE[0]
in order to prevent excess memory usage
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- Removed GMAO keyword, we now use the
FORMAT string to test for GMAO data files
phs & bmy, 13 Jul 2007: GAMAP VERSION 2.10
- Modified for 4-D data blocks
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_data.pro)
NAME:
CTM_READ_EOSGR
PURPOSE:
Reads data blocks from a HDF-EOS Grid file into GAMAP.
(This is an internal routine which is called by CTM_OPEN_FILE.)
CATEGORY:
GAMAP Internals, Scientific Data Formats
CALLING SEQUENCE:
CTM_READ_EOSGR, ILUN, FILENAME, FILEINFO, DATAINFO, [, Keywords ]
INPUTS:
ILUN -> GAMAP file unit which will denote the HDF-EOS file.
FILENAME -> Name of the HDF-EOS grid file to be read.
FILEINFO -> Array of FILEINFO structures which will be
returned to CTM_OPEN_FILE. CTM_OPEN_FILE will
append FILEINFO to the GAMAP global common block.
DATAINFO -> Array of DATAINFO structures (each element
specifies a GAMAP data block) which will be returned
to CTM_OPEN_FILE. CTM_OPEN_FILE will append FILEINFO
to the GAMAP global common block.
KEYWORD PARAMETERS:
_EXTRA=e -> Picks up any extra keywords
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
=====================================================
CRE_Get_DimInfo CRE_Get_TracerInfo CRE_Save_Data
External Subroutines Required:
=====================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_MAKE_DATAINFO (function) STRRIGHT (function)
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) Currently is set up to read HDF-EOS files containing
GMAO met data files. You must have all possible met
field names listed in your "tracerinfo.dat" file or
else you will get an "Invalid Selection" error.
EXAMPLE:
ILUN = 21
FILENAME = 'a_llk_03.tsyn2d_mis_x.t20030801'
CTM_READ_EOSGR, ILUN, FILENAME, FILEINFO, DATAINFO
; Reads data from HDF-EOS file a_llk_03.tsyn2d_mis_x.t20030801
; and stores it the FILEINFO and DATAINFO arrays of
; structures. If calling CTM_READ_GMI from CTM_OPEN_FILE,
; then CTM_OPEN_FILE will append FILEINFO and DATAINFO
; to the GAMAP common block.
MODIFICATION HISTORY:
bmy, 12 Nov 2003: GAMAP VERSION 2.01
- initial version
bmy, 19 Feb 2004: GAMAP VERSION 2.01a
- added c402_rp_02 to the assim list
- bug fix: use DEFAULT keyword for SELECT_MODEL
bmy, 09 Mar 2004: GAMAP VERSION 2.02
- now test for "GEOS3", "GEOS4" strings in
the file name to determine model type
- now undefine variables after use
- now make sure that data block begins at the
date line and has longitude values in the
range [-180,180] degrees.
- always ensure that L=1 is the surface level
bmy, 25 Aug 2004: GAMAP VERSION 2.03
- Added c402_cer to the assim list
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Remove reference to unused SORT_STRU
bmy, 05 Dec 2007: GAMAP VERSION 2.12
- Modified for DAS.llk.asm files
bmy, 01 Oct 2008: GAMAP VERSION 2.13
- Increase DI, DJ in CRE_GET_DIMINFO for
the 0.5 x 0.667 grid
- Also now test for GEOS-5 in the filename
in CRE_GET_DIMINFO
- Bug fix in CRE_SAVE_DATA: If there is
only one data time in the HDF-EOS file,
then add an extra dimension to THISDATA
so that the CASE statement will be
interpreted properly.
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_eosgr.pro)
NAME:
CTM_READ_GMAO
PURPOSE:
Reads GMAO I-6,(instantaneous 6h), A-6 (average 6h),
or A-3 (average 3-h) met field files, and constructs
a DATAINFO structure for each met field.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
Result = CTM_READ_GMAO( Ilun, FileInfo, DataInfo [, Keywords ] )
INPUTS:
ILUN --> The name of the input file (or a file mask).
FILENAME is passed to OPEN_FILE. If FILENAME is a null
string or a file mask, then OPEN_FILE will open a
pickfile dialog box.
FILEINFO --> a (single) fileinfo structure containing information
about the (open) file (see CREATE3DFSTRU). FILEINFO also
contains information about the model which generated
the output (see CTM_TYPE)
DATAINFO --> a named variable that will contain an array of
structures describing the file content (see
CREATE3DHSTRU)
KEYWORD PARAMETERS:
PRINT -> if activated, print all headers found in the file
OUTPUTS:
The function returns 1 if successful, and 0 otherwise.
FILEINFO --> toptitle and modelinfo tags will be set
DATAINFO --> contains an array of named structures
(see CREATE3DHSTRU) with all relevant information
from the punch file header and what is needed to find
and load the data.
SUBROUTINES:
Internal Subroutines:
================================================
CRG_GET_MODELINFO
External Subroutines Required:
================================================
CHKSTRU (function) CTM_GRID (function)
CTM_TYPE (function) CREATE3DHSTRU (function)
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) You must also add additional met field names to your
"tracerinfo.dat" file as is neccesary. CTM_READ_GMAO looks
up met fields stored under the GAMAP categories "GMAO-2D"
and "GMAO-3D$".
(2) GEOS-4 met field files have an 8-char ident string
of the format "G4 45 19", where:
(a) "G4" means that it is a GEOS-4 met field file/
(b) "45" is the resolution code (in this case 4x5).
(c) "19" is the number of met fields stored w/in the file.
CTM_READ_GMAO will now set the modeltype and resolution from
the information in this ident string. For older met field
types (e.g. GEOS-3) which do not have this ident string,
CTM_READ_GMAO will determine the modeltype and resolution
from the filename and date.
EXAMPLES:
FileInfo = CREATE3DFSTRU() ; not required !
FName = '/r/amalthea/N/scratch/bmy/960101.a3.4x5'
OPEN_FILE, FName, Ilun, /F77_Unformatted
if ( Ilun gt 0 ) $
then Result = CTM_READ_GMAO( Ilun, FileInfo, DataInfo )
print,result
MODIFICATION HISTORY:
bmy, 16 May 2000: GAMAP VERSION 1.45
- adapted from original program "read_gmao"
bmy, 12 Jun 2000: - declare XYMD and XHMS as integers for
GEOS-2 and GEOS-3 data
bmy, 28 Jul 2000: GAMAP VERSION 1.46
- added GEOS-3 names to list of recognized fields
- deleted a couple of field names we don't use
bmy, 25 Sep 2000: - added new field: SLP (sea level pressure)
bmy, 08 Dec 2000: GAMAP VERSION 1.47
- added new fields: TKE, RH, KH
bmy, 07 Mar 2001: - added new fields: CLDTMP, TPW
bmy, 25 Apr 2001: - added new fields: TAULOW, TAUMID, TAUHI
bmy, 26 Jul 2001: GAMAP VERSION 1.48
- added new field: T2M
bmy, 15 Aug 2001: - added new field: OPTDEPTH
bmy, 06 Nov 2001: GAMAP VERSION 1.49
- added new field: DELP
- changed units from "mb" to "hPa"
bmy, 29 Jan 2002: GAMAP VERSION 1.50
- added new field: GWET
- removed obsolete code from 11/6/01
bmy, 01 May 2002: - added GWETTOP as synonym for GWET
- now assign correct units for fvDAS/GEOS-4
CLDMAS and DTRAIN fields: kg/m2/s
- now assign correct units for fvDAS/GEOS-4
PBL field: m (instead of hPa)
bmy, 17 Jul 2002: GAMAP VERSION 1.51
- added PBLH, Z0M, Z0H fields for fvDAS/GEOS-4
bmy, 16 Dec 2002: GAMAP VERSION 1.52:
- added new fvDAS fields: CMFDTR, CMFETR,
ZMDU, ZMED, ZMEU, ZMMD, ZMMU, HKETA, HKBETA
bmy, 21 May 2003: GAMAP VERSION 1.53:
- added T, U, V as synonyms of TMPU, UWND, VWND
- added Q as a synonym of SPHU
- removed CMFDTR, CMFETR fields
- HKBETA is now #18; HKETA is now #19
- updated comments
- added EVAP field as tracer #28
- TGROUND and T2M are now tracers #29, #30
- LAI is now tracer #31
- PARDF, PARDR are now tracers #32, 33
bmy, 30 Jul 2003: - added TSKIN as a synonym for TGROUND
bmy, 12 Dec 2003: GAMAP VERSION 2.01
- renamed to CTM_READ_GMAO to reflect the
change of name from "DAO" to "GMAO".
- GMAO binary files now have FILETYPE=104
- Rewrote so that we don't have to hardwire
met field names...it now gets the met
field names from "tracerinfo.dat"
- Now gets modeltype and resolution info
from GEOS-4 ident string
- Added internal function CRG_GET_MODELINFO
to generate the MODELINFO structure based
on the filename and date.
- Improved error output if we can't find
the tracer name
bmy & phs, 03 Aug 2007: GAMAP VERSION 2.10
- Ident string value "56" now will specify
a grid with 0.5 x 0.666 degree resolution
- Ident string value "10" now will specify
a grid with 1.0 x 1.0 degree resolution
- Now don't reset ILUN for GEOS-5 files
- Now call EXTRACT_FILENAME in CRG_GET_MODELINFO
to get just the filename instead of the full
path name.
- Adjusted for GEOS-5 fields with LMX+1 levels
- Bug fix: set null strings if GMAO-2D and/or
GMAO-3D$ categories aren't found
- Bug fix: change "gt" to "ge" in IF statements
where NAME2D, NAME3D, etc. are defined.
- Now use IS_EDGED
- Added routine CRG_GET_HORZDIM to return NI,
NJ, NL, FIRST for global or nested grids.
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Now check for MERRA grid. This is
identical to GEOS-5, but retains the
"MERRA" name for clarity.
bmy, 11 Aug 2010: - Bug fix: define STRUC array of structures
with 1024 entries. 512 is not enough for
the hourly MERRA data.
bmy, 17 Aug 2010: - Bug fix: define STRUC array of structures
with 2048 entries. 1024 may not be
enough for the hourly MERRA data.
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_gmao.pro)
NAME:
CTM_READ_GMI
PURPOSE:
Reads data blocks from a GMI netCDF file into GAMAP.
(This is an internal routine called from CTM_OPEN_FILE.)
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_READ_GMI, ILUN, FILENAME, FILEINFO, DATAINFO, [, Keywords ]
INPUTS:
ILUN -> GAMAP file unit which will denote the GMI netCDF file.
FILENAME -> Name of the GMI netCDF grid file to be read.
FILEINFO -> Array of FILEINFO structures which will be
returned to CTM_OPEN_FILE. CTM_OPEN_FILE will
append FILEINFO to the GAMAP global common block.
DATAINFO -> Array of DATAINFO structures (each element
specifies a GAMAP data block) which will be returned
to CTM_OPEN_FILE. CTM_OPEN_FILE will append FILEINFO
to the GAMAP global common block.
KEYWORD PARAMETERS:
_EXTRA=e -> Picks up extra keywords
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
===============================================
CRG_Debug_Print CRG_Get_Name CRG_Get_Tau0
CRG_Get_Tracer CRG_Get_Data CRG_Save_Data
External Subroutines Required:
===============================================
CTM_GRID (function) CTM_TYPE (function)
NCDF_GET (function) TVMAP
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) Currently is hardwired to reading in data blocks
from netCDF files created for the GMI comparison
study. It is difficult to create a general netCDF
reader since there are many different ways to store
data w/ in a netCDF file.
EXAMPLE:
ILUN = 21
FILENAME = 'gmit4_maccm3_year_CO.nc'
CTM_READ_GMI, ILUN, FILENAME, FILEINFO, DATAINFO
; Reads data from the netCDF file gmit4_maccm3_year_CO.nc
; and stores it the FILEINFO and DATAINFO arrays of
; structures. If calling CTM_READ_GMI from CTM_OPEN_FILE,
; then CTM_OPEN_FILE will append FILEINFO and DATAINFO
; to the GAMAP common block.
MODIFICATION HISTORY:
bmy, 05 Nov 2003: GAMAP VERSION 2.01
- initial version
bmy, 13 Feb 2004: GAMAP VERSION 2.01a
- bug fix: now should get multiple months
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_gmi.pro)
NAME:
CTM_READ_MULTILEVEL
PURPOSE:
Read all levels of a multilevel diagnostic (e.g. IJ-AVG-$)
and return a 3D data block. The associated datainfo structure
must be created before and passed into this routine.
This is an internal procedure which should not be used
directly.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_READ_MULTILEVEL,data,datainfo, $
Use_DataInfo=Use_DataInfo, $
Use_FileInfo=Use_FileInfo, $
result=result
INPUTS:
DATAINFO -> The datainfo structure that is to hold the new
3D data block.
KEYWORD PARAMETERS:
USE_DATAINFO, USE_FILEINFO -> The array of Datainfo and Fileinfo
stuctures to select from. Unlike the higher level routines,
CTM_READ_MULTILEVEL does not provide default values for
these!
RESULT -> A named variable that will be 1 if successful,
0 otherwise.
OUTPUTS:
DATA -> The 3D data block composed of the individual levels
from the ASCII punch file.
SUBROUTINES:
External Subroutines Required:
===========================================
EXPAND_CATEGORY CTM_DIAGINFO
CTM_DOSELECT_DATA CTM_READ_DATA
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
The dimensional information of the DATAINFO parameter is
adapted to the number of levels actually read from disk.
EXAMPLE:
See source code of CTM_RETRIEVE_DATA
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 26 Oct 1998: - made more error tolerant:
= if file ends within record, now returns
what's there
= if no dimensions were read,
assumes 72x46 and prints warning
= added status keyword
mgs, 10 Nov 1998: VERSION 3.00
- major design change
mgs, 28 Nov 1998: - hopefully fixed scaling bug now
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- Now get diagnostic spacing from CTM_DIAGINFO
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_multilevel.pro)
NAME:
CTM_READ_MULTITRACER
PURPOSE:
Read all entries of a 'multitracer' diagnostic (i.e.
source type diagnostic) and return a 3D data block.
The associated datainfo structure must be created before
and passed into this routine. This routien is meant for
internal use in the CTM_GET_DATA routines.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_READ_MULTITRACER,data,datainfo, $
Use_DataInfo=Use_DataInfo, $
Use_FileInfo=Use_FileInfo, $
result=result,debug=debug
INPUTS:
DATAINFO -> The datainfo structure that is to hold the new
3D data block.
KEYWORD PARAMETERS:
USE_DATAINFO, USE_FILEINFO -> The array of Datainfo and Fileinfo
stuctures to select from. Unlike the higher level routines,
CTM_READ_MULTILEVEL does not provide default values for
these!
RESULT -> A named variable that will be 1 if successful,
0 otherwise.
OUTPUTS:
DATA -> The 3D data block composed of the individual levels
from the ASCII punch file.
SUBROUTINES:
REQUIREMENTS:
Uses CTM_DOSELECT_DATA, CTM_READ_DATA
NOTES:
The dimensional information of the DATAINFO parameter is
adapted to the number of levels actually read from disk.
EXAMPLE:
See source code of CTM_***
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 26 Oct 1998: made more error tolerant:
- if file ends within record, now returns what's there
- if no dimensions were read, assumes 72x46 and prints warning
mgs, 10 Nov 1998: VERSION 3.00
- major design change
mgs, 28 Nov 1998:
- hopefully fixed scaling bug now
bmy & phs: 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_multitracer.pro)
NAME:
CTM_READ_NCDF
PURPOSE:
Reads data blocks from a netCDF file created by routine
BPCH2NC or BPCH2GMI into GAMAP. (This is an internal routine
which is called by CTM_OPEN_FILE.)
CATEGORY:
GAMAP Internals, Scientific Data Formats
CALLING SEQUENCE:
CTM_READ_NCDF, [, Keywords ]
INPUTS:
ILUN -> GAMAP file unit which will denote the netCDF file.
FILENAME -> Name of the netCDF grid file to be read.
FILEINFO -> Array of FILEINFO structures which will be
returned to CTM_OPEN_FILE. CTM_OPEN_FILE will
append FILEINFO to the GAMAP global common block.
DATAINFO -> Array of DATAINFO structures (each element
specifies a GAMAP data block) which will be returned
to CTM_OPEN_FILE. CTM_OPEN_FILE will append FILEINFO
to the GAMAP global common block.
KEYWORD PARAMETERS:
_EXTRA=e -> Picks up extra keywords
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
====================================================
CRN_Get_DimInfo CRN_Get_Time CRN_Get_Tracer
CRN_Read_Global_Atts CRN_Get_Data CRN_Save_Data
External Subroutines Required:
====================================================
CTM_GRID (function) CTM_TYPE (function)
CTM_MAKE_DATAINFO (function) STRRIGHT (function)
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) Currently assumes that the netCDF file was written
by GAMAP routine BPCH2NC.
EXAMPLE:
ILUN = 21
FILENAME = 'geos.20010101.nc'
CTM_READ_NCDF, ILUN, FILENAME, FILEINFO, DATAINFO
; Reads data from the netCDF file geos.20010101.nc
; and stores it the FILEINFO and DATAINFO arrays of
; structures. If calling CTM_READ_GMI from CTM_OPEN_FILE,
; then CTM_OPEN_FILE will append FILEINFO and DATAINFO
; to the GAMAP common block.
MODIFICATION HISTORY:
bmy, 05 Nov 2003: GAMAP VERSION 2.01
- initial version
bmy, 26 Mar 2004: GAMAP VERSION 2.02
- bug fix: now correctly separates "__"
in netCDF tracer names with STRPOS
bmy, 28 Feb 2005: GAMAP VERSION 2.03
- bug fix: now also exclude ETAC from
being passed to CRN_GET_TRACER
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Modified to read files from BPCH2GMI
bmy, 19 Dec 2007: GAMAP VERSION 2.12
- Now also skip ETAE, SIGE arrays
- Also don't add any vertical info to
the GRIDINFO structure if NLAYERS=1
bmy, 24 Jan 2011: GAMAP VERSION 2.15
- Now skip over Ap and Bp index fields
in the netCDF file
bmy, 14 Dec 2011: GAMAP VERSION 2.16
- Now also check to see if the GAMAP
category string is passed via the netCDF
"gamap_category" attribute
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_ncdf.pro)
NAME:
CTM_RETRIEVE_DATA
PURPOSE:
Read one "compound" data block from disk. The datainfo
parameter must contain only one entry, and it must have
status=0. The data pointer is assumed to be NULL.
If requested data block is a multilevel or multitracer
diagnostics, the routine will search all individual data
records that belong to that block and loop over them
(this is actually done in ctm_read_multilevel and
ctm_read_multitracer).
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
CTM_RETRIEVE_DATA,DataInfo,DiagStru, $
Use_DataInfo=Use_DataInfo, $
Use_FileInfo=Use_FileInfo, $
result=result
INPUTS:
DataInfo -> DataInfo structure that is to hold the data.
Normally, this is either created in CTM_GET_DATA for
multilevel or multitracer diagnostics, or it is created
upon parsing the header information (ctm_read3d?_header).
DIAGSTRU -> A (single) diagnostic structure containing
information what to load (see CTM_DIAGINFO)
KEYWORD PARAMETERS:
USE_DATAINFO, USE_FILEINFO -> The array of Datainfo and Fileinfo
stuctures to select from. Unlike the higher level routines,
CTM_READ_MULTILEVEL does not provide default values for
these!
RESULT -> A named variable that will be 1 if successful,
0 otherwise.
OUTPUTS:
The DATAINFO structure will contain the correct dimensional
information, the status will be set to 1, and the data pointer
points to a 2D or 3D data array. (if reading was successful)
SUBROUTINES:
REQUIREMENTS:
Uses CTM_DOSELECT_DATA, CTM_READ_MULTILEVEL,
CTM_READ_MULTITRACER, CTM_READ_DATA,
gamap_cmn.pro
NOTES:
This routine is meant for internal use from CTM_GET_DATA.
EXAMPLE:
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 22 Oct 1998: - scale factor set to 1 after unit scaling
is applied for multi...
- tracername and unit setting now also done
for non-multi fields
mgs, 26 Oct 1998: - added status keyword. If used (0,1,or 2)
no data will be read but datainfo record
will be prepared as usual.
mgs, 04 Nov 1998: - bug fix for reading of 2D arrays. Now return
correct (offset) tracer number
mgs, 10 Nov 1998: VERSION 3.00
- major design change
mgs, 28 Nov 1998: - hopefully fixed scaling bug now!
bmy, 07 Apr 2000: - now can read DAO met field files
bmy, 21 Nov 2003: GAMAP VERSION 2.01
- Removed GMAO keyword in call to
CTM_READ_DATA
bmy, 23 Aug 2004: GAMAP VERSION 2.03
- Now account for single-point data blocks
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_retrieve_data.pro)
NAME:
CTM_SELECT_DATA (function)
PURPOSE:
Provide a user-friendly function to extract data
from a DATAINFO structure. The function returns an
index to the given DATAINFO structure which points
to all recored that fulfill the specified conditions.
CATEGORY:
GAMAP Internals, GAMAP Data Manipulation
CALLING SEQUENCE:
index = CTM_SELECT_DATA(DIAGN[,DATAINFO,keywords])
INPUTS:
DIAGN -> A diagnostic number or category name. Only one
diagnostic can be extracted at the same time. Complete
information about the requested diagnostic is returned
via the DIAGSTRU keyword. (see also CTM_DIAGINFO)
DATAINFO -> An [optional] subset of the global DataInfo
structure. As default, CTM_SELECT_DATA operates on
the global DATAINFO structure (see gamap_cmn.pro) scanning
all files that have been opened.
KEYWORD PARAMETERS:
ILUN -> A logical unit value or an array of logical unit
values. Only recored from these files will be returned.
Default is to use all files.
A link between logical unit numbers and filenames can be
made through the (global) FileInfo structure (see gamap_cmn.pro)
TRACER -> A tracer number or an array of tracer numbers to
restrict the selection of data records. Default is to
return information about all tracers.
Tracer numbers less than 100 are automatically expanded
to include the offset of certain diagnostics (see
CTM_DIAGINFO and CTM_DOSELECT_DATA).
TAU -> A time value (tau0 !) or an array of time values
to restrict the selection of data records. Default is to
return information about all time steps. (see also example)
LEVELRANGE -> A 1 or 2 element vector with a level index or
a range of level indices for multilevel diagnostics
(e.g. 'IJ-AVG$'). As default, information is returned
about full 3D data blocks only. See also
EXPAND keyword.
/EXPAND -> If set, multilevel diagnostic fields are
expanded to return the individual layers in addition to
the complete 3D cube.
DATA -> A named variable that will contain an array with
pointers to the indexed data blocks. Note that some may
be NIL pointers if the STATUS value is 0 or 2.
COUNT -> A named variable that will return the number of
data blocks found with the given selection criteria
DIAGSTRU -> A named variable that will contain complete
information about the requested diagnostics (see
CTM_DIAGINFO)
STATUS -> Restricts the data selection to
Data that has not been read (STATUS = 0)
Data that has been read (STATUS = 1, default)
All data blocks (STATUS = 2)
If STATUS is 1, all pointers returned in DATA are valid.
OUTPUTS:
The function returns an (long) integer array that contains
index values to all the data blocks that match the selection
criteria. If no data is found, -1 is returned.
SUBROUTINES:
REQUIREMENTS:
Uses CTM_DOSELECT_DATA, EXPAND_CATEGORY, gamap_cmn.pro,
GAMAP_INIT, CTM_DIAGINFO
NOTES:
This function acts for the most part as a convenient user
interface to CTM_DOSELECT_DATA which performs the actual
selection process and contains only minimal error checking.
For programming purposes, use CTM_DOSELECT_DATA when possible.
EXAMPLE:
; open a CTM punch file
CTM_OPEN_FILE
; Read diagnostic number 45 for all tracers and time steps
CTM_READ_DATA,45
; Select data for tracer 1 and diagnostics 45
index = CTM_SELECT_DATA(45,tracer=1,data=pdata)
; De-reference the data pointer for the first record
; (usually the first timestep)
if (index[0] ge 0) then data = (*pdata)[0]
; find data for a specific time range
DataInfo = (*pGlobalDataInfo)[index]
taus = where(DataInfo.tau0 ge 77666L AND DataInfo.tau1 le 78888L)
taus = DataInfo.tau0[taus]
index = CTM_SELECT_DATA(45,DataInfo,tracer=1,tau=taus,data=pdata)
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 07 Oct 1998: - removed obsolete FILEINFO parameter
- changed NO_EXPAND to EXPAND
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- Now get spacing between diagnostic offsets
from CTM_DIAGINFO and pass to CTM_DOSELECT_DATA
- Now use the /NO_DELETE keyword in the
call to routine EXPAND_CATEGORY
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_select_data.pro)
NAME:
CTM_VALIDATESTRUCTURES
PURPOSE:
Test validity of a FILEINFO and DATAINFO structure
or array of structures.
CATEGORY:
GAMAP Internals, Structures
CALLING SEQUENCE:
CTM_VALIDATESTRUCTURES,FILEINFO,DATAINFO,result=result, $
print_warn=print_warn
INPUTS:
FILEINFO -> A FileInfo structure (array) to be tested
DATAINFO -> A DataInfo (array) to be tested
Both arguments must be present!
KEYWORD PARAMETERS:
RESULT -> A named variable that will be set to 1 if
both structures are valid. This keyword is mandatory.
PRINT_WARN -> print a warning message on the screen if
a structure is non-existent or corrupt.
OUTPUTS:
None
SUBROUTINES:
Uses ROUTINE_NAME and CHKSTRU functions
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
CTM_VALIDATESTRUCTURES,FileInfo,DataInfo,result=result
if (not result) then return
MODIFICATION HISTORY:
mgs, 20 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_validatestructures.pro)
NAME:
EXPAND_CATEGORY (function)
PURPOSE:
Replace wildcards in a multilevel diagnostic category
and return a string array with one entry for each
level.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
xcatgeory = EXPAND_CATEGORY(category)
INPUTS:
CATGEORY -> The original category name containing one
wildcard character (see CTM_DIAGINFO). If category
does not contain a wildcard character, the category
will be returned unchanged.
KEYWORD PARAMETERS:
RANGE -> A level index or range of level indices (2-elements)
to be returned. Default is to return the maximum
possible range (currently 1..24).
WILDCHARD -> a character value that is searched for as
wildchard. Default is '$' which is used in CTM_DIAGINFO
to denote a varying level index.
/NO_DELETE -> if set, will return category with wildcard as
first entry in result list. Default is to delete the
wildcard string.
OUTPUTS:
A string array with category names.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, EXPAND_CATEGORY('IJ-AVG-$')
; prints IJ-AVG-1 IJ-AVG-2 IJ-AVG-3 ...
; ... IJ-AVG-A IJ-AVG-B ...
print, EXPAND_CATEGORY( 'IJ-AVG-$', range=5 )
; prints IJ-AVG-5
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
mgs, 26 Oct 1998: added no_delete keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- added extra letters for grids w/
more than about 30 layers
(See /n/home09/ryantosca/IDL/gamap2/internals/expand_category.pro)
NAME:
GAMAP_CMN
PURPOSE:
Contains global common block for Global Atmospheric Model
output Analysis Package include file (include with @gamap_cmn)
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
@gamap_cmn
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
Referenced by gamap_init.pro and gamap.pro
NOTES:
None
MODIFICATION HISTORY:
mgs, 14 Aug 1998 INITIAL VERSION
mgs, 21 Jan 1999: - added postscript variables
bmy, 22 Feb 1999: - added options for animation (GIF, MPEG filenames)
bmy, 10 Dec 2002: GAMAP VERSION 1.52
- removed DO_MPEG and DEFAULTMPEGFILENAME
- added DO_BMP and DEFAULTBMPFILENAME
- added DO_JPEG and DEFAULTJPEGFILENAME
- added DO_PNG and DEFAULTPNGFILENAME
- added DO_TIFF and DEFAULTTIFFFILENAME
bmy, 13 Nov 2003: GAMAP VERSION 2.01
- re-added DO_MPEG and DEFAULTMPEGFILENAME
- removed CREATEANIMATION, this was only
ever used for XINTERANIMATE (obsolete)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/gamap_cmn.pro)
NAME:
GAMAP_INIT
PURPOSE:
Initialize global common block for Global Atmospheric Model
(output) Analysis Package (GAMAP). This routine is called
automatically when gamap_cmn.pro is included in a file
( @gamap_cmn.pro ), but it executes only once. User
preferences are read from the file gamap.defaults in the
current directory or the directory where gamap_init.pro
resides.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
GAMAP_INIT
INPUTS:
none
KEYWORD PARAMETERS:
DEBUG -> set a (new) debug level (0 or 1).
OUTPUTS:
none
SUBROUTINES:
Uses FILE_EXIST, EXTRACT_PATH, and OPEN_FILE
REQUIREMENTS:
None
NOTES:
If you change the definition of the common block
in gamap_cmn.pro, make sure to accomodate these changes
in GAMAP_INIT.
EXAMPLE:
GAMAP_INIT
MODIFICATION HISTORY:
mgs, 14 Aug 1998: VERSION 1.00
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 05 Oct 1998: - type assignment fix to DEBUG when read
mgs, 08 Oct 1998: - now runs through after CTM_CLEANUP and does
not delete global pointers if valid.
- added DEBUG keyword
mgs, 21 Jan 1999: - added postscript options
bmy, 19 Feb 1999: - added GIF_FILENAME
bmy, 22 Feb 1999: VERSION 1.01
- added more animation options
- changed POSTSCRIPT to DO_POSTSCRIPT
- default path now amalthea
mgs, 23 Mar 1999: - slight change in defaults
bmy, 19 Jan 2000: GAMAP VERSION 1.44
- replaced the deprecated STR_SEP function
with STRSPLIT for IDL 5.3+
- Now STRTRIM each token so that the case
statement will find matches
- cosmetic changes, updated comments
bmy, 13 Mar 2001: GAMAP VERSION 1.47
- now supports MacOS operating system
bmy, 07 Jun 2001: - removed obsolete code prior to 3/13/01
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, 10 Dec 2002: GAMAP VERSION 1.52
- added options for BMP, JPEG, PNG, TIFF output
- added internal function TRIMTOK
bmy, 13 Nov 2003: GAMAP VERSION 2.01
- re-added option for MPEG animation
- removed CREATEANIMATION, this was only
ever used for XINTERANIMATE (obsolete)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now use the IDL FILE_WHICH routine to
locate the gamap.defaults file
(See /n/home09/ryantosca/IDL/gamap2/internals/gamap_init.pro)
NAME:
GETETA
PURPOSE:
Defines the eta levels for the various hybrid model grids.
GETETA is called by function CTM_GRID.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
RESULT = GETETA( MNAME [, NLAYERS [, Keywords ] ] )
INPUTS:
MNAME -> The name of the model for which eta level
information is desired ('GEOS4' or 'GEOS4_30L').
NLAYERS -> Specifies the number of eta layers for the
model type. Default is 55 layers.
KEYWORD PARAMETERS:
PSURF -> Surface pressure in hPa. If PSURF is not specified,
GETETA will use 1013.25 hPa (e.g. 1 atmosphere).
/CENTERS -> Returns to the calling program an array
containing the eta coordinate at grid box centers.
/EDGES -> Returns to the calling program an array
containing the eta coordinate at grid box edges.
A -> Returns to the calling program the "A" vector of
values that define the hybrid grid. A has units of
[hPa].
B -> Returns to the calling program the "B" vector of
values that define the hybrid grid. B is unitless.
PRESSURE -> Returns the pressure [hPa] at the grid box edges
(if /EDGES is set) or the pressure at the grid box centers
(if /CENTERS is set).
OUTPUTS:
RESULT -> contains the array of eta edges (if /EDGES is
set), or eta centers (if /CENTERS is set).
SUBROUTINES:
None
REQUIREMENTS:
Called by CTM_GRID.PRO
NOTES:
Supported models:
-----------------------------------------------------------
(1 ) GCAP, 23-layer (name: "GCAP" )
(2 ) GEOS-4, 55-layer (name: "GEOS4" )
(3 ) GEOS-4 30-layer (name: "GEOS4_30L" )
(4 ) GEOS-5, 72-layer (name: "GEOS5" )
(5 ) GEOS-5 47-layer (name: "GEOS5_47L" )
(6 ) GEOS-FP 72-layer (name: "GEOSFP" )
(7 ) GEOS-FP 47-layer (name: "GEOSFP_47L" )
(8 ) MERRA, 72-layer (name: "MERRA" )
(9 ) MERRA 47-layer (name: "MERRA_47L" )
(10) MERRA2, 72-layer (name: "MERRA2" )
(11) MERRA2, 47-layer (name: "MERRA2_47L" )
(12) GISS_II_PRIME 23-layer (name: "GISS_II_PRIME")
(13) MATCH 52-layer (name: "MATCH" )
Computing pressure and eta coordinates:
-----------------------------------------------------------
In a vertical column, the pressure at the bottom edge of
grid box (L) is given by:
Pe(L) = A(L) + ( B(L) * Psurface )
and the pressure at the vertical midpoint of grid box (L)
is just a simple average of the pressures at the box edges:
Pc(L) = ( Pe(L) + Pe(L+1) ) * 0.5
From PEDGE and PCENTER, we can construct the unitless coordinate
ETA (which is very similar to the sigma coordinate) as follows:
ETAe(L) = ( Pe(L) - Ptop ) / ( Psurface - Ptop )
ETAc(L) = ( Pc(L) - Ptop ) / ( Psurface - Ptop )
For GAMAP plotting routines, we will use the ETA coordinate
for hybrid models instead of the sigma coordinate.
Psurface is a function of longitude and latitude. GAMAP uses
a default Psurface of 1013 hPa (1 atm). However, you should
always compute the pressure edges and centers from an accurate
surface pressure field (i.e. from met field data files or from
GEOS-Chem or other model output.
EXAMPLE:
EETA = GETETA( 'GEOS4' PSURF=984.0, /EDGES );
; assigns GEOS-1 eta edges to array EETA
CETA = GETETA( 'GEOS4', /CENTERS, PRESSURE=CPRESS )
; assigns GISS-II eta centers to array CETA
; (Optional) also returns the pressure at level centers
MODIFICATION HISTORY:
bmy, 06 Nov 2001: GAMAP VERSION 1.49
- based on routine "getsigma.pro"
bmy, 04 Nov 2003: GAMAP VERSION 2.01
- now supports "GEOS4_30L" grid
- now tests for model name using STRPOS
instead of just a straight match
- stop w/ an error for non-hybrid grids
- now supports 23-layer GISS_II_PRIME model
- now supports 52-layer MATCH model
bmy, 18 Jun 2004: GAMAP VERSION 2.02a
- now supports GCAP 23-layer hybrid grid
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
bmy, 15 Oct 2009: GAMAP VERSION 2.13
- Now supports GEOS-5 grids
bmy, 29 Nov 2010: GAMAP VERSION 2.15
- Now returns hybrid-grid A and B
values via the A & B keywords
- Now returns the pressure corresponding
to ETA via the PRESSURE keyword
- Renamed /CENTER to /CENTERS
(See /n/home09/ryantosca/IDL/gamap2/internals/geteta.pro)
NAME:
GETSIGMA (function)
PURPOSE:
Defines the sigma levels for the various grids.
GETSIGMA is called by function CTM_GRID.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
RESULT = GETSIGMA( MNAME [ NLAYERS [ , keywords ] ] )
INPUTS:
MNAME -> The name of the model for which sigma level
information is desired (e.g. 'geos1', 'giss_ii', etc.)
NLAYERS -> Specifies the number of sigma layers for the
GISS family of models. Default is 9 layers.
KEYWORD PARAMETERS:
CENTER -> Returns to the calling program an array
containing the sigma centers.
EDGES -> Returns to the calling program an array
containing the sigma edges.
/HELP -> Prints a help screen and returns a value
of -1 to the calling program.
OUTPUTS:
RESULT contains the array of sigma edges (if /EDGES is
set), or sigma centers (if /CENTERS is set).
SUBROUTINES:
REQUIREMENTS:
NOTES:
Supported models:
-------------------------------------------------------
(1 ) GEOS-1 20-layer (6 ) GEOS-3 30-layer
(2 ) GEOS-STRAT 46-layer (7 ) GISS-II 9-layer
(3 ) GEOS-STRAT 26-layer (8 ) GISS-II-PRIME 9-layer
(4 ) GEOS-2 70-layer (9 ) GISS-II-PRIME 23-layer
(5 ) GEOS-2 47-layer (10) FSU 14-layer
(6 ) GEOS-3 48-layer (11) MOPITT 7-layer
You can add more grids as is necessary.
EXAMPLE:
ESIG = GETSIGMA( 'GEOS1' /EDGES );
; assigns GEOS-1 sigma edges to array ESIG
CSIG = GETSIGMA( 'GISS_II', 9, /CENTERS )
; assigns GISS-II sigma centers (9 layer model) to array CSIG
MODIFICATION HISTORY:
mgs, 02 Mar 1998: VERSION 1.00
bmy, 19 Jun 1998: - added dummy FSU sigma edges and centers
- brought comments up to date
bmy, 16 Oct 1998: - added 26 layer GEOS-STRAT sigma levels
mgs, 25 Nov 1998: - improved defaulting of NLayers
bmy, 24 Feb 1999: - updated FSU sigma centers & edges
with values provided by Amanda Staudt
bmy, 27 Jul 1999: GAMAP VERSION 1.42
- added GISS-II-PRIME 23-layer sigma levels
- updated comments, cosmetic changes
bmy, 16 May 2000: GAMAP VERSION 1.45
- added GEOS-2 grids (47 and 70 layers)
bmy, 19 Jun 2000: - added GEOS-2 36 pressure-layer grid
bmy, 26 Jul 2000: GAMAP VERSION 1.46
- added GEOS-3 grid (48 layers)
bmy, 26 Jul 2001: GAMAP VERSION 1.48
- added GEOS-3 grid (30 layers, regridded)
bmy, 18 Dec 2003: GAMAP VERSION 2.01
- Now recognizes GEOS3_30L grid name
- Now sets 30 layers as default for GEOS3_30L
- Removed HELP keyword, you can use usage.pro
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/getsigma.pro)
NAME:
GET_GEOS5_PRESS
PURPOSE:
Returns zonal mean pressure edges and pressure centers
for the GEOS-5 grid (47 layers or 72 layers). Because in
GEOS-5 we cannot compute the pressures at grid box edges
and centers, we must read them in from disk.
CATEGORY:
GAMAP Internals, GAMAP Models & Grids
CALLING SEQUENCE:
GET_GEOS5_PRESS, PEDGE, PMID [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
FILENAME -> Specifies the name of the file containing
average pressures on the GEOS-5 grid. If FILENAME
is omitted, then GET_GEOS5_PRESS will use the default
filename: "pedge.geos5.{RESOLUTION}.year".
NLAYERS -> Specifies the number of layers in the GEOS-5
grid. NLAYERS can be either 47 or 72. Default is 47.
RESOLUTION -> Specifies the resolution of the GEOS-5 grid.
Default is 4x5.
PSURF -> If specified, then PEDGE and PMID will be 1-D
vectors, with the surface pressure (i.e. PEDGE[0])
being closest to the passed value of PSURF.
/VERBOSE -> Set this switch to toggle verbose output.
OUTPUTS:
PEDGE -> Array (or vector if PSURF is specified) of pressures
at GEOS-5 grid box edges. The PEDGE values have been
averaged over 12 months and also averaged over longitudes
(i.e. zonal mean).
PMID -> Array (or vector if PSURF is specified) of pressures
at GEOS-5 grid box centers. The pressures have been
averaged over 12 months and also averaged over longitudes
(i.e. zonal mean).
SUBROUTINES:
External Subroutines Required:
===================================
CTM_GET_DATA CTM_TYPE (function)
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) At present, we only have saved out a file containing
pressure edges from the GEOS-5 47-layer model.
EXAMPLE:
(1)
GET_GEOS5_PRESS, PEDGE, PMID, RES=2
; Returns pressues at grid box edges (PEDGE) and centers
; (PMID) for the GEOS-5 47L model at 2 x 2.5 resolution.
; PEDGE is a 2-D array of size 91x48. PMID is also a
; 2-D array of size 91x47.
(2)
GET_GEOS5_PRESS, PEDGE, PMID, RES=2, PSURF=1000.0
; Returns pressues at grid box edges (PEDGE) and centers
; (PMID) for the GEOS-5 47L model at 2 x 2.5 resolution.
; for the column with the closest surface pressure to
; PSURF=1000 hPa. PEDGE is a 1-D vector w/ 48 elements.
; PMID is also a 1-D vector w/ 47 elements.
MODIFICATION HISTORY:
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
phs, 25 Feb 2008: - check on File_Which output
dbm & ccc, 15 Dec 2009: GAMAP VERSION 2.14
- Make sure PSURF is a scalar
(See /n/home09/ryantosca/IDL/gamap2/internals/get_geos5_press.pro)
NAME:
SELECT_MODEL
PURPOSE:
Primitive function to select a model.
Calls CTM_TYPE and returns the MODELINFO structure.
CATEGORY:
GAMAP Internals
CALLING SEQUENCE:
MODELINFO = SELECT_MODEL( [ Keywords ] )
INPUTS:
None
KEYWORD PARAMETERS:
DEFAULT -> String containing the default model name,
resolution, and number of levels.
OUTPUTS:
Returns the MODELINFO structure (from CTM_TYPE)
as the value of the function.
SUBROUTINES:
External subroutines required:
------------------------------
CTM_TYPE (function)
REQUIREMENTS:
References routines from GAMAP and TOOLS packages.
NOTES:
Add new model selections as is necessary. Also be sure to
update routines "ctm_type", "ctm_grid", and "getsigma".
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% NOTE: THIS ROUTINE IS MOSTLY OBSOLETE NOW BECAUSE %%%
%%% MOST DATA FILES NOW CONTAIN THE MODEL NAME AND %%%
%%% RESOLUTION INFORMATION. %%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
EXAMPLE:
MODELINFO = SELECT_MODEL( DEFAULT='GISS_II_PRIME 4x5 (23L)' )
; Will return the modelinfo structure for the 23-layer
; GISS-II-PRIME model. We need to specify the number
; of layers here since there is also a 9-layer version
; of the GISS-II-PRIME model.
MODIFICATION HISTORY:
mgs, 13 Aug 1998: VERSION 1.00
mgs, 21 Dec 1998: - added GEOS_STRAT 2x2.5
mgs, 25 Mar 1999: - changed FSU to 4x5 and added 'generic'
bmy, 27 Jul 1999: GAMAP VERSION 1.42
- now add the number of layers to the menu choices
- added GISS-II-PRIME 23-layer model as a choice
- more sophisticated testing for default model
- a few cosmetic changes
bmy, 03 Jan 2000: GAMAP VERSION 1.44
- added GEOS-2 as a model selection
- added standard comment header
bmy, 16 May 2000: GAMAP VERSION 1.45
- now use GEOS-2 47-layer grid
bmy, 28 Jul 2000: GAMAP VERSION 1.46
- added GEOS-3 48-layer grids for 1 x 1,
2 x 2.5, and 4 x 5 horizontal resolution
bmy, 26 Jul 2001: GAMAP VERSION 1.48
- added GEOS-3 30-layer grids for 2 x 2.5
and 4 x 5 horizontal resolution
bmy, 24 Aug 2001: - deleted GEOS-3 30-layer grids, since
we won't be using these soon
bmy, 06 Nov 2001: GAMAP VERSION 1.49
- added GEOS-4/fvDAS grids at 1 x 1.25,
2 x 2.5, and 4 x 5 resolution
clh & bmy, 18 Oct 2002: GAMAP VERSION 1.52
- added MOPITT 7L grid
bmy, 11 Dec 2002 - deleted GEOS-2 47L grid, nobody uses this
bmy, 18 May 2007: GAMAP VERSION 2.06
- added GEOS-4 30L grid
- added GEOS-5 47L and 72L grids
- added quit option
bmy, 11 May 2012: GAMAP VERSION 2.16
- Added MERRA, GEOS-5.7 options
(See /n/home09/ryantosca/IDL/gamap2/internals/select_model.pro)
NAME:
TVIMAGE
PURPOSE:
This purpose of TVIMAGE is to enable the TV command in IDL
to be a completely device-independent and color-decomposition-
state independent command. On 24-bit displays color decomposition
is always turned off for 8-bit images and on for 24-bit images.
The color decomposition state is restored for those versions of
IDL that support it (> 5.2). Moreover, TVIMAGE adds features
that TV lacks. For example, images can be positioned in windows
using the POSITION keyword like other IDL graphics commands.
TVIMAGE also supports the !P.MULTI system variable, unlike the
TV command. TVIMAGE was written to work especially well in
resizeable graphics windows. Note that if you wish to preserve
the aspect ratio of images in resizeable windows, you should set
the KEEP_ASPECT_RATIO keyword, described below. TVIMAGE works
equally well on the display, in the PostScript device, and in
the Printer and Z-Graphics Buffer devices. The TRUE keyword is
set automatically to the correct value for 24-bit images, so you
don't need to specify it when using TVIMAGE.
AUTHOR:
FANNING SOFTWARE CONSULTING:
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
GAMAP Internals, Graphics
CALLING SEQUENCE:
TVIMAGE, image
INPUTS:
image: A 2D or 3D image array. It should be byte data.
x : The X position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
If the Y position is not used, X is taken to be the image
"position" in the window. See the TV command documenation
for details.
y : The Y position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
KEYWORD PARAMETERS:
BACKGROUND: This keyword specifies the background color. Note that
the keyword ONLY has effect if the ERASE keyword is also
set or !P.MULTI is set to multiple plots and TVIMAGE is
used to place the *first* plot.
ERASE: If this keyword is set an ERASE command is issued
before the image is displayed. Note that the ERASE
command puts the image on a new page in PostScript
output.
_EXTRA: This keyword picks up any TV keywords you wish to use.
HALF_HALF: If set, will tell CONGRID to extrapolate a *half* row
and column on either side, rather than the default of
one full row/column at the ends of the array. If you
are interpolating images with few rows, then the
output will be more consistent with this technique.
This keyword is intended as a replacement for
MINUS_ONE, and both keywords probably should not be
used in the same call to CONGRID.
KEEP_ASPECT_RATIO: Normally, the image will be resized to fit the
specified position in the window. If you prefer, you can
force the image to maintain its aspect ratio in the window
(although not its natural size) by setting this keyword.
The image width is fitted first. If, after setting the
image width, the image height is too big for the window,
then the image height is fitted into the window. The
appropriate values of the POSITION keyword are honored
during this fitting process. Once a fit is made, the
POSITION coordiates are re-calculated to center the image
in the window. You can recover these new position coordinates
as the output from the POSITION keyword.
MARGIN: A single value, expressed as a normalized coordinate, that
can easily be used to calculate a position in the window.
The margin is used to calculate a POSITION that gives
the image an equal margin around the edge of the window.
The margin must be a number in the range 0.0 to 0.333. This
keyword is ignored if the POSITION or OVERPLOT keywords are
used. It is also ignored when TVImage is executed in a
multi-plot window, EXCEPT if it's value is zero. In this
special case, the image will be drawn into its position in
the multi-plot window with no margins whatsoever. (The
default is to have a slight margin about the image to separate
it from other images or graphics.
MINUS_ONE: The value of this keyword is passed along to the CONGRID
command. It prevents CONGRID from adding an extra row and
column to the resulting array, which can be a problem with
small image arrays.
NOINTERPOLATION: Setting this keyword disables the default bilinear
interpolation done to the image when it is resized. Nearest
neighbor interpolation is done instead. This is preferred
when you do not wish to change the pixel values of the image.
This keyword must be set, for example, when you are displaying
GIF files that come with their own non-IDL color table vectors.
NORMAL: Setting this keyword means image position coordinates x and y
are interpreted as being in normalized coordinates. This keyword
is only valid if the TV keyword is set.
OVERPLOT: Setting this keyword causes the POSITION keyword to be ignored
and the image is positioned in the location established by the
last graphics command. For example:
Plot, Findgen(11), Position=[0.1, 0.3, 0.8, 0.95]
TVImage, image, /Overplot
POSITION: The location of the image in the output window. This is
a four-element floating array of normalized coordinates of
the type given by !P.POSITION or the POSITION keyword to
other IDL graphics commands. The form is [x0, y0, x1, y1].
The default is [0.0, 0.0, 1.0, 1.0]. Note that this keyword is ALSO
an output keyword. That is to say, upon return from TVIMAGE
this keyword (if passed by reference) contains the actual
position in the window where the image was displayed. This
may be different from the input values if the KEEP_ASPECT_RATIO
keyword is set, or if you are using TVIMAGE with the POSITION
keyword when !P.MULTI is set to something other than a single
plot. One use for the output values might be to position other
graphics (e.g., a colorbar) in relation to the image.
Note that the POSITION keyword should not, normally, be used
when displaying multiple images with !P.MULTI. If it *is* used,
its meaning differs slightly from its normal meaning. !P.MULTI
is responsible for calculating the position of graphics in the
display window. Normally, it would be a mistake to use a POSITION
graphics keyword on a graphics command that was being drawn with
!P.MULTI. But in this special case, TVIMAGE will use the POSITION
coordinates to calculate an image position in the actual position
calculated for the image by !P.MULTI. The main purpose of this
functionality is to allow the user to display images along with
colorbars when using !P.MULTI. See the example below.
TV: Setting this keyword makes the TVIMAGE command work much
like the TV command, although better. That is to say, it
will still set the correct DECOMPOSED state depending upon
the kind of image to be displayed (8-bit or 24-bit). It will
also allow the image to be "positioned" in the window by
specifying the coordinates of the lower-left corner of the
image. The NORMAL keyword is activated when the TV keyword
is set, which will indicate that the position coordinates
are given in normalized coordinates rather than device
coordinates.
Setting this keyword will ensure that the keywords
KEEP_ASPECT_RATIO, MARGIN, MINUS_ONE, MULTI, and POSITION
are ignored.
OUTPUTS:
None.
SIDE EFFECTS:
Unless the KEEP_ASPECT_RATIO keyword is set, the displayed image
may not have the same aspect ratio as the input data set.
RESTRICTIONS:
If the POSITION keyword and the KEEP_ASPECT_RATIO keyword are
used together, there is an excellent chance the POSITION
parameters will change. If the POSITION is passed in as a
variable, the new positions will be returned in the same variable
as an output parameter.
If a 24-bit image is displayed on an 8-bit display, the
24-bit image must be converted to an 8-bit image and the
appropriate color table vectors. This is done with the COLOR_QUAN
function. The TVIMAGE command will load the color table vectors
and set the NOINTERPOLATION keyword if this is done. Note that the
resulting color table vectors are normally incompatible with other
IDL-supplied color tables. Hence, other graphics windows open at
the time the image is display are likely to look strange.
EXAMPLE:
To display an image with a contour plot on top of it, type:
filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
image = BYTARR(360,360)
OPENR, lun, filename, /GET_LUN
READU, lun, image
FREE_LUN, lun
TVIMAGE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO
CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $
YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10
To display four images in a window without spacing between them:
!P.Multi=[0,2,2]
TVImage, image, Margin=0
TVImage, image, Margin=0
TVImage, image, Margin=0
TVImage, image, Margin=0
!P.Multi = 0
To display four image in a window with associated color bars:
!P.Multi=[0,2,2]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 0
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 2
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 3
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 5
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
!P.Multi =0
MODIFICATION HISTORY:
Written by: David Fanning, 20 NOV 1996.
Fixed a small bug with the resizing of the image. 17 Feb 1997. DWF.
Removed BOTTOM and NCOLORS keywords. This reflects my growing belief
that this program should act more like TV and less like a "color
aware" application. I leave "color awareness" to the program
using TVIMAGE. Added 24-bit image capability. 15 April 1997. DWF.
Fixed a small bug that prevented this program from working in the
Z-buffer. 17 April 1997. DWF.
Fixed a subtle bug that caused me to think I was going crazy!
Lession learned: Be sure you know the *current* graphics
window! 17 April 1997. DWF.
Added support for the PRINTER device. 25 June 1997. DWF.
Extensive modifications. 27 Oct 1997. DWF
1) Removed PRINTER support, which didn't work as expected.
2) Modified Keep_Aspect_Ratio code to work with POSITION keyword.
3) Added check for window-able devices (!D.Flags AND 256).
4) Modified PostScript color handling.
Craig Markwart points out that Congrid adds an extra row and column
onto an array. When viewing small images (e.g., 20x20) this can be
a problem. Added a Minus_One keyword whose value can be passed
along to the Congrid keyword of the same name. 28 Oct 1997. DWF
Changed default POSITION to fill entire window. 30 July 1998. DWF.
Made sure color decomposition is OFF for 2D images. 6 Aug 1998. DWF.
Added limited PRINTER portrait mode support. The correct aspect ratio
of the image is always maintained when outputting to the
PRINTER device and POSITION coordinates are ignored. 6 Aug 1998. DWF
Removed 6 August 98 fixes (Device, Decomposed=0) after realizing that
they interfere with operation in the Z-graphics buffer. 9 Oct 1998. DWF
Added a MARGIN keyword. 18 Oct 1998. DWF.
Re-established Device, Decomposed=0 keyword for devices that
support it. 18 Oct 1998. DWF.
Added support for the !P.Multi system variable. 3 March 99. DWF
Added DEVICE, DECOMPOSED=1 command for all 24-bit images. 2 April 99. DWF.
Added ability to preserve DECOMPOSED state for IDL 5.2 and higher. 4 April 99. DWF.
Added TV keyword to allow TVIMAGE to work like the TV command. 11 May 99. DWF.
Added the OVERPLOT keyword to allow plotting on POSITION coordinates
estabished by the preceding graphics command. 11 Oct 99. DWF.
Added automatic recognition of !P.Multi. Setting MULTI keyword is no
longer required. 18 Nov 99. DWF.
Added NOINTERPOLATION keyword so that nearest neighbor interpolation
is performed rather than bilinear. 3 Dec 99. DWF
Changed ON_ERROR condition from 1 to 2. 19 Dec 99. DWF.
Added Craig Markwardt's CMCongrid program and removed RSI's. 24 Feb 2000. DWF.
Added HALF_HALF keyword to support CMCONGRID. 24 Feb 2000. DWF.
Fixed a small problem with image start position by adding ROUND function. 19 March 2000. DWF.
Updated the PRINTER device code to take advantage of available keywords. 2 April 2000. DWF.
Reorganized the code to handle 24-bit images on 8-bit displays better. 2 April 2000. DWF.
Added BACKGROUND keyword. 20 April 2000. DWF.
Fixed a small problem in where the ERASE was occuring. 6 May 2000. DWF.
Rearranged the PLOT part of code to occur before decomposition state
is changed to fix Background color bug in multiple plots. 23 Sept 2000. DWF.
Removed MULTI keyword, which is no longer needed. 23 Sept 2000. DWF.
Fixed a small problem with handling images that are slices from 3D image cubes. 5 Oct 2000. DWF.
Added fix for brain-dead Macs from Ben Tupper that restores Macs ability to
display images. 8 June 2001. DWF.
Fixed small problem with multiple plots and map projections. 29 June 2003. DWF.
Converted all array subscripts to square brackets. 29 June 2003. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Small modification at suggestion of Karsten Rodenacker to increase size of
images in !P.MULTI mode. 8 December 2004. DWF.
Minor modifications on Karsten Rodenacker's own account concerning margination
and TV behaviour. 8 December 2004. KaRo
There was a small inconsistency in how the image was resized for PostScript as
opposed to the display, which could occasionally result in a small black line
to the right of the image. This is now handled consistently. 3 January 2007. DWF.
Made a small change to CMCONGRID to permit nearest-neighbor interpolation for 3D arrays.
Previously, any 24-bit image was interpolated, no matter the setting of the NOINTERP
keyword. 22 April 2007. DWF.
Updated the program for the 24-bit Z-buffer in IDL 6.4. 11 June 2007. DWF.
Added new POSITION keyword functionality for !P.MULTI display. 9 Sept 2007. DWF.
(See /n/home09/ryantosca/IDL/gamap2/internals/tvimage.pro)