phistogram: Plot or print the histogram of an image or list

Package: plot

Usage

phistogram input

Parameters

input: The name of the image, image subsection, or the text file containing the stream of values whose histogram is to be computed. Input may be the standard input "STDIN".

z1 = INDEF, z2 = INDEF: The minimum and maximum values included in the histogram. The image or data minimum and maximum values are used by default.

binwidth = INDEF: The resolution of the histogram in data units. If binwidth is not defined, the parameters nbins, z1, and z2 determine the resolution of the histogram.

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 image data, automatically adjust nbins and z2 to avoid aliasing effects. Data in text files is not autoscaled.

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.

title = "imtitle": The plot title. If title = "imtitle", the image name and title or the text file name, and the characteristics of the histogram are included in the title.

xlabel = "Data values", ylabel = "Counts": The labels for the X and Y axes.

wx1 = INDEF, wx2 = INDEF, wy1 = 0.0, wy2 = INDEF: The range of user coordinates spanned by the plot. If either of the x axis limits is INDEF the histogram minimum or maximum data values are used. If either of the y axis limits is INDEF, the minimum or maximum counts in the histogram is used.

logx = no, logy = yes: Use log scaling on the x or y axes of the plot?

round = no: Round the axes minimum and maximum values up to "nice" values?

plot_type = "line": The style of histogram to plot. The options are "line", "box" and "fullbox". If plot_type is "line" the histogram data points are connected by straight lines; if it is "box" a stepped histogram is drawn; if it is "fullbox" the histogram lines are drawn to the base of the plot.

box = yes: Draw axes at the perimeter of the plotting window?

ticklabels = yes: Label the tick marks?

majrx = 5, minrx = 5, majry = 5, minry = 5: Number of major tick marks on each axis and number of minor tick marks between major tick marks. These quantities are ignored if log scaling is in effect for an axis.

fill = yes: Fill the output viewport regardless of the device aspect ratio?

vx1 = 0.0, vx2 = 1.0, vy1 = 0.0, vy2 = 1.0: The NDC coordinates (0.0:1.0) of the device plotting viewport.

append = no: Append to an existing plot?

pattern = "solid": The type of line used to draw the histogram. The options are "solid", "dashed" "dotted", and "dotdash". Pattern can be changed when appending to an existing plot.

device = "stdgraph": The output graphics device.

Description

Phistogram computes the histogram of the IRAF image or stream of values in the text file specified by input, using the parameters binwidth, nbins, z1 and z2. If either z1 or z2 is undefined the data minimum or maximum values define the histogram limits. If binwidth is undefined, nbins determines the resolution of the histogram. If listout = no, the histogram is plotted on the graphics device device in the style specified by plot_type. The plot may be log scaled if logy = yes (the default) and the input is an IRAF image. If listout = yes, the histogram is printed on the standard output.

In addition to computing the "normal" histogram, PHISTOGRAM can also calculate the cumulative and the first and second difference histograms depending on the value of the hist_type parameter. The options are: "normal", "cumulative", "difference", and "second_difference".

Each bin of the histogram is defined to be half open at the top. This results in an ambiguity in 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 of concern with integer image data and histograms with few bins.

If append is enabled, previous values for box, fill, round, the plotting viewport (vx1, vx2, vy1, vy2), and the plotting window (wx1, wx2, wy1, wy2) are used.

By default, the plot drawn will fill the device viewport. Setting the value of fill to "no" means the viewport will be adjusted so that equal numbers of data values in x and y will occupy equal lengths when plotted. That is, when fill = no, a unity aspect ratio is enforced, and plots appear square regardless of the device aspect ratio. On devices with non square full device viewports (e.g., the vt640), a plot drawn by PHISTOGRAM appears extended in the x direction unless fill = no.

Examples

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

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

2. Plot the histogram of an image using only values from 0 to 2000.

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

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

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

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

cl> phist R50.imh hist=cum

5. Plot the histogram of a stream of values in the textfile "list".

cl> phist list

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.