1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
=pod
=head1 NAME
B<funtable - copy selected rows from a Funtools file to a FITS binary table>
=head1 SYNOPSIS
funtable [-a] [-i|-z] [-m] [-s cols] <iname> <oname> [columns]
=head1 OPTIONS
-a # append to existing output file as a table extension
-i # for image data, only generate X and Y columns
-m # for tables, write a separate file for each region
-s "col1 ..." # columns on which to sort
-z # for image data, output zero-valued pixels
=head1 DESCRIPTION
B<funtable> selects rows from the specified
FITS Extension
(binary table only) of a FITS file, or from a non-FITS raw event
file, and writes those rows to a FITS binary table file. It also
will create a FITS binary table from an image or a raw array file.
The first argument to the program specifies the FITS file, raw event
file, or raw array file. If "stdin" is specified, data are read from
the standard input. Use Funtools Bracket
Notation to specify FITS extensions, and filters. The second
argument is the output FITS file. If "stdout" is specified, the FITS
binary table is written to the standard output. By default, all
columns of the input file are copied to the output file. Selected
columns can be output using an optional third argument in the form:
"column1 column1 ... columnN"
The B<funtable> program generally is used to select rows from a
FITS binary table using
Table Filters
and/or
Spatial Region Filters.
For example, you can copy only selected rows (and output only selected
columns) by executing in a command such as:
[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
The special column B<$REGION> can be specified to write 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
Here only rows with the proper fractional time and whose position also is
within one of the three annuli are written.
Columns can be excluded from display using a minus sign before the
column:
[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
All columns except the time column are written.
In general, the rules for activating and de-activating columns are:
=over 4
=item *
If only exclude columns are specified, then all columns but
the exclude columns will be activated.
=item *
If only include columns are specified, then only the specified columns
are activated.
=item *
If a mixture of include and exclude columns are specified, then
all but the exclude columns will be active; this last case
is ambiguous and the rule is arbitrary.
=back
In addition to specifying columns names explicitly, the special
symbols I<+> and I<-> can be used to activate and
de-activate I<all> columns. This is useful if you want to
activate the $REGION column along with all other columns. According
to the rules, the syntax "$REGION" only activates the region column
and de-activates the rest. Use "+ $REGION" to activate all
columns as well as the region column.
Ordinarily, only the selected table is copied to the output file. In
a FITS binary table, it sometimes is desirable to copy all of the
other FITS extensions to the output file as well. This can be done by
appending a '+' sign to the name of the extension in the input file
name. For example, the first command below copies only the EVENT table,
while the second command copies 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
B<funtable> will generate a FITS binary table from the pixel
values in the image. Note that it is not possible to specify the
columns to output (using command-line argument 3). Instead, there are
two ways to create such a binary table from an image. By default, a
3-column table is generated, where the columns are "X", "Y", and
"VALUE". For each pixel in the image, a single row (event) is
generated with the "X" and "Y" columns assigned the dim1 and dim2
values of the image pixel, respectively and the "VALUE" column
assigned the value of the pixel. With sort of table, running
B<funhist> on the "VALUE" column will give the same results as
running B<funhist> on the original image.
If the B<-i> ("individual" rows) switch is specified, then only
the "X" and "Y" columns are generated. In this case, each positive
pixel value in the image generates n rows (events), where n is equal
to the integerized value of that pixel (plus 0.5, for floating point
data). In effect, B<-i> approximately recreates the rows of a
table that would have been binned into the input image. (Of course,
this is only approximately correct, since the resulting x,y positions
are integerized.)
If the B<-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 also must be part of the output file (i.e. you cannot sort on a
column but not include it in the output). This facility uses the
B<_sort> program (included with funtools), which must be accessible
via your path.
For binary tables, the B<-m> ("multiple files") switch will
generate a separate file for each region in the filter specification
i.e. each file contains only the rows from that region. Rows
which pass the filter but are not in any region also are put in a
separate file.
The separate output file names generated by the B<-m> switch are
produced automatically from the root output file to contain the region id of
the associated region. (Note that region ids start at 1, so that the
file name associated with id 0 contains rows that pass the filter but
are not in any given region.) Output file names are generated as follows:
=over 4
=item *
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 single quotes
in the output root are required to protect the '$' from the shell.
=item *
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.
=item *
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.
=back
The multiple file mechanism provide a simple way to generate
individual source data files with a single pass through the data.
By default, a new FITS file is created and the binary table is written
to the first extension. If the B<-a> (append) switch is specified,
the table is appended to an existing FITS file as a BINTABLE extension.
Note that the output FITS file must already exist.
If the B<-z> ("zero" pixel values) switch is specified and
B<-i> is not specified, then pixels having a zero value will
be output with their "VALUE" column set to zero. Obviously, this
switch does not make sense when individual events are output.
=head1 SEE ALSO
See funtools(n) for a list of Funtools help pages
=cut
|
