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:
NCDF_GET
PURPOSE:
Convenience routine to read data into netCDF format.
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
DATA = NCDF_GET( FID, NAME [, Keywords ] )
INPUTS:
FID -> netCDF File ID, as returned by routine NCDF_OPEN.
NAME -> Name under which the data array will be saved
to the netCDF file.
KEYWORD PARAMETERS:
VARINFO -> Returns a structure containing information
about the variable read in from disk. The structure
has the following form:
{ NAME : "", $
DATATYPE : "", $
NDIMS : 0L, $
NATTS : 0L, $
DIM : LONARR(NDIMS) }
LONGNAME -> Returns the value saved under the "long_name"
attribute in the netCDF file.
UNIT -> Returns the value of the "unit" attribute
saved in the netCDF file.
RANGE -> Returns the value of the "valid_range"
saved in the netCDF file
_EXTRA=e -> Picks up extra keywords got NCDF_VarGet.
OUTPUTS:
DATA -> Array containing extracted data from the netCDF file.
SUBROUTINES:
Uses the following IDL netCDF routines:
========================================
NCDF_VarId (function) NCDF_VarGet
NCDF_VarInfo (function) NCDF_AttGet
NCDF_AttName (function)
REQUIREMENTS:
Need to use a version of IDL w/ netCDF routines installed.
NOTES:
(1) Only looks for the "long_name", "unit", and "valid_range"
attributes. The user can extend this as he/she desires.
For a more general program, see ~/IDL/tools/ncdf_read.pro
by Martin Schultz.
EXAMPLE:
; Define array to write to file
ARRAY = DIST( 100, 50 )
; Find out if netCDF is supported on this platform
IF ( NCDF_EXISTS() eq 0 ) then MESSAGE, 'netCDF not supported!'
; Open netCDF file and get the file ID # (FID)
FID = NCDF_OPEN( 'myfile.nc' )
IF ( FID lt 0 ) then Message, 'Error opening file!'
; Read data from the netCDF file
; Return data attributes in the VARINFO array
; Also returns the text from the UNIT string
DATA = NCDF_GET( FID, 'BIOBSRCE::NOx', $
VARINFO=VARINFO, UNIT=UNIT )
; Close the netCDF file
NCDF_CLOSE, FID
MODIFICATION HISTORY:
bmy, 22 May 2002: TOOLS VERSION 1.50
bmy, 21 Oct 2003: TOOLS VERSION 1.53
- If we can't find a netCDF variable name,
then try again using a "sanitized" name
w/ all bad characters stripped out
bmy, 28 Jun 2007: TOOLS VERSION 2.06
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Added /VERBOSE keyword to reduce
warning messages
(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_get.pro)
NAME:
NCDF_READ
PURPOSE:
Open a netCDF file and read data from it. The data is
returned as a structure whose tag names are the names of
the variables with blanks etc. replaced. If no variables
are specified with the VARIABLES keyword, only dimensional
information is returned. You can load all variables using
the ALL keyword. Other keyword options include OFFSET, COUNT, STRIDE,
NO_DIMENSIONS, NO_STRUCT, DIMNAMES, VARNAMES, VARDIMS, ATTRIBUTES.
Thus, this program includes ncdump functionality.
If no filename is given, a file selection dialog is
opened with the default mask '*.nc'. The name of the selected
file is returned in the TRUENAME keyword. A file selection
dialog also appears when the file cannot be found (see
OPEN_FILE.PRO). This can be turned off with the NO_DIALOG
keyword. The VERBOSE keyword provides information while
analyzing and reading the file.
AUTHOR:
Dr. Martin Schultz
Max-Planck-Institut fuer Meteorologie
Bundesstr. 55, D-20146 Hamburg
email: martin.schultz@dkrz.de
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
NCDF_READ, result, filename=, truename=,
variables=, all=, varnames=,
vardimid=, vardims=, attributes=,
count=, offset=, stride=,
dimnames=, dims=, no_dimensions=,
no_struct=, no_dialog=, verbose=, title=
ARGUMENTS:
RESULT(out) -> a structure containing all the variable data
from the netCDF file. If only one variable is specified
and the NO_STRUCT keyword set, then RESULT will be an
array instead of a structure. Use the ALL keyword
to load all variables at once. Note, that the COUNT, OFFSET,
and STRIDE keywords can affect the size of RESULT.
RESULT is set to -1L if an error occurs before the structure
has been built. You can use CHKSTRU.PRO to test for this.
KEYWORD PARAMETERS:
FILENAME(in) -> the name of the netCDF file to be opened.
NCDF_READ uses OPEN_FILE to check the validity of
the file first. You can specify a search mask
instead of a filename in which case a file selection
dialog is displayed (unless you set the NO_DIALOG
keyword). The TRUENAME keyword contains the name
of the selected file or an empty string if the
file selection was canceled.
TRUENAME(out) -> the (fully qualified) name of the file selected
with the file selection dialog or an unaltered copy
of FILENAME if FILENAME is a valid filename.
VARIABLES(in) -> a string array containing the names of variables
for which data shall be read. Default is to read
only the dimensional information from the file.
(Currently) no warning is issued if a variable is not in the file.
ALL(in) -> set this keyword to load all variables stored in the
netCDF file. Generally, you cannot usethis keyword together with
COUNT, OFFSET, and STRIDE.
VARNAMES(out) -> a string array containing the names of all variables
as stored in the file. Note, that the tag names of e.g. the
result structure are filtered with the Valid_TagName function.
VARDIMID(out) -> a structure with integer arrays containing the
dimension ID's for all variables. See also VARDIMS which returns
the dimensions themselves.
VARDIMS(out) -> a structure with integer arrays containing the
dimensions for all variables in the netCDF file. These are not
kept in sync with potential COUNT, OFFSET, and STRIDE values,
but reflect the data sizes as stored in the file.
ATTRIBUTES(out) -> a structure holding the variable and global
attributes stored in the netCDF file (global attributes
are stored in tag name GLOBAL).
COUNT(in) -> an integer array containing the number of values to
be read for each dimension of the variables. Mapping of the
COUNT dimensions to the variable dimensions is achieved via
the first entry in the VARIABLES list and the COUNT parameter
will be applied to all variables that have that dimension.
Example: The first variable has dimensions LON, LAT, LEV,
the second variable has dimensions LON, LAT, and the third
variable has LAT, LEV. A COUNT of [40,20,10] would lead to
result dimensions of [40,20,10], [40,20], and [20,10].
OFFSET(in) -> an integer array containing the offsets for each
dimension of the variables to be read. Dimension mapping
is the same as for COUNT.
STRIDE(in) -> an integer array containing the stride for each
dimension of the variables to be read. Dimension mapping
is the same as for COUNT.
DIMNAMES(out) -> a string array containing the names of the
dimensions stored in the netCDF file.
DIMS(out) -> a long array containing the dimension values. Purely
for convenience. Use VARDIMS to retrieve the dimensions of
the variables.
TITLE(in) -> A title for the file selection dialog if an
incomplete or incorrect filename is specified. This
keyword is ignored if the no_dialog keyword is set.
NO_DIMENSIONS(in) -> set this keyword if you do not want to store
the dimensional variables from the file in the result structure.
DIMNAMES and DIMS will still be retrieved.
NO_STRUCT(in) -> if only one variable is selected with the
VARIABLE keyword, you can set this keyword to return only
the data for this variable as an array. This keyword implies
the functionality of NO_DIMENSIONS.
NO_DIALOG(in) -> set this keyword if you do not want interactive
behaviour when a file mask is given instead of a filename or
when the specified file does not exist.
VERBOSE(in) -> set this keyword to get detailed information while
reading the netCDF file.
SUBROUTINES:
Valid_TagName : replaces invalid characters in variable names so that
a structure can be built.
ncdf_attributes : retrieves global and variable attributes from netcdf
file and stores them as structure.
ncdf_dimensions : retrieves size and name for all dimensions in netcdf file.
ncdf_varnames : retrieves names and dimension information for all variables
in the netCDF file.
ncdf_mapdims : map dimension indices for COUNT, OFFSET, and STRIDE with
dimensions of first selected variable.
ncdf_TestDimensions : compute the COUNT, OFFSET, and STRIDE vectors that
must be applied for retrieving the data of one variable.
REQUIREMENTS:
uses OPEN_FILE and STRREPL.
NOTES:
Correct handling of dimensional information requires that the variables
storing the dimension values have the same name as the dimensions
themselves - a common feature in most netCDF standards.
I am still working on a netcdf file object which will be even
more powerful. At some point ncdf_read will only be a
procedure interface to this objec!
EXAMPLE:
ncdf_read,result,/All
; plot ozone vs. temperature
plot,result.temperature,result.ozone
MODIFICATION HISTORY:
mgs, 18 Sep 1999: VERSION 1.00
mgs, 29 Feb 2000: - added variables keyword
- added CATCH error handler
mgs, 21 Mar 2000: - bug fix for tag names
mgs, 09 May 2000: VERSION 2.00
- now only reads dimensions as default
- added ALL keyword to compensate
- returns dimnames and attributes
(makes ncdf_detail obsolete)
- added COUNT, OFFSET and STRIDE keywords
- added NO_DIMENSIONS and NO_DIALOG
keywords and more
mgs, 22 Aug 2000: - added title keyword
bmy, 22 May 2002: GAMAP VERSION 1.50
- Now replace ":", "=", "#" with "_" in
structure tag names, so IDL won't choke
bmy, 21 Oct 2003: GAMAP VERSION 1.53
- also replace "(" and ")" in tag names
- replace "$" with "S" (close to dollar sign)
- replace "*" with "A" (for Asterisk)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_read.pro)
NAME:
NCDF_SET
PURPOSE:
Convenience routine to write data into netCDF format.
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
NCDF_SET, FID, DATA, NAME, DIMS [, Keywords ]
INPUTS:
FID -> netCDF File ID, as returned by routine NCDF_CREATE.
DATA -> Data (array or scalar) to be written to netCDF file.
NAME -> Name under which the data array will be saved
to the netCDF file.
KEYWORD PARAMETERS:
LONGNAME -> Longer descriptive name for the data.
This will be saved as the "long_name" attribute.
RANGE -> A 2-element vector containing the [min,max] of
the data array. If not passed, RANGE will be computed
(but only if DATA is a numeric type). RANGE is saved
to the netCDF file as the "valid_range" attribute.
UNIT -> String containing the units of the data.
This will be saved as the "unit" attribute.
_EXTRA=e -> Picks up extra keywords
OUTPUTS:
None
SUBROUTINES:
Uses the following routines:
=====================================================
NCDF_Control NCDF_VarDef (function)
NCDF_AttPut DATATYPE (function from TOOLS)
NCDF_VarPut NCDF_VALID_NAME (function from TOOLS)
REQUIREMENTS:
Need to use a version of IDL w/ netCDF routines installed.
NOTES:
(1) For now, treat BYTE data like CHAR data. This is
most likely since netCDF does not support STRING types,
strings have to be stored as arrays of bytes.
EXAMPLE:
; Define array to write to file
ARRAY = DIST( 100, 50 )
; Find out if netCDF is supported on this platform
IF ( NCDF_EXISTS() eq 0 ) then MESSAGE, 'netCDF not supported!'
; Open netCDF file and get the file ID # (FID)
FID = NCDF_CREATE( 'myfile.nc', /CLOBBER )
IF ( FID lt 0 ) then Message, 'Error opening file!'
; Set dimensions for netCDF file
S = SIZE( ARRAY, /DIM )
DIM1 = NCDF_DIMDEF( FID, 'Length', S[0] )
DIM2 = NCDF_DIMDEF( FID, 'Width', S[1] )
; Go into netCDF DATA mode
NCDF_CONTROL, FID, /ENDEF
; Call NCDF_SET to write the array to the file
NCDF_SET, FID, ARRAY, 'My Data', [ DIM1, DIM2 ], $
LONGNAME='Data array created by me!', $
UNIT='unitless'
; Close the netCDF file
NCDF_CLOSE, FID
MODIFICATION HISTORY:
bmy, 19 Apr 2002: TOOLS VERSION 1.50
bmy, 10 Sep 2002: TOOLS VERSION 1.51
- Now call routine DATATYPE to determine
the type of the data so that we can
write to the netCDF file appropriately
- Don't add the RANGE attribute to
the netCDF file for a string type value.
- Updated comments
bmy, 21 Oct 2003: TOOLS VERSION 1.53
- now "sanitize" the netCDF variable name
w/ routine NCDF_VALID_NAME. The new netCDF
library in IDL 6.0+ chokes on bad characters.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_set.pro)
NAME:
NCDF_VALID_NAME
PURPOSE:
Strips invalid characters from a string which is to be
used as a netCDF variable name. Based on original code
by Martin Schultz.
CATEGORY:
File & I/O, Scientific Data Formats
CALLING SEQUENCE:
RESULT = NCDF_VALID_NAME( ARG )
INPUTS:
ARG -> netCDF variable name string to be examined.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> New netCDF name string with "bad" characters
replaced by "good" characters.
SUBROUTINES:
External Subroutines Used:
==========================
STRREPL (function)
REQUIREMENTS:
None
NOTES:
In IDL 6.0+, the netCDF library has been updated. Some
characters which used to be allowed in netCDF variable names
are no longer allowed. Therefore, use this function to
replace "bad" characters with "good" characters when
reading or writing to/from netCDF files.
EXAMPLE:
RESULT = NCDF_VALID_NAME( 'IJ-AVG-$::CO' )
PRINT, RESULT
; Prints "IJ-AVG-S__CO"
MODIFICATION HISTORY:
bmy, 21 Oct 2003: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_valid_name.pro)
NAME:
NUMDEN
PURPOSE:
Calculates the number density of air for a given temperature
and pressure.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
RESULT = NUMDEN( T, P, /DOUBLE )
INPUTS:
T -> Temperature (or vector of temperatures) in K.
P -> Pressure (or vector of pressures) in hPa.
Default is 1000 hPa.
KEYWORD PARAMETERS:
/DOUBLE -> Set this switch to return the number density
in double precision. Default is to return the number
density in single precision.
OUTPUTS:
RESULT -> Number density of air in molec/cm3. If T and
P are vectors, then RESULT will be a vector of
number densities
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, NUMDEN( 298.0, 1013.0 )
2.46206e+19
; Prints the number density of air
; at 298K and 1013 hPa.
(2)
PRINT, NUMDEN( 298.0, 1013.0, /DOUBLE )
2.4620635e+19
; Prints the number density of air ; at 298K and
; 1013 hPa. Computation is done in double precision.
MODIFICATION HISTORY:
dbm, 30 Jul 2007: GAMAP VERSION 2.10
phs, 1 Sep 2009: GAMAP VERSION 2.13
- let you pass array
(See /n/home09/ryantosca/IDL/gamap2/atm_sci/numden.pro)
NAME:
NYMD2TAU (function)
PURPOSE:
Computes the value of TAU, which is the elapsed hours between
the current date/time and the beginning of an epoch. This is
the starting date for 3D model data assimilation.
CATEGORY:
Date & Time
CALLING SEQUENCE:
RESULT = NYMD2TAU( NYMD, [NHMS [,NYMD0, NHMS0]] )
INPUTS:
NYMD (long) -> YY/MM/DD for this date (e.g. 940101)
You can either specify year as 4 digits or 2 digits.
With 2 digits, year < 50 will be assumed to be 2000+YY.A
NHMS (long) -> HH/MM/SS for this date (e.g. 060000)
will be defaulted to 000000
NYMD0 (long) -> YY/MM/DD for the start of the epoch
default is {19}850101 which is the GEOS-1 start
NHMS0 (long) -> HH/MM/SS for the start of the epoch
will be defaulted to 000000
KEYWORD PARAMETERS:
/GEOS1 -> use 1985/01/01 as epoch start
/GISS_II -> use 1980/01/01 as epoch start
OUTPUTS:
RESULT -> The function returns the TAU value as a
double-precision number
SUBROUTINES:
NYMD2STRU : extracts year, month, day, hour, minute and seconds from
NYMD and NHMS values.
JULDAY (IDL user library procedure)
REQUIREMENTS:
NOTES:
Function NYMD2STRU is also contained in function TAU2YYMMDD.
Take care when changes are necessary !
EXAMPLE:
; (1) Compute TAU value for 0h on Jan 1, 1994, with the
; epoch starting on 0h on Jan 1, 1980 (GISS II value).
;
TAU = nymd2tau( 940101L, 0L, 800101L, 0L )
; (2) Compute TAU value for 0h on Jan 1, 1994, for the
; default GEOS-1 epoch (850101L, 0L).
;
TAU = nymd2tau( 940101L, 0L )
; (3) Compute GISS model II tau values for the first of
; each month in 1990
date = [ 900101L, 900201L, 900301L, 900401L, 900501L, 900601L, $
900701L, 900801L, 900901L, 901001L, 901101L, 901201L ]
tau = nymd2tau(date,/GISS)
MODIFICATION HISTORY:
bmy, 26 Mar 1998: VERSION 1.00
mgs, 26 Mar 1998: - now year 2000 compliable
mgs, 23 Mar 1999: - now handles vectors as input
bmy, 23 Mar 2005: GAMAP VERSION 2.03
- Added /NO_Y2K keyword to suppress
special Y2K treatment of dates (i.e.
treat dates w/ 2 digits as from 1900's)
- renamed internal function NYMD2STRU to
N2T_NYMD2STRU to avoid conflict with
similar function in "tau2yymmdd.pro"
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/date_time/nymd2tau.pro)
NAME:
N_UNIQ (function)
PURPOSE:
Returns the number of unique elements in an array.
CATEGORY:
General
CALLING SEQUENCE:
Result = N_UNIQ( Arr )
INPUTS:
ARR -> The array to be searched for unique values.
KEYWORD PARAMETERS:
None
OUTPUTS:
Returns the number of unique values in ARR as the value
of the function
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, N_UNIQ( [10, 20, 30] )
3
(2)
PRINT, N_UNIQ( [10,10] )
1
MODIFICATION HISTORY:
bmy, 17 Nov 1998: VERSION 1.00
mgs, 17 Nov 1998: - little streamlining
mgs, 16 Mar 1999: - don't print out warning for empty argument
and return 0 instead of -1
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/n_uniq.pro)