funtable(1)

🎀 funtable(1) — SAORD Documentation 🎀

okay bestie, listen. this is the funtable page from the SAORD Documentation crew, and it's literally the row-copying icon of the Funtools world 💅

---

✨ NAME ✨

funtable — copy selected rows from a Funtools file to a FITS binary table 🦋

---

🌸 SYNOPSIS 🌸

funtable [-a] [-i⎪-z] [-m] [-s cols] <iname> <oname> [columns]

---

💖 OPTIONS 💖

• -a — append to an existing output file, as a table extension 👑
• -i — when it's image data, only generate the X and Y columns 🎀
• -m — for tables, write a separate file for each region 🗂️
• -s "col1 ..." — the columns you wanna sort on ⭐
• -z — when it's image data, output the zero-valued pixels too 🙈

---

🦋 DESCRIPTION 🦋

funtable grabs rows from a specified FITS Extension (binary table only, no cap) of a FITS file, or from a non-FITS raw event file, and writes those rows into a FITS binary table file. It can also straight up build a FITS binary table out of an image or a raw array file. it's giving multitasker 💅

The first argument is the FITS file, raw event file, or raw array file. Say "stdin" and the data gets read from standard input instead. Use Funtools Bracket Notation to specify FITS extensions and filters, iykyk. The second argument is the output FITS file — and if you say "stdout", the FITS binary table goes to standard output instead. By default every single column of the input file gets copied to the output. Wanna pick and choose? There's an optional third argument shaped like this:

"column1 column1 ... columnN"

The funtable program is mostly used to select rows from a FITS binary table using Table Filters and/or Spatial Region Filters. So like, you can copy only selected rows (and output only selected columns) by running something like:

[sh] funtable "test.ev[pha==1&&pi==10]" stdout "x y pi pha" ⎪ fundisp stdin
       X       Y     PHA        PI
 ------- ------- ------- ---------
       1      10       1        10
       1      10       1        10
       1      10       1        10
       1      10       1        10
       1      10       1        10
       1      10       1        10
       1      10       1        10
       1      10       1        10
       1      10       1        10
       1      10       1        10

There's a special column called $REGION that you can ask for, and it writes the region id of each row 🌈:

[sh $] funtable "test.ev[time-(int)time>=.99&&annulus(0 0 0 10 n=3)]" stdout 'x y time $REGION' ⎪ fundisp stdin
        X        Y                  TIME     REGION
 -------- -------- --------------------- ----------
        5       -6           40.99000000          3
        4       -5           59.99000000          2
       -1        0          154.99000000          1
       -2        1          168.99000000          1
       -3        2          183.99000000          2
       -4        3          199.99000000          2
       -5        4          216.99000000          2
       -6        5          234.99000000          3
       -7        6          253.99000000          3

So here, only the rows with the right fractional time and a position inside one of the three annuli get written. vibe check passed ✨

You can also kick columns out of the display by putting a minus sign in front of the column name:

[sh $] funtable "test.ev[time-(int)time>=.99]" stdout "-time" ⎪ fundisp stdin
        X        Y      PHA         PI          DX          DY
 -------- -------- -------- ---------- ----------- -----------
        5       -6        5         -6        5.50       -6.50
        4       -5        4         -5        4.50       -5.50
       -1        0       -1          0       -1.50        0.50
       -2        1       -2          1       -2.50        1.50
       -3        2       -3          2       -3.50        2.50
       -4        3       -4          3       -4.50        3.50
       -5        4       -5          4       -5.50        4.50
       -6        5       -6          5       -6.50        5.50
       -7        6       -7          6       -7.50        6.50

Every column except the time column gets written. periodt 💅

In general, the rules for activating and de-activating columns are:

• If you only specify exclude columns, then all columns except the exclude columns will be activated. 🫶
• If you only specify include columns, then only the columns you named are activated. ✨
• If you mix include and exclude columns, then all but the exclude columns will be active — and ngl bestie, this last case is ambiguous and the rule is arbitrary. 💀

