NRAO Home > CASA > CASA Toolkit Reference Manual
##### image.statistics - Function

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:

• npts - the number of unmasked points used
• sum - the sum of the pixel values: Ii
• 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: Ii2
• mean - the mean of pixel values: I = Ii∕n
• sigma - the standard deviation about the mean: σ2 = ( Ii -I)2(n - 1)
• rms - the root mean square:
• 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 of the region of interest. If ’region’ is unset, this will be the bottom left corner of the whole image.
• blcf - the formatted absolute world coordinate of the bottom left corner of the bounding box of the region of interest.
• trc - the absolute pixel coordinate of the top right corner of the bounding box of the region of interest.
• trcf - the formatted absolute world coordinate of the top right corner of the bounding box of the region of interest.
• 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 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 can of course plot the statistics by accessing the arrays in the record.

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.

Arguments

 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 Mask to use. See help par.mask. 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 True print bounding box and statistics to logger. 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 log statistics allowed: bool Default: true async Run asynchronously? allowed: bool Default: false stretch Stretch the mask if necessary and possible? See help par.stretch. Default False allowed: bool Default: false logfile Name of file to which to write statistics. allowed: string Default: append Append results to logfile? Logfile must be specified. Default is to append. False means overwrite existing file if it exists. allowed: bool Default: true
Returns
anyrecord

Example

"""
#
print "\t----\t statistics Ex 1 \t----"
ia.maketestimage()
ia.statistics()
ia.close()
#

# evaluate statistics for each spectral plane in an ra x dec x frequency image
ia.fromshape("", [20,30,40])
# give pixels non-zero values
# These are the display axes, the calculation of statistics occurs
# for each (hyper)plane along axes not listed in the axes parameter,
# in this case axis 2 (the frequency axis)
# display the rms for each frequency plane (your mileage will vary with
# the values).
stats = ia.statistics(axes=[0,1])
stats["rms"]
Out[10]:
array([ 0.99576014,  1.03813124,  0.97749186,  0.97587883,  1.04189885,
1.03784776,  1.03371549,  1.03153074,  1.00841606,  0.947155  ,
0.97335404,  0.94389403,  1.0010221 ,  0.97151822,  1.03942156,
1.01158476,  0.96957082,  1.04212773,  1.00589049,  0.98696715,
1.00451481,  1.02307892,  1.03102005,  0.97334671,  0.95209879,
1.02088714,  0.96999902,  0.98661619,  1.01039267,  0.96842754,
0.99464947,  1.01536798,  1.02466023,  0.96956468,  0.98090756,
0.9835844 ,  0.95698935,  1.05487967,  0.99846411,  0.99634868])

"""

In this example, we ask to see statistics evaluated over the
entire image.

Example

"""
#
print "\t----\t statistics Ex 2 \t----"
ia.maketestimage()
stats = ia.statistics(axes=[1],plotstats=["sigma","rms"],
includepix=[0,100],list=F)
#
"""

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 {\stfaf ’stats’}.

__________________________________________________________________

More information about CASA may be found at the CASA web page

Copyright © 2010 Associated Universities Inc., Washington, D.C.

Home | Contact Us | Directories | Site Map | Help | Privacy Policy | Search