1.1.1.0 image.histograms

1.1.1 Compute histograms from the image
Description

This function computes histograms of the pixel values in the image file. You can retrieve them (into a record) for further analysis or display.

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 have control over the form of the histogram; the ordinate can be linear or logarithmic (log=T), and cumulative or non-cumulative (cumu=F).

You can overlay a Gaussian on each histogram (gauss=T). It has the same mean and standard deviation about the mean of the pixels that were binned and the same integral as the histogram.

You can list some additional statistical information about the data in each image chunk that is being histogrammed (list=T).

You can retrieve the histograms into a record (the counts and the abcissa values for each histogram). The names of the fields in the record are ‘values’ and ‘counts’. 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 in the image for which you did not compute the histograms. For example, in the second example above, we set axes=[2] and asked for histograms as a function of the remaining axes, in this case, the X and Y (axes 0 and 1) axes. The shape of each histogram array is then [nbins,nx,ny]. The form of the retrieved histograms is that specified by the cumu and log arguments.

This function generates “storage” images, into which the histograms and statistics are written. They are only regenerated when necessary. For example, if you run the function twice successively with identical arguments, the histograms will be directly retrieved from the storage image. 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.


Outputs
histout	record containing the histograms
	allowed:	any
	Default:	record
Inputs
axes	List of axes to compute histograms over. Default is all axes.
	allowed:	intArray
	Default:	-1
region	Region of interest. Default is whole image.
	allowed:	any
	Default:	record
mask	OTF mask, Boolean LEL expression or mask region. 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
gauss	If T overlay a Gaussian on each histogram
	allowed:	bool
	Default:	false
cumu	If T plot cumulative histograms, otherwise plot non-cumulatively
	allowed:	bool
	Default:	false
log	If T plot the ordinate logarithmically, otherwise plot linearly
	allowed:	bool
	Default:	false
list	If T then list some statistics as well
	allowed:	bool
	Default:	true
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
size	Size of plotter. Default is [600, 450].
	allowed:	intArray
	Default:	600 450
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
async	Run asynchronously?
	allowed:	bool
	Default:	false

In this example, let us assume the image has 3 dimensions. We generate cumulative histograms of XZ (axes 0 and 2) planes for pixels with values in the range -0.001 to 0.001 and plot them with Gaussian overlays as a function of Y-axis location. The histograms are retrieved into a record r[’histout’] for further use.

image.histograms - Function