XMM-Newton Science Analysis System


ssclib (ssclib-4.30) [xmmsas_20160201_1833-15.0.0]

Meta Index / Home Page / General-purpose array-processing utilities

aryStatInfo???T structure definition

A set of structure definitions is provided. The above `???' can be Double, Single, Int32, Int16 or Int8. This gives a structure for the statistics for a given (2-d?) array. The following is the example of aryStatInfoDoubleT.

  type, public :: aryStatInfoDoubleT
     real(double)   :: totalsum, mean, sigma
     real(double)   :: realsum
     integer(int32) :: totalentry, validentry
     real(double)   :: minval, maxval
     integer(int32), dimension(:), allocatable :: minindices, maxindices
     real(double)   :: vallower, valupper
     integer(int32), dimension(:), allocatable :: minareaindices, maxareaindices
     type(aryStatInfoFlagT) :: flag
  end type aryStatInfoDoubleT

This structure is meant to offer the statistical information of an array or its subset. That is, the statistical information for the array, where the valid entry can be filtered based on given

1. external mask file, where True entry is valid,
2. lower and/or upper thresholds for value at each cell,
3. lower and/or upper boundaries (area, if 2-dim) of the indices of the array cell.

If more than one filter condition are given, then the logical product of those conditions are considered, namely, only the entries that satisfy all the given filter conditions are used. Note that the boundary is inclusive for the second and third conditions. For example, if the lower thresholds for value at each cell is given to be 2.5, then the cells of which the value is smaller than 2.5 are regarded as invalid and are not counted as the valid entry.

Table 1 shows the (supposed) meaning of each element as well as gives the difference in types of elements between the structures (such as, aryStatInfoDoubleT and aryStatInfoInt32T). Technically each user could give a different meaning for them, but it is discouraged for an obvious reason.

Table 1: Elements in aryStatInfoT

Element	Type$^1$	Description
%totalsum	D/S/I32	Sum (for the valid entry)
%realsum	D	Sum (for the valid entry)
%mean	D (S for SingleT)	Mean
%sigma	D (S for SingleT)	Standard deviation$^2$
%totalentry	I32	Total entry (size) of the array.
%validentry	I32	The entry used in calculation.
%minval	D/S/I32/I16/I8	Minimum value among the valid entry.
%maxval	D/S/I32/I16/I8	Minimum value among the valid entry.
%minindices	I32 [Array]	Location (indices: x,y,...) of minval
%maxindices	I32 [Array]	Location (indices: x,y,...) of maxval
%vallower	D (S for SingleT)	Lower threshold to be a valid entry (if specified).
%valupper	D (S for SingleT)	Upper threshold to be a valid entry (if specified).
%minareaindices	I32 [Array]	Minimum indices for the area of valid entry.
%maxareaindices	I32 [Array]	Maximum indices for the area of valid entry.
%flag%status	Integer	0 if normal.
%flag%isValLowerUsed	Logical	True if vallower is used.
%flag%isValUpperUsed	Logical	True if valupper is used.
%flag%isAreaLowerUsed	Logical	True if minareaindices is used.
%flag%isAreaUpperUsed	Logical	True if maxareaindices is used.
%flag%isMaskUsed	Logical	True if an external mask is used.

$^1$: D(Double), S(Single), I32/I16/I8 (Int32/Int16/Int8)
$^2$: $\sqrt{\frac{1}{N}\sum_{i} (x_i- \bar{x})^2}$.

Notes: Some of the elements of the structure can be undefined. For example, if flag%isAreaLowerUsed is false, the array minareaindices is likely to be undefined, even its size (NOT allocated). Similarly flag%isValLowerUsed is false, vallower is likely to be undefined, and so on. If one tries to access those undefined values that may cause a trouble or even Fortran error, leading to abortion.

The difference between the elements of totalsum and realsum is the type; the latter is always double, whereas the former is double/single/int32, depending on the type of the input array; n.b., it is int32 for any of the integer array. The totalsum for an integer array may overflow; in that case totalsum has a value INTEGER_NULL. Another note is that although the they type of realsum for a single-precission float array is double, obviously it has a practical accuracy of only single-precission.