.\" 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