From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001 From: Joe Hunkeler Date: Tue, 11 Aug 2015 16:51:37 -0400 Subject: Repatch (from linux) of OSX IRAF --- pkg/plot/doc/phistogram.hlp | 181 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 pkg/plot/doc/phistogram.hlp (limited to 'pkg/plot/doc/phistogram.hlp') 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 -- cgit