1fundisp(1) SAORD Documentation fundisp(1)
2
6 fundisp - display data in a Funtools data file
7
9 fundisp [-f format] [-l] [-n] [-T] <iname> [columns⎪bitpix=n]
10
12 -f # format string for display
13 -l # display image as a list containing the columns X, Y, VAL
14 -n # don't output header
15 -F [c] # use specified character as column separator (def: space)
16 -T # output in rdb/starbase format (tab separators)
17
19 fundisp displays the data in the specified FITS Extension and/or Image
20 Section of a FITS file, or in a Section of a non-FITS array or raw
21 event file.
22 The first argument to the program specifies the FITS input image,
24 array, or raw event file to display. If "stdin" is specified, data are
25 read from the standard input. Use Funtools Bracket Notation to specify
26 FITS extensions, image sections, and filters.
27 If the data being displayed are columns (either in a FITS binary table
29 or a raw event file), the individual rows are listed. Filters can be
30 added using bracket notation. Thus:
31 [sh] fundisp "test.ev[time-(int)time>.15]"
33 X Y PHA PI TIME DX DY
34 ------- ------- ------- --------- ---------------- ---------- ----------
35 10 8 10 8 17.1600 8.50 10.50
36 9 9 9 9 17.1600 9.50 9.50
37 10 9 10 9 18.1600 9.50 10.50
38 10 9 10 9 18.1700 9.50 10.50
39 8 10 8 10 17.1600 10.50 8.50
40 9 10 9 10 18.1600 10.50 9.50
41 9 10 9 10 18.1700 10.50 9.50
42 10 10 10 10 19.1600 10.50 10.50
43 10 10 10 10 19.1700 10.50 10.50
44 10 10 10 10 19.1800 10.50 10.50
45 [NB: The FITS binary table test file test.ev, as well as the FITS image
47 test.fits, are contained in the funtools funtest directory.]
48 When a table is being displayed using fundisp, a second optional argu‐
50 ment can be used to specify the columns to display. For example:
51 [sh] fundisp "test.ev[time-(int)time>=.99]" "x y time"
53 X Y TIME
54 -------- -------- ---------------------
55 5 -6 40.99000000
56 4 -5 59.99000000
57 -1 0 154.99000000
58 -2 1 168.99000000
59 -3 2 183.99000000
60 -4 3 199.99000000
61 -5 4 216.99000000
62 -6 5 234.99000000
63 -7 6 253.99000000
64 The special column $REGION can be specified to display the region id of
66 each row:
67 [sh $] fundisp "test.ev[time-(int)time>=.99&&annulus(0 0 0 10 n=3)]" 'x y time $REGION'
69 X Y TIME REGION
70 -------- -------- --------------------- ----------
71 5 -6 40.99000000 3
72 4 -5 59.99000000 2
73 -1 0 154.99000000 1
74 -2 1 168.99000000 1
75 -3 2 183.99000000 2
76 -4 3 199.99000000 2
77 -5 4 216.99000000 2
78 -6 5 234.99000000 3
79 -7 6 253.99000000 3
80 Here only rows with the proper fractional time and whose position also
82 is within one of the three annuli are displayed.
83 Columns can be excluded from display using a minus sign before the col‐
85 umn:
86 [sh $] fundisp "test.ev[time-(int)time>=.99]" "-time"
88 X Y PHA PI DX DY
89 -------- -------- -------- ---------- ----------- -----------
90 5 -6 5 -6 5.50 -6.50
91 4 -5 4 -5 4.50 -5.50
92 -1 0 -1 0 -1.50 0.50
93 -2 1 -2 1 -2.50 1.50
94 -3 2 -3 2 -3.50 2.50
95 -4 3 -4 3 -4.50 3.50
96 -5 4 -5 4 -5.50 4.50
97 -6 5 -6 5 -6.50 5.50
98 -7 6 -7 6 -7.50 6.50
99 All columns except the time column are displayed.
101 The special column $N can be specified to display the ordinal value of
103 each row. Thus, continuing the previous example:
104 fundisp "test.ev[time-(int)time>=.99]" '-time $n'
106 X Y PHA PI DX DY N
107 ------- -------- -------- ---------- ----------- ----------- ----------
108 5 -6 5 -6 5.50 -6.50 337
109 4 -5 4 -5 4.50 -5.50 356
110 -1 0 -1 0 -1.50 0.50 451
111 -2 1 -2 1 -2.50 1.50 465
112 -3 2 -3 2 -3.50 2.50 480
113 -4 3 -4 3 -4.50 3.50 496
114 -5 4 -5 4 -5.50 4.50 513
115 -6 5 -6 5 -6.50 5.50 531
116 -7 6 -7 6 -7.50 6.50 550
117 Note that the column specification is enclosed in single quotes to pro‐
119 tect '$n' from begin expanded by the shell.
120 In general, the rules for activating and de-activating columns are:
122 · If only exclude columns are specified, then all columns but the
124 exclude columns will be activated.
125 · If only include columns are specified, then only the specified col‐
127 umns are activated.
128 · If a mixture of include and exclude columns are specified, then all
130 but the exclude columns will be active; this last case is ambiguous
131 and the rule is arbitrary.
132 In addition to specifying columns names explicitly, the special symbols
134 + and - can be used to activate and de-activate all columns. This is
135 useful if you want to activate the $REGION column along with all other
136 columns. According to the rules, the syntax "$REGION" only activates
137 the region column and de-activates the rest. Use "+ $REGION" to acti‐
138 vate all columns as well as the region column.
139 If the data being displayed are image data (either in a FITS primary
141 image, a FITS image extension, or an array file), an mxn pixel display
142 is produced, where m and n are the dimensions of the image. By
143 default, pixel values are displayed using the same data type as in the
144 file. However, for integer data where the BSCALE and BZERO header
145 parameters are present, the data is displayed as floats. In either
146 case, the display data type can be overridden using an optional second
147 argument of the form:
148 bitpix=n
150 where n is 8,16,32,-32,-64, for unsigned char, short, int, float and
152 double, respectively.
153 Of course, running fundisp on anything but the smallest image usually
155 results in a display whose size makes it unreadable. Therefore, one
156 can uses bracket notation (see below) to apply section and/or blocking
157 to the image before generating a display. For example:
158 [sh] fundisp "test.fits[2:6,2:7]" bitpix=-32
160 2 3 4 5 6
161 ---------- ---------- ---------- ---------- ----------
162 2: 3.00 4.00 5.00 6.00 7.00
163 3: 4.00 5.00 6.00 7.00 8.00
164 4: 5.00 6.00 7.00 8.00 9.00
165 5: 6.00 7.00 8.00 9.00 10.00
166 6: 7.00 8.00 9.00 10.00 11.00
167 7: 8.00 9.00 10.00 11.00 12.00
168 Note that is is possible to display a FITS binary table as an image
170 simply by passing the table through funimage first:
171 [sh] ./funimage test.ev stdout ⎪ fundisp "stdin[2:6,2:7]" bitpix=8
173 2 3 4 5 6
174 ------- ------- ------- ------- -------
175 2: 3 4 5 6 7
176 3: 4 5 6 7 8
177 4: 5 6 7 8 9
178 5: 6 7 8 9 10
179 6: 7 8 9 10 11
180 7: 8 9 10 11 12
181 If the -l (list) switch is used, then an image is displayed as a list
183 containing the columns: X, Y, VAL. For example:
184 fundisp -l "test1.fits[2:6,2:7]" bitpix=-32
186 X Y VAL
187 ---------- ---------- -----------
188 2 2 6.00
189 3 2 1.00
190 4 2 1.00
191 5 2 1.00
192 6 2 1.00
193 2 3 1.00
194 3 3 5.00
195 4 3 1.00
196 5 3 1.00
197 6 3 1.00
198 2 4 1.00
199 3 4 1.00
200 4 4 4.00
201 5 4 1.00
202 6 4 1.00
203 2 5 1.00
204 3 5 1.00
205 4 5 1.00
206 5 5 3.00
207 6 5 1.00
208 2 6 1.00
209 3 6 1.00
210 4 6 1.00
211 5 6 1.00
212 6 6 2.00
213 2 7 1.00
214 3 7 1.00
215 4 7 1.00
216 5 7 1.00
217 6 7 1.00
218 If the -n (nohead) switch is used, then no header is output for tables.
220 This is useful, for example, when fundisp output is being directed into
221 gnuplot.
222 The fundisp program uses a default set of display formats:
224 datatype TFORM format
226 -------- ----- --------
227 double D "%21.8f"
228 float E "%11.2f"
229 int J "%10d"
230 short I "%8d"
231 byte B "%6d"
232 string A "%12.12s"
233 bits X "%8x"
234 logical L "%1x"
235 Thus, the default display of 1 double and 2 shorts gives:
237 [sh] fundisp snr.ev "time x y"
239 TIME X Y
241 --------------------- -------- --------
242 79494546.56818075 546 201
243 79488769.94469175 548 201
244 ...
245 You can change the display format for individual columns or for all
247 columns of a given data types by means of the -f switch. The format
248 string that accompanies -f is a space-delimited list of keyword=format
249 values. The keyword values can either be column names (in which case
250 the associated format pertains only to that column) or FITS table TFORM
251 specifiers (in which case the format pertains to all columns having
252 that data type). For example, you can change the double and short for‐
253 mats for all columns like this:
254 [sh] fundisp -f "D=%22.11f I=%3d" snr.ev "time x y"
256 TIME X Y
258 ---------------------- --- ---
259 79494546.56818075478 546 201
260 79488769.94469174743 548 201
261 ...
262 Alternatively, you can change the format of the time and x columns like
264 this:
265 [sh] fundisp -f "time=%22.11f x=%3d" snr.ev "time x y"
267 TIME X Y
269 ---------------------- --- --------
270 79494546.56818075478 546 201
271 79488769.94469174743 548 201
272 ...
273 Note that there is a potential conflict if a column has the same name
275 as one of the TFORM specifiers. In the examples above, the the "X" col‐
276 umn in the table has the same name as the X (bit) datatype. To resolve
277 this conflict, the format string is processed such that TFORM datatype
278 specifiers are checked for first, using a case-sensitive comparison. If
279 the specified format value is not an upper case TFORM value, then a
280 case-insensitive check is made on the column name. This means that, in
281 the examples above, "X=%3d" will refer to the X (bit) datatype, while
282 "x=%3d" will refer to the X column:
283 [sh] fundisp -f "X=%3d" snr.ev "x y"
285 X Y
287 -------- --------
288 546 201
289 548 201
290 ...
291 [sh] fundisp -f "x=%3d" snr.ev "x y"
293 X Y
295 --- --------
296 546 201
297 548 201
298 ...
299 As a rule, therefore, it is best always to specify the column name in
301 lower case and TFORM data types in upper case.
302 The -f [format] will change the format for a single execution of
304 fundisp. You also can use the FUN_FORMAT envronment variable to change
305 the format for all invocations of fundisp. The format of this environ‐
306 ment variable's value is identical to that used with the -f switch.
307 This global value can be overridden in individual cases by use of the
308 -f [format] switch.
309 Caveats: Please also note that it is the user's responsibility to match
311 the format specifier to the column data type correctly. Also note that,
312 in order to maintain visual alignment between names and columns, the
313 column name will be truncated (on the left) if the format width is less
314 than the length of the name. However, truncation is not performed if
315 the output is in RDB format (using the -T switch).
316 [An older-style format string is supported but deprecated. It consists
318 of space-delimited C format statements for all data types, specified in
319 the following order:
320 double float int short byte string bit.
322 This order of the list is based on the assumption that people generally
324 will want to change the float formats.
325 If "-" is entered instead of a format statement for a given data type,
327 the default format is used. Also, the format string can be terminated
328 without specifying all formats, and defaults will be used for the rest
329 of the list. Note that you must supply a minimum field width, i.e.,
330 "%6d" and "%-6d" are legal, "%d" is not legal.
331 By using -f [format], you can change the double and short formats like
333 this:
334 [sh] fundisp -f "22.11f - - 3d" snr.ev "time x y"
336 TIME X Y
338 ---------------------- --- ---
339 79494546.56818075478 546 201
340 79488769.94469174743 548 201
341 ...
342 NB: This format is deprecated and will be removed in a future release.]
344 The -F[c] switch can be used to specify a (single-character) column
346 separator (where the default is a space). Note that column formatting
347 will almost certainly also add spaces to pad individual columns to the
348 required width. These can be removed with a program such as sed, at the
349 cost of generating unaligned columns. For example:
350 fundisp -F',' snr.ev'[cir 512 512 .1]'
352 X, Y, PHA, PI, TIME, DX,
353 DY
354 --------,--------,--------,--------,---------------------,--------,--------
355 512, 512, 6, 7, 79493997.45854475, 578,
356 574
357 512, 512, 8, 9, 79494575.58943175, 579,
358 573
359 512, 512, 5, 6, 79493631.03866175, 578,
360 575
361 512, 512, 5, 5, 79493290.86521725, 578,
362 575
363 512, 512, 8, 9, 79493432.00990875, 579,
364 573
365 fundisp -F',' snr.ev'[cir 512 512 .1]' ⎪ sed 's/ *, */,/g'
367 X,Y,PHA,PI,TIME,DX,DY
368 --------,--------,--------,--------,---------------------,--------,--------
369 512,512,6,7,79493997.45854475,578,574
370 512,512,8,9,79494575.58943175,579,573
371 512,512,5,6,79493631.03866175,578,575
372 512,512,5,5,79493290.86521725,578,575
373 512,512,8,9,79493432.00990875,579,573
374 fundisp -f "x=%3d y=%3d pi=%1d pha=%1d time=%20.11f dx=%3d dy=%3d"
376 -F',' snr.ev'[cir 512 512 .1]' ⎪ sed 's/ *, */,/g'
377 X,Y,A,I,TIME,DX,DY ---,---,-,-,--------------------,---,---
378 512,512,6,7,79493997.45854474604,578,574
379 512,512,8,9,79494575.58943174779,579,573
380 512,512,5,6,79493631.03866174817,578,575
381 512,512,5,5,79493290.86521725357,578,575
382 512,512,8,9,79493432.00990875065,579,573
383 If the -T (rdb table) switch is used, the output will conform to star‐
385 base/rdb data base format: tabs will be inserted between columns rather
386 than spaces. This format is not available when displaying image pixels
387 (except in conjunction with the -l switch).
388 Finally, note that fundisp can be used to create column filters from
390 the auxiliary tables in a FITS file. For example, the following shell
391 code will generate a good-time interval (GTI) filter for X-ray data
392 files that contain a standard GTI extension:
393 #!/bin/sh
395 sed '1,/---- .*/d
396 /^$/,$d' ⎪ awk 'tot>0{printf "⎪⎪"};{printf "time="$1":"$2; tot++}'
397 If this script is placed in a file called "mkgti", it can be used in a
399 command such as:
400 fundisp foo.fits"[GTI]" ⎪ mkgti > gti.filter
402 The resulting filter file can then be used in various funtools pro‐
404 grams:
405 funcnts foo.fits"[@gti.filter]" ...
407 to process only the events in the good-time intervals.
409
411 See funtools(n) for a list of Funtools help pages
412version 1.4.0 August 15, 2007 fundisp(1)