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:
CTM_EXTRACT (function)
PURPOSE:
Extracts a block of data from a 3-D CTM data cube.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_EXTRACT, DATA, MODELINFO, GRIDINFO [,Keywords]
INPUTS:
DATA -> The data cube from which to extract a region.
DATA must be 3-dimensional (e.g. lon-lat-alt, or
lon-lat-tracer, etc).
KEYWORD PARAMETERS:
MODELINFO -> The MODELINFO structure returned from function
CTM_TYPE.
GRIDINFO -> The GRIDINFO structure returned from function
CTM_GRID.
AVERAGE -> Bit flag indicating the dimensions over which to
average the data:
1 : longitudinal
2 : latitudinal
4 : vertical
These values can be combined. E.g., to average over
longitude and latitude use 3. A bit set in AVERAGE
superseeds the corresponding bit in TOTAL (see below).
TOTAL -> Bit flag indicating the dimensions over which
to sum the data:
1 : longitudinal
2 : latitudinal
4 : vertical
These values can be combined. E.g., to integrate over
longitude and latitude use 3. A bit set in AVERAGE
superseeds the corresponding bit in TOTAL (see above).
/INDEX -> If set, will interpret LAT, LEV, and LON as index
arrays. If not set, will interpret LAT, LEV, and LON as
ranges (i.e. two-element vectors containing min and max values).
LAT -> An index array of latitudes *OR* a two-element vector
specifying the min and max latitudes to be included in
the extracted data block. Default is [ -90, 90 ].
LEV -> An index array of sigma levels *OR* a two-element vector
specifying the min and max sigma levels to be included
in the extracted data block. Default is [ 1, GRIDINFO.LMX ].
LON -> An index array of longitudes *OR* a two-element vector
specifying the min and max longitudes to be included in
the extracted data block. Default is [ -180, 180 ].
ALTRANGE -> A vector specifying the min and max altitude
values (or a scalar specifying a single altitude) to
be included in the extracted data block.
PRANGE -> A vector specifying the min and max pressure levels
(or a scalar specifying a single pressure level) to be
included in the extracted data block.
WE -> Returns to the calling program the index array of longitudes
for the extracted data region, ordered from west to east.
SN -> Returns to the calling program the index array of latitudes
for the extracted data region, ordered from South to North.
UP -> Returns to the calling program the index array of vertical
levels for the extracted data region, ordered from surface
to top.
DIM -> A named variable will return the new dimension information
of the data block after averaging or totaling.
_EXTRA=e -> Picks up extra keywords for CTM_INDEX.
OUTPUTS:
X, Y, Z -> Arrays of latitude, longitude, or altitude values
corresponding to the the 1st, 2nd, and 3rd dimensions of
the DATA array, respectively.
SUBROUTINES:
CTM_INDEX
DEFAULT_RANGE (function)
REQUIREMENTS:
Uses GAMAP package subroutines.
NOTES:
(1) CTM_EXTRACT returns the extracted data region as
the function value.
(2) Assumes a 3-D data cube as input, of dimensions (lon, lat,
alt), or for some diagnostics (lon, lat, "tracer" number).
(3) In the calling program, CTM_TYPE and CTM_GRID must be
called to compute the MODELINFO and GRIDINFO structures,
which can then be passed to CTM_EXTRACT.
(4) If any of the LAT, LON, LEV, ALTRANGE, PRANGE keywords are
explicity specified, then CTM_EXTRACT will return to the
calling program their original, unmodified values. If any
of these are not explicitly specified , then CTM_EXTRACT
will return to the calling program default values.
EXAMPLE:
(1)
MODELINFO = CTM_TYPE( 'GEOS4', RES=4 )
GRIDINFO = CTM_GRID( MODELINFO )
DATAREGION = CTM_EXTRACT( DATACUBE, $
MODELINFO=MODELINFO, $
GRIDINFO=GRIDINFO $
LON=[-180,0], LAT=[-30,30], $
LEV=[1,10] )
; Extracts from a GEOS-4 4x5 data cube a region
; delimited by longitude = [-180, 0],
; latitude = [-30, 30], for levels 1 to 10.
(2)
LON = INDGEN( 36 )
LAT = INDGEN( 16 ) + 15
LEV = INDGEN( 10 )
MODELINFO = CTM_TYPE( 'GEOS4' )
GRIDINFO = CTM_GRID( MODELINFO )
DATAREGION = CTM_EXTRACT( DATACUBE, $
MODELINFO=MODELINFO, $
GRIDINFO=GRIDINFO, $
/INDEX, LON=LON, $
LAT=LAT, LEV=LEV )
; Extracts same data region as in Example (1) but
; here passes explicit index arrays instead of ranges.
MODIFICATION HISTORY:
bmy, 16 Sep 1998: VERSION 1.00
bmy, 17 Sep 1998: - now extracts data from data cube one
dimension at a time to avoid errors
bmy, 18 Sep 1998: VERSION 1.01
- INDEX, SN, WE, UP keywords added
- LATRANGE, LONRANGE, LEVRANGE renamed
to LAT, LON, LEV (since they may now
contain arrays and not just ranges).
mgs, 21 Sep 1998: - some more error checking
- removed MinData and MaxData
bmy and mgs, 22 Sep 1998: VERSION 1.02
- added AVERAGE and TOTAL keywords
bmy, 24 Sep 1998: VERSION 1.03
- Now returns original values of LAT, LON,
LEV, ALTRANGE, and PRANGE if those keywords
are specified. Otherwise returns
defaults.
MGS, 29 SEP 1998: - Introduced new DEFAULT_RANGE function.
bmy, 06 Oct 1998: - fixed bug: now S = size( NEWDATA )
bmy, 08 Oct 1998: VERSION 1.04
- MODELINFO and GRIDINFO are now keywords
- added X, Y, and Z as parameters
bmy, 11 Feb 1999: - updated comments
bmy, 19 Feb 1999: VERSION 1.05
- added FIRST keyword so that the values of
THISDATAINFO.FIRST can be passed from the
calling routine.
- now call ADJ_INDEX to adjust the WE,
SN, and UP index arrays for data blocks
that are less than global size.
- added DEBUG keyword
mgs, 16 Mar 1999: - cosmetic changes
mgs, 02 Apr 1999: - bug fixes that prevented use with 2D fields
(e.g. EPTOMS data)
mgs, 21 May 1999: - now catches error in multitracer diagnostics
when user requests a level beyond LMX.
qli, 26 May 1999: - "max(newlev) ge" corrected to "gt"
bmy, 15 Sep 1999: VERSION 1.43
- removed bugs that caused data blocks to
always have MODELINFO.NTROP vertical
layers
bmy, 04 Dec 2000: GAMAP VERSION 1.47
- add code for future bug fix
bmy, 24 Apr 2001: - bug fix: now can handle longitudes
greater than 180 degrees
bmy, 06 Jun 2001: - bug fix: Test if LON exists before
assigning it to NEWLON.
bmy, 30 Jul 2001: GAMAP VERSION 1.48
- bug fix: now extract proper latitude range
for data blocks smaller than global size
bmy, 26 Jun 2002: GAMAP VERSION 1.51
- Default value of FIRST is now [1,1,1],
since this has to be in Fortran notation.
- also do error checking on FIRST near
the beginning of the program.
bmy, 15 Nov 2002: GAMAP VERSION 1.52
- now can handle total/average for MOPITT grid
bmy, 23 Aug 2004: GAMAP VERSION 2.03
- now can handle single-point data blocks
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 19 Nov 2007: GAMAP VERSION 2.11
- Updated comments
bmy, 10 Dec 2007: GAMAP VERSION 2.12
- Now pad ALTRANGE and PRANGE to 2 elements
if they are passed w/ one element
bmy, 13 Aug 2009: GAMAP VERSION 2.13
- Bug fix: now compute DEF_X_RANGE from the
grid edges for computing NEWLON. Now
also works for nested grids.
phs & bmy, 13 Oct 2009: - Bug fix: now account for ranges that
straddle the date line when computing
DEF_X_RANGE
ccc, 21 Oct 2009: - Bug fix when PRange is passed.
bmy, 20 Mar 2017: GAMAP VERSION 2.19
- Now make sure that WE, SN, UP are converted
from Fortran to IDL notation properly
when /INDEX is specified.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_extract.pro)
NAME:
CTM_GET_DATA
PURPOSE:
Retrieve specific data records from CTM output files.
Opening files, parsing header information, and loading
of data are handled transparently and can be
controlled by various keywords. The routine returns a
subset of the global DATAINFO structure that matches the
requested category and (optional) tracer and time step(s).
This routine should be called *whenever* you want to
access data and you are not sure that it has been
loaded previously. It provides the general user-interface
for GAMAP (the Global Atmospheric Model output Analysis
Package).
For the future, a widget interface to this routine is
planned.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_GET_DATA, DATAINFO [,DIAGN] [,keywords]
INPUTS:
DIAGN -> A diagnostic number or category name (see
(CTM_DIAGINFO). A value of 0 (or an empty string)
prompts processing of all available diagnostics.
DIAGN can also be an array of diagnostic numbers or
category names.
KEYWORD PARAMETERS:
FILENAME -> (optional) If FILENAME is a fully qualified file path
the specified file is opened without user interaction.
If filename is empty or contains wildchards (*,?), a
pickfile dialog will be displayed.
If FILENAME is a named variable it will contain the full
file path upon return so that a subsequent call to
CTM_GET_DATA with the same FILENAME argument will not prompt
another file selection dialog.
If the FILENAME keyword is present, CTM_GET_DATA
will restrict it's scope to records from the selected
is file (even if FILENAME contains an empty string, it will
restrict the scope of the search!).
If the file is found in the global FILEINFO structure or
the USE_FILEINFO structure (i.e. it has been opened
previously), then it will not be parsed again; instead the
data records are returned from memory.
The data itself is loaded transparently via
CTM_RETRIEVE_DATA.
ILUN -> An optional value or array of logical unit numbers. If
given, the search is restricted to data from the specified
files. Default is to use all files (unless the FILENAME
keyword is present). If an undefined variable
is passed into ILUN, information about all accessible files
in the global FILEINFO structure (or USE_FILEINFO) is returned.
TRACER -> A tracer ID number or a list of those. If given, the
search is restricted to those tracers. Default is to use all
tracers. If an undefined variable is passed into TRACER,
and one specific diagnostics is requested with DIAGN,
information about all accessible tracers in the global
DATAINFO structure or USE_DATAINFO structure or the
DATAINFO structure associated with a specific file is returned.
TAU0 -> A time value or list of values to restrict the search.
Default handling as with ILUN or TRACER. TAU0 superseeds
/FIRST, /LAST or TAURANGE.
TAURANGE -> A 2-element vector containing the first and last tau0
value to look for.
/FIRST, /LAST -> extract first or last time step that is stored for
the selected diagnostics, ilun, and tracer. Only one can be
be active at a time. /LAST superseeds /FIRST.
INDEX -> A named variable that will contain the indices of the
records in USE_DATAINFO that match the selection criteria.
You can test INDEX[0] ge 0 in order to see if CTM_GET_DATA has
been successful although it is now recommended to test for
n_elements(DATAINFO) eq 0.
The INDEX keyword is useful if you want to change the
information contained in the selected DATAINFO structures
globally.
USE_FILEINFO -> (optional) If provided, CTM_GET_DATA will
restrict its search to only the files that are
contained in USE_FILEINFO which must be a FILEINFO
structure array. Default is to use the global information
(see gamap_cmn.pro).
If an undefined named variable is provided in USE_FILEINFO,
it will either contain the global FILEINFO structure array
or the FILEINFO record of the specified file.
USE_FILEINFO must contain entries for all logical unit numbers
that are used in USE_DATAINFO.
USE_DATAINFO -> (optional) Restrict search to records contained
in USE_DATAINFO which must be a DATAINFO structure array.
If an undefined named variable is provided in USE_DATAINFO,
it will either contain the global DATAINFO structure array
or all DATAINFO records of the specified file.
See also USE_FILEINFO.
/INTERNAL_USE -> Set this keyword if you want to prevent a call
to CTM_OPEN_FILE, but instead abort in case of undefined
(global) FILEINFO or DATAINFO structures.
OUTPUTS:
DATAINFO -> An array of DATAINFO records that match the selected
criteria. You can then simply loop over
0..n_elements(DATAINFO)-1 to access all data records and
extract the data as *(DATAINFO[i].data).
DATAINFO will be undefined if no records are found!!
Always test for IF (n_elements(DATAINFO) eq 0) ... !
NOTE: Alternatively you can return the INDEX to the selected
data records in the global (or USE_) datainfo structure array
with the INDEX keyword. This may in some cases eliminate the
need to make a local copy of the selected DATAINFO records.
SUBROUTINES:
pro reopen_all_files,fileinfo
(needed in order to get free unit numbers)
pro make_compound_datainfo,DataInfo,category,ilun,tracer,tau0,tau1
(make compound structure for multilevel or multitracer diagnostics)
pro update_tracer_datainfo,datainfo,traceroffset
(enter tracer information into global datainfo structure)
REQUIREMENTS:
Several ctm_* routines are used
Also uses UNDEFINE (by D. Fanning)
NOTES:
Please test rigorously. In case of read errors, try using CTM_OPEN_FILE
with the /PRINT keyword.
If your model output (ASCII punch file) does not contain the
dimensional information about each data block, it may cause problems
for diagnostics that do not contain 72x46 elements.
It's defintively a good idea to implement this little change *NOW* !
Outline of this procedure:
- get all data records that match selection criteria
- create "compound" datainfo structures for multilevel and
multitracer diagnostics (those hold 3D data blocks)
- read data for all selected compound structures unless only
status information requested
EXAMPLE:
See CTM_EXAMPLES
MODIFICATION HISTORY:
mgs, 20 Aug 1998: VERSION 1.00
mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
mgs, 22 Sep 1998: - changed to accomodate usage of
tracer information
mgs, 22 Oct 1998: - old FILEINFO and DATAINFO parameters now
keywords USE_..., new DATAINFO parameter
returns selected subset of records.
- print statements replaced with message
- DEBUG messages improved
- catch cancelled file open dialog
mgs, 26 Oct 1998: - datainfo now undefined at start
- allows for multiple categories
- ilun, tracer, tau0 keyword variables renamed
as sel_... in order to preserve them
mgs, 04 Nov 1998: - sel_tracer now expanded to include offsets
mgs, 10 Nov 1998: VERSION 3.0
- major update! Program structure much more
straightforward!
mgs, 12 Nov 1998: - bug fixes for simple diagnostics (line 732)
and finding offset tracers (in update_...)
replaced tracer by (tracer mod 100) in 3 places
mgs, 19 Nov 1998: - bug fix with scale factor. Didn't get globally
updated because it was linked to unit. Need a
more generic global update procedure !
mgs, 03 Dec 1998: - yet another bug fix in reopen files: needed
to test for negative ilun before fstat
bmy, 21 Jan 1999: - added outer parentheses to the FORMAT
descriptor (255(I4,1x)) to avoid errors
mgs, 17 Feb 1999: - bug fix for simple diagnostics: needed
to add dummy value to compound array.
mgs, 16 Mar 1999: - catch error in tracerinfo.dat (more than one
tracer with same number)
- error in update_tracer... should have been
fixed. Some more debug output added for
testing.
mgs, 23 mar 1999: - set vertical dimension to -1 for new compound
datainfo records
mgs, 24 May 1999: - updated filetype info
mgs, 02 Jun 1999: - added retall statement after error
message
bmy, 23 Nov 1999: - added /SMALLCHEM keyword for CTM_TRACERINFO
bmy, 27 Sep 2001: GAMAP VERSION 1.49
- Set F77=1 for filetype 4 (DAO met fields)
- Now reference function LITTLE_ENDIAN
- Swap endian in OPEN_FILE if reading data
on a little-endian machine (e.g. PC)
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- now test valid diagnostics using
DIAGSTRU[*].CATEGORY and not DIAGSTRU[*].INDEX
- removed /SMALLCHEM keyword, it's obsolete
- Now recognizes binary files as having
FILETYPE values between 100 and 200
- Removed /SMALLCHEM flag, it's obsolete
- Now uses diagnostic spacing from CTM_DIAGINFO
and pass this to UPDATE_TRACER_DIAGINFO
bmy, 11 Feb 2004: GAMAP VERSION 2.01a
- Internal routine MAKE_COMPOUND_DATAINFO
now passes SPACING from CTM_DIAGINFO
to routine CTM_DOSELECT_DATA
bmy, 27 Oct 2004: GAMAP VERSION 2.03
- added QUIET keyword to suppress printing
information about retrieved tracers
bmy, 06 Feb 2006: GAMAP VERSION 2.04
- Bug fix: use DIALOG_PICKFILE to get file name
before calling CTM_OPEN_FILE. This is necessary
because the tests for certain file types requires
the file name to be known ahead of time.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now passes _EXTRA keyword to
CTM_OPEN_FILE. This allows to read nested
met (GMAO) files by using /NA or /CHINA
bmy & phs, 20 Nov 2007: GAMAP VERSION 2.11
- If FILENAME is not defined, then the value
of the filename selected via dialog box
will be passed back to the calling program.
KNOWN BUGS OR WEAKNESSES:
- handling of USE_DATAINFO and USE_FILEINFO is not carried
through all lower level subroutines, i.e. they may be replaced
by *pGlobal... in some occasions. Since USE_... should always
be a subset of *pGlobal..., no serious errors are expected
from this weakness.
- known bug in update_tracer_datainfo, see comment in routine.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_get_data.pro)
NAME:
CTM_GET_DATABLOCK
PURPOSE:
Extracts a data block from a CTM punch file.
(Wrapper program for CTM_GET_DATA and CTM_EXTRACT.)
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
SUCCESS = CTM_GET_DATABLOCK(DATA [,DIAGN] [,Keywords])
INPUTS:
DIAGN -> A diagnostic number or category name (see
(CTM_DIAGINFO). This must uniquely identify a
specific data type. DIAGN is passed to CTM_GET_DATA
KEYWORD PARAMETERS:
Keywords that are passed to CTM_GET_DATA:
=========================================
FILENAME -> Name of the file to open. FILENAME is passed
to CTM_GET_DATA. CTM_GET_DATA will return
the full path name, which is then returned
to the calling program.
USE_FILEINFO -> (optional) If provided, CTM_GET_DATA will
restrict its search to only the files that are
contained in USE_FILEINFO which must be a FILEINFO
structure array. Default is to use the global information
(see gamap_cmn.pro).
If an undefined named variable is provided in USE_FILEINFO,
it will either contain the global FILEINFO structure array
or the FILEINFO record of the specified file.
USE_FILEINFO and USE_DATAINFO must be consistent, and should
either both be used or omitted. However, it is
possible to provide the global FILEINFO structure
(or nothing) with a local subset of DATAINFO.
USE_DATAINFO -> (optional) Restrict search to records contained
in USE_DATAINFO which must be a DATAINFO structure array.
If an undefined named variable is provided in USE_DATAINFO,
it will either contain the global DATAINFO structure array
or all DATAINFO records of the specified file.
See also USE_FILEINFO.
Keywords that are passed to CTM_EXTRACT:
========================================
AVERAGE -> Bit flag to average over certain dimensions
(see CTM_EXTRACT)
TOTAL -> Bit flag to sum over certain dimensions
(see CTM_EXTRACT)
/INDEX -> If set, will interpret LAT, LEV, and LON as index
arrays. If not set, will interpret LAT, LEV, and LON as
ranges (i.e. two-element vectors containing min and max values).
LAT -> An index array of latitudes *OR* a two-element vector
specifying the min and max latitudes to be included in
the extracted data block. Default is [ -90, 90 ].
LEV -> An index array of sigma levels *OR* a two-element vector
specifying the min and max sigma levels to be included in
the extracted data block. Default is [ 1, GRIDINFO.LMX ].
LON -> An index array of longitudes *OR* a two-element vector
specifying the min and max longitudes to be included in
the extracted data block. Default is [ -180, 180 ].
ALTRANGE -> A vector specifying the min and max altitude
values to be included in the extracted data block.
PRANGE -> A vector specifying the min and max pressure levels
to be included in the extracted data block.
Other keywords:
===============
XMID, YMID, ZMID -> Arrays of values (e.g. latitude,
longitude, or altitude) for the 1st, 2nd, and 3rd
dimensions of the DATA array, respectively.
NOTE: These are *NOT* index arrays.
THISDATAINFO -> Returns the DATAINFO structure for the
selected data block.
MODELINFO -> Returns to the calling program the model information
structure created by CTM_TYPE.
GRIDINFO -> Returns to the calling program the grid information
structure created by CTM_GRID.
WE -> Returns to the calling program the index array of longitudes
for the extracted data region, ordered from west to east.
SN -> Returns to the calling program the index array of latitudes
for the extracted data region, ordered from South to North
UP -> Returns to the calling program the index array of vertical
levels for the extracted data region, ordered from surface
to top.
PSURF -> Surface pressure to be used for the conversion from
sigma layers to pressure and altitude. For defaults
see function CTM_TYPE.
_EXTRA=e -> Picks up any extra keywords for CTM_GET_DATA
and CTM_EXTRACT.
OUTPUTS:
SUCCESS -> Returns 1 if successful or 0 otherwise.
DATA -> A 2D or 3D data array
SUBROUTINES:
External Subroutines Required:
==============================
CTM_GET_DATA
CTM_GRID (function)
CTM_EXTRACT (function)
REQUIREMENTS:
None
NOTES:
(1) CTM_GET_DATABLOCK returns the extracted data block as the
function value.
(2) CTM_GET_DATABLOCK is meant to be called whenever you need
to extract data from a punch file. If the punch file needs
to be opened, CTM_GET_DATABLOCK will do that automatically
(via CTM_GET_DATA).
EXAMPLE:
FILENAME = '~/amalthea/CTM4/run/ctm.pch'
LAT = [ -90, 90 ]
LON = [ -180, 180 ]
LEV = 1
SUCCESS = CTM_GET_DATABLOCK( DATA, 'IJ-AVG-$', $
XIND=XMID, YIND=YMID, ZIND=ZMID, $
THISDATAINFO=THISDATAINFO, $
TRACER=1, FILENAME=FILENAME, $
GRIDINFO=GRIDINFO, MODELINFO=MODELINFO, $
LEV=LEV, LAT=LAT, $
LON=LON, WE=WE, $
SN=SN, UP=UP )
IF ( NOT SUCCESS ) THEN RETURN, 0
; gets a data block for the IJ-AVG-$ (ND45) diagnostic,
; for the first tracer, at the first timestep, with the
; given latitude, longitude, and sigma level ranges.
; Returns FILEINFO, DATAINFO, THISDATAINFO, WE, SN, UP,
; XMID, YMID, and ZMID to the calling program.
MODIFICATION HISTORY:
bmy, 16 Sep 1998: VERSION 1.00
bmy, 17 Sep 1998: - added FILENAME keyword, so that the file
name can be passed back to the calling
program.
bmy, 18 Sep 1998: VERSION 1.01
- now compatible with CTM_EXTRACT v. 1.01
- INDEX, SN, WE, UP keywords added
- LATRANGE, LONRANGE, LEVRANGE renamed
to LAT, LON, LEV (since they may now
contain arrays and not just ranges).
mgs, 21 Sep 1998: VERSION 1.02
- more error checking
- added PSurf keywords
- frees gridinfo pointer before re-assignment
- removed MinData and MaxData
bmy, 22 Sep 1998: - Now pass AVERAGE and TOTAL keywords to
CTM_EXTRACT
mgs, 22 Sep 1998: - added THISDATAINFO keyword
bmy, 24 Sep 1998: - added FORWARD_FUNCTION for CTM_GRID
and CTM_EXTRACT
bmy, 08 Oct 1998: VERSION 1.03
- FILEINFO and DATAINFO are now keywords
- now returns X, Y, and Z as parameters
bmy, 03 Nov 1998: VERSION 1.04
- compatible with new CTM_GET_DATA routine
- now pass FILEINFO and DATAINFO structures
via USE_FILEINFO and USE_DATAINFO keywords
mgs, 10 Nov 1998: - once more adapted to changes in CTM_GET_DATA
- now extracts locally used FILEINFO structure
bmy, 11 Feb 1999: VERSION 1.05
- updated comments
bmy, 19 Feb 1999: - Renamed XIND, YIND, ZIND to XMID, YMID,
and ZMID, since these are not index
arrays, but the actual longitude,
latitude, or altitude values for each
dimension of the DATA array.
- added DEBUG keyword
- eliminate obsolete XARR, YARR, ZARR keywords
- added NOPRINT keyword to suppress
call to CTM_PRINT_DATAINFO
mgs, 02 Apr 1999: - replace gridinfo in fileinfo only if new
surface pressure is requested. Necessary
for 2D fields (e.g. EPTOMS)
- deactivated SMALLCHEM flag
- added error checking for FILEINFO
bmy, 28 Apr 1999: - return THISFILEINFO as a keyword
mgs, 30 Jun 1999: - Specification of PSURF finally works.
bmy, 13 Dec 1999: - now use CHKSTRU instead of N_ELEMENTS
to diagnose undefined GRIDINFO structure
bmy, 04 Dec 2000: GAMAP VERSION 1.47
- eliminated obsolete code from 12/31/99
bmy, 03 Jun 2001: GAMAP VERSION 1.48
- bug fix: also create GRIDINFO structure
for grids with no vertical layers
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_get_datablock.pro)
NAME:
CTM_LOCATEDIFF
PURPOSE:
Locates data blocks which differ in two binary
punch files or GMAO met field files.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_LOCATEDIFF, FILE1, FILE2 [, Keywords ]
INPUTS:
FILE1 -> Name of the first file to be tested. FILE1 may be
a binary punch file, and ASCII file, or a GMAO met field
file.
FILE2 -> Name of the second file to be tested. FILE2 may be
a binary punch file, and ASCII file, or a GMAO met field
file.
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name to restrict the selection
of data records.
OUTFILENAME -> Name of the output file which will contain
the location of differences found between data blocks
in FILE1 and FILE2. If OUTFILENAME is not specified,
then CTM_LOCATEDIFF will print this information to
the screen.
/HEADERS_ONLY -> Set this switch to just print the category
names and tracer numbers where differences occur instead
of printing all of the data points.
_EXTRA=e -> Picks up any extra keywords for CTM_GET_DATA.
OUTPUTS:
None
SUBROUTINES:
External subroutines required:
==============================
CTM_GET_DATA UNDEFINE
CTM_DIAGINFO
REQUIREMENTS:
References routines from both GAMAP and TOOLS directories.
NOTES:
(1) Both FILE1 and FILE2 must contain the same diagnostic
categories, listed in the same order.
EXAMPLE:
CTM_LOCATEDIFF, 'ctm.bpch.old', 'ctm.bpch.new'
; Locates data blocks which differ between ctm.bpch.old
; and ctm.bpch.new. You can investigate these further
; with routines CTM_PRINTDIFF and CTM_PLOTDIFF.
MODIFICATION HISTORY:
bmy, 24 Feb 2003: VERSION 1.00
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- Now get spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 27 Feb 2004: GAMAP VERSION 2.02
- Rewritten to also print out locations in
FORTRAN notation where differences occur
- added DIAGN keyword to specify category name
- added OUTFILENAME to specify output file
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 01 May 2013: GAMAP VERSION 2.17
- Corrected error in EXAMPLE section above
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_locatediff.pro)
NAME:
CTM_MAKE_DATAINFO (function)
PURPOSE:
Create a datainfo and fileinfo structure from an
"external" data set so that it can be used seamlessly
within the GAMAP package. The dataset can have up to
four dimensions (however, only the first 3 are currently
supported). The new datainfo and fileinfo structures
will be added to the global structure arrays.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, Structures
CALLING SEQUENCE:
RESULT = CTM_MAKE_DATAINFO( DATA, DATAINFO, FILEINFO [,Keywords] )
INPUTS:
DATA -> A 1-D, 2-D, or 3-D data array.
KEYWORD PARAMETERS:
DIAGN -> A diagnostics name (category) or number that describes
the data type. If not given, the user will be prompted.
If DIAGN is a number that is not recognized as valid
diagnostics by CTM_DIAGINFO, the number will be stored
as string value. If DIAGN is a string, it does not have
to be a valid diagnostics category.
DIM -> A 4 element vector with the DATA dimensions as
LON, LAT, LEVEL, TIME. If not given, the dimensions
of DATA will be entered sequentially. Use this keyword
to properly identify e.g. a zonal mean data set as
DIM = [ 0, 46, 20, 0 ] (for the GEOS-1).
The order and magnitude of the dimensions in DIM must
agree with the dimensions of the DATA array
(e.g. if DATA(72,46) then DIM=[46,72,0,0] is not allowed).
FILENAME-> Name of the file which is specified by the
FILEINFO structure. If FILENAME is not specified,
then the default FILENAME = "derived data".
FILETYPE -> A numeric code to identify the file type. If not
specified then the default FILETYPE = -1.
FIRSTBOX -> A 3 element vector containing IFIRST, JFIRST, and
LFIRST, which are the starting indices for the LON,
LAT, and LEVEL dimensions.
FORMAT -> A format string (for ASCII data) or descriptive
string (for binary or self-describing data) that is
saved to the DATAINFO structure. Default is ''.
GRIDINFO -> A gridinfo structure describing the grid set-up
of the data set (see CTM_GRID). If not given,
CTM_MAKE_DATAINFO attempts to use the MODELINFO
structure to construct GRIDINFO.
ILUN -> The file unit number that will be used to identify
FILEINFO and DATAINFO. If not passed, then ILUN will
be negative to denote derived data, and will increment
negatively for each data block, starting at -1.
MODELINFO -> A modelinfo structure containing information
about the model that generated the data (see CTM_TYPE).
If not given, the user is prompted for a selection.
/NO_GLOBAL -> If passed, will prevent the DATAINFO and FILEINFO
structures from being appended to the global GAMAP
common blocks. Useful for saving memory.
/NO_VERTICAL (passed via _EXTRA) -> set this keyword if you only want
to create a 2D gridfinfo structure.
TAU0, TAU1 -> Beginning and end of time interval that is spanned
by DATA (as TAU value). Default is -1 for both.
TOPTITLE -> A user defined string that may describe the data set
in more detail.
TRACER -> A tracer number or name that identifies the chemical
species or physical quantity contained in DATA. If
TRACER is an invalid name, it will be set to -1, and the
string value of TRACER will be used as TRCNAME (see below).
If not given, the user will be prompted.
TRCNAME -> A tracer name. Default is to use the name associated
with that tracer number in CTM_TRACERINFO.
SCALE -> A value that is entered in the SCALE field in DATAINFO.
Default is 1.0.
UNIT -> A unit string. Default is empty.
OUTPUTS:
DATAINFO, FILEINFO -> The datainfo and fileinfo structures
generated from the "external" data array. These are
automatically appended to the global DATAINFO and FILEINFO
structures, unless the /NO_GLOBAL keyword is set.
SUBROUTINES:
External Subroutines Required:
=========================================
CREATE3DHSTRU, CREATE3DFSTRU, TAU2YYMMDD
REQUIREMENTS:
None
NOTES:
In the current version, no error checking is made whether the
DATA dimensions agree with the grid information. This is the
users responsibility.
EXAMPLES:
(1)
DATA = DIST(72,46)
RESULT = CTM_MAKE_DATAINFO( DATA, DATAINFO, FILEINFO )
; Create a 2D array and make a DATAINFO structure.
; The user will be prompted for model type,
; diagnostics and tracer.
(2)
RESULT = CTM_MAKE_DATAINFO( DATA, DATAINFO, FILEINFO, $
MODEL=CTM_TYPE( 'GEOS1' ), DIAGN='IJ-AVG-$', $
TRACER=2, TAU0=NYMD2TAU(940901L), TAU1=NYMD2TAU(940930), $
UNIT='PPBV', DIM=[0,46,20,0], $
TOPTITLE='Zonal mean difference in Ox CLDS/no CLDS')
; Add a zonal mean difference data set (already in DATA)
(3)
HELP, DATAINFO, /STRU
** Structure H3DSTRU, 13 tags, length=72:
ILUN LONG -15
FILEPOS LONG 0
CATEGORY STRING 'ZONE-AVG'
TRACER INT 2
TRACERNAME STRING 'Ox'
TAU0 DOUBLE 84720.000
TAU1 DOUBLE 85416.000
SCALE FLOAT 1.00000
UNIT STRING 'ppbv'
FORMAT STRING ''
STATUS INT 1
DIM INT Array[4]
OFFSET INT Array[3]
DATA POINTER
; Display DATAINFO structure
MODIFICATION HISTORY:
mgs, 09 Oct 1998: VERSION 1.00
mgs, 19 Nov 1998: - bug fix. ILUN now always negative!
- unit now "required" parameter, i.e.
interactively asked for
bmy, 11 Feb 1999: VERSION 1.01
- added OFFSET keyword so that I0, J0, and
L0 offsets can be stored in DATAINFO
- DATAINFO.TAU0 and DATAINFO.TAU1 are now
stored as double precision
- updated comments
mgs, 16 Mar 1999: - cosmetic changes
- OFFSET changed into FIRSTBOX
mgs, 30 Mar 1999: - added _EXTRA keyword for ctm_grid
(use for /NO_VERTICAL)
bmy, 29 Jun 2001: GAMAP VERSION 1.48
- bug fix: now pass CTM_TRACERINFO the
tracer number plus diagnostic offset
bmy, 06 Mar 2002: GAMAP VERSION 1.50
- now take TRACER mod 100L before
adding the diagnostic offset to it
in call to CTM_TRACERINFO
bmy, 26 Nov 2003: GAMAP VERSION 2.01
- added /NO_GLOBAL keyword
- rewrote for clarity; updated comments
- Now get diagnostic spacing from CTM_DIAGINFO
- added ILUN, FILENAME, FILETYPE keywords
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 30 May 2008: GAMAP VERSION 2.12
- Minor fix to restrict FIRSTBOX to 3 elements
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_make_datainfo.pro)
NAME:
CTM_MASS_CHECK
PURPOSE:
Plots the time evolution of % difference of tracer mass and
air mass from a CTM simulation. Used to assess mass
conservation in CTM transport codes.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_MASS_CHECK [, Keywords ]
INPUTS:
FILENAME -> Name of the CTM output file containing air mass
and tracer concentrations. FILENAME can be either an
ASCII punch file or a BINARY punch file. If omitted,
the user will be prompted to supply FILENAME via a
dialog box.
KEYWORD PARAMETERS:
TRACER -> Number of the tracer that you wish to check for
mass conservation.
/PS -> Set this switch to create PostScript plot output.
OUTFILENAME -> If /PS is set, OUTFILENAME will be the name of
the PostScript plot output file. Default is "mass_check.ps".
_EXTRA=e -> Catches extra keywords for routines OPEN_DEVICE
and CLOSE_DEVICE.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
CLOSE_DEVICE CTM_GET_DATA
MULTIPANEL OPEN_DEVICE
UNDEFINE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) Assumes that the tracer concentration has been saved
under the IJ-AVG-$ diagnostic category. Also assumes
that the airmass has been saved under the BXHGHT-$
diagnostic category.
EXAMPLE:
CTM_MASS_CHECK, 'ctm.bpch.geos4', TRACER=4
; Plots the evolution of % difference of both
; tracer and air mass for CO from a GEOS-4 simulation.
MODIFICATION HISTORY:
bdf & bmy, 26 Jun 2003: GAMAP VERSION 2.03
bmy, 06 Mar 2007: GAMAP VERSION 2.06
- make FILENAME an input rather than
a keyword argument.
- now pass _EXTRA=e to the PLOT command
- Added WINPARAM keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_mass_check.pro)
NAME:
CTM_NOYBUDGET
PURPOSE:
Computes the NOy budget within a given 3-D region.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_NOYBUDGET [, BATCHFILE [, Keywords ] ]
INPUTS:
BATCHFILE (optional) -> Name of the batch file which
contains inputs that defines the 3-D region and NOy
constituents. If BATCHFILE is omitted, then the user
will be prompted to supply a file name via a dialog box.
KEYWORD PARAMETERS:
LOGFILENAME (optional) -> Name of the log file where output
will be sent. Default is "noy_budget.log".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
--------------------------------------------------------------
ErrorNOy (function)
TruncateAndWrapForNOy (function)
GetNoxEmissionsForNOy (function)
GetHNO3WetDepForNOy (function)
GetDryDepositionForNOy (function)
GetNetExportForNOy (function)
GetNetChemicalProductionForNOy (function)
ReadBatchFileForNOy (procedure)
External Subroutines:
--------------------------------------------------------------
CTM_Get_Datablock (function) CTM_BoxSize (function)
REQUIREMENTS:
None
NOTES:
(1) CTM_NOYBUDGET was developed for use with the GEOS-CTM,
there might be some adaptation required for use with
other models.
(2) Only 5 "families" are considered:
Dry Deposition, NOx, PAN, HNO3, R4N2.
(3) Wrapping around the date line seems to work but you
should always double-check.
EXAMPLE:
CTM_NOYBUDGET, 'box1.dat', LogFileName='box1.log'
; Computes NOy budgets for the region specified in
; the file "box1.dat" and sends output to the
; "box1.log" log file.
MODIFICATION HISTORY:
bmy, 28 Jan 2000: VERSION 1.00
- adapted original code from Isabelle Bey
bmy, 25 May 2000: VERSION 1.45
- now allow the user to specify diagnostic
category names in the batch file
- added internal function "TruncateAndWrapForNOy"
to wrap arrays around the date line
- added internal procedure "ErrorNOy"
to do error checking for CTM_GET_DATABLOCK
- now can create budgets for more than one
diagnostic interval
- now allow user not to compute chemical
production data for given families
acs, 26 May 2000: - bug fixes: now do not stop the run if
data blocks are not found
bmy, 01 Aug 2000: VERSION 1.46
- use abs( Total( X ) ) > 0 when testing if
transport fluxes are all nonzero
bmy, 24 Jan 2001: GAMAP VERSION 1.47
- now no longer require all types of emissions
to be nonzero in order to sum them
- now no longer require both HNO3 LS and
convective wetdep to be zero in order to
sum them
bmy, 17 Jan 2002: GAMAP VERSION 1.50
- now call STRBREAK wrapper routine from
the TOOLS subdirectory for backwards
compatiblity for string-splitting
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_noybudget.pro)
NAME:
CTM_OXBUDGET
PURPOSE:
Computes the Ox budget within a given 3-D region.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_OXBUDGET [, BATCHFILE [, Keywords ] ]
INPUTS:
BATCHFILE (optional) -> Name of the batch file which
contains inputs that defines the 3-D region and NOy
constituents. If BATCHFILE is omitted, then the user
will be prompted to supply a file name via a dialog box.
KEYWORD PARAMETERS:
LOGFILENAME (optional) -> Name of the log file where output
will be sent. Default is "ox_budget.log".
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
--------------------------------------------------------------
ErrorOx (function)
TruncateAndWrapForOx (function)
GetHNO3WetDepForOx (function)
GetDryDepositionForOx (function)
GetNetChemicalProductionForOx (function)
GetNetExportForOx (function)
ReadBatchFileForOx (procedure)
External Subroutines Required:
--------------------------------------------------------------
CTM_Get_Datablock (function) CTM_BoxSize (function)
REQUIREMENTS:
NOTES:
(1) CTM_OXBUDGET was developed for use with the GEOS-CTM,
there might be some adaptation required for use with
other models.
(2) Only 2 "families" are considered: Dry Deposition and Ox.
(3) Wrapping around the date line seems to work but you
should always double-check.
(4) Currently, the box of consideration must be less than
global size in order to m
EXAMPLE:
CTM_OXBUDGET, 'box1.ox', LogFileName='box1.log'
; Computes Ox budgets for the region specified in
; the file "box1.ox" and sends output to the
; "box1.log" log file.
MODIFICATION HISTORY:
bmy, 28 Jan 2000: VERSION 1.00
- adapted original code from Isabelle Bey
bmy, 25 May 2000: GAMAP VERSION 1.45
- now allow the user to specify diagnostic
category names in the batch file
- added internal function "TruncateAndWrapForOx"
to wrap arrays around the date line
- added internal procedure "ErrorOx"
to do error checking for CTM_GET_DATABLOCK
- now can create budgets for more than one
diagnostic interval
- now allow user not to compute chemical
production data for given families
acs, 26 May 2000: - bug fixes: now do not stop the run if
data blocks are not found.
bmy, 01 Aug 2000: GAMAP VERSION 1.46
- use abs( Total( X ) ) > 0 when testing if
transport fluxes are all nonzero
bmy, 13 Dec 2001: GAMAP VERSION 1.49
- Now do not require all transport fluxes
to be nonzero in order to compute budgets
- now truncate data blocks correctly for
E/W and N/S transport fluxes
- Now compute the total number of seconds
over the entire diagnostic interval
- Now divide fluxes by the number of diagnostic
time intervals in order to get average fluxes
bmy, 17 Jan 2002: GAMAP VERSION 1.50
- now call STRBREAK wrapper routine from
the TOOLS subdirectory for backwards
compatiblity for string-splitting;
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 23 Mar 2008: GAMAP VERSION 2.12
phs, 20 Aug 2008: GAMAP VERSION 2.13
- now 3D region can be as small as one box.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_oxbudget.pro)
NAME:
CTM_PRINTDIFF
PURPOSE:
Prints the sum of the differences between two CTM
output files. This is a quick way of ensuring that
two model versions are producing identical results.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_PRINTDIFF, DIAGN [, Keywords ]
INPUTS:
DIAGN -> A diagnostic number or category to restrict
the record selection (default is: "IJ-AVG-$").
KEYWORD PARAMETERS:
FILE1 -> Name of the first CTM output file (the "old" file).
If FILE1 is not given, or if it contains wildcard
characters (e.g. "*"), then the user will be prompted
to supply a file name via a pickfile dialog box.
FILE2 -> Name of the second CTM output file (the "new" file).
If FILE2 is not given, or if it contains wildcard
characters (e.g. "*"), then the user will be prompted
to supply a file name via a pickfile dialog box.
TRACER -> Number of the tracer for which differences
will be plotted.
_EXTRA=e -> Picks up other keywords for CTM_GET_DATABLOCK.
OUTPUTS:
Prints the quantity:
DIFF[L] = TOTAL( DATA2[*,*,L] - DATA1[*,*,L] )
for each level L. If DIFF[L] = 0 for all levels L, then
FILE1 and FILE2 contain identical data.
SUBROUTINES:
External Subroutines Required:
==============================
CTM_CLEANUP
CTM_GET_DATABLOCK (function)
REQUIREMENTS:
None
NOTES:
(1) If DATA1 corresponds to the "old" data, and DATA2
corresponds to the "new" data, then CTM_DIFF will
compute the following:
Abs. Diff = ( new - old )
(2) CTM_PRINTDIFF calls CTM_CLEANUP each time to remove
previously read datablock info from the GAMAP common
block.
EXAMPLE:
FILE1 = 'ctm.bpch.v4-30' ; the "old" file
FILE2 = 'ctm.bpch.v4-31' ; the "new" file
CTM_PRINTDIFF, 'IJ-AVG-$', $
FILE1=FILE1, FILE2=FILE2, TRACER=1
IDL prints:
Level: 26 Difference: -2.3841858e-07
Level: 25 Difference: 0.0000000e+00
Level: 24 Difference: 0.0000000e+00
Level: 23 Difference: 0.0000000e+00
Level: 22 Difference: -1.4901161e-08
Level: 21 Difference: 0.0000000e+00
Level: 20 Difference: 0.0000000e+00
Level: 19 Difference: 0.0000000e+00
Level: 18 Difference: 0.0000000e+00
Level: 17 Difference: 0.0000000e+00
Level: 16 Difference: 0.0000000e+00
Level: 15 Difference: 0.0000000e+00
Level: 14 Difference: -7.4505806e-09
Level: 13 Difference: 0.0000000e+00
Level: 12 Difference: 0.0000000e+00
Level: 11 Difference: 0.0000000e+00
Level: 10 Difference: 0.0000000e+00
Level: 9 Difference: 0.0000000e+00
Level: 8 Difference: 0.0000000e+00
Level: 7 Difference: 0.0000000e+00
Level: 6 Difference: 0.0000000e+00
Level: 5 Difference: 0.0000000e+00
Level: 4 Difference: 0.0000000e+00
Level: 3 Difference: 0.0000000e+00
Level: 2 Difference: 0.0000000e+00
Level: 1 Difference: 0.0000000e+00
; Prints the sum of differences at each level
; betweeen two GEOS-STRAT binary punch files
; for NOx (tracer=1).
MODIFICATION HISTORY:
bmy, 04 Apr 2002: GAMAP VERSION 1.50
bmy, 22 Apr 2002: - now takes diff of DATA2 - DATA1, in order
to be consistent with CTM_PLOTDIFF.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_printdiff.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_READ_PLANEFLIGHT
PURPOSE:
Reads GEOS-CHEM plane flight diagnostic (ND40) data.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
RESULT = CTM_READ_PLANEFLIGHT( FILENAME )
INPUTS:
FILENAME -> Name of the file containing data from the GEOS-CHEM
plane following diagnostic ND40. If FILENAME is omitted,
then a dialog box will prompt the user to supply a file name.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Array of structures containing data from read from
the input file. Each different plane type will have
a structure in RESULT containing the following tags:
NPOINTS : Number of points read from the file
NVARS : Number of variables read from the file
PLATFORM : Name of plane type (e.g. DC8, P3B, FALCON)
DATE : Array w/ YYYYMMDD at each flight point [GMT date]
TIME : Array w HHMM at each flight point [GMT time]
LAT : Array w/ latitude at each flight point [degrees ]
LON : Array w/ longitude at each flight point [degrees ]
PRESS : Array w/ pressure at each flight point [hPa ]
VARNAMES : Array w/ names of each variable
DATA : Array w/ data for each variable
SUBROUTINES:
External Subroutines Required:
==========================================
OPEN_FILE STRBREAK (function) UNDEFINE
REQUIREMENTS:
None
NOTES:
We read the data into arrays first, and then save the arrays
into an IDL structure. If you read the data into an array of
structures, this executes much more slowly. Also arrays of
structures seem to suck up an inordinate amount of memory.
EXAMPLES:
PLANEINFO = CTM_READ_PLANEFLIGHT( 'plane.log.20040601' )
; Reads data from file into the PLANEINFO structure
DC8 = WHERE( PLANEINFO[*].PLATFORM eq 'DC801' )
; Look for DC8 data
PRINT, PLANEINFO[DC8].LAT[*]
PRINT, PLANEINFO[DC8].LON[*]
; Prints latitudes and longitudes of DC8 to the screen
IND = WHERE( PLANEINFO[DC8].VARNAMES eq 'TRA_004' )
CO = PLANEINFO[DC8].DATA[ *, IND ]
; Extracts CO (tracer #4 in a GEOS-CHEM fullchem
; simulation) to an array
IND = WHERE( PLANEINFO[DC8].VARNAMES eq 'GMAO_UWND' )
UWND = PLANEINFO[DC8].DATA[ *, IND ]
; Extracts U-wind information to an array
MODIFICATION HISTORY:
bmy, 23 Mar 2005: GAMAP VERSION 2.03
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_read_planeflight.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_SUM
PURPOSE:
Calculate the sum of several CTM output data blocks
and store them in a new datainfo structure as "derived
data". The user can select data blocks by diagnostics,
tracer, tau0, or logical unit of the source file. With
the AVERAGE keyword averages will be computed instead of
totals.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_SUM [, DIAGN ] [, Keywords ]
INPUTS:
DIAGN -> The diagnostic category name. Default is 'IJ-AVG-$'
KEYWORD PARAMETERS:
TRACER -> Tracer number(s) to look for.
TAU0 -> beginning of time step to look for. You can
specify a date using function nymd2tau(YYMMDD,HHMMSS)
ILUN -> If you want to restrict summation to datablocks from
one particular file, set the ILUN keyword to the
respective logical unit number. ILUN and FILENAME are
mutually exclusive. If you select FILENAME then ILUN
will be ignored.
FILENAME -> Instead of ILUN you may pass the name of a
CTM data file containing data blocks to be summed.
FILENAME and ILUN are mutually exclusive. If you
select FILENAME then ILUN will be ignored.
NEWTRACER -> Tracer number for the new tracer. Default is
to use the same number as the tracer in the first
selected data block.
NEWTAU0 -> A new pair of values for the time stamp. Default
is to use the minimum tau0 and maximum tau1 from the
selected data blocks. If only one value is passed (tau0),
then tau1 will be set to tau0+1.
/AVERAGE -> set this keyword to compute a (simple) average
instead of the total.
OUTPUTS:
This routne produces no output but stores a new datainfo
and fileinfo structure into the global arrays.
SUBROUTINES:
uses gamap_cmn, ctm_get_data, ctm_grid, and ctm_make_datainfo
REQUIREMENTS:
None
NOTES:
All data blocks must originate from compatible models.
No test can be made whether an identical addition had been
performed earlier. Hence, it is a good idea to test the
existence of the "target" record before in order to avoid
duplicates.
EXAMPLE:
(1)
CTM_GET_DATA, DATAINFO, 'IJ-AVG-$', $
TRACER=1, TAU0=NYMD2TAU( 940301L )
IF (N_ELEMENTS(DATAINFO) EQ 0) THEN $
CTM_SUM, 'IJ-AVG-$', TRACER=[1,2,3,4,5], $
TAU0=NYMD2TAU(940301L), NEWTRACER=1
; Add individual CH3I tracers for 03/01/1994 and
; store them as total CH3I concentration.
; But first: test!
(2)
CTM_SUM,'IJ-AVG-$',$
TRACER=2, FILENAME='ctm.bpch.ox', /AVERAGE
; Compute annual averages from monthly means for Ox
MODIFICATION HISTORY:
mgs, 18 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Added FILENAME keyword as an
alternative to ILUN
- Updated comments, cosmetic changes
phs, 18 Aug 2008: GAMAP VERSION 2.13
- Added experimental keyword DIMAVER to
average along any dimension of the
datablocks.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_sum.pro)
NAME:
CTM_SUM_EMISSIONS
PURPOSE:
Computes totals of emissions in Tg [or Tg C] for the
following diagnostics: ND28, ND29, ND32, ND36, ND46, ND13, etc.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
CTM_SUM_EMISSIONS, DIAGN [, Keywords ]
INPUTS:
DIAGN -> A diagnostic category name to restrict
the record selection (default is "ANTHSRCE").
KEYWORD PARAMETERS:
FILENAME -> Punch file (ASCII or Binary) from which to
read CTM emissions data. If omitted, the user
will be prompted to select a file via a dialog box.
FORMAT -> To overwrite the default format to output the
sum.
TRACER -> The tracer number (or a 1-D array of tracer
numbers) to compute emission totals for.
/CUM_ONLY -> If this switch is set, SUM_EMISSIONS will
only print out cumuluative totals (and skip individual
totals for each data block).
RESULT -> An array of structures (tag names: NAME, SUM, UNIT)
that returns, the name of each tracer, its cumulative
total, and its unit to the calling program.
/NO_SECONDS -> Set this switch if the data to be summed is
independent of seconds (e.g. molec/cm2). CTM_SUM_EMISSIONS
will not multiply the data by the number of seconds in the
interval when converting to Tg.
/KG -> Set this switch if the data to be summed is in kg
instead of molec/cm2 or molec/cm2/s. CTM_SUM_EMISSIONS
will not multiply the data by the surface area of each
grid box when converting to Tg.
/TO_Mg -> Set this switch if you wish to display emissions
totals in Mg instead of Tg.
/TO_Gg -> Set this switch if you wish to display emissions
totals in Gg instead of Tg.
/SHORT -> Use a shorter output format to print totals.
Default is to print out w/ the long output format.
_EXTRA=e -> Picks up any extra keywords for CTM_GET_DATA
or CTM_TRACERINFO.
OUTPUTS:
Prints totals in Tg or Tg C for each tracer to the screen
SUBROUTINES:
Internal Subroutines:
==================================================
CSE_GetUnit (function) CSE_GetAreaCm2 (function)
CSE_GetInfo
External Subroutines Required:
==================================================
CTM_DIAGINFO CTM_TRACERINFO
CTM_GETDATA CTM_BOXSIZE (function)
CTM_GRID (function) GAMAP_CMN
TAU2YYMMDD (function) UNDEFINE
REQUIREMENTS:
None
NOTES:
(1) Most of the time there will be 1 data block per month,
and the cumulative total will be a yearly total.
(2) For NOx, a molecular weight of 14e-3 kg/mole will report
results in Tg N. A molecular weight of 46e-3 will report
results in Tg NOx. This can be changed in the file
"tracerinfo.dat".
(3) Should now be compatible with any model type and grid
resolution. As of 6/19/01, has only been tested using
GEOS-CHEM diagnostic output.
EXAMPLE:
CTM_SUM_EMISSIONS, 'ANTHSRCE', $
FILENAME='ctm.bpch', TRACER=1, $
MODELNAME='GEOS1', RESOLUTION=4
; Will print emission totals for tracer #1 (NOx)
; for the ANTHSRCE (ND36) diagnostic, using data
; in file "ctm.bpch". The data is from a GEOS-1
; simulation on a 4x5 grid.
MODIFICATION HISTORY:
bmy, 26 Apr 2001: GAMAP VERSION 1.47
bmy, 08 Jun 2001: - now uses correct tracer name, unit,
and molecular weight for CO--SRCE
bmy, 19 Jun 2001: GAMAP VERSION 1.48
- added internal function CSE_GETUNIT
to return the proper unit string
("Tg N", "Tg C", or "Tg").
- added internal function CSE_GETAREACM2
which gets the proper surface area
for each data block
- removed MODELNAME, RESOLUTION keywords
bmy, 03 Jul 2001: - now can sum emissions from GENERIC grids
bmy, 16 Aug 2001: - added /NO_SECONDS and /KG keywords
bmy, 26 Sep 2001: GAMAP VERSION 1.49
- set XNUMOL = 1d-3 if /KG is set; this
will convert from g/cm2 to Tg correctly
bmy, 21 Nov 2001: - added internal routine CSE_GETINFO
- now call CTM_EXTRACT to restrict the
totaling to any arbitrary lat/lon rectangle
bmy, 10 Jan 2002: GAMAP VERSION 1.50
- Bug fix: Don't call CTM_EXTRACT if /KG is,
set, since AREACM2 will be 1 in that case
bmy, 31 Jan 2002: - change output format from f10.4 to f12.4
bmy, 10 Jun 2002: GAMAP VERSION 1.51
- added "kludge" for biomass burning files
if /NO_SECONDS is set; will use proper
mol wts & units for ACET, C3H8, C2H6
bmy, 14 Jan 2003: GAMAP VERSION 1.52
- added another quick fix to get the unit strings
correct for sulfate and nitrogen tracers for ND13
bmy, 19 Sep 2003: GAMAP VERSION 1.53
- now call PTR_FREE to free the pointer memory
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- now get the spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 26 Mar 2004: GAMAP VERSION 2.02
- added FORMAT keyword
bmy, 03 Dec 2004: GAMAP VERSION 2.03
- now pass /QUIET to CTM_GET DATA which
reduces a lot of printing to the screen
bmy, 15 Mar 2005: - Added /TO_Gg and TO_Mg keywords, which
will print totals in either Gg or Mg
instead of the default unit of Tg
- Now pass _EXTRA=e to CTM_GET_DATA so that
we can restrict to a given time
bmy, 07 Apr 2006: GAMAP VERSION 2.05
- Added /SHORT keyword
bmy, 29 Sep 2006: - Bug fix: now test for molec wt in kg/mole
in internal function CSE_GETUNIT
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 20 Mar 2008: GAMAP VERSION 2.12
- updated to work with nested grid
mps, 23 Jan 2014: - Added case for NO to CSE_GetUnit for output from
GEOS-Chem v9-02 and higher versions
- Now report NO emissions in Tg N
- Now print unit 'Tg C' for BC/OC tracers
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_sum_emissions.pro)
NAME:
CTM_TRACERINFO
PURPOSE:
Return information about one or all tracers for a given
GEOS-Chem, GISS, or other CTM diagnostic.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, Structures
CALLING SEQUENCE:
CTM_TRACERINFO, TRACERN, TRACERSTRU [, Keywords ]
INPUTS:
TRACERN -> Tracer number or name for which to extract the
information. If TRACERN is numeric, it is interpreted as
an index to the FULLCHEM or SMALLCHEM tracernumber
in the global model. If it is a string, it will be compared
to NAME then FULLNAME. TRACERN may contain more than one
element. To retrieve information about all tracers, use the
/ALL_TRACERS keyword.
KEYWORD PARAMETERS:
/ALL_TRACERS -> Retrieve information about all tracers
FILENAME --> Name of the tracerinfo file (default tracerinfo.dat)
The file will be searched in the current directory first, then
in the directory where ctm_tracerinfo.pro is located. If not found
in either location, a standard data block is retrieved from this
file.
/FORCE_READING -> Overwrite the contents of the common block
FULLNAME -> Returns the (long) name of the requested tracer(s)
INDEX -> Returns the CTM index of the requested tracer(s)
MOLC -> Returns the carbon number of the requested tracer(s)
(For hydrocarbons, this is the # moles C/mole tracer)
MOLWT -> Returns the molecular weight (kg/mole) of the
requested tracer(s)
NAME -> Returns the (short) name of the requested tracer(s)
SCALE -> Standard scale factor for tracer
UNIT -> Returns the standard unit of the requested tracer(s)
(i.e. unit as supplied by CTM with standard scale factor
applied (e.g. ppbv instead of V/V))
IS_EDGED -> Returns whether the given tracer is defined on
level edges (IS_EDGED=1) or level centers (IS_EDGED=0).
OUTPUTS:
TRACERSTRU -> returns a structure or structure array with the
following tags:
NAME : short name for tracer as used in the model
FULLNAME : long name for tracer (may be used in titles)
MWT : molec. weight as kg N or kg C
INDEX : tracer number
MOLC : carbon number for NMHC
SCALE : standard scale factor
UNIT : standard unit for tracer with scale factor applied
IS_EDGED : Is tracer defined on level edges?
SUBROUTINES:
External Subroutines Required:
================================================
FILE_EXIST (function) ROUTINE_NAME (function)
OPEN_FILE
REQUIREMENTS:
None
NOTES:
At first call, the tracer information structure array is
either read from file or retrieved from the
DATA block at the end of this program. Thereafter, the information
is stored in a common block where it is accessible in subsequent
calls.
The newer tags MOLC, SCALE and UNIT are optional and defaulted
to 1.0, 1.0, and 'UNDEFINED', resp.
EXAMPLE:
CTM_TRACERINFO, 2, RES
PRINT, RES.NAME, RES.MWT, RES.INDEX
; prints Ox 0.0480000 2
CTM_TRACERINFO,'OX',RES
PRINT, RES.NAME, RES.MWT, RES.INDEX
; prints identical results
CTM_TRACERINFO,[1,3,5],NAME=NAME,MOLWT=MWT,MOLC=MOLC,/FORCE_READING
PRINT, NAME, MWT, MOLC
; reads tracerinfo.dat file and prints
; NOx PAN ALK4
; 0.0140000 0.121000 0.0120000
; 1.00000 1.00000 4.00000
MODIFICATION HISTORY:
mgs, 22 Apr 1998: VERSION 1.00
mgs, 24 Apr 1998: - added NAME keyword
bmy, 07 May 1998: - added MOLC structure field to store
carbon number for NMHC
mgs, 07 May 1998: VERSION 2.00
- substantially revised
mgs, 08 May 1998: - added SCALE and UNIT tags, made them optional
mgs, 28 May 1998: - bug fix with on_ioerror
mgs, 09 Oct 1998: - bug fix for tracern=0, changed CALLING SEQ. entry
mgs, 12 Nov 1998: - unit string now defaulted to 'UNDEFINED'
bmy, 03 Jan 2001: GAMAP VERSION 1.47
- skip tracer lines beginning with '#' character
bmy, 17 Nov 2003: GAMAP VERSION 2.01
- Removed FULLI, SMALLI, they're obsolete
- now use INDEX for tracer number
- Now use new file format for "tracerinfo.dat"
which allows for 8-digit offset numbers
- No longer read defaults from internal datablock
- Updated comments
bmy, 06 Apr 2004: GAMAP VERSION 2.02
- added /VERBOSE keyword
bmy, 09 Mar 2006: GAMAP VERSION 2.05
- Use "./tracerinfo.dat" as default in
order to facilitate reading in IDL 5.5-
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Add IS_EDGED tag to TRACERINFO structure
to denote whether the tracer is defined
on level centers or level edges
- Implement temporary fix: call GET_IS_EDGED
to determine if a tracer is defined on
level edges. There is probably a better way
to do this, work on that later.
- Now use FILE_WHICH to locate the
"tracerinfo.dat" file.
phs, 30 Jun 2008: GAMAP VERSION 2.12
- bug fix to account for FILENAME
phs, 22 Sep 2009: GAMAP VERSION 2.13
- added test on found/not found tracers
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_tracerinfo.pro)
NAME:
EXAMPLES_MANIP_4D
PURPOSE:
Shows how to manipulate TS data saved as 4D array with
GC_COMBINE_ND49 or GC_COMBINE_ND48.
The routine loops over all available 4D data blocks and print
information for each of them.
CATEGORY:
GAMAP Data Manipulation, GAMAP Examples, Time Series
CALLING SEQUENCE
EXAMPLES_MANIP_4D, File [ , Keywords ]
INPUTS:
FILE -> The name of the file created by GC_COMBINE_ND48/9.
OUTPUT KEYWORD PARAMETERS:
#### ONLY THE LAST DATA SET IF MORE THAN ONE IS AVAILABLE ####
DATA -> Output keyword. Set to a variable name that will
contain the data set on exist.
LON -> Output keyword. Set to a variable name that will
contain the vector of LONGITUDES on exit.
LAT -> Output keyword. Set to a variable name that will
contain the vector of LATITUDES on exit.
TIME -> Output keyword. Set to a variable name that will
contain the vector of TIME STEP on exit. Format is
YYYYMMDD if daily max is asked for (see DMAX keyword),
TAU value else.
LOCALTIME -> to get the output TIME in LOCALTIME. If there
is more than one longitude in the data block, TIME
becomes an array : one vector for each longitude.
KEYWORD PARAMETERS:
MAVG -> The window size (boxcar) of the moving average, if
you want to apply one.
DMAX -> Return daily maximum of the TS.
VERBOSE -> to print some basic information about the data
set.
_EXTRA=e -> Picks up extra keywords for routines
OUTPUTS:
With optional keyword.
SUBROUTINES:
REQUIREMENTS:
References many routines from GAMAP package. Requires GAMAP
v2.10 for handling 4D dataset.
NOTES:
EXAMPLES:
file = dialog_pickfile()
EXAMPLES_MANIP_4D, file, /v, data=ts, lat=lat, lon=lon, time=time
PLOT, time-time[0], ts[0,0,0,*], title='Time series at lon='+ $
strtrim(lon[0],2)+' / lat='+strtrim(lat[0],2)
MODIFICATION HISTORY:
phs, 6 Jun 2007: GAMAP VERSION 2.10
- Initial version
(See /n/home09/ryantosca/IDL/gamap2/examples/examples_manip_4d.pro)
NAME:
FIND_TRACER_INDEX
PURPOSE:
Given the diagnostic category and tracer name, returns the
tracer number as specified in the "tracerinfo.dat" file.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
RESULT = FIND_TRACER_INDEX( DIAGN, NAME )
INPUTS:
DIAGN -> Diagnostic category name as specified in the
"diaginfo.dat" file (e.g. "IJ-AVG-$", "GMAO-2D", etc.).
NAME -> Tracer name as specified in the "tracerinfo.dat"
file (e.g. NOx, Ox, CO, PS, TAUCLI, etc.)
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Tracer number corresponding to NAME and DIAGN.
SUBROUTINES:
External subroutines required:
------------------------------
CTM_DIAGINFO CTM_TRACERINFO
REQUIREMENTS:
Requires routines from the GAMAP package.
NOTES:
Here, "tracer" is used in the wider sense. It can be can be
any quantity saved out from a CTM diagnostic output, as long
as it is specified by "diaginfo.dat" and "tracerinfo.dat".
EXAMPLE:
PRINT, FIND_TRACER_INDEX( 'GMAO-2D', 'PS' )
IDL prints 5931
; Returns the tracer index number for the "PS"
; quantity in the "GMAO-2D" diagnostic category.
MODIFICATION HISTORY:
bmy, 06 Aug 2010: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/find_tracer_index.pro)
NAME:
GC_COMBINE_ND48
PURPOSE:
Combine timeseries data from the Geos-CHEM ND48
diagnostics contained in one or more binary punch files.
The goal is to combine, for one station, all the data blocks
(there is one per time step) into one single 4-D data block
(we want the time to be the 4th dimension). This is basically
to take advantage of support for 4D dataset in GAMAP v2-10.
GEOS-Chem ND48 (as in v7-04-12) outputs one file for all
stations and all time steps. GC_COMBINE_ND48 will write one
file but each timeseries will be in one data block instead of
as many as the number of timesteps. This will make reading
the timeseries with CTM_GET_DATA a lot faster.
Two basic signal processing before saving the data can be
applied: moving average and/or daily maximum.
LIMITATION: daily maximum will not make sense if series do
not cover full days.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, Time Series
CALLING SEQUENCE:
GC_COMBINE_ND48 [, Keywords ]
OPTIONAL INPUTS:
By defaults all stations are processed. And one output file
is created that contains all the stations timeseries.
KEYWORD PARAMETERS:
;============ For I/O files/directory =====================
INFILE -> one or more station file(s) from ND48
diagnostic. If more than one file is processed, it is
assumed that, once sorted in alphabetical order, they
are in chronological order (this is automatically the
case, if you insert YYYYMMDD into ND48 filenames in
input.geos).
INDIR -> Directory where to look for "stations" files. Can be
either input or output keyword:
Input: when defined, ALL files satisfying the MASK
keyword in the directory will be selected.
Ouput: set to a variable name that will contains the DIR
of the selected files.
It is ignored (both input and output roles) if INFILE is
provided.
If neither INFILE nor INDIR is set, then a dialog window
that allows multiple files selection (keep CTRL or SHIFT
key down) will pop-up.
MASK -> Pattern Mask to find files in INDIR. Default is
"stations*".
OUTFILENAME -> Name of the file that will contain the
new timeseries. Default is 'combined'+INFILE[0], in the
same directory as stations file. If the full path is not
included, the file is created in the working directory.
The routine prevents from overwriting any input file.
;================= Data Selection ======================
STATIONNB -> Station(s) number. Can be one or more elements
(up to the number of stations in ND48). Use to select a
subset of the stations instead of all of them.
TIME -> vector for selecting time span. The data covering
[min(TIME),max(TIME)] are selected. If only one
element, then the closest-in-time data is selected.
If min and/or max of TIME is outside the range of
available time steps, the first or last available time
step is used.
Note 1: this is also an output keyword. Then, if passed
by reference, TIME becomes the time vector in
output. See example (6).
Note 2: if using DMAX or DAVG, then TIME should be long
integer (YYYYMMDD), if not it should be Tau format.
;================= Signal Processing ======================
MAVG -> to apply a running average filter to the series. MAVG
value will define the boxcar size and must be GE
3. Even numbers are increased by +1. The IDL SMOOTH
routine is called and accept _extra keywords (NAN,
EDGE_TRUNCATE, and MISSING).
DMAX -> to select the daily maxima of the time series. If
both MAVG and Dmax are set, the moving average is
performed first and you get the daily max of the moving
average. (Local time is not accounted for: days start
and end at 0 UT everywhere).
DAVG -> to select the daily average of the time series. If
both MAVG and DAVG are set, the moving average is
performed first and you get the daily average of the
moving average. (Local time is not accounted for: days
start and end at 0 UT everywhere).
;================= Output keywords ========================
All the following keywords will apply to only ONE
station. The last one is used if none or more than one is
requested.
DATA -> set to a variable name that will hold the selected
timeseries data on exit. This is a 4D array
(1,1,lev,time) even though only one station is
selected.
LON -> set to a variable name that will hold the
longitude of the data set on exit.
LAT -> set to a variable name that will hold the
latitude of the data set on exit.
LEV -> set to a variable name that will hold the vector
of levels for the data set on exit.
TIME -> set to a variable name that will hold the time
vector for the station on exit. Given as Tau values,
unless DMAX or DAVG is set, then as YYYYMMDD.
LOCALTIME -> if set, the TIME vector is in local time
instead of UT. Has no effect if /DMAX or /DAVG.
;================= Others ========================
NOSAVE -> set to not save output into a BPCH file. Useful if
you just want to check results with output keywords.
VERBOSE -> Set to print informational message about the time
series. particularly useful to double check
area/location selected with subset keywords.
_EXTRA=e -> Picks up extra keywords for SMOOTH and
DIALOG_PICKFILE.
OUTPUTS:
See output keywords above.
SUBROUTINES:
REQUIREMENTS:
References many routines from GAMAP package. Requires GAMAP
v2.10 for handling 4D dataset.
NOTES:
If memory issues show up, try to save one timeseries (i.e.,
one station at a time).
EXAMPLES:
;; (1) Read multiple timeseries files selected w/ a pop-up
window (use SHIFT key for muliple selections). Save with the
default filename in the default directory:
GC_COMBINE_ND48
;; (2) Like example (1), but saves only the daily max of the
;; 9-hours average timeseries:
GC_COMBINE_ND48, /dmax, mavg=8
;; (3) read ALL stations files from directory '~/path/'
;; without a pop-up window (no interactivity, good for batch
;; processing). Default MASk and outfile name are used.
GC_COMBINE_ND48, indir='~/path/'
;; (4) Like example (3) but select only the first available
;; station, and save the result in a specified file:
GC_COMBINE_ND48, Station=1, indir='~/path/', outfile='~/path/series1.bpch'
;; (5) read files from directory '~/path/', and select 3rd station.
;; Do not save combined timeseries. Get outputs in variables
;; data, lon, lat and time.
GC_COMBINE_ND48, indir='~/path/', station=3, data=data, lon=lon, lat=lat, time=time
Help, reform(data)
PLOT, time, data[0,0,0,*], title='Lon= strtrim(lon,2)+'- Lat='+strtrim(lat,2)
;; (6) Like (5), but limit the time to 23rd-28th of July
;; 2001. Not the use of two commands to get the output
;; time vector.
time = [nymd2tau(20010723L,20010728l)]
GC_COMBINE_ND48, indir='~/path/', station=3, data=data, lon=lon, lat=lat, time=time
HELP, time
MODIFICATION HISTORY:
phs, 31 Jul 2007: GAMAP VERSION 2.10
- Initial version
phs, 11 Oct 2007: - few bugs fix
- added output keywords
phs, 15 Oct 2007: - added LOCALTIME keyword
phs, 18 Oct 2007: - do not save if output file is one of the
input file.
phs, 26 Oct 2007: - TIME can be use to select the time span
of the series.
Added DAVG keyword.
phs, 30 Oct 2007: - couple of minor fixes.
phs, 11 Aug 2009: - major fix: bug fix when same tracer
in several stations
bmy, 12 Mar 2009: GAMAP VERSION 2.14
- Typo at line 429 fixed
(See /n/home09/ryantosca/IDL/gamap2/timeseries/gc_combine_nd48.pro)
NAME:
GC_COMBINE_ND49
PURPOSE:
Combine timeseries data from several bpch files into 4D
data. Typically used with Geos-CHEM ND49 timeseries output
and met fields in bpch files (a3, a6, i6).
For met fields, see example (9) and (10).
Each ND49 and Met Fields file has data for one day. But,
files with time series that do no cover a day per file, can
also be processed. See example (11), but keep in mind that
the daily max or average options are then **** MEANINGLESS
****, and should not be used.
WHAT IS DONE:
(1) We combine all the data blocks for one tracer (there is
one per time step) into one single 4-D data block (with time
in 4th dimension). This takes advantage of support for 4D
dataset introduced in GAMAP v2-10.
(2) The combined series can be saved into a binary punch
file. You end up with one file per tracer that covers many
days of output, instead of one file per day for all
tracers. The space saving can be more than 60%.
(3) A subarea (even a single location) can be extracted. But
for multiple but not contiguous locations, call the routine
as many time as needed.
(4) Shorter timeseries can be selected/saved, by specifying
Tau range, or day (as YYYYMMDD long integer) range if daily
max or average is selected.
(5) Two basic signal processing before saving the data can be
performed: moving average and/or daily
maximum/minimum/average.
## LIMITATION ## : full days considered for ND49, ie,
GEOS-Chem runs should start and end at midnight (YYYYMMDD
000000 in input.geos)
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, Time Series
CALLING SEQUENCE:
GC_COMBINE_ND49 [, TRACER ][, CATEGORY ][, Keywords ]
INPUTS:
TRACER -> The tracer number. Default is 1.
CATEGORY -> The category name (default is "IJ-AVG-$")
for which to read data.
KEYWORD PARAMETERS:
;============ For I/O files/directory =====================
FILELIST -> list of files to process. Usually used as output
keyword to get the list of files selected with INDIR and
MASK or through a dialog window.
Can be used as input. Then INDIR and MASK are ignored.
INDIR -> Directory where to look for MASK files. If
provided, ALL files satisfying the MASK keyword in the
directory will be selected. If not provided, a dialog
window that allows multiple files selection (keep SHIFT
key down) will pop-up. See EXAMPLES below for tips.
If set to an undefined variable name, it will hold the
directory of the selected files (output keyword).
NOTE: If more than one file is processed, it is assumed
that, once sorted in alphabetical order, they are in
chronological order (this is the case with GEOS-Chem
default naming of ND49 output files: they contain
YYYYMMDD).
MASK -> Pattern Mask to find files in INDIR. Default is
"ts*.bpch".
OUTDIR -> Output directory where to save the file with the
new timeseries data set will be. Default is INDIR. If
the user has not write permission in INDIR, writintg is
cancelled.
OUTFILENAME -> Name of the file that will contain the
timeseries. Default is 'combts_%TRACERNAME%.bpch', for
COMB ined T ime S eries.
The routine prevents from overwriting any input file.
;============ To extract subset of data ===================
LON -> A one or two-elements vector specifying the longitude
of one location or one area. If LON is outside the ND49
area, the program print a warning, and uses border
value.
LAT -> same as LON, but for Latitudes
LEV -> same as LON, but for Levels. Refers to the model grid.
; - - you can also select indices into the requested 3D cube:
LLEV -> A one or two-element vector specifying the min and
max of available levels to be included in the file.
Default is ALL available levels.
Default FORTRAN indexing is used: LLEV #1 is the first
level ***requested*** in ND49. See LEV above otherwise.
ILON, JLAT -> same as LLEV but for Longitude and Latitude
indices. Starting at 1 at the first ***requested***
grid box in ND49.
TIME -> vector for selecting time span. The data covering
[min(TIME),max(TIME)] are selected. If only one
element, then the closest-in-time data are selected.
TIME must be given as Tau (double) or YYYYMMDD (long)
if /DMAX or /DAVG.
If both DMAX (or DAVG) and LOCALTIME are set, TIME is
ignored.
** TIP ** if you select a short time span, it may be
useful to limit the number of files to process
by redefining MASK or using FILELIST. That will
speed up the process.
;================= Signal Processing ======================
MAVG -> to apply a running average filter to the series. MAVG
value will define the boxcar size and must be GE
3. Even numbers are increased by +1. The IDL SMOOTH
routine is called and accept _extra keywords (NaN,
Edge_truncate, missing).
DMAX -> to select the daily maxima of the time series. If
both MAVG and Dmax are set, the moving average is
performed first and you get the daily max of the moving
average.
DAVG -> to select the daily average of the time series. If
both MAVG and DAVG are set, the moving average is
performed first and you get the daily average of the
moving average.
LOCALTIME -> to get DAVG or DMAX computed over local days
instead of UT days. See details below.
;================= Output keywords ========================
DATA -> set to a variable name that will hold the selected
timeseries data on exit. This is a 4D array
(nLon, nLat, nLevel, ntime) even if only one location is
selected.
OUTLON -> set to a variable name that will hold the vector
of longitudes of the data set on exit.
OUTLAT -> set to a variable name that will hold the vector
of latitudes of the data set on exit.
OUTLEV -> set to a variable name that will hold the vector
of Levels of the data set on exit.
OUTALT -> set to a variable name that will hold the vector
of altitudes for the data set on exit.
OUTTIME -> set to a variable name that will hold the time
vector corresponding to the data set on exit. Format
is Tau, or YYYYMMDD if /DMAX.
LOCALTIME -> if set, OUTTIME becomes a Nb_OutLon X Nb_TimeStep
array, with each vector OUTTIME[i,*] holding the time
vector in local time instead of UT. That vector will
apply to all j and k for DATA[i,j,k,*].
Specific case of... both DMAX (or DAVG) and LOCALTIME
being set. The daily max (average) is obtained after
shifting the timeseries, so they start at 00 LT
everywhere (or the first available time step just before
00 LT). The first max (average) value is for the first
complete local day of the series. The OUTTIME array is
then a [numbers of complete days, 2] array that gives
the local YYYYMMDD for both positive and negative
longitudes.
See also note about TAU0/TAU1 below.
Note that the time step of the series must be small
enough for the DMAX/DAVG w/r/t Local Time to be
reliable.
;================= Others ========================
NOSAVE -> set to not save output into a BPCH file. Useful if
you just want to check results with output keywords.
VERBOSE -> Set to print informational message about the time
series. Particularly useful to double check the
area/location selected with subset keywords.
_EXTRA=e -> Picks up extra keywords for SMOOTH and
DIALOG_PICKFILE.
OUTPUTS:
See output keywords above.
SUBROUTINES:
REQUIREMENTS:
References many routines from GAMAP package. Requires GAMAP
v2.10 for saving 4D dataset into binary punch file.
NOTES:
######## ND49 and Met Fields only. For ND48, see ########
######## GC_COMBINE_ND48 (not as well maintained) ########
Written with batch processing in mind. It is recommended to
save all ND49 outputs into one dedicated directory, and to
use keywords (INDIR, OUTDIR, OUTFILE..) and save the new
combined timeseries in a new directory.
About TAU0 and TAU1 : in the DataInfo structure, they are set
to the beginning and end of the timeseries. For daily data,
we compute them by setting HH:MM:SS to 00:00:00. If LocalTime
is set, UT is still used for TAU0 and TAU1, so we can use
only one value. If both LocalTime and DMAX are set, tau0 and
tau1 give the first and last (local) days for longitudes less
than 0 (west). For East longitudes, you need to add one day
to these to get the correct date.
EXAMPLES:
;; In the following examples, it is assumed that tracer 1
;; has been saved with ND49
;; (1) Read multiple timeseries files selected w/ a pop-up
window (use SHIFT key for muliple selections). Saved series
at ALL available locations into default directory and filename:
GC_COMBINE_ND49
exactly the same as:
GC_COMBINE_ND49, 1, 'IJ-AVG-$'
;; (2) Like example (1), but saves only the daily max of the
;; 9-hours average timeseries:
GC_COMBINE_ND49, 1, 'IJ-AVG-$', /dmax, mavg=8
;; (3) Like example (1), but do not save the timeseries. Get
;; the timeseries in the variable TS in output:
GC_COMBINE_ND49, 1, 'IJ-AVG-$', /nosave, data=TS
;; (4) read **ALL** MASK-files from directory '~/path/'
;; without a pop-up window (no interactivity, good for batch
;; processing):
GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='series1.dat'
;; (5) Like example (4), but with selection of ONE station:
GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='station1.bpch',$
lon=-65., lat=45., lev=1
;; (6) Like example (5), but with shorter time series (from
;; 2001/7/20 20:00 to 2001/7/23 2:00):
GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='station1.bpch',$
lon=-65., lat=45., lev=1, $
Time=[nymd2tau(20010720l,200000l),nymd2tau(20010723l,20000l)]
;; (7) Like example (6), but select Daily Max and for few
;; days only (from 23rd to 28th of July 2001):
GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='station1.bpch',$
lon=-65., lat=45., lev=1, /DMax,
Time=[20010723L,20010728L]
;; (8) read **ALL** MASK-files from a directory selected with
;; a pop-up window:
GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir=dialog_pickfile(/dir)
;; (9) read CLOUD FRACTION from GEOS-4 met fields. Interactive way.
GC_COMBINE_ND49, nosave=1, data=ts, $
mask='/as/data/master/ctm/GEOS_4x5.d/GEOS_4_v4/1985/02/*a6*', $
7, 'GMAO-2d', outtime=time
;; (10) read CLOUD FRACTION from GEOS-4 met fields. All data
from February 1985 automatically:
GC_COMBINE_ND49, nosave=1, data=ts, $
indir='/as/data/master/ctm/GEOS_4x5.d/GEOS_4_v4/1985/02/', $
mask='*a6*', $
7, 'GMAO-2d', outtime=time
;; (11) Read 3 series of 2004 GFED2 emissions (3hr, 8-day and
monthly):
; -- get data from MASK and DIRECTORY
dir3hr = '/as/data/geos/GEOS_1x1/GFED2_3hr_200901/2004/'
dirMon = '/as/data/geos/GEOS_1x1/GFED2_200601/2004/'
dir8day = '/as/data/geos/GEOS_1x1/GFED2_8day_200712/2004/'
mask3hr = 'GFED2.3hr.C_20040*.generic.1x1'
maskMon = 'GFED2_C_2004*.generic.1x1'
mask8day = 'GFED2_8day_C_2004*.generic.1x1'
gc_combine_nd49, 99, 'GFED2-BB', /nosave, data=d3hr, $
mask=mask3hr, indir=dir3hr, outTime=tau3hr, /verb
gc_combine_nd49, 99, 'GFED2-BB', /nosave, data=d8day, $
mask=mask8day, indir=dir8day, outTime=tau8day, /verb
gc_combine_nd49, 99, 'GFED2-BB', /nosave, data=dMon, $
mask=maskMon, indir=dirMon, outTime=tauMon, /verb
;-- Julian Time for each data set (the half time step is added to
; get the time series centered on their period, since we plot
; histograms, with psym=10)
temp = tau2yymmdd( tau3hr + 1.5 )
Jul3hr = JulDay(temp.month, temp.day, temp.year, temp.hour, temp.minute)
temp = tau2yymmdd( tau8day + (4.*24.) )
Jul8day = JulDay(temp.month, temp.day, temp.year, temp.hour, temp.minute)
temp = tau2yymmdd(tauMon + 15.*24.)
JulMon = JulDay(temp.month, temp.day, temp.year, temp.hour, temp.minute)
; -- convert from [g C/m2/time-period] to [Tg C/time-period]
GridInfo = CTM_GRID( CTM_TYPE( 'generic', res=[1., 1.] ) )
Surface = CTM_BOXSIZE( GridInfo, /cm2 )
dim = size(surface, /dimensions)
d3hr = d3hr * rebin( Surface, dim[0], dim[1], 1, (size(d3hr))[4] )
d8day = d8day * rebin( Surface, dim[0], dim[1], 1, (size(d8day))[4] )
dMon = dMon * rebin( Surface, dim[0], dim[1], 1, (size(dMon))[4] )
d3hr = d3hr * 1e-9
d8day = d8day * 1e-9
dMon = dMon * 1e-9
; -- Sum data over space, and convert to [ Tg C/s ]
sum3hr = total( total( total(d3hr, 1), 1), 1) / (3. * 3600.)
sum8day = total( total( total(d8day, 1), 1), 1) / (8. *24. * 3600.)
; -- Plot time series
dummy = label_date( date_format=['%D', '%M'] )
plot, Jul3hr, sum3hr, /ynozero, color=!myct.black, $
title='Total GFED2 emissions in 2004 (Tg C/sec)', $
/xstyle, $
xtickformat=['label_date', 'label_date', 'label_date'], $
xtickunit=['day', 'month'], $
position=[0.1, 0.15, 0.9, 0.9], $
psym=10
oplot, Jul8day, sum8day, thick=2., color=!myct.black, psym=10
MODIFICATION HISTORY:
phs, 6 Jun 2007: GAMAP VERSION 2.05
- Initial version
phs, 25 Jul 2007: GAMAP VERSION 2.10
- added Moving Average and Daily Max as
signal processing available before
saving/passing data.
- added Lon and Lat keywords to select one
location or a smaller area.
- added output keywords.
phs, 4 Oct 2007: - Bug fix for OUTTIME keyword
phs, 12 Oct 2007: - Added OUTLEV output keyword, and LEV
input keyword.
- INDIR can be used as output keyword.
phs, 15 Oct 2007: - added LOCALTIME keyword
phs, 18 Oct 2007: - do not save if output file is one of the
input file.
phs, 26 Oct 2007: - bug fix for LON and LAT
- added TIME keyword to limit
timeseries in time.
phs, 28 Oct 2007: - DMAX accounts for LOCALTIME if set.
- Bug fix for OutTime when /DMax.
phs, 04 Apr 2008: GAMAP VERSION 2.12
- added DAVG keyword
- now cleanup the /no_global pointers
- added the FILELIST keyword
phs, 17 Jul 2008: - Added comments
phs, 15 Aug 2008: GAMAP VERSION 2.13
- Bug fix for OutTime when /DMax or /DMean
and input are from at least two different
months
mb & phs, 02 Dec 2008: - DIM is forced to 32-bit integer (LONG)
phs, 08 Jan 2009: - Now can process files that cover time
periods different from one day.
bmy, 14 Apr 2010: GAMAP VERSION 2.14
- Add _EXTRA=e to CTM_GET_DATA so as to pass
down any flags for nested grids
(See /n/home09/ryantosca/IDL/gamap2/timeseries/gc_combine_nd49.pro)
NAME:
GET_IS_EDGED (function)
PURPOSE:
Determine if a GEOS-5 data field is defined on the
vertical grid box edges or centers.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
RESULT = GET_IS_EDGED( NAME )
INPUTS:
NAME -> Name of the tracer or met field to be tested.
KEYWORD PARAMETERS:
OUTPUTS:
RESULT -> Returns 1 if the tracer or met field specified by
NAME is defined on grid box vertical edges, or 0
otherwise.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
(1) This is currently a KLUDGE. Figure out a more
robust way of determining if fields are defined on
level edges or level centers later on. (bmy, 7/16/07)
(2) Add more names to the CASE statement as necessary.
EXAMPLES:
(1)
PRINT, GET_IS_EDGED( 'PEDGE' )
1
; The GEOS-5 PEDGE field is defined on the vertical
; grid edges, so GET_IS_EDGED returns 1.
(2)
PRINT, GET_IS_EDGED( 'UWND' )
0
; The GEOS-5 UWND field is defined on the vertical
; grid centers, so GET_IS_EDGED returns 0.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/internals/get_is_edged.pro)
NAME:
READ_EPTOMS
PURPOSE:
Read Earth Probe TOMS data as retrieved from
http://jwocky.gsfc.nasa.gov and store them as datainfo
records so that they can be displayed with GAMAP.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
READ_EPTOMS [,DATA] [,keywords]
INPUTS:
KEYWORD PARAMETERS:
FILENAME -> filename of TOMS data
DATAINFO -> A named variable will return the newly
created daatinfo structure.
MODELINFO, GRIDINFO -> named variables will return
the "model" and grid information for the EP-TOMS
data. The grid is a 2-dimensional "generic" grid.
OUTPUTS:
DATA -> contains 2D array with EP-TOMS data (for use without
GAMAP).
SUBROUTINES:
uses open_file, ctm_type, ctm_grid, ctm_make_datainfo
REQUIREMENTS:
None
NOTES:
For tropical ozone in March, I used the following options
in the call to GAMAP:
myct,27,ncol=32,bot=20,range=[0.15,0.8]
c_lev = [150,200,220,230,240,250,260,270,280, $
290,300,310,320,330,340,350,375,400]
gamap,/nofile,c_lev=c_lev,c_col=[0,17,2*indgen(21)+18], $
/cbar,mlinethick=2,ncolors=32,bottom=18, $
cbmin=220,cbmax=400,div=10 [,frame0=4]
(the frame0 keyword is used to save GIF files)
EXAMPLE:
read_eptoms,file='/data/pem-tb/satellite/eptoms/*.ept'
gamap [... options]
MODIFICATION HISTORY:
mgs, 02 Apr 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/read_eptoms.pro)
NAME:
READ_MLD
PURPOSE:
Read Ocean mixed layer depth data as retrieved from
http://www.nodc.noaa.gov/OC5/mixdoc.html and store
them as datainfo records so that they can be displayed
with GAMAP.
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation
CALLING SEQUENCE:
READ_MLD [,DATA] [,keywords]
INPUTS:
None
KEYWORD PARAMETERS:
FILENAME -> filename of MLD data
DATAINFO -> A named variable will return the newly
created daatinfo structure.
MODELINFO, GRIDINFO -> named variables will return
the "model" and grid information for the EP-TOMS
data. The grid is a 2-dimensional "generic" grid.
OUTPUTS:
DATA -> contains 2D array with mixed layer depth data
(for use without GAMAP).
SUBROUTINES:
uses open_file, ctm_type, ctm_grid, ctm_make_datainfo
REQUIREMENTS:
None
NOTES:
In the call to GAMAP you must use the /NOFILE option.
EXAMPLE:
READ_MLD, FILE='~/download/mixed_layer_depth/mld*'
GAMAP, /NOFILE, ...
MODIFICATION HISTORY:
mgs, 30 Jun 1999: VERSION 1.00 (derived from read_eptoms)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/read_mld.pro)
NAME:
TSDIAG
PURPOSE:
Reads and plots CTM time series (station) data. The
data are returned in a structure together with longitude,
latitude, altitude, and time information. TSDIAG tries to
construct a time vector from the TAU information stored
in the file. This may not always work (e.. it is assumed
that time steps are 1 hour).
While reading, TSDIAG displays a '.' for each new station
encountered, and a '+' if a station is continued. If you want
more detailed output, set the /VERBOSE flag.
%%% NOTE: May need updating %%%
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, GAMAP Plotting
CALLING SEQUENCE:
TSDIAG [,RESULT] [,keywords]
INPUTS:
None
KEYWORD PARAMETERS:
FILENAME -> Path of the input file containing CTM
Data data.
SCALE -> A global scale factor that will be applied to all
data. Default is 1. Note that concentration data is
stored as v/v, hence for ppt you should set
SCALE=1.E-12.
/VERBOSE -> display detailed information on what is being read.
/PLOT -> set this flag to produce quick-and-dirty plots of the
time-series data.
OUTPUTS:
RESULT -> A structure containing LON, LAT, ALT and Data data
together with TRACER and a "global" TIME array.
SUBROUTINES:
OPEN_DEVICE CLOSE_DEVICE
CTM_TRACERINFO FILE_EXIST (function)
STRSCINOT (function)
REQUIREMENTS:
NOTES:
Lines with the Data data (Header = 'TB' or 'DV') will be
read from disk. Statistics are ignored for now.
EXAMPLE:
; read time series data from file and return result structure
; in variable TSDATA
tsdiag, TSDATA, FILENAME='ctm.ts'
MODIFICATION HISTORY:
bmy, 06 May 1998: VERSION 1.00
bmy, 07 May 1998: VERSION 1.01
- added PPBC and INTERVAL keywords
- now calls FILE_EXIST to make sure
the input file exists
bmy, 27 May 1998 - now uses CTM_DIAGINFO to return
the proper tracer offset
bmy, 28 May 1998 - now uses SCALE, UNIT, and MOLC information
as returned by CTM_TRACERINFO.
- now uses EXP_STR to compute a
power-of-ten string for the plot title
bmy, 29 May 1998 - now calls CLEANPLOT to initialize
all system variables
bmy, 02 Jun 1998 - now uses STRSCI and STRCHEM string
formatting functions
mgs, 11 Jun 1998: - couple of bug fixes
mgs, 15 Jun 1998: - default tick interval now 48 h
mgs, 22 Jun 1998: - added Data and CSTEPS keywords
mgs, 20 Nov 1998: - now uses convert_unit
hsu, 22 Mar 1999: - increased MAXSTEPS and changed input format
mgs, 04 May 1999: - added MS as a tracer offset (100*MS)
mgs, 05 May 1999: - ... and a little bug fix
mgs, 19 May 1999: - updated comments
- default SCALE factor now 1 instead of 1.E-12
- CLEANPLOT no longer called
mgs, 24 May 1999: - added VERBOSE keyword
- fixed at least two bugs
- improved output. Now need to say /VERBOSE in
order to get details.
mgs, 25 May 1999: - new format had MS and N swapped.
bmy, 27 Jul 1999: GAMAP VERSION 1.42
- updated comments
bmy, 30 Jan 2002: GAMAP VERSION 1.50
- Now use STRBREAK to split each line into
elements of data
- Also no longer restrict data to be > 0
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tsdiag.pro)