Matrix/
cmapply.pro
Utility function, adapted from CMPRODUCT
cmapply_redim : Utility function, used to collect collaped dimensions
Applies a function to specified dimensions of an array
Description:
CMAPPLY will apply one of a few select functions to specified
dimensions of an array. Unlike some IDL functions, you *do* have
a choice of which dimensions that are to be "collapsed" by this
function. Iterative loops are avoided where possible, for
performance reasons.
The possible functions are: (and number of loop iterations:)
+ - Performs a sum (as in TOTAL) number of collapsed dimensions
AND - Finds LOGICAL "AND" (not bitwise) same
OR - Finds LOGICAL "OR" (not bitwise) same
* - Performs a product LOG_2[no. of collapsed elts.]
MIN - Finds the minimum value smaller of no. of collapsed
MAX - Finds the maximum value or output elements
USER - Applies user-defined function no. of output elements
It is possible to perform user-defined operations arrays using
CMAPPLY. The OP parameter is set to 'USER:FUNCTNAME', where
FUNCTNAME is the name of a user-defined function. The user
defined function should be defined such that it accepts a single
parameter, a vector, and returns a single scalar value. Here is a
prototype for the function definition:
FUNCTION FUNCTNAME, x, KEYWORD1=key1, ...
scalar = ... function of x or keywords ...
RETURN, scalar
END
The function may accept keywords. Keyword values are passed in to
CMAPPLY through the FUNCTARGS keywords parameter, and passed to
the user function via the _EXTRA mechanism. Thus, while the
definition of the user function is highly constrained in the
number of positional parameters, there is absolute freedom in
passing keyword parameters.
It's worth noting however, that the implementation of user-defined
functions is not particularly optimized for speed. Users are
encouraged to implement their own array if the number of output
elements is large.
Routine summary
- result = cmapply_product(x)
-
-
- cmapply_redim, newarr, dimapply, dimkeep, nkeep, totcol, totkeep
-
-
- result = cmapply(op, array[, dimapply], DOUBLE=DOUBLE, TYPE=TYPE, FUNCTARGS=FUNCTARGS, NOCATCH=NOCATCH)
-
-
cmapply_product
result = cmapply_product(x)
Parameters
x
Version history
Version
$Id: cmapply.pro 325 2007-12-06 10:04:53Z pinsard $
Known issues
Todo items
seb
cmapply_redim
cmapply_redim, newarr, dimapply, dimkeep, nkeep, totcol, totkeep
Parameters
newarr
dimapply
dimkeep
nkeep
totcol
totkeep
Known issues
Todo items
seb
cmapply
Array
result = cmapply(op, array[, dimapply], DOUBLE=DOUBLE, TYPE=TYPE, FUNCTARGS=FUNCTARGS, NOCATCH=NOCATCH)
Return value
An array of the required TYPE, whose elements are the result of
the requested operation. Depending on the operation and number of
elements in the input array, the result may be vulnerable to
overflow or underflow.
Parameters
op
in
required
type: string
The operation to perform, as a string. May be upper or lower case.
If a user-defined operation is to be passed, then OP is of
the form, 'USER:FUNCTNAME', where FUNCTNAME is the name of
the user-defined function.
array
in
required
type: array
An array of values to be operated on.
Must not be of type STRING (7) or STRUCTURE (8).
dimapply
in
optional
type: array
default: 1 (ie, first dimension)
An array of dimensions that are to be "collapsed", where
the first dimension starts with 1 (ie, same convention
as IDL function TOTAL). Whereas TOTAL only allows one
dimension to be added, you can specify multiple dimensions
to CMAPPLY. Order does not matter, since all operations
are associative and transitive. NOTE: the dimensions refer
to the *input* array, not the output array. IDL allows a
maximum of 8 dimensions.
Keywords
DOUBLE
default: not set
Set this if you wish the internal computations to be done
in double precision if necessary. If ARRAY is double
precision (real or complex) then DOUBLE=1 is implied.
TYPE
default: same as input type
Set this to the IDL code of the desired output type (refer
to documentation of SIZE). Internal results will be
rounded to the nearest integer if the output type is an
integer type.
FUNCTARGS
If OP is 'USER:...', then the contents of this keyword
are passed to the user function using the _EXTRA
mechanism. This way you can pass additional data to
your user-supplied function, via keywords, without
using common blocks.
DEFAULT: undefined (i.e., no keywords passed by _EXTRA)
NOCATCH
Examples
First example:
Shows how cmapply can be used to total the second dimension of
the array called IN. This is equivalent to OUT = TOTAL(IN, 2)
IDL> IN = INDGEN(5,5)
IDL> OUT = CMAPPLY('+', IN, [2])
IDL> HELP, OUT
OUT INT = Array[5]
Second example: Input is assumed to be an 5x100 array of 1's and
0's indicating the status of 5 detectors at 100 points in time.
The desired output is an array of 100 values, indicating whether
all 5 detectors are on (=1) at one time. Use the logical AND
operation.
IDL> IN = detector_status ; 5x100 array
IDL> OUT = CMAPPLY('AND', IN, [1]) ; collapses 1st dimension
IDL> HELP, OUT
OUT BYTE = Array[100]
(note that MIN could also have been used in this particular case,
although there would have been more loop iterations).
Third example: Shows sum over first and third dimensions in an
array with dimensions 4x4x4:
IDL> IN = INDGEN(4,4,4)
IDL> OUT = CMAPPLY('+', IN, [1,3])
IDL> PRINT, OUT
408 472 536 600
Fourth example: A user-function (MEDIAN) is used:
IDL> IN = RANDOMN(SEED,10,10,5)
IDL> OUT = CMAPPLY('USER:MEDIAN', IN, 3)
IDL> HELP, OUT
OUT FLOAT = Array[10, 10]
(OUT[i,j] is the median value of IN[i,j,*])
Version history
Version
$Id: cmapply.pro 325 2007-12-06 10:04:53Z pinsard $
History
Mar 1998, Written, CM
Changed usage message to not bomb, 24 Mar 2000, CM
Significant rewrite for *, MIN and MAX (inspired by Todd Clements
); FOR loop indices are now type
LONG; copying terms are liberalized, CM, 22, Aug 2000
More efficient MAX/MIN (inspired by Alex Schuster), CM, 25 Jan
2002
Make new MAX/MIN actually work with 3d arrays, CM, 08 Feb 2002
Add user-defined functions, ON_ERROR, CM, 09 Feb 2002
Correct bug in MAX/MIN initialization of RESULT, CM, 05 Dec 2002
Author: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
Produced by IDLdoc 2.0.
