

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 3dimensional 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 noncumulative 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 

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=1e3,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