CCG_COMB1x - Combines a stack of array lines into one line, using a variety of methods

Description:

The routine works along each line of the input stack of lines, combining the data. This variant uses a complete variance array propagates them.

The array NCON holds the actual numbers of pixels that were used in deriving the output value plus any values already present in the array; thus a cumulative sum of contributing pixel numbers may be kept.

Invocation:

CALL CCG_COMB1x( NPIX, NLINES, STACK, VARS, COORDS, IMETH, MINPIX, NITER, NSIGMA, ALPHA, RMIN, RMAX, NMAT, RESULT, RESVAR, WIDTHS, COIND, WRK1, WRK2, PP, COVEC, POINT, USED, NCON, NFLAG, STATUS )

Arguments:

NPIX = INTEGER (Given)

The number of pixels in a line of data.

NLINES = INTEGER (Given)

The number of lines of data in the stack.

STACK( NPIX, NLINES ) = ? (Given)

The array of lines which are to be combined into a single line.

VARS( NPIX, NLINES ) = ? (Given)

The data variances.

COORDS( NPIX, NLINES ) = ? (Given)

The co-ordinates along the collapse axis for each pixel. It is accessed only for IMETH = 22, 23, 33, 34.

IMETH = INTEGER (Given)

The method to use in combining the lines. It has a code of 1 to 300 which represent the following statistics. 1 = Mean 2 = Weighted mean 3 = Median 4 = Trimmed mean 5 = Mode 6 = Sigma-clipped mean 7 = Threshold exclusion mean 8 = Minmax mean 9 = Broadened median 10 = Sigma-clipped median 11 = Fast median 12 = Sum 13 = Standard deviation about the mean 14 = Sigma-clipped standard deviation about the mean 21 = Integrated value (sum of pixel co-ordinate width times value) 22 = Intensity-weighted co-ordinate 23 = Intensity-weighted dispersion of the co-ordinate 24 = Root mean square 25 = Absolute mean deviation 31 = Maximum 32 = Minimum 33 = Co-ordinate of maximum 34 = Co-ordinate of minimum 300 = Median, but estimating variance from mean variance

MINPIX = INTEGER (Given)

The minimum number of pixels required to contribute to an output pixel.

NITER = INTEGER (Given)

The maximum number of iterations (IMETH = 5).

NSIGMA = REAL (Given)

The number of sigmas to clip the data at (IMETH = 5 and 6).

ALPHA = REAL (Given)

The fraction of data values to remove from data (IMETH = 4).

RMIN = REAL (Given)

The minimum allowed data value (IMETH = 7).

RMAX = REAL (Given)

The maximum allowed data value (IMETH = 7).

NMAT = INTEGER (Given)

Number of columns in covariance matrix. It should be at least NLINES $*$ ( NLINES $+$ 1 )/ 2.

RESULT( NPIX ) = ? (Returned)

The output line of data.

RESVAR( NPIX ) = ? (Returned)

The output variances.

WIDTHS( NPIX, NLINES ) = ? (Returned)

The widths along the collapse axis for each pixel. It is calculated only for IMETH = 21.

COIND( NPIX ) = INTEGER (Returned)

Workspace to hold co-ordinate indices.

WRK1( NLINES ) = ? (Returned)

Workspace for calculations.

WRK2( NLINES ) = ? (Returned)

Workspace for calculations.

PP( NLINES ) = DOUBLE PRECISION (Returned)

Workspace for order statistics calculations.

COVEC( NMAT, NLINES ) = DOUBLE PRECISION (Returned)

Workspace for storing ordered statistics variance-covariance matrix. Used for IMETHs 3 to 11, and 14.

POINT( NLINES ) = INTEGER (Returned)

Workspace to hold pointers to the original positions of the data before extraction and conversion in to the WRK1 array.

USED( NLINES ) = LOGICAL (Returned)

Workspace used to indicate which values have been used in estimating a resultant value.

NCON( NLINES ) = DOUBLE PRECISION (Returned)

The actual number of contributing pixels from each input line to the output line.

NFLAG = INTEGER (Returned)

Number of output pixels set to bad because insufficient pixels were present to form the statistic for the collapsed axis, provided the minimum number of contributing data values is one.

STATUS = INTEGER (Given and Returned)

The global status.

Notes:

• There is a routine for real and double-precision: replace "x" in the routine name by D or R as appropriate. The STACK, VARS, COORDS, RESULT, RESVAR, WIDTHS, WRK1, and WRK2 arguments supplied to the routine must have the data type specified.

• Various of the options are simply variations on a theme. The Broadened median is just a trimmed mean with a variable trimming fraction. The Mode is an iteratively carried out version of the sigma clipping (or more precisely the reverse). The minmax and threshold mean are also just trimmed means, but require their own mechanisms.

• The 'propagation' of the input variances assumes that the input data are fairly represented by a normal distribution. This fact is used together with the 'order statistics' of a normal population to form a new variance estimate. The order statistics are not independent so have non-zero covariances (off diagonal components of the variance-covariance matrix). All 'trimmed means' of any description use the order of the values to estimate which values are corrupt. This applies to all the methods supported here except the mean which rejects no data. The variance used to represent the input normal population is the reciprocal of the sum of the reciprocal variances. We have no other estimate of this value except from the population itself.

• Calculations are performed in double precision.