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:

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  
ia.addnoise()  
# 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.

This code is available under the terms of the GNU General Public Lincense


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