Reduces the number of axes in an n-dimensional NDF by compressing it along a nominated axis
For each output pixel, all corresponding input pixel values between the specified bounds of the nominated axis to be collapsed are combined together using one of a selection of estimators, including a mean, mode, or median, to produce the output pixel value.
Possible uses include such things as collapsing a range of wavelength planes in a three-dimensional RA/DEC/Wavelength cube to produce a single two-dimensional RA/DEC image, or collapsing a range of slit positions in a two-dimensional slit position/wavelength image to produce a one-dimensional wavelength array.
Its integer index within the current Frame of the input NDF (in the range 1 to the number of axes in the current Frame).
Its Symbol string such as "RA"
or "VRAD"
.
A generic option where "SPEC"
requests the spectral axis, "TIME"
selects the time axis, "SKYLON"
and
"SKYLAT"
picks the sky longitude and latitude axes respectively. Only those axis domains present are
available as options.
A list of acceptable values is displayed if an illegal value is supplied. If the axes of the current Frame are not parallel to the NDF pixel axes, then the pixel axis which is most nearly parallel to the specified current Frame axis will be used.
"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"
, "Error"
, "Quality"
or "Variance"
(where "Error"
is the alternative to "Variance"
and
causes the square root of the variance values to be taken before computing the statistics). If "Quality"
is specified, then the quality values are treated as numerical values (in the range 0 to 255). ["Data"]
"Mean"
— Mean value
"WMean"
— Weighted mean in which each data value is weighted by the reciprocal of the associated
variance (not available for COMP="Variance"
or "Error"
).
"Mode"
— Modal value
"Median"
— Median value. Note that this is extremely memory and CPU intensive for large datasets;
use with care! If strange things happen, use "Mean"
.
"FastMed"
— Faster median using Wirth’s algorithm for selecting the
$k$th
value, rather than a full sort. Weighting is not supported, thus this option is unavailable if both
Parameter VARIANCE is TRUE
and the input NDF contains a VARIANCE component.
"Absdev"
— Mean absolute deviation from the unweighted mean.
"Cmean"
— Sigma-clipped mean.
"Csigma"
— Sigma-clipped standard deviation.
"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.
co-ordinates.
"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.
"Max"
— Maximum value.
"Min"
— Minimum value.
"NBad"
— Count of bad pixel values.
"NGood"
— Count of good pixel values.
"Rms"
— Root-mean-square value.
"Sigma"
— Standard deviation about the unweighted mean.
"Sum"
— The total value.
["Mean"]
!
) is supplied for either HIGH or LOW, the
entire range of the axis is collapsed. [!]
!
) is supplied for either LOW or HIGH, the
entire range of the axis is collapsed. [!]
!
) propagates the title from the
input NDF to the output NDF. [!]
TRUE
value is supplied, the collapsed WCS axis will be removed from the
WCS FrameSet of the output NDF, and the collapsed pixel axis will also be removed from
the NDF, resulting in the output NDF having one fewer pixel axes than the input NDF. If
a FALSE
value is supplied, the collapsed WCS and pixel axes are retained in the output
NDF, resulting in the input and output NDFs having the same number of pixel axes. In
this case, the pixel-index bounds of the collapse axis will be set to (1:1) in the output NDF
(that is, the output NDF will span only a single pixel on the collapse axis). Thus, setting
TRIM to FALSE
allows information to be retained about the range of values over which the
collapse occurred. [TRUE]
TRUE
and the NDF contains a
variance array, this array will be used to define the weights, otherwise all the weights will
be set equal. By definition this parameter is set to FALSE
when COMP is "Variance"
or
"Error"
.
The VARIANCE parameter is ignored and set to FALSE
when there are more than 300 pixels along the
collapse axis and ESTIMATOR is "Median"
, "Mode"
, "Cmean"
, or "Csigma"
. This prevents the
covariance matrix from being huge. For "Median"
estimates of variance come from mean variance
instead. The other affected estimators switch to use equal weighting. [TRUE]
A comma-separated list of strings should be given in which each string is either
an attribute setting, or the name of a text file preceded by an up-arrow character
"$$
.
Such text files should contain further comma-separated lists which will be read and interpreted in the
same manner. Attribute settings are applied in the order in which they occur within the list, with later
settings overriding any earlier settings given for the same attribute.
"
Each individual attribute setting should be of the form:
$<$name$>$=$<$value$>$
where $<$name$>$
is the name of a plotting attribute, and
$<$value$>$
is the value to assign to the attribute. Any unspecified attributes will retain the value they have in the
supplied NDF. No attribute values will be changed if a null value (!
) is supplied. Any unrecognised
attributes are ignored (no error is reported). [!]
WLIM specifies the minimum fraction of good pixels which must be present in order to generate a
good output pixel. If this specified minimum fraction of good input pixels is not present, then a bad
output pixel will result, otherwise a good output value will be calculated. The value of this
parameter should lie between 0.0 and 1.0 (the actual number used will be rounded up if
necessary to correspond to at least one pixel). [0.3]
"RA"
, "DEC"
and "Lambda"
, with the lambda
axis being parallel to the third pixel axis. The above command extracts a slab of the input
cube between wavelengths 4500 and 4550 Ångstroms, and collapses this slab into a single
two-dimensional output NDF called slab with RA and DEC axes. Each pixel in the output NDF
is the mean of the corresponding input pixels with wavelengths between 4500 and 4550
Ångstroms. The collapse is always performed along one of the pixel axes, even if the current Frame in the input NDF is not the PIXEL Frame. Special care should be taken if the current-Frame axes are not parallel to the pixel axes. The algorithm used to choose the pixel axis and the range of values to collapse along this pixel axis proceeds as follows.
The current-Frame co-ordinates of the central pixel in the input NDF are determined (or some other point if the co-ordinates of the central pixel are undefined). Two current-Frame positions are then generated by substituting in turn into this central position each of the HIGH and LOW values for the current-Frame axis specified by Parameter AXIS. These two current-Frame positions are transformed into pixel co-ordinates, and the projections of the vector joining these two pixel positions on to the pixel axes are found. The pixel axis with the largest projection is selected as the collapse axis, and the two end points of the projection define the range of axis values to collapse.
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.
This routine correctly processes the AXIS, DATA, VARIANCE, LABEL, TITLE, UNITS, WCS, and HISTORY components of the input NDF; and propagates all extensions. QUALITY is not propagated.
Processing of bad pixels and automatic quality masking are supported.
All non-complex numeric data types can be handled.
Any number of NDF dimensions is supported.
Huge NDFs are supported.