Program: HISTOG
Purpose: Program creates histogram of intensities in a set
or part of a set.
Category: ANALYSIS, PLOTTING
File: histog.c
Author: M. Vogelaar
Keywords:
INSET= Give set (, subsets) for histogram:
Maximum number of subsets is 2048.
BOX= Frame for input subsets. [entire subset]
RANGE= Give range in pixel values: [all values]
To exclude pixels from the calculations, specify
a range. Example:
RANGE=1 5 : INCLUDE all pixels with value
equal to or between 1 and 5.
RANGE=5 1 : EXCLUDE all pixels with value
between 1 and 5.
GRDEVICE= Give graphics device to [list of available devices]
plot on:
** PGMOSAIC= View surface sub divisions in x,y: [1,1]
View surface can contain a number of plots in
in X and Y direction (mosaic). Default is 1 plot in
both X- and Y direction.
** PAPER= Give width (cm), aspect ratio: [0.0,1.0]
Change the size of the (output) view surface.
The aspect ratio is defined as height/width.
The default is a calculated size and aspect ratio 1.
** LINEWIDTH= Give line width (1-21): [2]
Only required if a hardcopy device is selected.
AUTOSCALE= Automatic scaling of each plot: [Y]/N
In the default mode the program calculates
suitable plot boundaries. If no automatic
scaling is selected, the boundaries of the first
plot will be default for plots of data from other
subsets.
MINMAX= Give min. and max. value of data:
MINMAX= determines the length of the X-axis of the
histogram.
If the set header provides minimum and maximum, the
keyword is asked hidden.
FIXBIN= Do you want to fix the bin width? Y/[N]
If the user wants to select a constant bin width,
FIXBIN=Y has to be specified and you are prompted
with keyword BINWIDTH=
BINS= Give number of histogram bins: [100]
If FIXBIN=N, specify the number of bins.
BINWIDTH= Give width of histogram bin:
If FIXBIN=Y, specify the width of a bin.
** CUMULATIVE= Plot cumulative histogram? Y/[N]
** YLOG= Y axis logarithmic? Y/[N]
** LOGFILE= Print histogram values in Log-file Y/[N]
** GAUSS= Plot a Gauss? Y/[N]
Include a Gaussian curve in the plot.
GAUPAR= Amplitude, Mean, Sigma & Zero level: [calculated]
The defaults for the Gauss parameters are the value
of the mode, the mean and rms of the histogram
data. The default for the offset is 0.
COUNTS= Interval of counts to plot: [total range of counts]
Select Y-axis interval of histogram.
Description: The pixels in a set have a value in units given by the
header of the set. HISTOG creates a histogram of these
values. The bin width is in the same units as the pixel
values and the bin height is the number of pixels in
your (sub)set that have a value in that bin.
Along with a plot some elementary statistics are calculated
(mean, rms, etc). There is also an option to plot a
gaussian curve in the histogram.
Set and subsets are given by INSET=
Example: INSET=n1260s60 f ra 0
to get a histogram of data in set n1260s60 ( a RA-DEC-FREQ
set ) along the DEC axis at RA = 0 and for all frequencies.
If you want only a part of the DEC axis use keyword BOX=
to define that part. If you are not satisfied with some
data values and want to exclude these values use RANGE=
Note that there is a special syntax for this keyword.
RANGE=3 5 INCLUDES all values between 3 and 5 (values 3
and 5 included),
RANGE=5 3 EXCLUDES all values between 3 and 5.
If the calculations extend over more than one subset then
there are two plot modes: first there is a possibility
to scale the data for each plot automatically
(AUTOSCALE=Y), second there is an option to fix the plot
characteristics. With AUTOSCALE=N, histograms of
different subsets can be compared (Use PGMOSAIC= to create
'sub pages' on screen or paper). The choice has
to be made before starting the loop over your subsets.
The plot dimensions are controlled by two keywords:
MINMAX= gives the lowest and the highest bin values
(in header units) along the histogram's X-axis.
COUNTS= gives the minimum and maximum heights of all
histogram bins. The minimum value is 0 and the maximum
value cannot be less than the minimum value + 1.
The program automatically corrects for wrong input.
Defaults are calculated for each subset individually.
Lets discuss MINMAX= in more detail:
For each subset the values of the minimum and maximum on the
x-axis can be set with MINMAX=. With these numbers the
number of histogram bins (BINS=) or the bin width (BINWIDTH=)
is calculated. The MINMAX= keyword can be asked hidden
or with defaults. This depends on the program status:
1) If a valid range was given (RANGE=a b and a < b)
the keyword is hidden and the default for MINMAX=
are these range values. These values are used for all
subsets.
2) If 1) is not valid, the program looks in the header of
the input set if "DATAMIN" and "DATAMAX" are defined.
If not, then the user is prompted for the keyword (no
defaults allowed) for each subset.
3) If the header items are defined however, and the user
did not select automatic scaling (AUTOSCALE=N), the keyword
is hidden. The defaults for all subsets are the values that
were found in the header of the first subset.
If automatic scaling was selected, the defaults
are the header values found for each subset.
The bin width can be controlled in two different ways.
If FIXBIN=N, the user must give the number of bins to create
within the given data range. If FIXBIN=N
you must specify a bin width in units of your data.
Other plot options are:
-Create a cumulative histogram ((CUMULATIVE=Y).
-Label 'count' axis Logarithmically (YLOG=Y).
-Include a gaussian curve (GAUSS=Y) with user given
(GAUPAR=) parameters. The defaults for amplitude, mean
and sigma, are calculated by the program. The default for
the offset in Y-direction (zero level) is 0.
-Write bin values and bin heights in log file (LOGFILE=Y).
-Adjust size of plot on output device with PAPER=.
The first parameter is the requested plot width in
cm. The second is the aspect ratio (height/width).
Define the number of histograms in one plot with
PGMOSAIC=
-The width of the plotted lines can be changed on
the output device with LINEWIDTH=. The default
gives a reasonable plot. The keyword is asked only if
you specified a printer after GRDEVICE=.
Example:
histog paper=14 gauss=y
INSET=test2
Set TEST2 has 3 axes
RA-NCP from -9 to 10
DEC-NCP from -9 to 10
FREQ-OHEL from 0 to 9
BOX=
BOX range for set TEST2 :
RA-NCP from -9 to 10
DEC-NCP from -9 to 10
FREQ-OHEL from 0 to 9
RANGE=
GRDEVICE=laserp
FIXBIN=
BINS=200
============================================================
Set: TEST2 (RA,DEC,VELO)=(*,*,*)
============================================================
Range in selected data: All values
Total number of valid pixels: 4000
Number of blanks: 0
Min. and max. in data: (-4.87012, 14.6622)
Min. and max. in plot: (-4.87012, 14.8575)
Sum : 17987.4
Mean: 4.49684
Rms: 3.49833
Mode: X=(4.69777, 4.7964), (Y=54)
============================================================
GAUPAR=
COUNTS=
histog - +++ FINISHED +++
Updates: Mar 1, 1991: VOG, Document created.
Oct 10, 1991: WZ, PGPLOT standard names implemented.
Jun 20, 1994: VOG, Changed defaults for some keywords.
Dec 14, 1994: VOG, Allocate array space dynamical.
Feb 22, 1996: VOG, Bug removed in length of dynamical
array 'counts'.