PIXBIN

Places each pixel value in an input NDF into an output bin

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 N pixel axes, the user provides a set of M N-dimensional “index” NDFs (where M is between 1 and 6). For each pixel in the input NDF, the corresponding value in each of the M index NDFs is found. This vector of M values is used (after rounding them to the nearest integer) to determine the pixel indices within the output (M-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 M 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 N-dimensional NDF.
INDEX = NDF (Read)
A group of index NDFs (all with N-dimensions). The number of index NDFs (referred to below as “M”) 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 Jth index NDF are converted to _INTEGER (by finding the nearest integer) and then used as the pixel indices on the Jth 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 M + 1 pixel axes, where M 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 N-dimensions) that define the WCS to be stored in the output NDF. The number of NDFs in this group should be M, the number of index NDFs (see Parameter INDEX). The data values in the Jth WCS NDF determine the values to be stored for the Jth axis in the WCS of the output NDF (the WCS values on the final trailing axis in the output NDF, axis M + 1, 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 M 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

KAPPA: COLLAPSE

Implementation Status: