Rebin a region of a sequence of data grids astRebinSeqX
In addition, the weights associated with each output pixel are returned. The weight of an output pixel indicates the number of input pixels which have been accumulated in that output pixel. If the entire value of an input pixel is assigned to a single output pixel, then the weight of that output pixel is incremented by one. If some fraction of the value of an input pixel is assigned to an output pixel, then the weight of that output pixel is incremented by the fraction used.
The start of a new sequence is indicated by specifying the AST__REBININIT flag via the
"
flags"
parameter. This causes the supplied arrays to be filled with zeros before the
rebinned input data is added into them. Subsequenct invocations within the same
sequence should omit the AST__REBININIT flag.
The last call in a sequence is indicated by specifying the AST__REBINEND flag.
Depending on which flags are supplied, this may cause the output data and variance
arrays to be normalised before being returned. This normalisation consists of dividing
the data array by the weights array, and can eliminate artifacts which may be
introduced into the rebinned data as a consequence of aliasing between the input and
output grids. This results in each output pixel value being the weighted mean of the
input pixel values that fall in the neighbourhood of the output pixel (rather like
astResampleX).
Optionally, these normalised values can then be multiplied by a scaling factor to
ensure that the total data sum in any small area is unchanged. This scaling factor is
equivalent to the number of input pixel values that fall into each output pixel. In
addition to normalisation of the output data values, any output variances are also
appropriately normalised, and any output data values with weight less than "
wlim"
are
set to "
badval"
.
Output variances can be generated in two ways; by rebinning the supplied input variances with appropriate weights, or by finding the spread of input data values contributing to each output pixel (see the AST__GENVAR and AST__USEVAR flags).
The number of input coordinates used by this Mapping (as given by its Nin attribute)
should match the number of input grid dimensions given by the value of "
ndim_in"
below. Similarly, the number of output coordinates (Nout attribute) should match
the number of output grid dimensions given by "
ndim_out"
. If "
in"
is NULL,
the Mapping will not be used, but a valid Mapping must still be supplied.
"
flags"
parameter. It gives the required number of input pixel values which
must contribute to an output pixel (i.e. the output pixel weight) in order
for the output pixel value to be considered valid. If the sum of the input
pixel weights contributing to an output pixel is less than the supplied "
wlim"
value, then the output pixel value is returned set to the supplied bad value.
If the supplied value is less than 1.0E-10 then 1.0E-10 is used instead. "
in"
is NULL. "
ndim_in"
elements, containing the coordinates of the centre of the first
pixel in the input grid along each dimension. Not used if "
in"
is NULL. "
ndim_in"
elements, containing
the coordinates of the centre of the last pixel in the input grid along each
dimension.
Note that "
lbnd_in"
and "
ubnd_in"
together define the shape and size of
the input grid, its extent along a particular (j’
th) dimension being
ubnd_in[j]-lbnd_in[j]1
(assuming the index "
j"
to be zero-based). They also define the input grid’
s
coordinate system, each pixel having unit extent along each dimension with integral
coordinate values at its centre. Not used if "
in"
is NULL.
"
float"
).
The storage order of data within this array should be such that the index of the first
grid dimension varies most rapidly and that of the final dimension least rapidly (i.e.
Fortran array indexing is used). If a NULL pointer is supplied for "
in"
, then no
data is added to the output arrays, but any initialisation or normalisation
requested by "
flags"
is still performed.
"
in"
array. If given, this
should contain a set of non-negative values which represent estimates of the
statistical variance associated with each element of the "
in"
array. If neither the
AST__USEVAR nor the AST__VARWGT flag is set, no input variance estimates are
required and this pointer will not be used. A NULL pointer may then be supplied. "
Pixel Spreading Schemes"
section in the description of the
astRebinX
functions. If a value of zero is supplied, then the default linear spreading scheme is
used (equivalent to supplying the value AST__LINEAR). Not used if "
in"
is NULL. "
Pixel Spreading Schemes"
section in the description of the
astRebinX
functions.
If no additional parameters are required, this array is not used and a NULL pointer may
be given. See also flag AST__PARWGT. Not used if "
in"
is NULL.
"
Control Flags"
section below for a description of the
options available. If no flag values are to be set, a value of zero should be given. ’
s coordinate
system.
If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time.
If the value is too high, discontinuities between the linear approximations used in
adjacent panel will be higher, and may cause the edges of the panel to be visible when
viewing the output image at high contrast. If this is a problem, reduce the tolerance
value used. Not used if "
in"
is NULL.
If a smaller value is used, the input region will first be divided into sub-regions
whose size does not exceed "
maxpix"
pixels in any dimension. Only at this point will
attempts at approximation commence.
This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal.
If too small a value is given, it will have the effect of inhibiting linear
approximation altogether (equivalent to setting "
tol"
to zero). Although this may
degrade performance, accurate results will still be obtained. Not used if "
in"
is
NULL.
"
in"
array. It specifies the value used to flag missing data (bad pixels) in the input and
output arrays.
If the AST__USEBAD flag is set via the "
flags"
parameter, then this value is used to
test for bad pixels in the "
in"
(and "
in_var"
) array(s).
In all cases, this value is also used to flag any output elements in the "
out"
(and "
out_var"
) array(s) for which rebined values could not be obtained (see the "
Propagation of Missing Data"
section below for details of the circumstances under which
this may occur).
"
ndim_out"
elements,
containing the coordinates of the centre of the first pixel in the output grid along
each dimension. "
ndim_out"
elements, containing the coordinates of the centre of the last pixel in the output grid
along each dimension.
Note that "
lbnd_out"
and "
ubnd_out"
together define the shape, size and coordinate
system of the output grid in the same way as "
lbnd_in"
and "
ubnd_in"
define the
shape, size and coordinate system of the input grid.
"
ndim_in"
elements, containing the coordinates of the
first pixel in the region of the input grid which is to be included in the
rebined output array. Not used if "
in"
is NULL. "
ndim_in"
elements, containing the coordinates of the last pixel in
the region of the input grid which is to be included in the rebined output
array.
Note that "
lbnd"
and "
ubnd"
together define the shape and position of a
(hyper-)rectangular region of the input grid which is to be included in the
rebined output array. This region should lie wholly within the extent of the
input grid (as defined by the "
lbnd_in"
and "
ubnd_in"
arrays). Regions of the
input grid lying outside this region will not be used. Not used if "
in"
is
NULL.
"
in"
array, and the data storage order should be such that the index of the
first grid dimension varies most rapidly and that of the final dimension least
rapidly (i.e. Fortran array indexing is used). "
out"
array. This pointer will only
be used if the AST__USEVAR or AST__GENVAR flag is set in which case variance
estimates for the rebined data values will be added into the array. If neither the
AST__USEVAR flag nor the AST__GENVAR flag is set, no output variance estimates will
be calculated and this pointer will not be used. A NULL pointer may then be
supplied. "
flags"
parameter. If AST__GENVAR has not been
specified then the array should have one element for each output pixel, and it
will be used to accumulate the weight associated with each output pixel. If
AST__GENVAR has been specified then the array should have two elements for
each output pixel. The first half of the array is again used to accumulate
the weight associated with each output pixel, and the second half is used to
accumulate the square of the weights. In each half, the data storage order
should be such that the index of the first grid dimension varies most rapidly
and that of the final dimension least rapidly (i.e. Fortran array indexing
is used). "
flags"
. D: double
F: float
I: int
B: byte (signed char)
UB: unsigned byte (unsigned char)
For example, astRebinSeqD would be used to process "
double"
data, while astRebinSeqI
would be used to process "
int"
data, etc.
Note that, unlike astResampleX, the astRebinSeqX set of functions does not yet support unsigned integer data types or integers of different sizes.
"
ast.h"
header file and may be used to provide additional control over the rebinning process.
Having selected a set of flags, you should supply the bitwise OR of their values via
the "
flags"
parameter:
AST__REBININIT: Used to mark the first call in a sequence. It indicates that the
supplied "
out"
, "
out_var"
and "
weights"
arrays should be filled with zeros
(thus over-writing any supplied values) before adding the rebinned input data
into them. This flag should be used when rebinning the first input array in a
sequence.
AST__REBINEND: Used to mark the last call in a sequence. It causes each value in the "
out"
and "
out_var"
arrays to be divided by a normalisation factor before being
returned. The normalisation factor for each output data value is just the corresponding
value from the weights array. The normalisation factor for each output variance value
is the square of the data value normalisation factor (see also AST__CONSERVEFLUX). It
also causes output data values to be set bad if the corresponding weight is less than
the value supplied for parameter "
wlim"
. It also causes any temporary values stored
in the output variance array (see flag AST__GENVAR below) to be converted into
usable variance values. Note, this flag is ignored if the AST__NONORM flag is
set.
AST__USEBAD: Indicates that there may be bad pixels in the input array(s) which must be
recognised by comparing with the value given for "
badval"
and propagated to the output
array(s). If this flag is not set, all input values are treated literally and the "
badval"
value is only used for flagging output array values.
AST__USEVAR: Indicates that output variance estimates should be created by rebinning the supplied input variance estimates. An error will be reported if both this flag and the AST__GENVAR flag are supplied.
AST__GENVAR: Indicates that output variance estimates should be created based on the spread of input data values contributing to each output pixel. An error will be reported if both this flag and the AST__USEVAR flag are supplied. If the AST__GENVAR flag is specified, the supplied output variance array is first used as a work array to accumulate the temporary values needed to generate the output variances. When the sequence ends (as indicated by the AST__REBINEND flag), the contents of the output variance array are converted into the required variance estimates. If the generation of such output variances is required, this flag should be used on every invocation of this function within a sequence, and any supplied input variances will have no effect on the output variances (although input variances will still be used to weight the input data if the AST__VARWGT flag is also supplied). The statistical meaning of these output varianes is determined by the presence or absence of the AST__DISVAR flag (see below).
AST__DISVAR: This flag is ignored unless the AST__GENVAR flag has also been specified. It determines the statistical meaning of the generated output variances. If AST__DISVAR is not specified, generated variances represent variances on the output mean values. If AST__DISVAR is specified, the generated variances represent the variance of the distribution from which the input values were taken. Each output variance created with AST__DISVAR will be larger than that created without AST__DISVAR by a factor equal to the number of input samples that contribute to the output sample.
AST__VARWGT: Indicates that the input data should be weighted by the reciprocal of the input variances. Otherwise, all input data are given equal weight. If this flag is specified, the calculation of the output variances (if any) is modified to take account of the varying weights assigned to the input data values. See also AST__PARWGT.
AST__PARWGT: Indicates that a constant weight should be used when pasting each pixel of
the supplied input array into the returned arrays. This extra weight value should be
inserted at the start of the "
params"
array (which should consequently be one element
longer than specified in the "
Pixel Spreading Schemes"
section in the description of the
astRebinX
functions). If the AST__VARWGT flag is also specified, the total weight for each pixel
is the product of the reciprocal of the pixel variance and the value supplied in the
last element of the "
params"
array.
AST__NONORM: If the simple unnormalised sum of all input data falling in each
output pixel is required, then this flag should be set on each call in the
sequence and the AST__REBINEND should not be used on the last call. In this case
NULL pointers can be supplied for "
weights"
and "
nused"
. This flag cannot
be used with the AST__CONSERVEFLUX, AST__GENVAR, AST__PARWGT or AST__VARWGT
flag.
AST__CONSERVEFLUX: Indicates that the normalized output pixel values generated by the AST__REBINEND flag should be scaled in such a way as to preserve the total data value in a feature on the sky. Without this flag, each normalised output pixel value represents a weighted mean of the input data values around the corresponding input position. is appropriate if the input data represents the spatial density of some quantity (e.g. surface brightness in Janskys per square arc-second) because the output pixel values will have the same normalisation and units as the input pixel values. However, if the input data values represent flux (or some other physical quantity) per pixel, then the AST__CONSERVEFLUX flag could be of use. It causes each output pixel value to be scaled by the ratio of the output pixel size to the input pixel size.
This flag can only be used if the Mapping is successfully approximated by one or more
linear transformations. Thus an error will be reported if it used when the "
tol"
parameter is set to zero (which stops the use of linear approximations), or if the
Mapping is too non-linear to be approximated by a piece-wise linear transformation. The
ratio of output to input pixel size is evaluated once for each panel of the piece-wise
linear approximation to the Mapping, and is assumed to be constant for all output
pixels in the panel. The scaling factors for adjacent panels will in general differ
slightly, and so the joints between panels may be visible when viewing the output
image at high contrast. If this is a problem, reduce the value of the "
tol"
parameter until the difference between adjacent panels is sufficiently small to be
insignificant.
This flag should normally be supplied on each invocation of astRebinSeqX within a given sequence.
Note, this flag cannot be used in conjunction with the AST__NOSCALE flag (an error will be reported if both flags are specified).
"
badval"
value in the "
out"
array. These are only produced if the AST__REBINEND flag is
specified and a pixel has zero weight.
An input pixel is considered bad (and is consequently ignored) if its data
value is equal to "
badval"
and the AST__USEBAD flag is set via the "
flags"
parameter.
In addition, associated output variance estimates (if calculated) may be declared bad
and flagged with the "
badval"
value in the "
out_var"
array for similar reasons.
"
8-byte"
interface for this
function should be used. This alternative interface uses 8 byte integer arguments
(instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments
"
lbnd_in"
, "
ubnd_in"
, "
lbnd_out"
, "
ubnd_out"
, "
lbnd"
, "
ubnd"
are changed
from type "
int"
to type "
int64_t"
(defined in header file stdint.h). The
function return type is similarly changed to type int64_t. The function name is
changed by inserting the digit "
8"
before the trailing data type code. Thus,
astRebinSeqX
becomes astRebinSeq8X.