1fundisp(1)                    SAORD Documentation                   fundisp(1)
2
3
4

NAME

6       fundisp - display data in a Funtools data file
7

SYNOPSIS

9       fundisp  [-f format] [-l] [-n] [-T] <iname> [columns⎪bitpix=n]
10

OPTIONS

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

DESCRIPTION

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
23       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
28       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
32         [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
46       [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
49       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
52         [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
65       The special column $REGION can be specified to display the region id of
66       each row:
67
68         [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
81       Here only rows with the proper fractional time and whose position also
82       is within one of the three annuli are displayed.
83
84       Columns can be excluded from display using a minus sign before the col‐
85       umn:
86
87         [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
100       All columns except the time column are displayed.
101
102       The special column $N can be specified to display the ordinal value of
103       each row. Thus, continuing the previous example:
104
105         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
118       Note that the column specification is enclosed in single quotes to pro‐
119       tect '$n' from begin expanded by the shell.
120
121       In general, the rules for activating and de-activating columns are:
122
123       ·   If only exclude columns are specified, then all columns but the
124           exclude columns will be activated.
125
126       ·   If only include columns are specified, then only the specified col‐
127           umns are activated.
128
129       ·   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
133       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
140       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
149         bitpix=n
150
151       where n is 8,16,32,-32,-64, for unsigned char, short, int, float and
152       double, respectively.
153
154       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
159         [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
169       Note that is is possible to display a FITS binary table as an image
170       simply by passing the table through funimage first:
171
172         [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
182       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
185         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
219       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
223       The fundisp program uses a default set of display formats:
224
225         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
236       Thus, the default display of 1 double and 2 shorts gives:
237
238         [sh] fundisp snr.ev "time x y"
239
240                           TIME        X        Y
241          --------------------- -------- --------
242              79494546.56818075      546      201
243              79488769.94469175      548      201
244              ...
245
246       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
255         [sh] fundisp -f "D=%22.11f I=%3d" snr.ev "time x y"
256
257                           TIME   X   Y
258         ---------------------- --- ---
259           79494546.56818075478 546 201
260           79488769.94469174743 548 201
261           ...
262
263       Alternatively, you can change the format of the time and x columns like
264       this:
265
266         [sh] fundisp -f "time=%22.11f x=%3d" snr.ev "time x y"
267
268                           TIME   X        Y
269         ---------------------- --- --------
270           79494546.56818075478 546      201
271           79488769.94469174743 548      201
272           ...
273
274       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
284         [sh] fundisp -f "X=%3d" snr.ev "x y"
285
286                X        Y
287         -------- --------
288              546      201
289              548      201
290              ...
291
292         [sh] fundisp -f "x=%3d" snr.ev "x y"
293
294           X        Y
295         --- --------
296         546      201
297         548      201
298         ...
299
300       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
303       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
310       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
317       [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
321        double float int short byte string bit.
322
323       This order of the list is based on the assumption that people generally
324       will want to change the float formats.
325
326       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
332       By using -f [format], you can change the double and short formats like
333       this:
334
335         [sh] fundisp -f "22.11f - - 3d" snr.ev "time x y"
336
337                            TIME   X   Y
338          ---------------------- --- ---
339            79494546.56818075478 546 201
340            79488769.94469174743 548 201
341            ...
342
343       NB: This format is deprecated and will be removed in a future release.]
344
345       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
351       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
366       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
375       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
384       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
389       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
394         #!/bin/sh
395         sed '1,/---- .*/d
396         /^$/,$d' ⎪ awk 'tot>0{printf "⎪⎪"};{printf "time="$1":"$2; tot++}'
397
398       If this script is placed in a file called "mkgti", it can be used in a
399       command such as:
400
401         fundisp foo.fits"[GTI]" ⎪ mkgti > gti.filter
402
403       The resulting filter file can then be used in various funtools pro‐
404       grams:
405
406         funcnts foo.fits"[@gti.filter]" ...
407
408       to process only the events in the good-time intervals.
409

SEE ALSO

411       See funtools(n) for a list of Funtools help pages
412
413
414
415version 1.4.2                   January 2, 2008                     fundisp(1)
Impressum