diff options
Diffstat (limited to 'funtools/man/man1/funhist.1')
| -rw-r--r-- | funtools/man/man1/funhist.1 | 370 |
1 files changed, 370 insertions, 0 deletions
diff --git a/funtools/man/man1/funhist.1 b/funtools/man/man1/funhist.1 new file mode 100644 index 0000000..38708ee --- /dev/null +++ b/funtools/man/man1/funhist.1 @@ -0,0 +1,370 @@ +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to +.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' +.\" expand to `' in nroff, nothing in troff, for use with C<>. +.tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "funhist 1" +.TH funhist 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +funhist \- create a 1D histogram of a column (from a FITS binary table or raw event file) or an image +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBfunhist\fR [\-n|\-w|\-T] <iname> [column] [[lo:hi:]bins] +.SH "OPTIONS" +.IX Header "OPTIONS" +.Vb 3 +\& \-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) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBfunhist\fR creates a one-dimensional histogram from the specified +columns of a \s-1FITS\s0 Extension +binary table of a \s-1FITS\s0 file (or from a non-FITS raw event file), or +from a \s-1FITS\s0 image or array, and writes that histogram as an \s-1ASCII\s0 +table. Alternatively, the program can perform a 1D projection of one +of the image axes. +.PP +The first argument to the program is required, and specifies the +Funtools file: \s-1FITS\s0 table or image, raw event file, or array. If +\&\*(L"stdin\*(R" is specified, data are read from the standard input. Use +Funtools Bracket Notation to specify \s-1FITS\s0 +extensions, and filters. +.PP +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 \*(L"x\*(R" (or \*(L"X\*(R"), \*(L"y\*(R" +(or \*(L"Y\*(R") 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 +\&\*(L"xy\*(R" (or \*(L"\s-1XY\s0\*(R") is specified for the image, then a histogram is +performed on the values contained in the image pixels. +.PP +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 \s-1TLMIN/TLMAX\s0 headers values (if these exist +in the table \s-1FITS\s0 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 \s-1DATAMIN/DATAMAX\s0 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. +.PP +For binary table processing, the \fB\-w\fR (bin width) switch can be used +to specify the width of each bin rather than the number of bins. Thus: +.PP +.Vb 1 +\& funhist test.ev pha 1:100:5 +.Ve +.PP +means that 5 bins of width 20 are used in the histogram, while: +.PP +.Vb 1 +\& funhist \-w test.ev pha 1:100:5 +.Ve +.PP +means that 20 bins of width 5 are used in the histogram. +.PP +The data are divvied up into the specified number of bins and the +resulting 1D histogram (or projection) is output in \s-1ASCII\s0 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 \*(L"pha\*(R" column whose values range from \-7.5 to 7.5 +can be processed thus: +.PP +.Vb 4 +\& [sh] funhist test.ev pha +\& # data file: /home/eric/data/test.ev +\& # column: pha +\& # min,max,bins: \-7.5 7.5 15 +.Ve +.PP +.Vb 17 +\& 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 +.Ve +.PP +.Vb 4 +\& [sh] funhist test.ev pha 1:6 +\& # data file: /home/eric/data/test.ev +\& # column: pha +\& # min,max,bins: 0.5 6.5 6 +.Ve +.PP +.Vb 8 +\& 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 +.Ve +.PP +.Vb 4 +\& [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 +.Ve +.PP +.Vb 5 +\& bin value lo_edge hi_edge +\& ------ --------- --------------------- --------------------- +\& 1 33 0.50000000 2.50000000 +\& 2 37 2.50000000 4.50000000 +\& 3 41 4.50000000 6.50000000 +.Ve +.PP +For a table histogram, the \fB\-n\fR(normalize) switch can be used to +normalize the bin value by the width of the bin (i.e., hi_edge\-lo_edge): +.PP +.Vb 5 +\& [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 +.Ve +.PP +.Vb 5 +\& 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 +.Ve +.PP +This could used, for example, to produce a light curve with values +having units of counts/second instead of counts. +.PP +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: +.PP +.Vb 3 +\& [sh] funhist test.fits +\& # data file: /home/eric/data/test.fits +\& # min,max,bins: 1 7 7 +.Ve +.PP +.Vb 9 +\& 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 +.Ve +.PP +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.: +.PP +.Vb 4 +\& [sh] funhist test.fits x 2:7 +\& # data file: /home/eric/data/test.fits +\& # column: X +\& # min,max,bins: 2 7 6 +.Ve +.PP +.Vb 8 +\& 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 +.Ve +.PP +.Vb 4 +\& [sh] funhist test.fits x 2:7:2 +\& # data file: /home/eric/data/test.fits +\& # column: X +\& # min,max,bins: 2 7 2 +.Ve +.PP +.Vb 4 +\& bin value lo_bin hi_bin +\& ------ --------------------- --------------------- --------------------- +\& 1 60.00000000 2.00000000 4.00000000 +\& 2 51.00000000 5.00000000 7.00000000 +.Ve +.PP +You can use gnuplot or other plotting programs to graph the +results, using a script such as: +.PP +.Vb 7 +\& #!/bin/sh +\& sed \-e '1,/---- .*/d +\& /^$/,$d' | \e +\& awk '\e +\& BEGIN{print "set nokey; set title \e"funhist\e"; set xlabel \e"bin\e"; set ylabel \e"counts\e"; plot \e"-\e" with boxes"} \e +\& {print $3, $2, $4-$3}' | \e +\& gnuplot \-persist - 1>/dev/null 2>&1 +.Ve +.PP +Similar plot commands are supplied in the script \fBfunhist.plot\fR: +.PP +.Vb 1 +\& funhist test.ev pha ... | funhist.plot gnuplot +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages |