1.1.1.0 image.statistics

1.1.1 Compute statistics from the image
Description

This function computes statistics from the pixel values in the image. You can then list them and retrieve them (into a record) for further analysis.

The chunk of the image over which you evaluate the statistics is specified by an array of axis numbers (argument axes). For example, consider a 3-dimensional image for which you specify axes=[0,2]. The statistics would be computed for each XZ (axes 0 and 2) plane in the image. You could then examine those statistics as a function of the Y (axis 1) axis. Or perhaps you set axes=[2], whereupon you could examine the statistics for each Z (axis 2) profile as a function of X and Y location in the image.

If you retrieve the statistics from the returned record, each statistic is stored in an array in one named field in the record. The shape of that array is that of the axes which you did not evaluate the statistics over. For example, in the second example above, we set axes=[2] and asked for statistics as a function of the remaining axes, in this case, the X and Y (axes 0 and 1) axes. The shape of each statistics array is then [nx,ny].

The names of the fields in this record are the same as the names of the statistics that you can plot:

The last four fields only appear if you evaluate the statistics over all axes in the image. As an example, if the returned record is saved in ‘mystats’, then you could access the ‘mean’ field via print mystats[’mean’].

If there are no good points (e.g. all pixels are masked bad in the region), then the length of these fields will be 0 (e.g. len(mystats[’npts’])==0).

You have no control over which statistics are listed to the logger, you always get the same selection. You can choose to list the statistics or not (argument list).

As well as the simple (and faster to calculate) statistics like means and sums, you can also compute some robust statistics. Currently these are the median, median absolute deviations from the median and the inter-quartile range. Because these are computationally expensive, they are only computed if you directly ask for them. You can do this in two ways. First by requesting a robust statistic in the string array assigned to plotstats. Second by setting robust=T (it defaults to F).

Note that if the axes are set to all of the axes in the image (which is the default) there is just one point per statistic.

You have control over which pixels are included in the statistical sums via the includepix and excludepix arguments. These vectors specify a range of pixel values for which pixels are either included or excluded. They are mutually exclusive; you can specify one or the other, but not both. If you only give one value for either of these, say includepix=b, then this is interpreted as includepix=[-abs(b),abs(b)].

This function generates a ‘storage’ lattice, into which the statistics are written. It is only regenerated when necessary. For example, if you run the function twice with identical arguments, the statistics will be directly retrieved from the storage lattice the second time. However, you can force regeneration of the storage image if you set force=T. The storage medium is either in memory or on disk, depending upon its size. You can force it to disk if you set disk=T, otherwise it decides for itself.


Inputs
axes	List of axes to evaluate statistics over. Default is all axes.
	allowed:	intArray
	Default:	-1
region	Region of interest. Default is whole image.
	allowed:	any
	Default:	record
mask	OTF mask, Boolean LEL expression or mask region. Default is none.
	allowed:	any
	Default:	variant
plotstats	List of statistics to plot String containing any combination of ’npts’, ’sum’, ’flux’, ’sumsq’, ’min’, ’max’, ’mean’, ’sigma’ (or ’stddev’), ’rms’, ’median’, ’medabsdevmed’, ’quartile’ Default is [’mean’,’sigma’].
	allowed:	stringArray
	Default:
includepix	Range of pixel values to include. Vector of 1 or 2 doubles. Default is to include all pixels.
	allowed:	doubleArray
	Default:	-1
excludepix	Range of pixel values to exclude. Vector of 1 or 2 doubles. Default is exclude no pixels.
	allowed:	doubleArray
	Default:	-1
plotter	The PGPLOT device name to make plots on. Default is no plotting.
	allowed:	string
	Default:
nx	The number of subplots per page in the x direction, ¿ 0
	allowed:	int
	Default:	1
ny	The number of subplots per page in the y direction, ¿ 0
	allowed:	int
	Default:	1
list	If T then list the statistics as well
	allowed:	bool
	Default:	true
force	If T then force the stored statistical accumulations to be regenerated
	allowed:	bool
	Default:	false
disk	If T then force the storage image to disk
	allowed:	bool
	Default:	false
robust	If T then compute robust statistics as well
	allowed:	bool
	Default:	false
verbose	If T then print useful messages to the logger
	allowed:	bool
	Default:	true
async	Run asynchronously?
	allowed:	bool
	Default:	false

In this example, let us assume the image has 2 dimensions. We want the standard deviation about the mean and the rms of Y (axes 1) for pixels with values in the range 0 to 100 as a function of the X-axis location. The statistics are not listed to the logger but are saved in the record ’stats’.

image.statistics - Function