1 files changed, 181 insertions, 0 deletions
diff --git a/pkg/plot/doc/phistogram.hlp b/pkg/plot/doc/phistogram.hlp
new file mode 100644
index 00000000..adfe5a1f
--- /dev/null
+++ b/pkg/plot/doc/phistogram.hlp
@@ -0,0 +1,181 @@
+.help phistogram Nov89 plot
+.ih
+NAME
+phistogram -- print or plot the histogram of an image or stream of values
+.ih
+USAGE
+phistogram input
+.ih
+PARAMETERS
+.ls input
+The name of the image, image subsection, or the text file containing the
+stream of values whose histogram is to be computed. \fIInput\fR may be
+the standard input "STDIN".
+.le
+.ls 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.
+.le
+.ls binwidth = INDEF
+The resolution of the histogram in data units. If \fIbinwidth\fR is not defined,
+the parameters \fInbins\fR, \fIz1\fR, and \fIz2\fR determine the resolution of
+the histogram.
+.le
+.ls nbins = 512
+The number of bins in, or resolution of, the histogram. 
+The \fInbins\fR parameter is overridden if \fIbinwidth\fR is defined.
+.le
+.ls autoscale = yes
+In the case of integer image data, automatically adjust \fInbins\fR and
+\fIz2\fR to avoid aliasing effects. Data in text files is not autoscaled.
+.le
+.ls top_closed = no
+Include z2 in the top bin?  Each bin of the histogram is a subinterval
+that is half open at the top.  \fITop_closed\fR decides whether those
+pixels with values equal to z2 are to be counted in the histogram.  If
+\fBtop_closed\fR is yes, the top bin will be larger than the other bins.
+.le
+.ls 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].
+.le
+.ls listout = no
+List instead of plot the histogram?  The list is never log scaled.
+.le
+.ls 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.
+.le
+.ls xlabel = "Data values", ylabel = "Counts"
+The labels for the X and Y axes.
+.le
+.ls 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.
+.le
+.ls logx = no, logy = yes
+Use log scaling on the x or y axes of the plot?
+.le
+.ls round = no
+Round the axes minimum and maximum values up to "nice" values?
+.le
+.ls plot_type = "line"
+The style of histogram to plot. The options are "line", "box" and "fullbox".
+If \fIplot_type\fR 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.
+.le
+.ls box = yes
+Draw axes at the perimeter of the plotting window?
+.le
+.ls ticklabels = yes
+Label the tick marks?
+.le
+.ls 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.
+.le
+.ls fill = yes
+Fill the output viewport regardless of the device aspect ratio?
+.le
+.ls vx1 = 0.0, vx2 = 1.0, vy1 = 0.0, vy2 = 1.0
+The NDC coordinates (0.0:1.0) of the device plotting viewport.
+.le
+.ls append = no
+Append to an existing plot?
+.le
+.ls pattern = "solid"
+The type of line used to draw the histogram. The options are "solid",
+"dashed" "dotted", and "dotdash". \fIPattern\fR can be changed when
+appending to an existing plot.
+.le
+.ls device = "stdgraph"
+The output graphics device.
+.le
+.ih
+DESCRIPTION
+\fIPhistogram\fR computes the histogram of the IRAF image or stream
+of values in the text file specified by
+\fIinput\fR, using the parameters \fIbinwidth\fR, \fInbins\fR,
+\fIz1\fR and \fIz2\fR.
+If either \fIz1\fR or \fIz2\fR is undefined the data minimum or
+maximum values define the histogram limits.
+If \fIbinwidth\fR is undefined, \fInbins\fR
+determines the resolution of the histogram. If \fIlistout\fR = no,
+the histogram is plotted on
+the graphics device \fIdevice\fR in the style specified by
+\fIplot_type\fR.  The plot may be log scaled if \fIlogy\fR = yes (the
+default) and the input is an IRAF image.  If \fIlistout\fR = 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 \fIhist_type\fR 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
+\fItop_closed\fR parameter.  This is usually only of concern with integer
+image data and histograms with few bins.
+
+If \fBappend\fR is enabled, previous values for \fBbox\fR,
+\fBfill\fR, \fBround\fR, the plotting viewport (\fBvx1\fR, \fBvx2\fR, 
+\fBvy1\fR, \fBvy2\fR), and the plotting window (\fBwx1\fR, \fBwx2\fR, 
+\fBwy1\fR, \fBwy2\fR) are used.
+
+By default, the plot drawn will fill the device viewport.  Setting
+the value of \fBfill\fR  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 \fBfill = no\fR, 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 \fBfill\fR = no.
+
+.ih
+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
+.ih
+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 \fIaliasing\fR can occur.  The effect is to cause periodic zero dropouts
+(for an oversampled histogram) or excess-valued bins (for a slightly
+undersampled histogram).  The \fIautoscaling\fR 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 \fIsmoothing\fR of
+the histogram will occur whenever the data range exceeds the histogram
+resolution.
+.ih
+SEE ALSO
+listpixels, plot.graph, proto.mkhistogram
+.endhelp