NAME

imhistogram -- print or plot the histogram of an image

USAGE

imhistogram image

PARAMETERS

image

The name of the image or image subsection whose histogram is to be calculated.

z= INDEF, z2 = INDEF

The minimum and maximum histogram intensity. The image minimum and maximum pixel values are used by default.

binwidth = INDEF

The resolution of the histogram in counts. If binwidth is not defined, the parameter nbins determines the histogram resolution.

nbins = 512

The number of bins in, or resolution of, the histogram. The nbins parameter is overridden if binwidth is defined.

autoscale = yes

In the case of integer data, automatically adjust nbins and z2 to avoid aliasing effects.

top_closed = no

Include z2 in the top bin? Each bin of the histogram is a subinterval that is half open at the top. Top_closed decides whether those pixels with values equal to z2 are to be counted in the histogram. If top_closed is yes, the top bin will be larger than the other bins.

hist_type = "normal"

The type of histogram to plot or list. The choices are "normal", "cumulative", "difference", or "second_difference". The two "difference" options are calculated as forward differences, i.e., diff[n] = hist[n+1] - hist[n].

listout = no

List instead of plot the histogram? The list is never log scaled.

plot_type = "line"

The plot vector type. The options are "line" and "box".

logy = yes

Use log scaling on the y-axis of the plot?

device = "stdgraph"

The output graphics device.

DESCRIPTION

imhistogram calculates the histogram of the IRAF image image using the parameters nbins , z1 and z2 . If either z1 or z2 is undefined the image mininum or maximum is used. If listout = no, the histogram is plotted on the graphics device device in the vector mode specified by plot_type . The plot may be log scaled if logy = yes (the default). If listout = yes, the histogram is listed on the standard output.

In addition to producing the "normal" histogram, the task will also calculate cumulative and marginal (forward difference) histograms depending on the choice of the hist_type parameter (choices are: "normal", "cumulative", "difference", and "second_difference"). The plot will be labeled by the type of histogram as well as the image name and title and the binning parameters.

Each bin of the histogram is defined to be half open at the top. This results in an ambiguity deciding whether those pixels with z=z2 are included in the topmost bin. This decision is left to the user via the top_closed parameter. This is usually only important with integer images and histograms with few bins.

EXAMPLES

1. Output the histogram of an image to a file.

cl> imhist M51.imh li+ nbins=100 > fits1.hst

2. Plot the histogram of another image between the values 0 and 2000.

cl> imhist M31.imh nbins=100 z1=0. z2=2000.

3. Ditto, but set the histogram resolution explicitly to avoid smoothing the histogram.

cl> imhist M31.imh nbins=100 z1=0 z2=2000 nbins=2001

4. Plot the cumulative histogram. This is most useful for images with fairly flat "normal" histograms.

cl> imhist R50.imh hist=cum

BUGS

If the resolution of the histogram (number of bins) is a non-integral multiple of the intensity resolution of the data (number of possible intensity values), then aliasing can occur. The effect is to cause periodic zero dropouts (for an oversampled histogram) or excess-valued bins (for a slightly undersampled histogram). The autoscaling feature, if enabled, will adjust the histogram parameters to avoid such aliasing effects for integer data. This is not possible for floating point data, however, in which case aliasing is certainly possible and can only be avoided by manually adjusting the histogram parameters. One should also be aware that smoothing of the histogram will occur whenever the data range exceeds the histogram resolution.

SEE ALSO

listpixels, plot.graph, proto.mkhistogram