1funtable(1) SAORD Documentation funtable(1)
2
6 funtable - copy selected rows from a Funtools file to a FITS binary ta‐
7 ble
8
10 funtable [-a] [-i⎪-z] [-m] [-s cols] <iname> <oname> [columns]
11
13 -a # append to existing output file as a table extension
14 -i # for image data, only generate X and Y columns
15 -m # for tables, write a separate file for each region
16 -s "col1 ..." # columns on which to sort
17 -z # for image data, output zero-valued pixels
18
20 funtable selects rows from the specified FITS Extension (binary table
21 only) of a FITS file, or from a non-FITS raw event file, and writes
22 those rows to a FITS binary table file. It also will create a FITS
23 binary table from an image or a raw array file.
24 The first argument to the program specifies the FITS file, raw event
26 file, or raw array file. If "stdin" is specified, data are read from
27 the standard input. Use Funtools Bracket Notation to specify FITS
28 extensions, and filters. The second argument is the output FITS file.
29 If "stdout" is specified, the FITS binary table is written to the stan‐
30 dard output. By default, all columns of the input file are copied to
31 the output file. Selected columns can be output using an optional
32 third argument in the form:
33 "column1 column1 ... columnN"
35 The funtable program generally is used to select rows from a FITS
37 binary table using Table Filters and/or Spatial Region Filters. For
38 example, you can copy only selected rows (and output only selected col‐
39 umns) by executing in a command such as:
40 [sh] funtable "test.ev[pha==1&&pi==10]" stdout "x y pi pha" ⎪ fundisp stdin
42 X Y PHA PI
43 ------- ------- ------- ---------
44 1 10 1 10
45 1 10 1 10
46 1 10 1 10
47 1 10 1 10
48 1 10 1 10
49 1 10 1 10
50 1 10 1 10
51 1 10 1 10
52 1 10 1 10
53 1 10 1 10
54 The special column $REGION can be specified to write the region id of
56 each row:
57 [sh $] funtable "test.ev[time-(int)time>=.99&&annulus(0 0 0 10 n=3)]" stdout 'x y time $REGION' ⎪ fundisp stdin
59 X Y TIME REGION
60 -------- -------- --------------------- ----------
61 5 -6 40.99000000 3
62 4 -5 59.99000000 2
63 -1 0 154.99000000 1
64 -2 1 168.99000000 1
65 -3 2 183.99000000 2
66 -4 3 199.99000000 2
67 -5 4 216.99000000 2
68 -6 5 234.99000000 3
69 -7 6 253.99000000 3
70 Here only rows with the proper fractional time and whose position also
72 is within one of the three annuli are written.
73 Columns can be excluded from display using a minus sign before the col‐
75 umn:
76 [sh $] funtable "test.ev[time-(int)time>=.99]" stdout "-time" ⎪ fundisp stdin
78 X Y PHA PI DX DY
79 -------- -------- -------- ---------- ----------- -----------
80 5 -6 5 -6 5.50 -6.50
81 4 -5 4 -5 4.50 -5.50
82 -1 0 -1 0 -1.50 0.50
83 -2 1 -2 1 -2.50 1.50
84 -3 2 -3 2 -3.50 2.50
85 -4 3 -4 3 -4.50 3.50
86 -5 4 -5 4 -5.50 4.50
87 -6 5 -6 5 -6.50 5.50
88 -7 6 -7 6 -7.50 6.50
89 All columns except the time column are written.
91 In general, the rules for activating and de-activating columns are:
93 · If only exclude columns are specified, then all columns but the
95 exclude columns will be activated.
96 · If only include columns are specified, then only the specified col‐
98 umns are activated.
99 · If a mixture of include and exclude columns are specified, then all
101 but the exclude columns will be active; this last case is ambiguous
102 and the rule is arbitrary.
103 In addition to specifying columns names explicitly, the special symbols
105 + and - can be used to activate and de-activate all columns. This is
106 useful if you want to activate the $REGION column along with all other
107 columns. According to the rules, the syntax "$REGION" only activates
108 the region column and de-activates the rest. Use "+ $REGION" to acti‐
109 vate all columns as well as the region column.
110 Ordinarily, only the selected table is copied to the output file. In a
112 FITS binary table, it sometimes is desirable to copy all of the other
113 FITS extensions to the output file as well. This can be done by append‐
114 ing a '+' sign to the name of the extension in the input file name. For
115 example, the first command below copies only the EVENT table, while the
116 second command copies other extensions as well:
117 [sh] funtable "/proj/rd/data/snr.ev[EVENTS]" events.ev
119 [sh] funtable "/proj/rd/data/snr.ev[EVENTS+]" eventsandmore.ev
120 If the input file is an image or a raw array file, then funtable will
122 generate a FITS binary table from the pixel values in the image. Note
123 that it is not possible to specify the columns to output (using com‐
124 mand-line argument 3). Instead, there are two ways to create such a
125 binary table from an image. By default, a 3-column table is generated,
126 where the columns are "X", "Y", and "VALUE". For each pixel in the
127 image, a single row (event) is generated with the "X" and "Y" columns
128 assigned the dim1 and dim2 values of the image pixel, respectively and
129 the "VALUE" column assigned the value of the pixel. With sort of table,
130 running funhist on the "VALUE" column will give the same results as
131 running funhist on the original image.
132 If the -i ("individual" rows) switch is specified, then only the "X"
134 and "Y" columns are generated. In this case, each positive pixel value
135 in the image generates n rows (events), where n is equal to the inte‐
136 gerized value of that pixel (plus 0.5, for floating point data). In
137 effect, -i approximately recreates the rows of a table that would have
138 been binned into the input image. (Of course, this is only approxi‐
139 mately correct, since the resulting x,y positions are integerized.)
140 If the -s [col1 col2 ... coln] ("sort") switch is specified, the output
142 rows of a binary table will be sorted using the specified columns as
143 sort keys. The sort keys must be scalar columns and also must be part
144 of the output file (i.e. you cannot sort on a column but not include it
145 in the output). This facility uses the _sort program (included with
146 funtools), which must be accessible via your path.
147 For binary tables, the -m ("multiple files") switch will generate a
149 separate file for each region in the filter specification i.e. each
150 file contains only the rows from that region. Rows which pass the fil‐
151 ter but are not in any region also are put in a separate file.
152 The separate output file names generated by the -m switch are produced
154 automatically from the root output file to contain the region id of the
155 associated region. (Note that region ids start at 1, so that the file
156 name associated with id 0 contains rows that pass the filter but are
157 not in any given region.) Output file names are generated as follows:
158 · A $n specification can be used anywhere in the root file name
160 (suitably quoted to protect it from the shell) and will be expanded
161 to be the id number of the associated region. For example:
162 funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo.goo_$n.fits'
164 will generate files named foo.goo_0.fits (for rows not in any
166 region but still passing the filter), foo.goo_1.fits (rows in
167 region id #1, the first region), foo.goo_2.fits (rows in region id
168 #2), etc. Note that single quotes in the output root are required
169 to protect the '$' from the shell.
170 · If $n is not specified, then the region id will be placed before
172 the first dot (.) in the filename. Thus:
173 funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' foo.evt.fits
175 will generate files named foo0.evt.fits (for rows not in any region
177 but still passing the filter), foo1.evt.fits (rows in region id
178 #1), foo2.evt.fits (rows in region id #2), etc.
179 · If no dot is specified in the root output file name, then the
181 region id will be appended to the filename. Thus:
182 funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo_evt'
184 will generate files named foo_evt0 (for rows not in any region but
186 still passing the filter), foo_evt1 (rows in region id #1),
187 foo_evt2 (rows in region id #2), etc.
188 The multiple file mechanism provide a simple way to generate individual
190 source data files with a single pass through the data.
191 By default, a new FITS file is created and the binary table is written
193 to the first extension. If the -a (append) switch is specified, the
194 table is appended to an existing FITS file as a BINTABLE extension.
195 Note that the output FITS file must already exist.
196 If the -z ("zero" pixel values) switch is specified and -i is not spec‐
198 ified, then pixels having a zero value will be output with their
199 "VALUE" column set to zero. Obviously, this switch does not make sense
200 when individual events are output.
201
203 See funtools(n) for a list of Funtools help pages
204version 1.4.0 August 15, 2007 funtable(1)