NRAO Home > CASA > CASA Toolkit Reference Manual
image.histograms - Function

1.1.1 Compute histograms from the image


Description

This method computes histograms of the pixel values in the image. The values are returned in a dictionary.

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

You have control over the number of bins for each histogram (nbins). The bin width is worked out automatically for each histogram and may vary from histogram to histogram (the range of pixel values is worked out for each chunk being histogrammed).

You have control over which pixels are included in the histograms via the includepix argument. This vector specifies a range of pixel values to be included in the histograms. If you only give one value for this, say includepix=[b], then this is interpreted as includepix=[-abs(b),abs(b)]. If you specify an inclusion range, then the range of pixel intensities over which the histograms are binned is given by this range too. This is a way to make the bin width the same for each histogram.

You can control if the histogram is cumulative or non-cumulative via the cumu parameter.

You have countrol over how the bin counts are returned. If log = false, the actual counts are returned. If true, the values returned are the log10 values of the actual counts.

The results are returned as a dictionary. The counts (field ”counts”) and the abscissa values (field ”values”) for all bins in each histogram are returned. The shape of the first dimension of those arrays contained in those fields is nbins. The number and shape of the remaining dimensions are those of the display axes(the axes in the image for which you did not compute the histograms). For example, if one has a three dimensional image and sets axes=[2], the display axes are 0 and 1, so the shape of each counts and values array is then [nbins,nx,ny], where nx and ny are the length of the zeroth and first axes, respectively.

In addition, the mean (field ”mean”) and standard deviation (field ”sigma”) computed using the data in each histogram is returned. The shape of these arrays is equal to the shape of the display axes. So,

Arguments





Inputs

axes

List of axes to compute histograms over. Default is all axes.

allowed:

intArray

Default:

-1

region

Region selection. See ”help par.region” for details. Default is to use the full image.

allowed:

any

Default:

variant

mask

Mask to use. See help par.mask. Default is none.

allowed:

any

Default:

variant

nbins

Number of bins in histograms, > 0

allowed:

int

Default:

25

includepix

Range of pixel values to include. Default is to include all pixels.

allowed:

doubleArray

Default:

-1

cumu

If T the bin values are cumulative.

allowed:

bool

Default:

false

log

If true, the returned counts values will be the log10 values of the actual counts, if false, the actual counts will be returned.

allowed:

bool

Default:

false

stretch

Stretch the mask if necessary and possible? See help par.stretch. Default False

allowed:

bool

Default:

false

Returns
record

Example

 
 
# obtain a histogram using the entire image  
ia.maketestimage()  
res = ia.histograms()  
ia.close()  
 
# obtain histograms for each plane along axis 1 with each  
# histogram having 30 bins. Only pixel values in the range  
# -0.001 to 0.001 are used in computing the histograms and the  
# statistics. The counts in the returned data structure represent  
# the cumulative number of data points in the current bin and in  
# bins less than the current bin.  
ia.open("myimage.im")  
r = ia.histograms(axes=[0,2],nbins=30,includepix=1e-3,cumu=T)  
ia.close()  
 

__________________________________________________________________


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

Copyright 2016 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