Description:
This application collects groups of pixel values together from an
input NDF and places each group into a single column of an output NDF. Each
such output column represents a “bin” into which a group of input pixels is
placed.
If the input NDF has pixel axes,
the user provides a set of
-dimensional “index”
NDFs (where
is between 1 and 6). For each pixel in the input NDF, the corresponding value in each of the
index NDFs is found.
This vector of
values is used (after rounding them to the nearest integer) to determine the pixel indices within the
output (-dimensional)
NDF at which to store the input pixel value. Thus each output pixel corresponds to a
bin into which one or more input pixels can be placed, as selected by the index
NDFs.
There are many possible ways in which the input pixels values that fall in a single bin
could be combined to create a single representative output value for each bin. For
instance, the output NDF could contain the mean of the input values that fall in each
bin, or the maximum, or the standard deviation, etc. However, this application does not
store a single representative value for each bin. Instead it stores all the separate
input pixel values that fall in each bin. This requires an extra trailing pixel axis in
the output NDF, with a lower pixel bounds of 1 and and upper pixel bound equal to the
maximum population of any bin. Each “column” of values parallel to this final output
pixel axis represents one bin, and contains the corresponding input pixel values at
its lower end, with bad values filling any unused higher pixels. The COLLAPSE
application could then be used to get a representative value for each bin by
collapsing this final pixel axis using any of the many estimators provided by
COLLAPSE.
An extra group of
NDFs can be supplied that define the WCS to be stored in the output NDF–-see Parameter
WCS.
Usage:
pixbin in out index [wcs]
Parameters:
IN = NDF (Read)
The input
-dimensional
NDF.
INDEX = NDF (Read)
A group of index NDFs (all with
-dimensions).
The number of index NDFs (referred to below as
“”) supplied
should be in the range 1–6 and determines the dimensionality of the output NDF. A section is
taken from each one so that it matches the input NDF supplied by Parameter IN. The data values
in the th index
NDF are converted to _INTEGER (by finding the nearest integer) and then used as the pixel indices
on the th
output pixel axis.
OUT = NDF (Write)
The output NDF containing all the
values from the input NDF collected into a set of bins. This NDF will have
pixel axes,
where
is the number of index NDF supplied using Parameter INDEX. The final
pixel axis enumerates the individual input pixels that fall within
each bin.
WCS = NDF (Read)
An optional group of NDFs (all with
-dimensions)
that define the WCS to be stored in the output NDF. The number of NDFs in this group should
be ,
the number of index NDFs (see Parameter INDEX). The data values in the
th WCS NDF determine the
values to be stored for the th
axis in the WCS of the output NDF (the WCS values on the final trailing axis in the output
NDF, axis ,
are just equal to pixel index). If a null (!) value is supplied, no
WCS is stored in the output NDF. The WCS values for each of the first
output axes are described using a look-up-table (one for each axis) that converts
value in an index NDF into the corresponding value in a WCS NDF. For all pixels
with the same integer index value, the mean of the corresponding WCS values is
found and stored in the look-up-table. The label and unit for each axis is
taken from the Label and Unit components of the corresponding WCS NDF. [!]
Examples:
pixbin m31 binned radius
Here the pixel values in a two-dimensional
NDF called m31 are placed into bins as defined by the contents of a single
two-dimensional NDF called radius, to create a two-dimensional output NDF called
binned. (The number of pixel axes in the output is always one more than the
number of index NDFs.) The data values in NDF radius are used as the pixel
indices along the first axis of the output NDF, at which to store each input
pixel value. Each column in the output NDF contains the individual input pixel
values assigned to that bin, padded with bad values if necessary to fill the
column. Related Applications
Implementation Status:
-
This routine correctly processes the DATA, QUALITY, VARIANCE, LABEL, TITLE, UNITS, and
HISTORY, components of the input NDF and propagates all extensions.
-
Processing of bad pixels and automatic quality masking are supported.
-
All non-complex numeric data types can be handled.