image.statistics - Function

Compute statistics from the image

Synopsis
statistics(statsout, axes, region, mask, plotstats, includepix, excludepix, plotter, nx, ny, list, force, disk, robust, verbose, async)

Arguments

statsout	out	Glish record containing all statistics
		Allowed:	Glish record
		Default:	No retrieval into a Glish record
axes	in	List of axes to evaluate statistics over
		Allowed:	Vector of integers
		Default:	All axes
region	in	Region of interest
		Allowed:	Region tool
		Default:	Whole image
mask	in	OTF mask
		Allowed:	Boolean LEL expression or mask region
		Default:	None
plotstats	in	List of statistics to plot
		Allowed:	String containing any combination of 'npts', 'sum', 'flux', 'sumsq', 'min', 'max', 'mean', 'sigma' (or 'stddev'), 'rms', 'median', 'medabsdevmed', 'quartile'
		Default:	'mean sigma'
includepix	in	Range of pixel values to include
		Allowed:	Vector of 1 or 2 Floats
		Default:	Include all pixels
excludepix	in	Range of pixel values to exclude
		Allowed:	Vector of 1 of 2 Floats
		Default:	Exclude no pixels
plotter	in	The PGPLOT device name to make plots on
		Allowed:	Any valid PGPLOT device
		Default:	No plotting
nx	in	The number of subplots per page in the x direction
		Allowed:	Any positive integer
		Default:	1
ny	in	The number of subplots per page in the y direction
		Allowed:	Any positive integer
		Default:	1
list	in	If T then list the statistics as well
		Allowed:	Bool
		Default:	T
force	in	If T then force the stored statistical accumulations to be regenerated
		Allowed:	Bool
		Default:	F
disk	in	If T then force the storage image to disk
		Allowed:	Bool
		Default:	F
robust	in	If T then compute robust statistics as well
		Allowed:	Bool
		Default:	F
verbose	in	If T then print useful messages to the logger
		Allowed:	Bool
		Default:	T
async	in	Run asynchronously?
		Allowed:	Bool
		Default:	!dowait - but always F if plotting

Returns
T or fail

Description

This function (short-hand name is stats) computes statistics from the pixel values in the image. You can then plot them, list them and retrieve them (into a Glish 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=[1,3]. The statistics would be computed for each XZ (axes 1 and 3) plane in the image. You could then examine those statistics as a function of the Y (axis 2) axis. Or perhaps you set axes=[3], whereupon you could examine the statistics for each Z (axis 3) profile as a function of X and Y location in the image.

You have control over how the statistics are presented; whether they are listed, or plotted, or retrieved into Glish records or all of the above.

A variety of statistics are offered for plotting and you can plot any combination of them simultaneously (argument plotstats).

If you retrieve the statistics into a Glish record (argument statsout) each statistic is stored in an array in one named field in the Glish 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=[3] and asked for statistics as a function of the remaining axes, in this case, the X and Y (axes 1 and 2) 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:

npts - the number of unmasked points used
sum - the sum of the pixel values: $\sum$ I_i
flux - the integrated flux density if the beam is defined and the brightness units are Jy/beam
sumsq - the sum of the squares of the pixel values: $\sum$ I_i²
mean - the mean of pixel values: $\bar{I}$ = $\sum$ I_i/n
sigma - the standard deviation about the mean: $\sigma^{2}_{}$ = ( $\sum$ I_i - $\bar{I}$ )²/(n - 1)
rms - the root mean square: $\sqrt{\sum I_i^2 / n}$
min - minimum pixel value
max - the maximum pixel value
median - the median pixel value (if robust=T)
medabsdevmed - the median of the absolute deviations from the median (if robust=T)
quartile - the inter-quartile range (if robust=T). Find the points which are 25% largest and 75% largest (the median is 50% largest), find their difference and divide that difference by 2.
blc - the absolute pixel coordinate of the bottom left corner of the bounding box
blcf - the formatted absolute world coordinate of the bottom left corner of the bounding box
trc - the absolute pixel coordinate of the top right corner of the bounding box
trcf - the formatted absolute world coordinate of the top right corner of the bounding box
minpos - absolute pixel coordinate of minimum pixel value
maxpos - absolute pixel coordinate of maximum pixel value
minposf - formatted string of the world coordinate of the minimum pixel value
maxposf - formatted string of the world coordinate of the maximum pixel value

the last four fields only appear if you evaluate the statistics over all axes in the image. As an example, if your output Glish record is called `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. length(rec.npts)==0).

If you retrieve statistics all of the available statistics are retrieved into the Glish record regardless of what you might have asked to plot. You can of course also plot the statistics by accessing the arrays in the Glish record, rather than using the built in plotting capability.

You also 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 list of statistics to plot. Second by setting robust=T (it defaults to F). For example, it may be that you are not making any plots but wish to recover the robust statistics into the output record. This is why this extra argument is needed.

Note that if the axes are set to all of the axes in the image (which is the default), no plotting is available as there would be 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)].

The plotting is done directly on a PGPLOT plotting device. The syntax is plotter=name/type. For example plotter='plot1.ps/ps' (disk postscript file) or plotter='plot/glish' (Glish pgplotter).

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.

Example

 
- im.statistics()

In this example, we ask to see statistics evaluated over the entire image. No plotting is available under these conditions.

Example

 
- im.statistics(statsout=mystats,axes=[2,3],plotstats='sigma, rms',
+               includepix=[0,100],plotter='/glish',list=F)

In this example, let us assume the image has 3 dimensions. We plot the standard deviation about the mean and the rms of YZ (axes 2 and 3) planes for pixels with values in the range 0 to 100 as a function of X-axis location on the standard PGPLOT X-windows device. The statistics are not listed to the logger. Because we are making plots, the tool function is automatically run synchronously so we can directly recover the the Glish record containing the statistics arrays.

Next: image.twopointcorrelation - Function Up: image - Tool Previous: image.setrestoringbeam - Function Contents Index

	Package	general
	Module	images
	Tool	image