Calculate statistics over a group of data arrays or points
In array mode (SINGLE=FALSE
), statistics are calculated for each pixel in one
of the array components (DATA, VARIANCE or QUALITY) accumulated over all the
input NDFs and written to an output NDF; each pixel of the output NDF is a
result of combination of pixels with the same Pixel co-ordinates in all the
input NDFs. There is a selection of statistics available to form the output
values.
The input NDFs must all have the same number of dimensions, but need not all be the same shape. The shape of the output NDF can be set to either the intersection or the union of the shapes of the input NDFs using the TRIM parameter.
In single pixel mode (SINGLE=TRUE
) a position in the current co-ordinate Frame of all
the NDFs is given, and the value at the pixel covering this point in each of the input
NDFs is accumulated to form the results that comprise the mean, variance, and median.
These statistics, and if environment variable MSG_FILTER is set to VERBOSE
, the value
of each contributing pixel, is reported directly to you.
"Mode"
, "Cmean"
and "Csigma"
statistics (see Parameter ESTIMATOR). The application first computes statistics using
all the available pixels. It then rejects all those pixels whose values lie beyond CLIP
standard deviations from the mean and will then re-evaluate the statistics. For
"Cmean"
and "Csigma"
there is currently only one iteration, but up to seven for
"Mode".
The value must be positive. [3.0]
COMP = LITERAL (Read)
"Data"
,
"Quality"
, "Variance"
, or "Error"
(where "Error"
is an alternative to "Variance"
and
causes the square root of the variance values to be used). If "Quality"
is specified,
then the quality values are treated as numerical values (in the range 0 to 255). In
cases other than "Data"
, which is always present, a missing component will be treated
as having all pixels set to the ‘bad’ value. ["Data"]
"Mean"
–- Mean value
"WMean"
–- Weighted mean in which each data value is weighted by the reciprocal of the
associated variance. (2)
"Mode"
–- Modal value. (4)
"Median"
–- Median value. Note that this is extremely memory and CPU intensive
for large datasets; use with care! If strange things happen, use "Mean"
. (3)
"Absdev"
–- Mean absolute deviation from the unweighted mean. (2)
"Cmean"
–- Sigma-clipped mean. (4)
"Csigma"
–- Sigma-clipped standard deviation. (4)
"Comax"
–- Co-ordinate of the maximum value.
"Comin"
–- Co-ordinate of the minimum value.
"FBad"
–- Fraction of bad pixel values.
"FGood"
–- Fraction of good pixel values.
"Integ"
–- Integrated value, being the sum of the products of the value and pixel width
in world co-ordinates. Note that for sky co-ordinates the width is measured in
radians.
"Iwc"
–- Intensity-weighted co-ordinate, being the sum of each value times its
co-ordinate, all divided by the integrated value (see the "Integ"
option).
"Iwd"
–- Intensity-weighted dispersion of the co-ordinate, normalised like "Iwc"
by the
integrated value. (4)
"Max"
–- Maximum value.
"Min"
–- Minimum value.
"FBad"
–- Fraction of bad pixel values.
"FGood"
–- Fraction of good pixel values.
"NBad"
–- Count of bad pixel values.
"NGood"
–- Count of good pixel values.
"Rms"
–- Root-mean-square value. (4)
"Sigma"
–- Standard deviation about the unweighted mean. (4)
"Sum"
–- The total value.
Where needed, the co-ordinates are the indices of the input NDFs in the supplied order. Thus the calculations behave like the NDFs were stacked one upon another to form an extra axis, and that axis had GRID co-ordinates. Care using wildcards is necessary, to achieve a specific order, say for a time series, and hence assign the desired co-ordinate for a each NDF. Indirection through a text file is recommended.
The selection is restricted if there are only a few input NDFs. For instance, measures
of dispersion like "Sigma"
and "Iwd"
are meaningless for combining only two NDFs. The
minimum number of input NDFs for each estimator is given in parentheses in the list
above. Where there is no number, there is no restriction. If you supply an
unavailable option, you will be informed, and presented with the available
options. ["Mean"]
An NDF name, optionally containing wild-cards and/or regular expressions
("$\ast $"
,
"?"
, "[a-z]"
etc.);
the name of a text file, preceded by an up-arrow character
"$$
.
Each line in the text file should contain a comma-separated list of elements, each of
which can in turn be an NDF name (with optional wild-cards, etc), or another file
specification (preceded by an up-arrow). Comments can be included in the file by
commencing lines with a hash character
""#"
.
If the value supplied for this parameter ends with a minus sign "-"
, then the user is
re-prompted for further input until a value is given which does not end with a minus
sign. All the images given in this way are concatenated into a single group.
FALSE
. TRUE
), this parameter gives the position in the current co-ordinate
Frame at which the statistics should be calculated (supplying a colon ":"
will
display details of the required co-ordinate Frame). The position should be
supplied as a list of formatted axis values separated by spaces or commas.
The pixel covering this point in each input array, if any, will be used. TRUE
, then the POS parameter will
be used to get the point to which the statistics refer, but if SINGLE=FALSE
an output NDF will be generated containing the results for all the pixels.
[FALSE]
["KAPPA - Mstats"]
TRUE
, then the output NDF is the shape of the intersection of all
the input NDFs, i.e. only pixels which appear in all the input arrays will
be represented in the output. If TRIM=FALSE
, the output is the shape of the
union of the inputs, i.e. every pixel which appears in the input arrays will
be represented in the output. [TRUE]
TRUE
and all the input NDFs contain a variance array, this
array will be used to define the weights, otherwise all the weights will be set
equal. [TRUE]
TRUE
. TRUE
. TRUE
. "idat"
, and writes the result in a new NDF
called ostats. The shape of ostats will be the intersection of the volumes of all the
indat$\ast $ NDFs.
"m31"
, which all
have SKY as their current co-ordinate Frame. The mean and variance of the pixels at
that position in all the NDFs are printed to the screen. If the reporting level
is verbose, the command also prints the value of the sampled pixel in each
of the NDFs. For those in which the pixel at the selected position is bad or
falls outside the NDF, this is also indicated. A warning is issued (at the normal reporting level) whenever any output values are set bad because there are too few contributing data values. This reports the fraction of flagged output data generated by the WLIM parameter’s threshold.
No warning is given when Parameter WLIM=0
. Input data containing only bad values are
not counted in the flagged fraction, since no potential good output value has been
lost.
For SINGLE=TRUE
the value of the MSG_FILTER environment variable is used to output
messages. If it is QUIET
, nothing is reported on the screen. If it is undefined, NORMAL
or VERBOSE
, the statistics are reported. If it is VERBOSE
, the individual pixel values
are also reported.
This routine correctly processes the AXIS, DATA, VARIANCE, QUALITY, LABEL, TITLE, UNITS, WCS, and HISTORY components of the first input NDF, and propagates all its extensions.
Processing of bad pixels and automatic quality masking are supported.
All non-complex numeric data types can be handled. Calculations are performed using the most appropriate of the data types integer, real or double precision. If the input NDFs’ structures contain values with other data types, then conversion will be performed as necessary.
Up to six NDF dimensions are supported.
Huge NDFs are supported.