List routines by category:
Atmospheric Sciences | 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
Last modified: Thu Jul 17 10:11:00 2008.
NAME:
BARGRAPH
PURPOSE:
Creates a bar graph from a vector of data points.
CATEGORY:
Plotting
CALLING SEQUENCE:
BARGRAPH, DATA, BASELINE [,keywords]
INPUTS
DATA -> Vector of data points to be plotted as a bargraph.
BASELINE -> Vector of points to be used as a baseline for
DATA (i.e., Y(I) = DATA(I) + BASELINE(I) ). If BASELINE
is not specified, its default value will be an array
of zeroes.
KEYWORD PARAMETERS:
/OVERPLOT -> Set this switch to prevent the current plot
window from being erased. This is useful for producing
stacked bar plots with successive calls to BARGRAPH.
BARWIDTH -> The width of the bars. If BARWIDTH is not
specified, its default value will be 1.0.
BARCOLOR -> a value or an array containing the colorindex for
all boxes or each box, respectively. If a single value
is given, *all* boxes will have this color. If an array
is passed that has less elements than there are groups to
plot, the remaining colors will be filled with 15 (grey
in MYCT standard-scheme).
BARLABELS -> A string array of labels to be plotted above each
bar. If BARLEVELS may be originally set equal to the
DATA vector, and it will be converted to the string
representation of DATA, using the FORMAT statement
contained in L_FORMAT.
BARCHARSIZE -> Character size for BARLABELS. Default is 1.0.
COLOR -> Color index for the plot axes and labels.
Default is !MYCT.BLACK.
L_FORMAT -> The FORMAT statement used to convert BARLABELS
from a numeric array to a string array.
/NO_LABELS -> Set this switch to suppress printing the labels
contained in the BARLABELS atop each bar. This is useful
for producing stacked bar plots.
XLABELS -> A string array containing the labels that will be
printed underneath each bar on the X-axis.
NOTE: If /HORIZONTAL is set, then these labels will be
printed along the Y-axis instead.
ALSO NOTE: IDL only allows a maximum limit of 60 ticks
along any axis. If XLABELS has more than 58 elements
(also allowing for null labels at the beginning and end
of the plot range), then the labels will not be printed.
YRANGE -> Use this keyword to specify the range of the data
values. If YRANGE is not specified, then YRANGE will be
computed based on the maximum value of the DATA array.
For stacked plots, it is useful to compute YRANGE in the
calling program and pass it to BARGRAPH.
NOTE: If HORIZONTAL is set, then the YRANGE settings
will apply to the X-axis instead.
/HORIZONTAL -> Set this switch to plot the bars in the
horizontal instead of in the vertical. NOTE: In this
case, the YRANGE settings will be applied to the X-axis.
and the XRANGE and XLABELS settings will be applied to
the Y-axis.
_EXTRA=e -> Passes extra keywords to PLOT and other routines.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
(1) This routine has been modified to be more general and
more robust than the original version in the IDL 5.0
User's Guide (p. 170).
(2) IDL 5.x array notation [] is now used.
EXAMPLES:
(1)
BARGRAPH, [1,2,3], BARWIDTH=1.0, BARCOLOR=[10,11,12]
XLABELS=['Bart', 'Lisa', 'Maggie']
; Create a simple bar graph with bars of 3 different
; colors, using a baseline of zero.
(2)
DATA = [2,3.5,6,7,2,1]
DATA2 = 0.0*DATA + 2
BARGRAPH, DATA, XLABELS=['A','B','C','D','E','F'], $
XSTYLE=1, BARWIDTH=0.8
BARGRAPH, DATA2, DATA, BARWIDTH=0.8 ,/OVERPLOT, $
BARCOLOR=2, BARLABELS=DATA+DATA2, L_FORMAT='(F8.2)'
; Use successive calls to BARGRAPH to create a
; "stacked" bar graph with two different data vectors.
; The first vector is used as the baseline for the
; second. The BARLABELS array is created from the actual
; data values.
(3)
BARGRAPH, [1,2,3], BARWIDTH=1.0, BARCOLOR=[10,11,12]
XLABELS=['Bart', 'Lisa', 'Maggie'], /HORIZONTAL
; Same as example (1), but plot bars in the horizontal.
MODIFICATION HISTORY:
bmy, 18 Nov 1997: VERSION 1.00
bmy, 19 Nov 1997: VERSION 1.01
bmy, 29 Apr 1999: VERSION 1.10
- added COLOR keyword
- eliminated help screen
- enhanced readability & updated comments
bmy, 15 Mar 2000: VERSION 1.45
- added BARCHARSIZE keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- added HORIZONTAL keyword to plot
bars in the horizontal
- Now limits XLABELS array to 58 elements
in order to prevent exceeding an IDL
plotting limit
(See /san/home/ctm/bmy/IDL/gamap2/plotting/bargraph.pro)
NAME:
BINARY (function)
PURPOSE:
This function returns the binary representation of a number.
Numbers are converted to LONG integers if necessary.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = BINARY( NUMBER )
INPUTS:
NUMBER -> Number for which its binary representation
will be returned. Number may be any of the numeric
types (BYTE, INT, LONG, FLOAT, DOUBLE, COMPLEX, etc).
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, BINARY( 11B )
0 0 0 0 1 0 1 1
; Binary representation of 11B
(2)
PRINT, FORMAT='(Z9.8,5X,4(1X,8A1))', LONG(!PI,0), BINARY(!PI)
40490fdb 01000000 01001001 00001111 11011011
; If data extraction is used instead of conversion
; Binary representation of pi (little endian IEEE
; representation)
AUTHOR:
Kevin Ivory Tel: +49 5556 979 434
Max-Planck-Institut fuer Aeronomie Fax: +49 5556 979 240
Max-Planck-Str. 2 mailto:Kevin.Ivory@linmpi.mpg.de
D-37191 Katlenburg-Lindau, GERMANY
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /san/home/ctm/bmy/IDL/gamap2/math_units/binary.pro)
NAME:
BOXPLOT
PURPOSE:
Produce a box and whisker plot of a data vector
CATEGORY:
Plotting
CALLING SEQUENCE:
BOXPLOT,DATA [,keywords]
INPUTS:
DATA --> the data vector
KEYWORD PARAMETERS:
GROUP --> array of the same dimension as DATA which contains
grouping information. One box is plotted for each group.
If MINGROUP or MAXGROUP are given, boxes and whiskers are
only plotted for group values within this range.
GROUP may not contain more than 28 different values.
Group can also be a string array. In this case MINGROUP
and MAXGROUP make no sense of course.
MINGROUP --> the minimum group value for which a box shall be
plotted
MAXGROUP --> the maximum group value for which a box shall be
plotted
LABEL --> string array containing labels for *different* groups.
NOTE: The user must take care that one label is passed for
each group to be plotted. If label is not specified, the
group values will be used as axis labels
COLOR --> plotting color for axis (default : 1, i.e. black in MYCT
color scheme). Will also be used as default for BOXCOLOR.
BOXCOLOR --> color of the boxes (frames). Default is the COLOR
value, i.e. 1 if not specified. This color will also be used as
default for MEDIANCOLOR and MEANCOLOR. If you want boxes that
are only filled but have no frame, you must specify BOXCOLOR=-1.
In this case the default for MEDIANCOLOR and MEANCOLOR will
be the COLOR value.
BOXWIDTH --> relative width of boxes (default: 0.8).
BOXPOSITION --> relative position of box on x axis (default: 0.).
This parameter can be used together with the OVERPLOT keyword
to plot multiple groups of boxes in one graph.
MEDIANCOLOR --> a color value for the median bar
(default: value of BOXCOLOR)
MEANSYMBOL --> symbol to be used for mean values. If no symbol
is given, no mean values will be drawn.
MEANCOLOR --> color for mean symbols (default: value of BOXCOLOR)
FILLCOLOR --> a value or an array containing the colorindex for all
boxes or each box, respectively. If a single value is given,
*all* boxes will be filled with this color. If an array is
passed that has less elements than there are groups to plot,
the remaining colors will be filled with 15 (grey in MYCT
standard-scheme). If no FILLCOLOR is specified, the boxes will
be empty.
MISSING --> a value that represents missing data. If given, any data
with a value of missing will be filtered out before plotting.
PRINTN --> print number of elements on top of each box/whisker
CHARSIZE --> character size of the PRINTN labels (default: 0.8)
/OVERPLOT --> do not draw a new coordinate system but overlay new
data. For 2 sets of data you should use BOXWIDTH=0.4 and
BOXPOSITION=-0.25 and 0.25, respectively.
ORIENTATION -> orientation for axis labels (see XYOUTS procedure)
/IS_PERCENTILE --> data are already processed percentiles. In this
case data must be an array with dimensions 5,N. The GROUP keyword
is ignored, and each set of the N percentiles will be treated as
one group.
PERCVAL --> float array with 5 elements denoting the percentile
values (default: 0.05, 0.25, 0.5, 0.75, 0.95)
Further keywords are passed to the PLOT routine and can be used
to determine the appearance of the plot (e.g. XTITLE,YTITLE,
YSTYLE,YRANGE,/YLOG,COLOR,THICK)
OUTPUTS:
SUBROUTINES:
External Subroutines Required:
===============================
PERCENTILES (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
O3 = DATA( WHERE( HEADER EQ 'O3' ), * )
ALT = DATA( WHERE( HEADER EQ 'ALT' ), * )
IALT = 2.0* FIX( ALT / 2.0 )
BOXPLOT, O3, GROUP=IALT
; Produces a boxplot with ozone percentiles in
; altitude bins of 2 (km). Axis, box frames and
; labels will be black, boxes are not color filled.
(2)
BOXPLOT, O3, GROUP=IALT, FILLC=15, MEANSYM=SYM(1), $
MEANCOL=2, BOXWIDTH=0.6, YTITLE='O3', $
XTITLE='alt. bin', MISSING=-999.99, /PRINTN
; Produces boxes that are filled with light grey and
; have a black frame and median line. A red filled
; circle denotes the mean value, titles are assigned
; to the x and y axis. The number of valid observations
; is printed on top of each box. The boxes are reduced
; in size.
CO = DATA( WHERE( HEADER EQ 'CO' ), * )
BOXPLOT, O3, GROUP=IALT, MISSING=-999.99, BOXCOL=4, $
BOXWIDTH=0.4, BOXPOS=-0.25
BOXPLOT, CO, GROUP=IALT, MISSING=-999.99, BOXCOL=2, $
BOXWIDTH=0.4, BOXPOS=+0.25, /OVERPLOT
; Produces a plot with blue box frames for ozone
; and red frames for CO data.
MODIFICATION HISTORY:
mgs, 30 Jul 1997: VERSION 1.00
mgs, 03 Aug 1997: added template
mgs, 27 Nov 1997: some revisions and suggested changes by T.Brauers:
- better color handling (NOTE: meaning of BOXCOLOR has changed)
- optional overlay of mean value
- box frames
- variable boxwidth
- error fixing lower upper boundaries in log plots
- bug fix with label keyword
- added OVERPLOT and BOXPOSITION keywords
mgs, 22 Jan 1998: added IS_PERCENTILE keyword to allow
plotting of data that has been processed already
mgs, 17 Apr 1998:
- x-axis handling improved (now uses axis command and xyouts)
- orientation and medianthick keywords added
mgs, 21 May 1998:
- added percval keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/plotting/boxplot.pro)
NAME:
BPCH2ASCII
PURPOSE:
Translates data from GAMAP-readable binary punch file v. 2.0
format to a simple ASCII file format
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH2ASCII, INFILE, OUTFILE [ , Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the ASCII file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2ASCII will write a separate
netCDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2nc_output.%DATE%.%TIME%.ascii".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in ASCII format to OUTFILE.
/VERBOSE -> If set, then BPCH2ASCII will also echo the
header lines for each data block to the screen.
FORMAT -> String containing the numeric format for
for the data values. Default is '(7(e13.6,1x))'
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=============================================
CTM_GET_DATA TAU2YYMMDD (function)
GETMODELANDGRIDINFO REPLACE_TOKEN (function)
UNDEFINE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) BPCH2ASCII assumes that all data blocks in the *.bpch file
file adhere to same grid. This will be true for output
files from the GEOS-CHEM model.
(2) BPCH2ASCII will write a separate ASCII file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(3) BPCH2NC will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. The tokens %DATE% and %TIME% tokens
may be either in uppercase or lowercase.
(4) The format of the ASCII file is:
Data block #1 header line
Data block #1 values (format specified by FORMAT keyword)
Data block #2 header line
Data block #2 values (format specified by FORMAT keyword)
...
The header line will contain the units and size of
each data block.
(5) The data is written to the ASCII file in column-major
order (i.e. the same way as in FORTRAN), so you can read
the data into FORTRAN w/ the following code:
READ( IUNIT, '(a)' ) HEADER
READ( IUNIT, '(1p,7(e13.6,1x))' )
& ((DATA(I,J), I=1,IMX), J=1,JMX)
where IMX and JMX are the dimensions of the data block.
EXAMPLE:
BPCH2ASCII, 'myfile.bpch', 'myfile.%DATE%.%TIME%.ascii'
; Read data from binary punch file 'myfile.bpch'
; and writes it to ASCII file 'myfile.bpch.ascii'.
MODIFICATION HISTORY:
bmy, 22 May 2002: GAMAP VERSION 1.50
bmy, 28 May 2002: GAMAP VERSION 1.51
- Added FORMAT keyword
bmy, 03 Jun 2004: GAMAP VERSION 2.02
- now pass extra keywords to CTM_GET_DATA
via _EXTRA=e keyword
bmy, 03 Dec 2004: GAMAP VERSION 2.03
- add CATEGORY keyword (passed to CTM_GET_DATA)
in order to refine data block search
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/file_io/bpch2ascii.pro)
NAME:
BPCH2COARDS
PURPOSE:
Reads data from a binary punch file and saves it in a
COARDS-compliant netCDF (network Common Data Format) file.
NOTE: COARDS is a formatting standard for netCDF files which
is widely used in both the atmospheric & climate communities.
COARDS-compliant netCDF files can be read by GAMAP, GrADS and
other plotting packages.
See http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html
for more information about the COARDS standard.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2COARDS, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If INFILE
is not passed, the user will be prompted to supply a
file name via a dialog box.
OUTFILE -> Name of the netCDF file to be written. It is
recommended to insert the tokens %DATE% (or %date%)
into OUTFILE, since BPCH2COARDS will write a separate
netCDF file for each unique YYYYMMDD value contained
within the *.bpch file. If OUTFILE is not specified,
BPCH2COARDS will use the default file name
"coards.%DATE%.nc".
KEYWORD PARAMETERS:
DIAGN -> Array of diagnostic categories from the bpch file
to save to netCDF format. If omitted, BPCH2COARDS will
save all diagnostic categories.
/VERBOSE -> If set, will print the name of each tracer
as it is being written to the netCDF file. Useful
for debugging purposes.
_EXTRA=e -> Picks up additional keywords for NCDF_SET
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
============================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
STRREPL (function) GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the NCDF routines.
NOTES:
(1) BPCH2COARDS assumes that each data block in the *.bpch
file is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2COARDS assumes that the number type of each data
block in the *.bpch file is REAL*4 (a.k.a. FLOAT).
(3) BPCH2COARDS assumes that all data blocks in the *.bpch
file adhere to same horizontal grid. This will always
be true for output files from the GEOS-CHEM model.
(4) BPCH2COARDS will write a separate COARDS-compliant netCDF
file corresponding to each unique YYYYMMDD date. This
prevents the files from becoming too large to be read
with IDL.
(5) BPCH2COARDS will replace the %DATE% (or %date%) token with
the current YYYYMMDD value. Therefore, it is recommended
to insert this token into the string passed via OUTFILE.
(6) BPCH2COARDS will write arrays containing the latitudes,
longitudes to the netCDF file. For 3-D data blocks,
the eta or sigma centers will also be written to the
file. Time will be written as TAU values (i.e. hours
since 00:00 GMT on 01-Jan-1985.
(7) The netCDF library has apparently been updated in
IDL 6.0+. The result is that variable names containing
characters such as '$', '=', and ':' may now cause an
error in NCDF_VARDEF. Therefore, we now pre-screen
tracer names with function NCDF_VALID_NAME.
EXAMPLE:
BPCH2COARDS, 'myfile.bpch', 'myfile.%DATE%.nc'
; Will write the contents of "myfile.bpch" to one
; or more COARDS-compliant netCDF files adhering
; to the filename convention "myfile.YYYYMMDD.nc"
MODIFICATION HISTORY:
rjp & bmy, 17 Mar 2005: GAMAP VERSION 2.03
- Based on bpch2nc.pro
bmy, 21 Jul 2005: GAMAP VERSION 2.04
- Bug fix:
bmy, 13 Jul 2006: GAMAP VERSION 2.05
- Remove call to PTR_FREE
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now count GCAP among the GEOS family
for the purpose of converting the TAU
date to a YYYY/MM/DD date.
(See /san/home/ctm/bmy/IDL/gamap2/file_io/bpch2coards.pro)
NAME:
BPCH2GMI
PURPOSE:
Reads data from a binary punch file and saves it in
netCDF (network Common Data Format) format. The data
will be shifted so that the first longitude is 0 degrees
(i.e. the prime meridian) in order to conform with the
GMI (Global Model Initiative) model grid definition.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2GMI, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the netCDF file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2NC will write a separate
netCDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2nc_output.%DATE%.%TIME%.nc".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in netCDF format to OUTFILE.
/VERBOSE -> If set, will print the names of each tracer
as it is being written to the netCDF file.
_EXTRA=e -> Picks up additional keywords for netCDF routines
OUTPUTS:
SUBROUTINES:
Internal Subroutines:
============================================
B2G_Valid_VarName (function)
B2G_SetNcDim (function)
B2G_GetNcDim (function)
External Subroutines Required:
============================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
STRREPL (function) GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the NCDF routines.
NOTES:
(1) BPCH2GMI assumes that each data block in the *.bpch file
is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2GMI assumes that the number type of each data block
in the *.bpch file is REAL*4 (a.k.a. FLOAT).
(3) BPCH2GMI assumes that all data blocks in the *.bpch file
file adhere to same horizontal grid. This will always
be true for output files from the GEOS-CHEM model.
(4) BPCH2GMI will write a separate NC file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(5) BPCH2GMI will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. The tokens %DATE% and %TIME% tokens
may also be passed in lowercase (e.g, %date%, %time% ).
(6) BPCH2GMI will write arrays containing the latitudes,
longitudes to the netCDF file. For 3-D data blocks,
the sigma centers will also be written to the file.
Date and time are stored as global attributes.
(7) The netCDF library has apparently been updated in
IDL 6.0+. The result is that variable names containing
characters such as '$', '=', and ':' may now cause an
error in NCDF_VARDEF. Therefore, we now pre-screen
tracer names with function NCDF_VALID_NAME.
EXAMPLE:
BPCH2GMI, 'myfile.bpch', 'myfile.%DATE%.%TIME%.nc'
; Will write the contents of "myfile.bpch" to one
; or more netCDF files "myfile.YYYYMMDD.HHMMSS.nc"
MODIFICATION HISTORY:
bmy & phs, 20 Aug 2007: GAMAP VERSION 2.10
- Based on BPCH2NC
bmy, 19 Dec 2007: GAMAP VERSION 2.12
- Now save sigma edges & centers or
eta edges & centers to the file.
- Extra error trap, if there is only one
level in the file then set IS_3D=0.
(See /san/home/ctm/bmy/IDL/gamap2/file_io/bpch2gmi.pro)
NAME:
BPCH2HDF
PURPOSE:
Reads data from a binary punch file and saves it in HDF-SD
(Hierarchical Data Format, Scientific Dataset) format.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2HDF, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the HDF file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2HDF will write a separate
HDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2hdf_output.%DATE%.%TIME%.hdf".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in HDF format to OUTFILE.
_EXTRA=e -> Picks up additional keywords for HDF_SETSD
OUTPUTS:
SUBROUTINES:
External Subroutines Required:
=========================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
HDF_SETSD GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the HDF-SD routines.
NOTES:
(1) BPCH2HDF assumes that each data block in the *.bpch file
is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2HDF assumes that all data blocks in the *.bpch file
file adhere to same horizontal grid. This will be true
for output files from the GEOS-CHEM model.
(3) BPCH2HDF will write a separate HDF file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(4) BPCH2HDF will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. These tokens may be in either
uppercase or lowercase.
(4) BPCH2HDF will also write arrays containing the latitudes,
longitudes, sigma coordinates (for 3-D data blocks only!)
to the HDF file.
(5) BPCH2HDF will write arrays containing the latitudes,
longitudes to the netCDF file. For 3-D data blocks,
the sigma centers and sigma edges will also be written
to the file.
EXAMPLE:
BPCH2HDF, 'myfile.bpch', 'myfile.%DATE%.%TIME%.hdf'
; Will write the contents of "myfile.bpch" to
; one or more HDF files "myfile.YYYYMMDD.HHMMSS.hdf"
MODIFICATION HISTORY:
bmy, 22 May 2002: GAMAP VERSION 1.50
bmy, 22 Oct 2002: GAMAP VERSION 1.52
- bug fix: now do not write vertical layer
dim info to HDF file for 2-D grids
bmy, 22 May 2003: GAMAP VERSION 1.53
- Make sure LONGNAME is not a null string
bmy, 18 Sep 2003: - Call PTR_FREE to free the pointer memory
bmy, 03 Jun 2004: GAMAP VERSION 2.02
- now pass extra keywords to CTM_GET_DATA
via _EXTRA=e keyword
bmy, 03 Sep 2004: GAMAP VERSION 2.03
- now defines ETAC and ETAE variables
for hybrid grids
bmy, 03 Dec 2004: GAMAP VERSION 2.03
- add DIAGN keyword (passed to CTM_GET_DATA)
in order to refine data block search
bmy, 19 May 2006: GAMAP VERSION 2.05
- Now do not free the pointer memory
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now count GCAP among the GEOS family
for the purpose of converting the TAU
date to a YYYY/MM/DD date.
(See /san/home/ctm/bmy/IDL/gamap2/file_io/bpch2hdf.pro)
NAME:
BPCH2NC
PURPOSE:
Reads data from a binary punch file and saves it in
netCDF (network Common Data Format) format.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2NC, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the netCDF file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2NC will write a separate
netCDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2nc_output.%DATE%.%TIME%.nc".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in netCDF format to OUTFILE.
/VERBOSE -> If set, will print the names of each tracer
as it is being written to the netCDF file.
_EXTRA=e -> Picks up additional keywords for NCDF_SET
OUTPUTS:
SUBROUTINES:
Internal Subroutines:
============================================
B2N_Valid_VarName (function)
B2N_SetNcDim (function)
B2N_GetNcDim (function)
External Subroutines Required:
============================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
STRREPL (function) GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the NCDF routines.
NOTES:
(1) BPCH2NC assumes that each data block in the *.bpch file
is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2NC assumes that the number type of each data block
in the *.bpch file is REAL*4 (a.k.a. FLOAT).
(3) BPCH2NC assumes that all data blocks in the *.bpch file
file adhere to same horizontal grid. This will always
be true for output files from the GEOS-CHEM model.
(4) BPCH2NC will write a separate NC file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(5) BPCH2NC will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. The tokens %DATE% and %TIME% tokens
may also be passed in lowercase (e.g, %date%, %time% ).
(6) BPCH2NC will write arrays containing the latitudes,
longitudes to the netCDF file. For 3-D data blocks,
the sigma centers will also be written to the file.
Date and time are stored as global attributes.
(7) The netCDF library has apparently been updated in
IDL 6.0+. The result is that variable names containing
characters such as '$', '=', and ':' may now cause an
error in NCDF_VARDEF. Therefore, we now pre-screen
tracer names with function NCDF_VALID_NAME.
EXAMPLE:
BPCH2NC, 'myfile.bpch', 'myfile.%DATE%.%TIME%.nc'
; Will write the contents of "myfile.bpch" to one
; or more netCDF files "myfile.YYYYMMDD.HHMMSS.nc"
MODIFICATION HISTORY:
bmy, 22 May 2002: GAMAP VERSION 1.50
bmy, 22 Oct 2002: GAMAP VERSION 1.52
- bug fix: now do not write vertical layer
dim info to netCDF file for 2-D grids
bmy, 22 May 2003: GAMAP VERSION 1.53
- Bug fix: LONGNAME cannot be a null string
bmy, 22 Sep 2003: - Now declare all variables first, then save
data into them. This is much more efficient!
- Remove reference to NCDF_SET routine
- Call PTR_FREE to free the pointer memory
- Bug fix: now sort TAU0 values for call to UNIQ
- added /VERBOSE keyword
bmy, 09 Oct 2003: - for IDL 6.0+, use '__' to separate category
name from the tracer name
bmy, 21 Oct 2003: - Now uses function NCDF_Valid_Name to screen
out and replace invalid characters for netCDF
variable names
bmy, 06 Nov 2003: GAMAP VERSION 2.01
- added extra global attributes to facilitate
reading netCDF files created by BPCH2NC
into GAMAP
bmy, 29 Mar 2004: GAMAP VERSION 2.02
- Now saves ETA centers for hybrid grid
instead of sigma centers
bmy, 17 Mar 2005: GAMAP VERSION 2.03
- Bug fix: now prints ETAC properly
when the /VERBOSE keyword is set
bmy, 03 Oct 2006: GAMAP VERSION 2.05
- Bug fix: now do not call PTR_FREE
to free the pointer memory
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now count GCAP among the GEOS family
for the purpose of converting the TAU
date to a YYYY/MM/DD date.
bmy, 21 Jan 2008: GAMAP VERSION 2.12
- Now save sigma edges & centers or
eta edges & centers to the file.
- Extra error trap, if there is only one
level in the file then set IS_3D=0.
- Now error check for duplicate variable names
(See /san/home/ctm/bmy/IDL/gamap2/file_io/bpch2nc.pro)
NAME:
BPCH2PCH
PURPOSE:
Translates data from GAMAP-readable binary punch
file v. 2.0 format to the ancient ASCII-punch
file standard.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH2PCH, FILENAME [, OUTFILENAME [, Keywords ] ]
INPUTS:
FILENAME -> Name of the binary punch file from which
to read data. FILENAME may be a file mask, and may
contain wild card characters (e.g. ~/ctm.bpch.*). If
FILENAME is omitted or contains a wild card character,
the user will be prompted to pick a file via a dialog box.
OUTFILENAME (optional) -> Name of the output ASCII punch
file. Default is 'ASCIIfile.pch'
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in ASCII punch format
to OUTFILE.
/EXTRA_SPACE -> If set, will put an extra space between
the numbers in the ASCII punch file. This might
be necessary when using MATLAB or S-PLUS to read
in the ASCII punch file.
OUTPUTS:
Writes data to ASCII punch file format
SUBROUTINES:
CTM_GET_DATA
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
Some limitations:
(1) Works only for global lon-lat diagnostics.
(2) The top header line might be inaccurate (but nobody
really reads that anyway, so forget it for now...)
EXAMPLE:
BPCH2PCH, '~/bmy/ctm.bpch', '~/bmy/ctm.pch'
; Reads data from binary punch file '~/bmy/ctm.bpch'
; and writes it to ASCII punch file '~/bmy/ctm.pch'.
MODIFICATION HISTORY:
bmy, 08 Nov 1999: VERSION 1.00
bmy, 03 Jun 2004: GAMAP VERSION 2.02
- now pass extra keywords to CTM_GET_DATA
via _EXTRA=e keyword;
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/file_io/bpch2pch.pro)
NAME:
BPCH_LINK
PURPOSE:
Copies data from several binary punch files into a single
binary punch file. Also can trim data down to nested-grid
resolution if necessary
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH_LINK, INFILES, OUTFILE [, Keywords ]
INPUTS:
INFILES -> A path name or file mask (with wildcards)
which indicates the names of the individual files
to be linked together in a single bpch file.
OUTFILE -> Name of the bpch file that will contain data
from the individual bpch files specified by INFILES.
KEYWORD PARAMETERS:
/CREATE_NESTED --> If set, then BPCH_LINK will trim data
to the nested grid resolution as specified by the
XRANGE and YRANGE keywords.
XRANGE -> A 2-element vector containing the minimum and
maximum box center longitudes which define the nested
model grid. Default is [-180,180].
YRANGE -> A 2-element vector containing the minimum and
maximum box center latitudes which define the nested
model grid. Default is [-90,90].
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
OPEN_FILE UNDEFINE
CTM_DIAGINFO
REQUIREMENTS:
Requires routines from the GAMAP and TOOLS packages.
NOTES:
None
EXAMPLE:
BPCH_LINK, 'ctm.bpch.*', 'new.ctm.bpch'
; Consolidates data from the 'ctm.bpch.*' files
; into a single file named 'new.ctm.bpch'
MODIFICATION HISTORY:
bmy, 31 Jan 2003: VERSION 1.00
bmy, 09 Apr 2003: VERSION 1.01
- now can save to nested grid
bmy, 15 May 2003: VERSION 1.02
- now can pass a list of files via INFILES
bmy, 20 Nov 2003: GAMAP VERSION 2.01
- now gets the spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 28 May 2004: GAMAP VERSION 2.02
- Now use MFINDFILE to get INLIST regardless
of the # of elements of INFILES
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read/write bpch as big-endian
(See /san/home/ctm/bmy/IDL/gamap2/file_io/bpch_link.pro)
NAME:
BPCH_SEP
PURPOSE:
Separates data from one binary punch file into another binary
punch file by time (TAU0), tracer, or location indices. Useful
for making smaller bpch files so that we don't run out of IDL
memory when reading/processing them.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:p
BPCH_SEP, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> A path name or file mask (with wildcards)
which indicates the names of the individual files
to be linked together in a single bpch file.
OUTFILE -> Name of the bpch file that will contain data
from the individual bpch files specified by INFILES.
KEYWORD PARAMETERS:
DIAGN -> Array of diagnostic categories for which to
save out to OUTFILE Default is to save all diagnostic
categories to OUTFILE.
TAU0 -> Time index (hours from 1 Jan 1985) denoting the
data blocks to be saved from INFILE to OUTFILE. You
can use NYMD2TAU to compute this from a YYYYMMDD date.
TRACER -> Tracer number(s) for which to save to OUTFILE.
Default is to save all tracers.
II, JJ, KK -> Longitude, latitude, altitude index arrays used
to cut down the data block to less than global size.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================================
CTM_DIAGINFO LITTLE_ENDIAN (function)
OPEN_FILE UNDEFINE
REQUIREMENTS:
None
NOTES:
(1) Assumes that II, JJ, LL contain consecutive indices in
longitude, latitude, and altitude, respectively.
(2) Also assumes that II, JJ, LL are in IDL notation
(i.e. starting from zero). This is so that you can
pass the output from the WHERE command to BPCH_SEP.
EXAMPLES:
(1)
BPCH_SEP, 'ctm.bpch.big', 'ctm.bpch.small', tau0=140256D
; Pulls out data blocks for TAU0=140256 (1/1/2001) from
; "ctm.bpch.big" and saves them in "ctm.bpch.small"
(2)
INTYPE = CTM_TYPE( 'GEOS4', RES=4 )
INGRID = CTM_GRID( INTYPE )
INDX = WHERE( INGRID.XMID ge -60 AND INGRID.XMID le 60 )
INDY = WHERE( INGRID.YMID ge 0 AND INGRID.YMID le 60 )
BPCH_SEP, 'ctm.bpch.big', 'ctm.bpch.small', II=INDX, JJ=INDY
; Pulls out all data blocks for the geographical area
; from 60W - 60E longitude and 0-60N latitude.
MODIFICATION HISTORY:
bmy, 18 Sep 2003: GAMAP VERSION 1.53
bmy, 20 Nov 2003: GAMAP VERSION 2.01
- now gets the spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 07 Jul 2005: GAMAP VERSION 2.04
- minor bug fix; now can save out data
blocks for more than one matching TAU0
phs, 24 Oct 2006: GAMAP VERSION 2.05
- Added the II, JJ, LL keywords for
selecting a smaller geographical area.
These must be index arrays.
- Added the TRACERN keyword
- Added SWAP_ENDIAN=LITTLE_ENDIAN() in
the call to OPEN_FILE
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Cosmetic changes
(See /san/home/ctm/bmy/IDL/gamap2/file_io/bpch_sep.pro)
NAME:
BPCH_TEST
PURPOSE:
Reads header and data block information from binary punch
(BPCH for short) files and prints the file pointer locations.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH_TEST [, FILENAME, [ Keywords ] ]
INPUTS:
FILENAME (optional) -> Name of the binary punch file to read.
If omitted, a dialog box will prompt the user to make
a selection.
KEYWORD PARAMETERS:
/NOPAUSE -> If set, will not pause after displaying information
about each data block. Default is to pause to allow the
user to examine each data blocks header information.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
------------------------------
LITTLE_ENDIAN (function)
REQUIREMENTS:
References routines from the TOOLS package.
NOTES:
BPCH_TEST does not return any data values from the binary
punch file. It is meant to be used for debugging purposes.
EXAMPLES:
BPCH_TEST, 'my.bpch'
BPCH_TEST, FILENAME = 'my.bpch'
; will print info about each data block in 'my.bpch'
MODIFICATION HISTORY:
bmy, 10 Dec 1999: VERSION 1.00
bmy, 25 May 2000: GAMAP VERSION 1.45
- allow user to quit after viewing
each data block header
- add FILENAME keyword, so that the filename
can be passed as a parameter or a keyword
bmy, 21 Jul 2000: GAMAP VERSION 1.46
- now print locations of min, max data values
- changed FILETYPE to reflect new definitions
from CTM_OPEN_FILE
bmy, 24 Aug 2004: GAMAP VERSION 2.03
- Now recognizes bpch file containing
GEOS-CHEM station timeseries data
- Updated comments, cosmetic changes
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /san/home/ctm/bmy/IDL/gamap2/file_io/bpch_test.pro)