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'.