diff options
Diffstat (limited to 'funtools/doc/pod/funhist.pod')
| -rw-r--r-- | funtools/doc/pod/funhist.pod | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/funtools/doc/pod/funhist.pod b/funtools/doc/pod/funhist.pod new file mode 100644 index 0000000..fc1885d --- /dev/null +++ b/funtools/doc/pod/funhist.pod @@ -0,0 +1,252 @@ +=pod + +=head1 NAME + + + +B<funhist - create a 1D histogram of a column (from a FITS binary table or raw event file) or an image> + + + +=head1 SYNOPSIS + + + + + +funhist [-n|-w|-T] <iname> [column] [[lo:hi:]bins] + + + + + +=head1 OPTIONS + + + + + + -n # normalize bin value by the width of each bin + -w # specify bin width instead of number of bins in arg3 + -T # output in rdb/starbase format (tab separators) + + + + +=head1 DESCRIPTION + + + + +B<funhist> creates a one-dimensional histogram from the specified +columns of a FITS Extension +binary table of a FITS file (or from a non-FITS raw event file), or +from a FITS image or array, and writes that histogram as an ASCII +table. Alternatively, the program can perform a 1D projection of one +of the image axes. + + +The first argument to the program is required, and specifies the +Funtools file: FITS table or image, raw event file, or array. If +"stdin" is specified, data are read from the standard input. Use +Funtools Bracket Notation to specify FITS +extensions, and filters. + + +For a table, the second argument also is required. It specifies the +column to use in generating the histogram. If the data file is of +type image (or array), the column is optional: if "x" (or "X"), "y" +(or "Y") is specified, then a projection is performed over the x +(dim1) or y (dim2) axes, respectively. (That is, this projection will +give the same results as a histogram performed on a table containing +the equivalent x,y event rows.) If no column name is specified or +"xy" (or "XY") is specified for the image, then a histogram is +performed on the values contained in the image pixels. + + +The argument that follows is optional and specifies the number of bins +to use in creating the histogram and, if desired, the range of bin +values. For image and table histograms, the range should specify the +min and max data values. For image histograms on the x and y axes, +the range should specify the min and max image bin values. If this +argument is omitted, the number of output bins for a table is +calculated either from the TLMIN/TLMAX headers values (if these exist +in the table FITS header for the specified column) or by going through +the data to calculate the min and max value. For an image, the number +of output bins is calculated either from the DATAMIN/DATAMAX header +values, or by going through the data to calculate min and max value. +(Note that this latter calculation might fail if the image cannot be +fit in memory.) If the data are floating point (table or image) and +the number of bins is not specified, an arbitrary default of 128 is +used. + + +For binary table processing, the B<-w> (bin width) switch can be used +to specify the width of each bin rather than the number of bins. Thus: + + funhist test.ev pha 1:100:5 + +means that 5 bins of width 20 are used in the histogram, while: + + funhist -w test.ev pha 1:100:5 + +means that 20 bins of width 5 are used in the histogram. + + +The data are divvied up into the specified number of bins and the +resulting 1D histogram (or projection) is output in ASCII table +format. For a table, the output displays the low_edge (inclusive) and +hi_edge (exclusive) values for the data. For example, a 15-row table +containing a "pha" column whose values range from -7.5 to 7.5 +can be processed thus: + + + [sh] funhist test.ev pha + # data file: /home/eric/data/test.ev + # column: pha + # min,max,bins: -7.5 7.5 15 + + bin value lo_edge hi_edge + ------ --------- --------------------- --------------------- + 1 22 -7.50000000 -6.50000000 + 2 21 -6.50000000 -5.50000000 + 3 20 -5.50000000 -4.50000000 + 4 19 -4.50000000 -3.50000000 + 5 18 -3.50000000 -2.50000000 + 6 17 -2.50000000 -1.50000000 + 7 16 -1.50000000 -0.50000000 + 8 30 -0.50000000 0.50000000 + 9 16 0.50000000 1.50000000 + 10 17 1.50000000 2.50000000 + 11 18 2.50000000 3.50000000 + 12 19 3.50000000 4.50000000 + 13 20 4.50000000 5.50000000 + 14 21 5.50000000 6.50000000 + 15 22 6.50000000 7.50000000 + + [sh] funhist test.ev pha 1:6 + # data file: /home/eric/data/test.ev + # column: pha + # min,max,bins: 0.5 6.5 6 + + bin value lo_edge hi_edge + ------ --------- --------------------- --------------------- + 1 16 0.50000000 1.50000000 + 2 17 1.50000000 2.50000000 + 3 18 2.50000000 3.50000000 + 4 19 3.50000000 4.50000000 + 5 20 4.50000000 5.50000000 + 6 21 5.50000000 6.50000000 + + [sh] funhist test.ev pha 1:6:3 + # data file: /home/eric/data/test.ev + # column: pha + # min,max,bins: 0.5 6.5 3 + + bin value lo_edge hi_edge + ------ --------- --------------------- --------------------- + 1 33 0.50000000 2.50000000 + 2 37 2.50000000 4.50000000 + 3 41 4.50000000 6.50000000 + + + +For a table histogram, the B<-n>(normalize) switch can be used to +normalize the bin value by the width of the bin (i.e., hi_edge-lo_edge): + + [sh] funhist -n test.ev pha 1:6:3 + # data file: test.ev + # column: pha + # min,max,bins: 0.5 6.5 3 + # width normalization (val/(hi_edge-lo_edge)) is applied + + bin value lo_edge hi_edge + ------ --------------------- --------------------- --------------------- + 1 16.50000000 0.50000000 2.50000000 + 2 6.16666667 2.50000000 4.50000000 + 3 4.10000000 4.50000000 6.50000000 + +This could used, for example, to produce a light curve with values +having units of counts/second instead of counts. + + +For an image histogram, the output displays the low and high image +values (both inclusive) used to generate the histogram. For example, +in the following example, 184 pixels had a value of 1, 31 had a value +of 2, while only 2 had a value of 3,4,5,6, or 7: + + [sh] funhist test.fits + # data file: /home/eric/data/test.fits + # min,max,bins: 1 7 7 + + bin value lo_val hi_val + ------ --------------------- --------------------- --------------------- + 1 184.00000000 1.00000000 1.00000000 + 2 31.00000000 2.00000000 2.00000000 + 3 2.00000000 3.00000000 3.00000000 + 4 2.00000000 4.00000000 4.00000000 + 5 2.00000000 5.00000000 5.00000000 + 6 2.00000000 6.00000000 6.00000000 + 7 2.00000000 7.00000000 7.00000000 + + + +For the axis projection of an image, the output displays the low and +high image bins (both inclusive) used to generate the projection. For +example, in the following example, 21 counts had their X bin value of +2, etc.: + + [sh] funhist test.fits x 2:7 + # data file: /home/eric/data/test.fits + # column: X + # min,max,bins: 2 7 6 + + bin value lo_bin hi_bin + ------ --------------------- --------------------- --------------------- + 1 21.00000000 2.00000000 2.00000000 + 2 20.00000000 3.00000000 3.00000000 + 3 19.00000000 4.00000000 4.00000000 + 4 18.00000000 5.00000000 5.00000000 + 5 17.00000000 6.00000000 6.00000000 + 6 16.00000000 7.00000000 7.00000000 + + [sh] funhist test.fits x 2:7:2 + # data file: /home/eric/data/test.fits + # column: X + # min,max,bins: 2 7 2 + + bin value lo_bin hi_bin + ------ --------------------- --------------------- --------------------- + 1 60.00000000 2.00000000 4.00000000 + 2 51.00000000 5.00000000 7.00000000 + + + +You can use gnuplot or other plotting programs to graph the +results, using a script such as: + + #!/bin/sh + sed -e '1,/---- .*/d + /^$/,$d' | \ + awk '\ + BEGIN{print "set nokey; set title \"funhist\"; set xlabel \"bin\"; set ylabel \"counts\"; plot \"-\" with boxes"} \ + {print $3, $2, $4-$3}' | \ + gnuplot -persist - 1>/dev/null 2>&1 + + +Similar plot commands are supplied in the script B<funhist.plot>: + + funhist test.ev pha ... | funhist.plot gnuplot + + + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + +=cut |