1funhist(1) SAORD Documentation funhist(1)
2
6 funhist - create a 1D histogram of a column (from a FITS binary table
7 or raw event file) or an image
8
10 funhist [-n⎪-w⎪-T] <iname> [column] [[lo:hi:]bins]
11
13 -n # normalize bin value by the width of each bin
14 -w # specify bin width instead of number of bins in arg3
15 -T # output in rdb/starbase format (tab separators)
16
18 funhist creates a one-dimensional histogram from the specified columns
19 of a FITS Extension binary table of a FITS file (or from a non-FITS raw
20 event file), or from a FITS image or array, and writes that histogram
21 as an ASCII table. Alternatively, the program can perform a 1D projec‐
22 tion of one of the image axes.
23 The first argument to the program is required, and specifies the Fun‐
25 tools file: FITS table or image, raw event file, or array. If "stdin"
26 is specified, data are read from the standard input. Use Funtools
27 Bracket Notation to specify FITS extensions, and filters.
28 For a table, the second argument also is required. It specifies the
30 column to use in generating the histogram. If the data file is of type
31 image (or array), the column is optional: if "x" (or "X"), "y" (or "Y")
32 is specified, then a projection is performed over the x (dim1) or y
33 (dim2) axes, respectively. (That is, this projection will give the same
34 results as a histogram performed on a table containing the equivalent
35 x,y event rows.) If no column name is specified or "xy" (or "XY") is
36 specified for the image, then a histogram is performed on the values
37 contained in the image pixels.
38 The argument that follows is optional and specifies the number of bins
40 to use in creating the histogram and, if desired, the range of bin val‐
41 ues. For image and table histograms, the range should specify the min
42 and max data values. For image histograms on the x and y axes, the
43 range should specify the min and max image bin values. If this argu‐
44 ment is omitted, the number of output bins for a table is calculated
45 either from the TLMIN/TLMAX headers values (if these exist in the table
46 FITS header for the specified column) or by going through the data to
47 calculate the min and max value. For an image, the number of output
48 bins is calculated either from the DATAMIN/DATAMAX header values, or by
49 going through the data to calculate min and max value. (Note that this
50 latter calculation might fail if the image cannot be fit in memory.)
51 If the data are floating point (table or image) and the number of bins
52 is not specified, an arbitrary default of 128 is used.
53 For binary table processing, the -w (bin width) switch can be used to
55 specify the width of each bin rather than the number of bins. Thus:
56 funhist test.ev pha 1:100:5
58 means that 5 bins of width 20 are used in the histogram, while:
60 funhist -w test.ev pha 1:100:5
62 means that 20 bins of width 5 are used in the histogram.
64 The data are divvied up into the specified number of bins and the
66 resulting 1D histogram (or projection) is output in ASCII table format.
67 For a table, the output displays the low_edge (inclusive) and hi_edge
68 (exclusive) values for the data. For example, a 15-row table containing
69 a "pha" column whose values range from -7.5 to 7.5 can be processed
70 thus:
71 [sh] funhist test.ev pha
73 # data file: /home/eric/data/test.ev
74 # column: pha
75 # min,max,bins: -7.5 7.5 15
76 bin value lo_edge hi_edge
78 ------ --------- --------------------- ---------------------
79 1 22 -7.50000000 -6.50000000
80 2 21 -6.50000000 -5.50000000
81 3 20 -5.50000000 -4.50000000
82 4 19 -4.50000000 -3.50000000
83 5 18 -3.50000000 -2.50000000
84 6 17 -2.50000000 -1.50000000
85 7 16 -1.50000000 -0.50000000
86 8 30 -0.50000000 0.50000000
87 9 16 0.50000000 1.50000000
88 10 17 1.50000000 2.50000000
89 11 18 2.50000000 3.50000000
90 12 19 3.50000000 4.50000000
91 13 20 4.50000000 5.50000000
92 14 21 5.50000000 6.50000000
93 15 22 6.50000000 7.50000000
94 [sh] funhist test.ev pha 1:6
96 # data file: /home/eric/data/test.ev
97 # column: pha
98 # min,max,bins: 0.5 6.5 6
99 bin value lo_edge hi_edge
101 ------ --------- --------------------- ---------------------
102 1 16 0.50000000 1.50000000
103 2 17 1.50000000 2.50000000
104 3 18 2.50000000 3.50000000
105 4 19 3.50000000 4.50000000
106 5 20 4.50000000 5.50000000
107 6 21 5.50000000 6.50000000
108 [sh] funhist test.ev pha 1:6:3
110 # data file: /home/eric/data/test.ev
111 # column: pha
112 # min,max,bins: 0.5 6.5 3
113 bin value lo_edge hi_edge
115 ------ --------- --------------------- ---------------------
116 1 33 0.50000000 2.50000000
117 2 37 2.50000000 4.50000000
118 3 41 4.50000000 6.50000000
119 For a table histogram, the -n(normalize) switch can be used to normal‐
121 ize the bin value by the width of the bin (i.e., hi_edge-lo_edge):
122 [sh] funhist -n test.ev pha 1:6:3
124 # data file: test.ev
125 # column: pha
126 # min,max,bins: 0.5 6.5 3
127 # width normalization (val/(hi_edge-lo_edge)) is applied
128 bin value lo_edge hi_edge
130 ------ --------------------- --------------------- ---------------------
131 1 16.50000000 0.50000000 2.50000000
132 2 6.16666667 2.50000000 4.50000000
133 3 4.10000000 4.50000000 6.50000000
134 This could used, for example, to produce a light curve with values hav‐
136 ing units of counts/second instead of counts.
137 For an image histogram, the output displays the low and high image val‐
139 ues (both inclusive) used to generate the histogram. For example, in
140 the following example, 184 pixels had a value of 1, 31 had a value of
141 2, while only 2 had a value of 3,4,5,6, or 7:
142 [sh] funhist test.fits
144 # data file: /home/eric/data/test.fits
145 # min,max,bins: 1 7 7
146 bin value lo_val hi_val
148 ------ --------------------- --------------------- ---------------------
149 1 184.00000000 1.00000000 1.00000000
150 2 31.00000000 2.00000000 2.00000000
151 3 2.00000000 3.00000000 3.00000000
152 4 2.00000000 4.00000000 4.00000000
153 5 2.00000000 5.00000000 5.00000000
154 6 2.00000000 6.00000000 6.00000000
155 7 2.00000000 7.00000000 7.00000000
156 For the axis projection of an image, the output displays the low and
158 high image bins (both inclusive) used to generate the projection. For
159 example, in the following example, 21 counts had their X bin value of
160 2, etc.:
161 [sh] funhist test.fits x 2:7
163 # data file: /home/eric/data/test.fits
164 # column: X
165 # min,max,bins: 2 7 6
166 bin value lo_bin hi_bin
168 ------ --------------------- --------------------- ---------------------
169 1 21.00000000 2.00000000 2.00000000
170 2 20.00000000 3.00000000 3.00000000
171 3 19.00000000 4.00000000 4.00000000
172 4 18.00000000 5.00000000 5.00000000
173 5 17.00000000 6.00000000 6.00000000
174 6 16.00000000 7.00000000 7.00000000
175 [sh] funhist test.fits x 2:7:2
177 # data file: /home/eric/data/test.fits
178 # column: X
179 # min,max,bins: 2 7 2
180 bin value lo_bin hi_bin
182 ------ --------------------- --------------------- ---------------------
183 1 60.00000000 2.00000000 4.00000000
184 2 51.00000000 5.00000000 7.00000000
185 You can use gnuplot or other plotting programs to graph the results,
187 using a script such as:
188 #!/bin/sh
190 sed -e '1,/---- .*/d
191 /^$/,$d' ⎪ \
192 awk '\
193 BEGIN{print "set nokey; set title \"funhist\"; set xlabel \"bin\"; set ylabel \"counts\"; plot \"-\" with boxes"} \
194 {print $3, $2, $4-$3}' ⎪ \
195 gnuplot -persist - 1>/dev/null 2>&1
196 Similar plot commands are supplied in the script funhist.plot:
198 funhist test.ev pha ... ⎪ funhist.plot gnuplot
200
202 See funtools(n) for a list of Funtools help pages
203version 1.4.2 January 2, 2008 funhist(1)