funhist(1)
🌸 funhist(1) — NAME 🌸
okay bestie, welcome to funhist — she lives in the SAORD Documentation family (it's giving classic Unix manual energy, and I'm obsessed) 💅
funhist — make a 1D histogram out of a column (from a FITS binary table or a raw event file) or out of an image ✨
🦋 SYNOPSIS 🦋
funhist [-n|-w|-T] <iname> [column] [[lo:hi:]bins]🎀 OPTIONS 🎀
-n— normalize each bin value by the width of that bin 💖-w— say the bin width instead of the number of bins inarg3🫶-T— output in rdb/starbase format (tab separators, periodt) ✨
👑 DESCRIPTION 👑
So basically: funhist builds a one-dimensional histogram out of the columns you specify in a FITS Extension binary table inside a FITS file (or out of a non-FITS raw event file), or out of a FITS image or array — and then it writes that histogram out as an ASCII table. Alternatively, she can do a 1D projection of one of the image axes. no cap 🔥
The first argument is required — that's the Funtools file: a FITS table or image, a raw event file, or an array. If you pass "stdin", the data get read from standard input 💫 Use Funtools Bracket Notation to specify FITS extensions, and filters, iykyk.
For a table, the second argument is also required. It's the column you want the histogram built from. But if the data file is an image (or an array), the column is optional: if you say "x" (or "X"), or "y" (or "Y"), then a projection happens over the x (dim1) or y (dim2) axes respectively. (That projection gives you the exact same results as a histogram done on a table that contains the equivalent x,y event rows, fr fr.) And if you specify no column name at all — or you say "xy" (or "XY") for an image — then the histogram is performed on the values contained in the image pixels 🌸
The argument that follows is optional and it's where you say how many bins to use, and if you want, the range of bin values too. 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 you leave this argument out, the number of output bins for a table gets calculated either from the TLMIN/TLMAX header values (if those 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 gets calculated either from the DATAMIN/DATAMAX header values, or by going through the data to calculate the min and max value. (Heads up: that second calculation might fail if the image cannot be fit in memory 😭.) And if the data are floating point (table or image) and the number of bins isn't specified, an arbitrary default of 128 is used.
For binary table processing, the -w (bin width) switch lets you specify the width of each bin instead of the number of bins. So check this out:
funhist test.ev pha 1:100:5means 5 bins of width 20 are used in the histogram, while:
funhist -w test.ev pha 1:100:5means 20 bins of width 5 are used in the histogram. same numbers, completely different vibe, wild right 💀
The data get 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 shows you the low_edge (inclusive) and the 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 like this:
[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.50000000For a table histogram, the -n (normalize) switch can 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.50000000You could use that, for example, to produce a light curve with values having units of counts/second instead of counts. glow up 💅
For an image histogram, the output shows the low and high image values (both inclusive) used to generate the histogram. For example, in the following, 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.00000000For the axis projection of an image, the output shows the low and high image bins (both inclusive) used to generate the projection. For example, in the following, 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.00000000You 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>&1Similar plot commands are supplied in the script funhist.plot:
funhist test.ev pha ... | funhist.plot gnuplot🌈 SEE ALSO 🌈
See funtools(7) for a list of Funtools help pages 🫶
and that's the whole page bestie 💖 this was version 1.4.5, dated April 14, 2011, and it's the funhist(1) manual — iconic, timeless, we stan a classic 🎀✨
📦 where this page comes from
- debian bookworm: funtools 1.4.8-1 · GPL
- debian trixie: funtools 1.4.8-1.1+b2 · GPL
- ubuntu jammy: funtools 1.4.8-1 · GPL
- ubuntu noble: funtools 1.4.8-1.1build2 · GPL
- ubuntu questing: funtools 1.4.8-2
- ubuntu resolute: funtools 1.4.8-2build1 · GPL
- ubuntu stonking: funtools 1.4.8-2build1 · GPL
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms