1.1.1.0 image.histograms

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()

__________________________________________________________________

[next] [prev] [prev-tail] [front] [up]

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

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