Besides spelling out column names, the special symbols + and - can activate and de-activate all the columns. Super useful if you want the $REGION column live alongside all the others. Going by the rules above, plain "$REGION" only activates the region column and de-activates everything else. So use "+ $REGION" to activate all columns and the region column 🌟

Normally, only the selected table gets copied to the output file. But with a FITS binary table, sometimes you lowkey want all the other FITS extensions copied over too. You do that by appending a '+' sign to the name of the extension in the input file name. So like, the first command below copies only the EVENT table, while the second copies the other extensions as well:

[sh] funtable "/proj/rd/data/snr.ev[EVENTS]" events.ev
[sh] funtable "/proj/rd/data/snr.ev[EVENTS+]" eventsandmore.ev

If the input file is an image or a raw array file, then funtable will generate a FITS binary table from the pixel values in that image. Heads up though: it is not possible to specify the columns to output (that would be command-line argument 3). Instead, there are two ways to create a binary table from an image. By default, a 3-column table is generated, where the columns are "X", "Y", and "VALUE". For every pixel in the image, a single row (event) is generated, with the "X" and "Y" columns getting the dim1 and dim2 values of the image pixel respectively, and the "VALUE" column getting the value of the pixel. With that kind of table, running funhist on the "VALUE" column gives you the same results as running funhist on the original image. slay 🔥

If the -i ("individual" rows) switch is specified, then only the "X" and "Y" columns get generated. In that case, each positive pixel value in the image generates n rows (events), where n is the integerized value of that pixel (plus 0.5, for floating point data). Basically, -i approximately recreates the rows of a table that would have been binned into the input image. (And yeah, that's only approximately correct, since the resulting x,y positions get integerized. 🫠)

If the -s [col1 col2 ... coln] ("sort") switch is specified, the output rows of a binary table will be sorted using the specified columns as sort keys. The sort keys must be scalar columns and must also be part of the output file — meaning you can't sort on a column and then not include it in the output. no sneaky business 🙅‍♀️ This facility uses the _sort program (included with funtools), which has to be accessible via your path.

For binary tables, the -m ("multiple files") switch generates a separate file for each region in the filter specification — so each file contains only the rows from that one region. Rows that pass the filter but aren't in any region also get dropped into a separate file. 🗂️

The separate output file names generated by -m are produced automatically from the root output file, so they contain the region id of the associated region. (Quick note: region ids start at 1, so the file name associated with id 0 holds the rows that pass the filter but aren't in any given region.) Output file names are generated like this:

• A $n specification can be used anywhere in the root file name (suitably quoted to protect it from the shell) and will be expanded to be the id number of the associated region. For example:

funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo.goo_$n.fits'

will generate files named foo.goo_0.fits (for rows not in any region but still passing the filter), foo.goo_1.fits (rows in region id #1, the first region), foo.goo_2.fits (rows in region id #2), etc. Note that the single quotes in the output root are required to protect the '$' from the shell 🐚

• If $n is not specified, then the region id will be placed before the first dot (.) in the filename. Thus:

funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' foo.evt.fits

will generate files named foo0.evt.fits (for rows not in any region but still passing the filter), foo1.evt.fits (rows in region id #1), foo2.evt.fits (rows in region id #2), etc. ✨

• If no dot is specified in the root output file name, then the region id will be appended to the filename. Thus:

funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo_evt'

will generate files named foo_evt0 (for rows not in any region but still passing the filter), foo_evt1 (rows in region id #1), foo_evt2 (rows in region id #2), etc. 🌈

The multiple file mechanism provides a simple way to generate individual source data files with a single pass through the data. one pass, many files, main character energy 👑

By default, a new FITS file is created and the binary table is written to the first extension. If the -a (append) switch is specified, the table is appended to an existing FITS file as a BINTABLE extension. > Careful bestie: with -a, the output FITS file must already exist. 💀

If the -z ("zero" pixel values) switch is specified and -i is not specified, then pixels having a zero value will be output with their "VALUE" column set to zero. And obviously, this switch does not make sense when individual events are output. like, it literally cannot 🙈

---

💜 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 ATE. go copy some rows, you got this 💅✨🎀