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:
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 BARLABELS 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.
YFACTOR -> Use this to add space between the bar and bar label.
This will multiply DATA + BASELINE by a factor that you
specify. Default is 1.01.
_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
bmy, 15 Dec 2016: GAMAP VERSION 2.19
- Now plot top-of-bar labels in the right
place when using the /HORIZONTAL option
bmy, 20 Dec 2017: - Now compute YOffSet dynamically, for more
consistent spacing between bars & bar labels
(See /n/home09/ryantosca/IDL/gamap2/plotting/bargraph.pro)
NAME:
BENCHMARK_1MON
PURPOSE:
Produces maps of tracers and other quantities from two
GEOS-Chem benchmark simulations (for model validation).
CATEGORY:
Benchmarking
CALLING SEQUENCE:
BENCHMARK_1MON, INPUTFILE, [, Keywords ]
INPUTS:
INPUTFILE -> A file containing default values for version
numbers, directories, model names, resolutions, etc.
Default is "input_bm.1mon"
KEYWORD PARAMETERS:
By default, BENCHMARK_1MON will produce the following types
of output:
(a) Table of Ox and CO budgets, mean OH conc. and CH3CCL3 lifetime
(b) Table of emissions totals
(c) Frequency distribution histogram
(d) Vertical profiles of tracer differences along 15S and 42N
(e) Maps of tracer concentration @ surface and 500 hPa
(f) Maps of tracer differences @ surface and 500 hPa
(g) Maps of J-value differences @ surface and 500 hPa
(h) Maps of tracer ratios @ surface and 500 hPa
Each of these types of output can be turned off individually
with the following keywords:
/NO_AOD_DIFFS -> Do not create difference maps of aerosol optical
depths.
/NO_AOD_MAPS -> Do not create concentration plots for aerosol
optical depths.
/NO_BUDGET -> Do not create the table of Ox and CO budgets,
mean OH concentration and CH3CCl3 lifetime.
/NO_CONC_MAPS -> Do not create the plot the maps of tracer
concentrations @ sfc and 500 hPa altitude.
/NO_DIFFS -> Do not create the maps of tracer differences
at the surface and 500 hPa altitude.
/NO_EMISSIONS -> Do not create the table of emissions totals.
/NO_FREQ_DIST -> Do not create the the frequency distribution
histogram plot.
/NO_JVALUES -> Do not create the maps of J-value ratios
at the surface and 500 hPa altitude.
/NO_JVDIFFS -> Do not create the maps of J-value differences
at the surface and 500 hPa altitude.
/NO_JVMAPS -> Do not create the maps of J-values
at the surface and 500 hPa altitude.
/NO_PROFILES -> Do not create the plot of vertical profiles
of tracer differences along 15S and 42N.
/NO_RATIOS -> Do not create the maps of tracer ratios at
the surface and 500 hPa altitude.
/NO_STRATDIFF -> Do not create the maps of zonal mean differences
in the stratosphere (100hPa-0.01hPa)
/NO_STRATCONC -> Do not create the maps of zonal mean concentrations
in the stratosphere (100hPa-0.01hPa)
/NO_ZONALDIFF -> Do not create the maps of zonal mean differences
/NO_ZONALCONC -> Do not create the maps of zonal tracer concentrations
/NO_CLOUDDIFF -> Do not create difference plots of cloud optical depth
/NO_2D_MET -> Do not create difference plots for 2-D met fields
/NO_3D_MET -> Do not create difference plots for 3-D met fields
Additional keywords:
--------------------
/DEBUG -> Set this switch to print the values of the various
input variables. Use this to make sure that all values
have been created corectly.
/DYNRANGE -> Set this switch to create additional difference
plots, ratio plots, and profile plots using the whole
dynamic range of the data.
/NO_FULLCHEM -> Set this switch to only plot the advected
tracers and omit full-chemistry quantities such as OH
and aerosol optical depths. This is useful if you wish
to compare output from offline GEOS-Chem simulations
(e.g. Rn-Pb-Be, CH4).
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines:
====================================================
DynOutFile (function) GetSfc500Levels (function)
External Subroutines Required:
====================================================
CTM_NAMEXT (function) CTM_TYPE (function)
DIFFERENCES FREQ_DIST
FULLCHEM_BUDGET FULLCHEM_EMISSIONS
JV_RATIO PROFILES
MAPS NYMD2TAU (function)
RATIOS REPLACE_TOKEN
STRUADDVAR (function) MCF_LIFETIME (function)
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
BENCHMARK_1MON assumes that the following GEOS-Chem
diagnostic quantities have been archived for the
"old" and "new" model versions:
(a) ND22 ("JV-MAP-$") (h) ND44 ("DRYD-FLX")
(b) ND24 ("EW-FLX-$") (i) ND45 ("IJ-AVG-$")
(c) ND25 ("NS-FLX-$") (j) ND65 ("PORL-L=$")
(d) ND26 ("UP-FLX-$") (k) ND66 ("DAO-3D-$")
(e) ND31 ("PEDGE-$" ) (l) ND67 ("DAO-FLDS")
(f) ND43 ("CHEM-L=$") (m) ND69 ("DXYP" )
(g) ND32 (""NOX-AC-$", "NOX-AN-$", "NOX-BIOB",
"NOX-FERT", "NOX-LI-$", "NOX-SOIL")
EXAMPLES:
BENCHMARK_1MON, 'input.1mon'
; Produces the full suite of benchmark output plots.
BENCHMARK_1MON, 'input.1mon', /DYNRANGE
; Produces the full suite of benchmark output plots.
; Will also produce an additional set of difference and
; ratio maps using the full dynamic range of the data.
BENCHMARK_1MON, 'input.1mon', /DEBUG, /NO_FREQ_DIST
; Will produce the standard plots except for the
; frequency distribution histogram. Also will cause
; extra information to be echoed to the screen.
MODIFICATION HISTORY:
bmy, 09 Nov 2007: VERSION 1.01
- based on "benchmark.pro"
bmy, 10 Jan 2011: VERSION 1.02
- Now set proper symbolic links to
diaginfo.dat and tracerinfo.dat
- Set 500hPa level for MERRA
- Added /NO_PROFILES keyword to suppress
printing of vertical profiles
bmy, 08 Jun 2011: VERSION 1.03
- Updated comments
- Added /NO_BUDGET, /NO_EMISSIONS,
/NO_PROFILES, /NO_CONC_MAPS, /NO_DIFFS,
/NO_JVALUES, /NO_RATIOS, /NO_FULLCHEM
keywords.
- Now pass _EXTRA=e to all routines
- Now use FILE_WHICH to locate the
diff_range.1mon file
- Now look for diaginfo.dat and
tracerinfo.dat in RUNDIR_2. Do not
use symbolic links anymore.
bmy, 10 Jun 2011: - Now call EMISSION_RATIOS
bmy, 23 Jun 2011 - Now call ZONAL_DIFF
bmy, 18 Jul 2011 - Now pass /PRESSURE keyword to ZONAL_DIFF
to create plots w/ pressure on Y-axis
bmy, 11 May 2012: GAMAP VERSION 2.16
- Now do not stop the run if the two model
grids are equivalent. This allows
comparisons between GEOS-5, MERRA,
GEOS-5.7 data.
- Return 500hPa level for GEOS-5.7 met
cdh, 18 Mar 2013: GAMAP VERSION 2.17
- Added Zonal concentration plots for !
1-month benchmarks
mps, 16 Sep 2013: - Now create AOD difference plots
- Now create AOD map plots
mps, 18 Nov 2013: - Read in Model_1 and Model_2 as printed in input
file. Previously, model names were converted to
filename extensions using CTM_NamExt.
- Update GetSfc500Levels to accept model names
- Rename all instances of GEOS57_47L to GEOSFP_47L
mps, 02 Dec 2013: - Now create difference plots for 2-D and 3-D
met fields
mps, 03 Dec 2013: - Now create absolute difference plots for J-values
mps, 21 Apr 2015: - Now create emission maps and emission difference
plots
mps, 11 Sep 2015: - Now create stratospheric benchmark plots showing
zonal mean differences and concentrations for
100-0.01 hPa
mps, 04 Mar 2016: - Include MERRA2 in the check for equivalent
vertical grids
mps, 29 Mar 2016: - Add plots for cloud optical depth
(See /n/home09/ryantosca/IDL/gamap2/benchmark/benchmark_1mon.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 /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/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.
/NC4 -> Write a netCDF4 file instead of netCDF3. Default is
NetCDF3. NetCDF4 support requires IDL 8.0 or later.
COMPRESS -> Integer 0-9 specifies amount of compression in
netCDF4 files. Default is 2, with very little benefit
for higher compression.
/PCOORD -> Use mean pressure as the vertical coordinate rather
sigma or eta
/ALTCOORD -> Use mean altitude as the vertical coordinate
rather than sigma or eta
/TROPONLY -> Write only tropospheric layers
/ONEFILE -> Write all data to one netCDF output file.
Default is one file per calendar day.
_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.
phs, 29 Oct 2009: GAMAP VERSION 2.14
- Can process files with 3D data on both
centers and edges of the grid boxes.
bmy, 19 Dec 2011: GAMAP VERSION 2.16
- Now handles multiple vertical dimensions
in the bpch file properly.
- Bug fix: now write vertical levels edges to
the file.
bmy, 27 Sep 2012: - Bug fix: Now handle data blocks that straddle
the date line.
bmy, 05 Nov 2013: GAMAP VERSION 2.17
- Change attributes for better COARDS compliance
bmy, 12 Feb 2014: GAMAP VERSION 2.18
- Add more modifications for 4-D data blocks
from bpch files created w/ GC_COMBINE_ND49
bmy, 03 Mar 2015: - Now define dims in order: time, lev, lon, lat,
which is more COARDS compliant.
cdholmes, 29 Mar 2017 - Add support for NetCDF4 and
compression
- Add support for pressure and altitude
as vertical coordinate
- ONEFILE puts all data into a single
output file
- TROPONLY limits the output to
troposphere layers
- Singleton "altXXX" dimensions are avoided
(See /n/home09/ryantosca/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.
bmy, 20 Dec 2011: GAMAP VERSION 2.16
- Changed default filename to "bpch2
(See /n/home09/ryantosca/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.
bmy, 18 Feb 2009: GAMAP VERSION 2.13
- Bug fix: should be N_ELEMENTS( DiagN )
instead of N_ELEMENTS( Category ) in the
IF statement for CTM_GET_DATA.
(See /n/home09/ryantosca/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.
(7) For pure-sigma grids (e.g. GEOS-1, GEOS-STRAT, GEOS-3),
BPCH2NC will write the following additional variables to
the netCDF file:
(1) SIGE : Sigma coordinate at level edges
(2) SIGC : Sigma coordinate at level centers
The pressure at the bottom edge of level L is given by:
Pe(L) = Ptop + [ SIGE(L) * ( Psurface - Ptop ) ]
and the pressure at the vertical center of level L is:
Pc(L) = Ptop + [ SIGC(L) * ( Psurface - Ptop ) ]
%%%%% NOTE: This is mostly obsolete, as most met fields
%%%%% that are used to drive CTM's are now placed onto
%%%%% hybrid grids.
(8) For hybrid grids (e.g. GEOS-4, GEOS-5, MERRA), the following
dditional variables will be written to the netCDF file:
(1) ETAE : Eta coordinate on level edges
(2) ETAC : Eta coordinate on level centers
(3) Ap : Hybrid grid "A" parameter
(4) Bp : Hybrid grid "B" parameter
The pressure at the bottom edge of level L is given by:
Pe(L) = Ap(L) + ( Bp(L) * Psurface )
and the pressure at the vertical center of level L is:
Pc(L) = ( Pe(L) + Pe(L+1) ) * 0.5
The hybrid ETA coordinates (similar to sigma) at the
level edges and centers are, correspondingly:
ETAE(L) = ( Pe(L) - Ptop ) / ( Psurface - Ptop )
ETAC(L) = ( Pc(L) - Ptop ) / ( Psurface - Ptop )
%%%%% NOTE: The ETAe and ETAc values are only approximate
%%%%% and are computed with a surface pressure of 1013.25
%%%%% hPa. For your scientific analysis, you should compute
%%%%% the pressures at level edges from Ap, Bp, and a
%%%%% spatially-varying surface pressure field (e.g. saved
%%%%% out from GEOS-Chem or another model).
(7) The date and time of the data are stored in the netCDF
file as global attributes.
(8) 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
bmy, 28 Nov 2008: GAMAP VERSION 2.15
- Now save out hybrid-grid Ap and Bp
parameters so that users can accurately
compute the pressure at level edges and
centers.
- Updated comments
bmy, 07 Mar 2012: GAMAP VERSION 2.16
- Correct typos in /VERBOSE output
(See /n/home09/ryantosca/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 /n/home09/ryantosca/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 /n/home09/ryantosca/IDL/gamap2/file_io/bpch_link.pro)
NAME:
BPCH_MONTHLY_MEAN
PURPOSE:
Creates monthly means from GEOS-Chem output saved at less
than monthly intervals. Ideal for working with output of
high-resolution model output, especially if your queuing
system time limits do not permit a 1-month simulation to be
completed in a single run stage.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH_MONTHLY_MEAN, FILES [, Keywords ]
INPUTS:
FILES -> A vector containing the pathnames of the files from
which you would like to create monthly mean output.
KEYWORD PARAMETERS:
OUTFILENAME -> Name of the file (bpch format) that will
contain the monthly mean output. The default is
"bpch_monthly_mean_output.bpch".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required
================================
REQUIREMENTS:
Requires other routines from the GAMAP package.
NOTES:
Assumes that each of the files passed via the FILES argument
contains an identical sequence of diagnostic data blocks.
This will normally be the case for GEOS-Chem simulations that
have to be separated into several run stages for the queue
system.
Error checking is minimal, we will fix this later. This
routine in intended for use with files that are created from
individual stages of a long GEOS-Chem simulation. As such,
we can usually assume that all files will have the same
sequence of data blocks, and that all data blocks will be on
the same grid.
EXAMPLE:
FILES = [ 'ctm.bpch.2011010100', 'ctm.bpch.2011011500' ]
BPCH_MONTHLY_MEAN, FILES, OUTFILENAME = 'monthly_mean.bpch'
; Creates monthly-mean output from two GEOS-Chem bpch
; files that contain 15-day averaged data.
MODIFICATION HISTORY:
bmy, 21 Dec 2011: GAMAP VERSION 2.16
- Initial version
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_monthly_mean.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, LL -> Longitude, latitude, altitude index arrays used
to cut down the data block to less than global size. Use
IDL notation, meaning first element is 0.
GLOBALCOORDS -> When the data entries in the bpch file
contain only part of the global CTM grid (e.g. ND48,
ND49, ND50, ND51) this indicates
that II, JJ, LL indices should be
interpreted as global CTM indices, rather than relative
to the regional subset grid.
EXCLUDE -> Reverses the selection criteria, so that the
designated DIAGN, TAU0, and TRACER are EXCLUDED from the
output file. Everything else is included. In order to be
excluded, a datablock must match all specified keywords:
DIAGN, TAU0, and TRACER.
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
bmy, 18 Jul 2016: GAMAP VERSION 2.19
- Now use the spacing obtained from
the diaginfo.dat file
cdh, 04 Apr 2017: -Add GlobalCoord keyword so that II,JJ,LL keywords
work with ND48, ND49, ND50 and ND51 output
-Prevent writing data when no matching
II,JJ,LL coordinates
(See /n/home09/ryantosca/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 change
bmy, 05 Feb 2013: GAMAP VERSION 2.17
- Now recognize FTI "CTM bin 4D", which is
output from gc_combine_nd49.pro etc.
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_test.pro)