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:
ARREX (function)
PURPOSE:
This function extracts a multi-dimensional subset
of an array. For each dimension the start index,
end index, and stride can be specified - default values
are 0 (i.e. first start index), "all" (i.e. last end
index), and 1 (i.e. every element). A negative stride
causes reversion of the respective array dimension.
CATEGORY:
Math & Units
CALLING SEQUENCE:
Result = ARREX(Array [, Starti [,Endi [, Stride ]]] [,/Reform])
INPUTS:
ARRAY -> The parent array from which the extraction shall be made.
Currently up to 4 dimensions are supported.
STARTI -> An array with starting indices. Each element of STARTI
corresponds to one dimension of ARRAY. If STARTI has less
elements than ARRAY dimensions, the remainder is assumed 0.
ENDI -> An array with ending indices. Each element of ENDI
corresponds to one dimension of ARRAY. If ENDI has less
elements than ARRAY dimensions, the remainder is set to the
maximum possible value for that dimension.
STRIDE -> An array with stride values. A stride of 1 (default)
signifies extraction of every element, 2 returns every
second element for that dimension, etc. Negative values
cause the respective dimension to be reversed.
Each value of STRIDE corresponds to one dimension of ARRAY.
If STRIDE has less elements than ARRAY dimensions, the
remainder is assumed 1.
KEYWORD PARAMETERS:
/REFORM -> Set this keyword to eliminate unnecessary dimensions
in the result.
OUTPUTS:
A subset of the original array. This will have the same
dimensionality as ARRAY unless the REFORM keyword is set.
SUBROUTINES:
Function arrex_ComputeInd
REQUIREMENTS:
None
NOTES:
Created after discussion in newsgroup idl-pvwave.
This version contains some debug output.
EXAMPLE:
A = indgen(10,10)
print,arrex(A,[2,1],-1,[2,4])
; yields 12 14 16 18
; 52 54 56 58
; 92 94 96 98
print,arrex(A,[10,1],[1,10],[5,5])
; yields 19 15
; 69 65
; note that stride for dimension 1 is adjusted automatically.
MODIFICATION HISTORY:
mgs, 20 May 1999: VERSION 1.00
- with a lot of input from
L. Gumley, S. Vidar, and others
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/arrex.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:
CMSET_OP
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Performs an AND, OR, or XOR operation between two sets
CATEGORY:
Math & Units
CALLING SEQUENCE:
SET = CMSET_OP(A, OP, B)
DESCRIPTION:
SET_OP performs three common operations between two sets. The
three supported functions of OP are:
OP Meaning
'AND' - to find the intersection of A and B;
'OR' - to find the union of A and B;
'XOR' - to find the those elements who are members of A or B
but not both;
Sets as defined here are one dimensional arrays composed of
numeric or string types. Comparisons of equality between elements
are done using the IDL EQ operator.
The complements of either set can be taken as well, by using the
NOT1 and NOT2 keywords. For example, it may be desireable to find
the elements in A but not B, or B but not A (they are different!).
The following IDL expressions achieve each of those effects:
SET = CMSET_OP(A, 'AND', /NOT2, B) ; A but not B
SET = CMSET_OP(/NOT1, A, 'AND', B) ; B but not A
Note the distinction between NOT1 and NOT2. NOT1 refers to the
first set (A) and NOT2 refers to the second (B). Their ordered
placement in the calling sequence is entirely optional, but the
above ordering makes the logical meaning explicit.
NOT1 and NOT2 can only be set for the 'AND' operator, and never
simultaneously. This is because the results of an operation with
'OR' or 'XOR' and any combination of NOTs -- or with 'AND' and
both NOTs -- formally cannot produce a defined result.
The implementation depends on the type of operands. For integer
types, a fast technique using HISTOGRAM is used. However, this
algorithm becomes inefficient when the dynamic range in the data
is large. For those cases, and for other data types, a technique
based on SORT() is used. Thus the compute time should scale
roughly as (A+B)*ALOG(A+B) or better, rather than (A*B) for the
brute force approach. For large arrays this is a significant
benefit.
INPUTS:
A, B - the two sets to be operated on. A one dimensional array of
either numeric or string type. A and B must be of the same
type. Empty sets are permitted, and are either represented
as an undefined variable, or by setting EMPTY1 or EMPTY2.
OP - a string, the operation to be performed. Must be one of
'AND', 'OR' or 'XOR' (lower or mixed case is permitted).
Other operations will cause an error message to be produced.
KEYWORDS
NOT1, NOT2 - if set and OP is 'AND', then the complement of A (for
NOT1) or B (for NOT2) will be used in the operation.
NOT1 and NOT2 cannot be set simultaneously.
EMPTY1, EMPTY2 - if set, then A (for EMPTY1) or B (for EMPTY2) are
assumed to be the empty set. The actual values
passed as A or B are then ignored.
INDEX - if set, then return a list of indices instead of the array
values themselves. The "slower" set operations are always
performed in this case.
The indices refer to the *combined* array [A,B]. To
clarify, in the following call: I = CMSET_OP(..., /INDEX);
returned values from 0 to NA-1 refer to A[I], and values
from NA to NA+NB-1 refer to B[I-NA].
COUNT - upon return, the number of elements in the result set.
This is only important when the result set is the empty
set, in which case COUNT is set to zero.
RETURNS
The resulting set as a one-dimensional array. The set may be
represented by either an array of data values (default), or an
array of indices (if INDEX is set). Duplicate elements, if any,
are removed, and element order may not be preserved.
The empty set is represented as a return value of -1L, and COUNT
is set to zero. Note that the only way to recognize the empty set
is to examine COUNT.
SEE ALSO:
SET_UTILS.PRO by RSI
MODIFICATION HISTORY:
Written, CM, 23 Feb 2000
Added empty set capability, CM, 25 Feb 2000
Documentation clarification, CM 02 Mar 2000
Incompatible but more consistent reworking of EMPTY keywords, CM,
04 Mar 2000
Minor documentation clarifications, CM, 26 Mar 2000
Corrected bug in empty_arg special case, CM 06 Apr 2000
Add INDEX keyword, CM 31 Jul 2000
Clarify INDEX keyword documentation, CM 06 Sep 2000
Made INDEX keyword always force SLOW_SET_OP, CM 06 Sep 2000
Added CMSET_OP_UNIQ, and ability to select FIRST_UNIQUE or
LAST_UNIQUE values, CM, 18 Sep 2000
Removed FIRST_UNIQUE and LAST_UNIQUE, and streamlined
CMSET_OP_UNIQ until problems with SORT can be understood, CM, 20
Sep 2000 (thanks to Ben Tupper)
Still trying to get documentation of INDEX and NOT right, CM, 28
Sep 2000 (no code changes)
Correct bug for AND case, when input sets A and B each only have
one unique value, and the values are equal. CM, 04 Mar 2004
(thanks to James B. jbattat at cfa dot harvard dot edu)
Add support for the cases where the input data types are mixed,
but still compatible; also, attempt to return the same data
type that was passed in; CM, 05 Feb 2005
Fix bug in type checking (thanks to "marit"), CM, 10 Dec 2005
Work around a stupidity in the built-in IDL HISTOGRAM routine,
which tries to "help" you by restricting the MIN/MAX to the
range of the input variable (thanks to Will Maddox), CM, 16 Jan 2006
$Id: cmset_op.pro,v 1.4 2007/11/20 21:55:32 bmy Exp $
(See /n/home09/ryantosca/IDL/gamap2/math_units/cmset_op.pro)
NAME:
CONVERT_KG_MOLCM2
PURPOSE:
Converts the units of a 2-D array from kg to molecules/cm2
(or kg/s to molecules/cm2/s).
CATEGORY:
Math & Units
CALLING SEQUENCE:
CONVERT_KG_MOLCM2, DATA, AREACM2, KGPERMOLE
INPUTS:
DATA -> 2-D array of data values in units of
kg or kg s^-1.
AREACM2 -> 2-D array containing the surface area of each
gridbox in cm^2
KGPERMOLE -> The molecular weight of the tracer or
molecule, in units of kg mole^-1.
OUTPUTS:
DATA -> The converted array in molecules cm^-2 s^-1
is returned in DATA.
KEYWORD PARAMETERS:
None
SUBROUTINES:
None
REQUIREMENTS:
CTM_SURFACE_AREA must be called to compute the AREACM2 array.
TRACER_KG_PER_MOLE (or a similar subroutine) must be called
to compute the KGPERMOLE array.
NOTES:
None
EXAMPLE:
AreaCm2 = CTM_SURFACE_AREA( GridInfo, /cm2, /GEOS )
KgPerMole = TRACER_KG_PER_MOLE( /FULLCHEM )
TracerNumber = 1 ; for NOx
CONVERT_KG_MOLCM2, Data, AreaCm2, KgPerMole(TracerNumber)
; Will convert the Data array for the GEOS-1 model (using
; the molecular weight for NOx) from kg/s to molecules/cm2/s.
MODIFICATION HISTORY:
bmy, 07 Apr 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/convert_kg_molcm2.pro)
NAME:
CONVERT_MOLCM2_KG
PURPOSE:
Converts the units of a 2-D or 3-D array from molecules/cm2
to kg (or, equivalently, from molecules/cm2/s to kg/s).
CATEGORY:
Math & Units
CALLING SEQUENCE:
CONVERT_MOLCM2_KG, DATA, AREACM2, KGPERMOLE
INPUTS:
DATA -> 2-D or 3-D array of data values in units of
molecules cm^-2 or molecules cm^-2 s^-1.
AREACM2 -> 2-D array containing the surface area of each
gridbox in cm^2
KGPERMOLE -> The molecular weight of the tracer or
molecule, in units of kg/mole.
OUTPUTS:
DATA -> The converted array in kg/s is returned in DATA.
DATA is returned with the same dimensions as
it had when it was passed to CONVERT_MOLCM2_KG.
KEYWORD PARAMETERS:
None
SUBROUTINES:
None
REQUIREMENTS:
CTM_SURFACE_AREA must be called to compute the AREACM2 array.
TRACER_KG_PER_MOLE (or a similar subroutine) must be called
to compute the KGPERMOLE array.
NOTES:
EXAMPLE:
AreaCm2 = CTM_SURFACE_AREA( GridInfo, /cm2, /GEOS )
KgPerMole = TRACER_KG_PER_MOLE( /FULLCHEM )
TracerNumber = 1 ; for NOx
CONVERT_MOLCM2_KG, Data, AreaCm2, KgPerMole
Will convert the Data array for the GEOS-1 model (using
the molecular weight for NOx) from molecules/cm2/s to kg/s.
MODIFICATION HISTORY:
bmy, 07 Apr 1998: VERSION 1.00
bmy, 09 Apr 1998: VERSION 1.01
- DATA can now be a 2-D or 3-D array.
- KgPerMole can now be an array of the same
dimension as the 3rd dimension of Data.
bmy, 07 Oct 1998: VERSION 1.02
- now uses MESSAGE statement
- also uses [] instead of () for array
indices
bmy 23 Nov 1998: VERSION 2.00
- now uses double precision array NEWDATA
to avoid overflow/underflow errors
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/convert_molcm2_kg.pro)
NAME:
CONVERT_UNIT
PURPOSE:
Convert data to a different unit. You can either
replace a unit by the corresponding standard SI unit or
replace a specific unit with another one.
CATEGORY:
Math & Units
CALLING SEQUENCE:
CONVERT_UNIT,DATA,UNIT,TOPARAM [,keywords]
INPUTS:
DATA -> A data vector, array, or a single value that shall
be converted to a new unit.
UNIT -> A string variable containing the (current) unit of
DATA. This will be replaced by the new unit afterwards.
If omitted, you must give the FROM_UNIT keyword to indicate
the current unit of DATA.
TOPARAM -> The unit to convert DATA to. This is equivalent to
the keyword TO_UNIT and overwrites it.
KEYWORD PARAMETERS:
FROM_UNIT -> An individual unit to search and replace. If not
given, any unit will be converted to TO_UNIT, as long as
the current unit belongs to the same category.
TO_UNIT -> An individual unit to convert to. If not given, all
unit that are converted (see FROM_UNIT) will be replaced
by the standard SI unit of their category.
For the individual unit and categories see FIND_UNIT
RESULT -> returns 1 if conversion was successful, 0 otherwise
This keyword is mostly for consistency witholder routines.
It is more convenient to test !ERROR_STATE.CODE for being
0.
MINVAL -> minimum valid data value. Only data above this
value will be converted (default: -1.E30)
QUIET -> In case of an error, an error message is displayed,
and the !ERROR_STATUS system variable is set to reflect the
error condition (program execution continues). Set the
QUIET keyword to suppress the error message.
OUTPUTS:
DATA will be converted and unit will contain new names.
SUBROUTINES:
Uses FIND_UNIT
REQUIREMENTS:
None
NOTES:
CONVERT_UNIT wil return the value and unit unchanged if
the unit was not found in the standard list (see FIND_UNIT)
or the category of the target unit does not match the
category of the source unit. In these cases, !ERROR_STATE.CODE
will be set to signal an error condition.
EXAMPLE:
; create some data
data = findgen(100)
unit = 'cm'
; convert all data to SI unit of same category (m)
convert_unit,data,unit
; test success
if (!ERROR_STATE.CODE ne 0) then stop
; convert temperature in Fahrenheit to 'deg C'
; (multiple calls to capture all different spellings)
; Data will only be changed if unit is indeed Fahrenheit
convert_unit,data,unit,from='F',to='deg C'
convert_unit,data,unit,from='degF',to='deg C'
convert_unit,data,unit,from='deg F',to='deg C'
; (easier way) convert any temperature to 'C'
; This will also convert 'K' !
; Don't display error message
convert_unit,data,unit,to='C',/QUIET
; convert 'mph' data to SI ('m/s')
convert_unit,data,unit,from='mph'
; explicitely convert 'cm' to 'm'
convert_unit,data,'cm','m'
; equivalent to
convert_unit,data,from='cm',to='m'
MODIFICATION HISTORY:
mgs, 26 Aug 1998: VERSION 1.00
mgs, 27 Aug 1998:
- added RESULT and QUIET keywords
- improved error handling
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/convert_unit.pro)
NAME:
CUM_TOTAL (function)
PURPOSE:
Compute cumulative total of a data vector.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = CUM_TOTAL(Y)
INPUTS:
Y -> The data vector
KEYWORD PARAMETERS:
None
OUTPUTS:
A data vector with the same number of elements
and the cumulative totals.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
See also function RUN_AV.
EXAMPLE:
Y = FINDGEN(10)
PRINT, CUM_TOTAL(Y)
; IDL prints: 0 1 3 6 10 15 21 28 36 45
MODIFICATION HISTORY:
mgs, 21 Oct 1998: VERSION 1.00
bmy, 23 May 2007: TOOLS VERSION 2.06
- Now use longword for loop counter
- Updated comments, cosmetic changes
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/cum_total.pro)
NAME:
FCONVERT_UNIT (function)
PURPOSE:
Wrapper for CONVERT_UNIT. Passes all of the input data to
CONVERT_UNIT and returns the result to the calling program.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = FCONVERT_UNIT( DATA, UNIT, TOPARAM [, Keywords ] )
INPUTS:
DATA -> A data vector, array, or a single value that shall
be converted to a new unit.
UNIT -> A string variable containing the (current) unit of
DATA. This will be replaced by the new unit afterwards.
If omitted, you must give the FROM_UNIT keyword to
indicate the current unit of DATA.
TOPARAM -> The unit to convert DATA to. This is equivalent to
the keyword TO_UNIT and overwrites it.;
KEYWORD PARAMETERS:
RESULT -> returns 1 if conversion was successful, 0 otherwise
This keyword is mostly for consistency witholder routines.
It is more convenient to test !ERROR_STATE.CODE for being
0.
_EXTRA=e -> Passes extra keywords to CONVERT_UNIT.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
CONVERT_UNIT
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
MODIFICATION HISTORY:
mgs, 26 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Added std documentation header
(See /n/home09/ryantosca/IDL/gamap2/math_units/fconvert_unit.pro)
NAME:
FIND_UNIT
PURPOSE:
Return classification and conversion information for
physical units. You pass a unit name, and you will
get a standard form of that name as well as a factor
and an offset that convert the unit to SI standard.
To convert one unit to another, use FIND_UNIT twice
(see example below).
CATEGORY:
Math & Units
CALLING SEQUENCE:
FIND_UNIT,NAME,STDNAME,FACTOR,OFFSET,CATEGORY [,keywords]
INPUTS:
NAME -> A string containing the name to search for
KEYWORD PARAMETERS:
/GET_SI -> Return the name of the SI unit of the category of
the given unit. Factor and offset will always be 1.0 and
0.0, CATEGORY will contain the category number.
/NO_STANDARD -> Do not return the standard name of a unit. The
standard spelling is identified as the first occurrence
of a given unit with the same conversion factor and offset
in the same category and normally replaces the input name.
/TEST -> Check standard unit strings for consistency
This keyword is only useful when you add extra units.
OUTPUTS:
STDNAME -> The unit name as saved in the stdunits array
(e.g. 'KG' is returned as 'kg')
FACTOR -> A conversion factor to SI
OFFSET -> A conversion offset
CATEGORY -> The class to which the unit belongs:
-1 : unit not found
0 : distance
1 : area
2 : volume
3 : time
4 : frequency
5 : speed
6 : accelaration
7 : temperature
8 : weight
9 : pressure
10 : force
11 : energy
12 : power
13 : mixing ratio
14 : currency
15 : voltage
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
FIND_UNIT,'kM/H',stdname,factor,offset,category
print,stdname,factor,offset,category
; prints km/h 0.277780 0.00000 5
; conversion from Fahrenheit to Celsius
temp = [ 0., 32., 80., 100. ]
FIND_UNIT,'F',fromname,fromfac,fromoff,fromcat
FIND_UNIT,'C',toname,tofac,tooff,tocat
if (fromcat ne tocat) then print,'bullsh...'
ctemp = ((fromfac*temp+fromoff) - tooff) / tofac
print,ctemp
; prints -17.7778 0.000152588 26.6670 37.7782
; find name of corresponding SI unit
FIND_UNIT,'mph',stdname,/get_si
print,stdname
; prints m/s
; find standard form of any unit
FIND_UNIT,'miles/hour',stdname
print,stdname
; prints mph
MODIFICATION HISTORY:
mgs, 26 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/find_unit.pro)
NAME:
MEAN
PURPOSE:
Computes the mean value of an array, along a given dimension.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = MEAN( X, DIM, _EXTRA=e )
INPUTS:
X -> The input vector or array.
DIM -> The dimension along which to compute the mean of X.
DIM may be omitted if the X is 1-dimensional.
KEYWORD PARAMETERS:
_EXTRA=e -> Passes extra keywords to the TOTAL command.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
Multidimensional version from Kevin Ivory (04/03/1997)
EXAMPLES:
(1)
PRINT, MEAN( FINDGEN(10) )
IDL prints:
4.50000
; Prints the mean of a 1-D array
(2)
ARRAY = MEAN( DIST(10,10), 2 )
HELP, ARRAY
PRINT, ARRAY
IDL prints:
ARRAY FLOAT = Array[10]
2.50000 2.79703 3.36695 4.08519 4.89073
5.75076 4.89073 4.08519 3.36695 2.79703
; Prints the mean of a 2-D array along
; the second dimension.
MODIFICATION HISTORY:
ivory, 04 Mar 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Cosmetic changes, added comments
(See /n/home09/ryantosca/IDL/gamap2/math_units/mean.pro)
NAME:
MULTISORT
PURPOSE:
hierarchical sorting of a data set, each column can be sorted
reversely. Works well together with W_SORT, a widget interface
that handles up to three sort levels/columns. COLUMNS are defined
as first array index (e.g. DATA=FLTARR(5,20) has 5 columns).
CATEGORY:
Math & Units
CALLING SEQUENCE:
multisort,data,index=index,revert=revert
INPUTS:
DATA --> a 2D array to be sorted
KEYWORD PARAMETERS:
INDEX --> an integer or integer array containing the indices for
which the array shall be sorted (e.g. [ 3,1,0 ] will sort DATA
first by column 3, then within groups of same values for column
3 values will be sorted by column 1, and finally by column 0.
Default is to sort by the first column.
REVERT --> an integer or integer array indicating which columns shall
be sorted in reverse order. REVERT=1 reverts all sorting,
REVERT=[0,1,0] reverts the sort order only for the 2nd column.
Default is 0, i.e. do not revert.
OUTPUTS:
The DATA array will be sorted according to the specifications.
SUBROUTINES:
testsort : little test program (historic debugging purposes)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
MULTISORT, DATA, INDEX=[3,1,0], REVERT=[0,1,0]
; Sort data first in column 3, then in reverse order
; for column 1, and finally ascending order for column 0.
MODIFICATION HISTORY:
mgs, 30 Jun 1997: VERSION 1.00
mgs, 08 Apr 1998: - now stand-alone routine and documentation
mgs, 22 Dec 1998: - bug fix (startindex must be -1)
mgs, 17 Mar 1999: - bug fix: now has default 0 for revert
(thanks to G. Fireman)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/multisort.pro)
NAME:
ORG_CORR
PURPOSE:
Calculate reduced major axis. Given two vectors X and Y, this
subroutine computes the Gradient and Y intercept of the line
given by the reduced major axis. The main advantage of this
is that the best fit line of X and Y will be the same as the
best fit line of Y and X.
CATEGORY:
Math & Units
CALLING SEQUENCE:
ORG_CORR, X, Y, R, NP, GRADIENT, INTERCEPT, $
GRADIENT_ERR, INTERCEPT_ERR [, VERBOSE=VERBOSE ]
INPUTS:
X -> Vector containing X-axis values.
Y -> Vector containing Y-axis values.
R -> Correlation coefficient
NP -> Number of elements of X and Y arrays to process.
NP should be smaller than or equal to the number of
elements of X and Y.
KEYWORD PARAMETERS:
/VERBOSE -> Set this switch to print the gradient,
intercept, and standard errors to the screen.
The default is not to print these values.
OUTPUTS:
GRADIENT -> Gradient of reduced major axis
INTERCEPT -> Y-Intercept of reduced major axis
GRADIENT_ERR -> Standard error in gradient.
INTERCEPT_ERR -> Standard error in Y-intercept.
SUBROUTINES:
External Subroutines Required:
==============================
SIGN (function)
REQUIREMENTS:
References routines from the TOOLS package.
NOTES:
(1) More details are in Hirsch and Gilroy, Water Res. Bull.,
20(5), Oct 1984.
(2) Standard errors also calculated according to Miller and
Kahn, Statistical Analysis in the Geological Sciences,
1962, pp. 204-210.
(3) Computations are now performed in double precision.
EXAMPLE:
MODIFICATION HISTORY:
pip, clh, bmy, 10 Oct 2002: TOOLS VERSION 1.52
bmy, 26 Jan 2007: TOOLS VERSION 2.06
- Now compute gradient of YNEW with max
& min values & subscripts of. This avoids
the assumption that the first & last
elements of YNEW are different.
(Fix submitted by Mike Barkley, 1/26/07)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/org_corr.pro)
NAME:
PERCENTILES
PURPOSE:
Compute percentiles of a data array (both ways: data that
correspond to %, and % that correspond to data)
CATEGORY:
Math & Units
CALLING SEQUENCE:
Y = PERCENTILES( DATA [,VALUE=value-array] )
INPUTS:
DATA -> the vector containing the data
KEYWORD PARAMETERS:
VALUE --> array or scalar that specify percentile(s) to
compute. If /REVERSE is set, a percentage that
correspond to Value is return.
Default percentile to compute is standard set of min
(0%), 25%, median (=50%), 75%, and max(100%) which can
be used for box- and whisker plots. The values in the
VALUE array must lie between 0. and 1.
If /REVERSE, default value is mean(data)
INTERPOLATE --> Behaves like EVEN keyword for MEDIAN.
If no element of the data falls exactly on the requested
percentile value, then the 2 adjacent data elements are
linearly interpolated to the requested percentile value.
When using the INTERPOLATE keyword, returned values may
not be elements of the input array.
/NAN --> if set, ignores NaN values. You must use that
keyword if your dataset may have NaN.
/REVERSE --> to get % corresponding to data value, instead of
data corresponding to %
OUTPUTS:
Y -> The function returns an array with the percentile
values or -1 if no data was passed or value contains
invalid numbers.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
x = (findgen(31)-15.)*0.2 ; create sample data
y = exp(-x^2)/3.14159 ; compute some Gauss distribution
p = percentiles(y,value=[0.05,0.1,0.9,0.95])
print,p
IDL prints : 3.92826e-05 0.000125309 0.305829 0.318310
MODIFICATION HISTORY:
mgs, 03 Aug 1997: VERSION 1.00
mgs, 20 Feb 1998: - improved speed and memory usage
(after tip from Stein Vidar on newsgroup)
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
cdh & jaf, 21 Oct 2009: GAMAP VERSION 2.13
- fixed incorrect values for small sample sizes
- removed unnecessary loop
- added NaN keyword
phs, 22 Oct 2009: - added REVERSE keyword
- updated handling of NaN
cdh, 19 Jun 2012: - added INTERPOLATE keyword
(See /n/home09/ryantosca/IDL/gamap2/math_units/percentiles.pro)
NAME:
QQNORM
PURPOSE:
Procedure: sort the data, assign actual "probability" and
calculate the expected deviation from the mean.
CATEGORY:
Math & Units
CALLING SEQUENCE:
RESULT = QQNORM( DATA )
INPUTS:
DATA -> Vector containing the data values. NOTE: DATA
will be sorted in ascending order and then returned.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Array where each element contains the expected
deviation from the mean of DATA.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
RESULT = QQNORM( DATA )
; Computes expected deviation from the mean.
MODIFICATION HISTORY:
mgs, 14 Dec 1998: VERSION 1.0
- extracted from w_calc.pro
pip, clh, bmy, 10 Oct 2002: TOOLS VERSION 1.52
amf, swu, bmy, 10 Oct 2006: TOOLS VERSION 2.05
- Now use simpler algorithm from
Arlene Fiore's code
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/qqnorm.pro)
NAME:
RUN_AV (function)
PURPOSE:
Compute running average or running total of a
data vector. Compared to the IDL function TS_SMOOTH,
this function takes into account missing values or
gaps in an optional x vector, and it allows for
even bandwidths. It can also be used to compute cumulative
totals.
CATEGORY:
Math & Units
CALLING SEQUENCE:
result = RUN_AV(Y [,X] [,keywords] )
INPUTS:
Y -> the data vector (a 2-D array will be treated as a vector)
X -> an optional X vector defining e.g. the sample times.
This only has an effect when the DELTAX keyword is specified.
X must be monotonically increasing and have the same
number of elements as Y.
KEYWORD PARAMETERS:
WIDTH -> The number of points to use for the average or total
Default is 1, i.e. Y is returned unchanged.
MINWIDTH -> The minimum number of points that must be valid
in order to return a average or total for the given point.
Default is MINWIDTH=WIDTH, i.e. all points must be valid
(and if X and DELTAX are specified, all points must lie
within WIDTH*DELTAX).
MIN_VALID -> The minimum value for valid data. Data with less than
MIN_VALID will be considered missing. MIN_VALID is also used
to indicate invalid totals or averages (1% is subtracted).
DELTAX -> The maximum gap between two consecutive x values.
Only effective when X is given.
COUNT -> A named variable will return the number of points used
in each average or total.
/TOTAL -> Set this keyword to compute running totals instead
of running averages.
OUTPUTS:
The function returns a vector with running averages or totals.
The number of elements in the result vector always equals the
number of elements in Y (unless an error occurs).
SUBROUTINES:
REQUIREMENTS:
NOTES:
This function can also be used to compute accumulative totals.
Simply set WIDTH to n_elements(Y) and MINWIDTH to 1 and use
the /TOTAL keyword. However, this is very uneffective for large
data vectors!
EXAMPLE:
y = findgen(20)
print,run_av(y,width=4)
; IDL prints: -1E31 -1E31 -1E31 1.5 2.5 3.5 4.5 ...
print,run_av(y,width=4,/TOTAL)
; IDL prints: -1E31 -1E31 -1E31 6 10 14 18 ...
; (cumulative total)
print,run_av(y,width=n_elements(y),minwidth=1,/TOTAL)
; IDL prints: 0 1 3 ... 190
x = [ 0, 2, 4, 6, 16, 20, 24, 25, 26, 27, 28, 29, 30, 32, 33 ]
y = fltarr(n_elements(x)) + 1.
print,run_av(y,x,width=4,count=c)
; IDL prints: -1E31 -1E31 -1E31 1 1 1 1 ...
print,c
; IDL prints: 1 2 3 4 4 4 4 4 4 4 4 4 4 4 4
print,run_av(y,x,deltax=2,width=4,count=c)
; IDL prints: -1E31 -1E31 -1E31 1 -1E31 -1E31 -1E31
; -1E31 -1E31 -1E31 1 1 1 1 1
print,c
; IDL prints: 1 2 3 4 3 2 1 1 2 3 4 4 4 4 4
MODIFICATION HISTORY:
mgs, 21 Oct 1998: VERSION 1.00
mgs, 07 Jun 1999: - changed loop variable to LONG type.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/run_av.pro)
NAME:
SEARCH (function)
PURPOSE:
Perform a binary search for the data point closest
to a given value. Data must be sorted.
CATEGORY:
Math & Units
CALLING SEQUENCE:
INDEX = SEARCH( DATA, VALUE )
INPUTS:
DATA -> a sorted data vector
VALUE -> the value to look for
KEYWORD PARAMETERS:
None
OUTPUTS:
INDEX -> The function returns the index of the
nearest data point.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
This routine is much faster than WHERE or MIN for
large arrays. It was written in response to a newsgroup
request by K.P. Bowman.
EXAMPLE:
TEST = FINDGEN(10000)
PRINT, SEARCH( TEST, 532.3 )
; prints 532
MODIFICATION HISTORY:
mgs, 21 Sep 1998: VERSION 1.00
bmy, 24 May 2007: TOOLS VERSION 2.06
- updated comments, cosmetic changes
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/math_units/search.pro)
NAME:
SIGN
PURPOSE:
Return the mathematical sign of the argument.
CATEGORY:
Math & Units
CALLING SEQUENCE:
s = sign(x)
INPUTS:
x = value of array of values.
KEYWORD PARAMETERS:
OUTPUTS:
s = sign of value(s).
COMMON BLOCKS:
None
NOTES:
Note:
s = -1 for x < 0
s = 0 for x = 0
s = 1 for x > 0
MODIFICATION HISTORY:
R. Sterner, 7 May, 1986.
Johns Hopkins University Applied Physics Laboratory.
RES 15 Sep, 1989 --- converted to SUN.
RES 23 Sep, 1991 --- rewrote, reducing 11 lines of code to 1.
(See /n/home09/ryantosca/IDL/gamap2/math_units/sign.pro)