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 argument. 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 AST_RESAMPLE$<$X$>$). 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).

THIS = INTEGER (Given)

WLIM = DOUBLE PRECISION (Given)

NDIM_IN = INTEGER (Given)

LBND_IN( NDIM_IN ) = INTEGER (Given)

UBND_IN( NDIM_IN ) = INTEGER (Given)

IN( $\ast$ ) = $<$Xtype$>$ (Given)

IN_VAR( $\ast$ ) = $<$Xtype$>$ (Given)

SPREAD = INTEGER (Given)

PARAMS( $\ast$ ) = DOUBLE PRECISION (Given)

FLAGS = INTEGER (Given)

TOL = DOUBLE PRECISION (Given)

MAXPIX = INTEGER (Given)

BADVAL = $<$Xtype$>$ (Given)

NDIM_OUT = INTEGER (Given)

LBND_OUT( NDIM_OUT ) = INTEGER (Given)

UBND_OUT( NDIM_OUT ) = INTEGER (Given)

LBND( NDIM_IN ) = INTEGER (Given)

UBND( NDIM_IN ) = INTEGER (Given)

OUT( $\ast$ ) = $<$Xtype$>$ (Given and Returned)

OUT_VAR( $\ast$ ) = $<$Xtype$>$ (Given and Returned)

WEIGHTS( $\ast$ ) = DOUBLE PRECISION (Given and Returned)

NUSED = INTEGER$\ast$8 (Given and Returned)

STATUS = INTEGER (Given and Returned)

• D: DOUBLE PRECISION

• R: REAL

• I: INTEGER

• B: BYTE (treated as signed)

• UB: BYTE (treated as unsigned)

For example, AST_REBIND would be used to process DOUBLE PRECISION data, while AST_REBINI would be used to process integer data (stored in an INTEGER array), etc.

Note that, unlike AST_RESAMPLE$<$X$>$, the AST_REBINSEQ$<$X$>$ set of functions does not yet support unsigned integer data types or integers of different sizes.

• 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 argument 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 routine 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 AST_REBIN$<$X$>$ routines). 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 WEIGHTS and NUSED are ignored. 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. (i.e. AST_REBINSEQ$<$F$>$ behaves similarly to AST_RESAMPLE$<$X$>$). This (i.e. AST_REBINSEQ$<$F$>$ behaves similarly to AST_RESAMPLE$<$X$>$). This 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 argument 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 argument until the difference between adjacent panels is sufficiently small to be insignificant.

This flag should normally be supplied on each invocation of AST_REBINSEQ$<$X$>$ 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).

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 argument.

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.