diff options
Diffstat (limited to 'funtools/man/man1/fundisp.1')
| -rw-r--r-- | funtools/man/man1/fundisp.1 | 589 |
1 files changed, 589 insertions, 0 deletions
diff --git a/funtools/man/man1/fundisp.1 b/funtools/man/man1/fundisp.1 new file mode 100644 index 0000000..21d1e87 --- /dev/null +++ b/funtools/man/man1/fundisp.1 @@ -0,0 +1,589 @@ +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to +.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' +.\" expand to `' in nroff, nothing in troff, for use with C<>. +.tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "fundisp 1" +.TH fundisp 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +fundisp \- display data in a Funtools data file +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBfundisp\fR [\-f format] [\-l] [\-n] [\-T] <iname> [columns|bitpix=n] +.SH "OPTIONS" +.IX Header "OPTIONS" +.Vb 5 +\& \-f # format string for display +\& \-l # display image as a list containing the columns X, Y, VAL +\& \-n # don't output header +\& \-F [c] # use specified character as column separator (def: space) +\& \-T # output in rdb/starbase format (tab separators) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBfundisp\fR displays the data in the specified +\&\s-1FITS\s0 Extension +and/or +Image Section +of a \s-1FITS\s0 file, or in a +Section +of a non-FITS array or raw event file. +.PP +The first argument to the program specifies the \s-1FITS\s0 input image, array, or +raw event file to display. If \*(L"stdin\*(R" is specified, data are read from +the standard input. Use Funtools Bracket +Notation to specify \s-1FITS\s0 extensions, image sections, and filters. +.PP +If the data being displayed are columns (either in a \s-1FITS\s0 binary table +or a raw event file), the individual rows are listed. Filters can be +added using bracket notation. Thus: +.PP +.Vb 13 +\& [sh] fundisp "test.ev[time-(int)time>.15]" +\& X Y PHA PI TIME DX DY +\& ------- ------- ------- --------- ---------------- ---------- ---------- +\& 10 8 10 8 17.1600 8.50 10.50 +\& 9 9 9 9 17.1600 9.50 9.50 +\& 10 9 10 9 18.1600 9.50 10.50 +\& 10 9 10 9 18.1700 9.50 10.50 +\& 8 10 8 10 17.1600 10.50 8.50 +\& 9 10 9 10 18.1600 10.50 9.50 +\& 9 10 9 10 18.1700 10.50 9.50 +\& 10 10 10 10 19.1600 10.50 10.50 +\& 10 10 10 10 19.1700 10.50 10.50 +\& 10 10 10 10 19.1800 10.50 10.50 +.Ve +.PP +[\s-1NB:\s0 The \s-1FITS\s0 binary table test file test.ev, as well as the \s-1FITS\s0 +image test.fits, are contained in the funtools funtest directory.] +.PP +When a table is being displayed using \fBfundisp\fR, a second optional +argument can be used to specify the columns to display. For example: +.PP +.Vb 12 +\& [sh] fundisp "test.ev[time-(int)time>=.99]" "x y time" +\& X Y TIME +\& -------- -------- --------------------- +\& 5 \-6 40.99000000 +\& 4 \-5 59.99000000 +\& \-1 0 154.99000000 +\& \-2 1 168.99000000 +\& \-3 2 183.99000000 +\& \-4 3 199.99000000 +\& \-5 4 216.99000000 +\& \-6 5 234.99000000 +\& \-7 6 253.99000000 +.Ve +.PP +The special column \fB$REGION\fR can be specified to display the +region id of each row: +.PP +.Vb 12 +\& [sh $] fundisp "test.ev[time-(int)time>=.99&&annulus(0 0 0 10 n=3)]" 'x y time $REGION' +\& 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 +.Ve +.PP +Here only rows with the proper fractional time and whose position also is +within one of the three annuli are displayed. +.PP +Columns can be excluded from display using a minus sign before the +column: +.PP +.Vb 12 +\& [sh $] fundisp "test.ev[time-(int)time>=.99]" "\-time" +\& 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 +.Ve +.PP +All columns except the time column are displayed. +.PP +The special column \fB$N\fR can be specified to display the +ordinal value of each row. Thus, continuing the previous example: +.PP +.Vb 12 +\& fundisp "test.ev[time-(int)time>=.99]" '\-time $n' +\& X Y PHA PI DX DY N +\& ------- -------- -------- ---------- ----------- ----------- ---------- +\& 5 \-6 5 \-6 5.50 \-6.50 337 +\& 4 \-5 4 \-5 4.50 \-5.50 356 +\& \-1 0 \-1 0 \-1.50 0.50 451 +\& \-2 1 \-2 1 \-2.50 1.50 465 +\& \-3 2 \-3 2 \-3.50 2.50 480 +\& \-4 3 \-4 3 \-4.50 3.50 496 +\& \-5 4 \-5 4 \-5.50 4.50 513 +\& \-6 5 \-6 5 \-6.50 5.50 531 +\& \-7 6 \-7 6 \-7.50 6.50 550 +.Ve +.PP +Note that the column specification is enclosed in single quotes to protect +\&'$n' from begin expanded by the shell. +.PP +In general, the rules for activating and de-activating columns are: +.IP "\(bu" 4 +If only exclude columns are specified, then all columns but +the exclude columns will be activated. +.IP "\(bu" 4 +If only include columns are specified, then only the specified columns +are activated. +.IP "\(bu" 4 +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. +.PP +In addition to specifying columns names explicitly, the special +symbols \fB+\fR and \fB\-\fR can be used to activate and +de-activate \fBall\fR columns. This is useful if you want to +activate the \f(CW$REGION\fR column along with all other columns. According +to the rules, the syntax \*(L"$REGION\*(R" only activates the region column +and de-activates the rest. Use \*(L"+ \f(CW$REGION\fR\*(R" to activate all +columns as well as the region column. +.PP +If the data being displayed are image data (either in a \s-1FITS\s0 primary +image, a \s-1FITS\s0 image extension, or an array file), an mxn pixel display +is produced, where m and n are the dimensions of the image. By +default, pixel values are displayed using the same data type as in the +file. However, for integer data where the \s-1BSCALE\s0 and \s-1BZERO\s0 header parameters +are present, the data is displayed as floats. In either case, the +display data type can be overridden using an optional second argument +of the form: +.PP +.Vb 1 +\& bitpix=n +.Ve +.PP +where n is 8,16,32,\-32,\-64, for unsigned char, short, int, float and double, +respectively. +.PP +Of course, running \fBfundisp\fR on anything but the smallest image +usually results in a display whose size makes it unreadable. +Therefore, one can uses bracket notation (see below) +to apply section and/or blocking to the image before generating a +display. For example: +.PP +.Vb 9 +\& [sh] fundisp "test.fits[2:6,2:7]" bitpix=-32 +\& 2 3 4 5 6 +\& ---------- ---------- ---------- ---------- ---------- +\& 2: 3.00 4.00 5.00 6.00 7.00 +\& 3: 4.00 5.00 6.00 7.00 8.00 +\& 4: 5.00 6.00 7.00 8.00 9.00 +\& 5: 6.00 7.00 8.00 9.00 10.00 +\& 6: 7.00 8.00 9.00 10.00 11.00 +\& 7: 8.00 9.00 10.00 11.00 12.00 +.Ve +.PP +Note that is is possible to display a \s-1FITS\s0 binary table as an image +simply by passing the table through \fBfunimage\fR first: +.PP +.Vb 9 +\& [sh] ./funimage test.ev stdout | fundisp "stdin[2:6,2:7]" bitpix=8 +\& 2 3 4 5 6 +\& ------- ------- ------- ------- ------- +\& 2: 3 4 5 6 7 +\& 3: 4 5 6 7 8 +\& 4: 5 6 7 8 9 +\& 5: 6 7 8 9 10 +\& 6: 7 8 9 10 11 +\& 7: 8 9 10 11 12 +.Ve +.PP +If the \fB\-l\fR (list) switch is used, then an image is displayed as a +list containing the columns: X, Y, \s-1VAL\s0. For example: +.PP +.Vb 33 +\& fundisp \-l "test1.fits[2:6,2:7]" bitpix=-32 +\& X Y VAL +\& ---------- ---------- ----------- +\& 2 2 6.00 +\& 3 2 1.00 +\& 4 2 1.00 +\& 5 2 1.00 +\& 6 2 1.00 +\& 2 3 1.00 +\& 3 3 5.00 +\& 4 3 1.00 +\& 5 3 1.00 +\& 6 3 1.00 +\& 2 4 1.00 +\& 3 4 1.00 +\& 4 4 4.00 +\& 5 4 1.00 +\& 6 4 1.00 +\& 2 5 1.00 +\& 3 5 1.00 +\& 4 5 1.00 +\& 5 5 3.00 +\& 6 5 1.00 +\& 2 6 1.00 +\& 3 6 1.00 +\& 4 6 1.00 +\& 5 6 1.00 +\& 6 6 2.00 +\& 2 7 1.00 +\& 3 7 1.00 +\& 4 7 1.00 +\& 5 7 1.00 +\& 6 7 1.00 +.Ve +.PP +If the \fB\-n\fR (nohead) switch is used, then no header is output for +tables. This is useful, for example, when fundisp output is being +directed into gnuplot. +.PP +The \fBfundisp\fR program uses a default set of display formats: +.PP +.Vb 10 +\& datatype TFORM format +\& -------- ----- -------- +\& double D "%21.8f" +\& float E "%11.2f" +\& int J "%10d" +\& short I "%8d" +\& byte B "%6d" +\& string A "%12.12s" +\& bits X "%8x" +\& logical L "%1x" +.Ve +.PP +Thus, the default display of 1 double and 2 shorts gives: +.PP +.Vb 1 +\& [sh] fundisp snr.ev "time x y" +.Ve +.PP +.Vb 5 +\& TIME X Y +\& --------------------- -------- -------- +\& 79494546.56818075 546 201 +\& 79488769.94469175 548 201 +\& ... +.Ve +.PP +You can change the display format for individual columns or for all +columns of a given data types by means of the \-f switch. The format +string that accompanies \-f is a space-delimited list of keyword=format +values. The keyword values can either be column names (in which case +the associated format pertains only to that column) or \s-1FITS\s0 table +\&\s-1TFORM\s0 specifiers (in which case the format pertains to all columns +having that data type). For example, you can change the double and +short formats for all columns like this: +.PP +.Vb 1 +\& [sh] fundisp \-f "D=%22.11f I=%3d" snr.ev "time x y" +.Ve +.PP +.Vb 5 +\& TIME X Y +\& ---------------------- --- --- +\& 79494546.56818075478 546 201 +\& 79488769.94469174743 548 201 +\& ... +.Ve +.PP +Alternatively, you can change the format of the time and x columns like this: +.PP +.Vb 1 +\& [sh] fundisp \-f "time=%22.11f x=%3d" snr.ev "time x y" +.Ve +.PP +.Vb 5 +\& TIME X Y +\& ---------------------- --- -------- +\& 79494546.56818075478 546 201 +\& 79488769.94469174743 548 201 +\& ... +.Ve +.PP +Note that there is a potential conflict if a column has the same name +as one of the \s-1TFORM\s0 specifiers. In the examples above, the the \*(L"X\*(R" +column in the table has the same name as the X (bit) datatype. To +resolve this conflict, the format string is processed such that +\&\s-1TFORM\s0 datatype specifiers are checked for first, using a +case-sensitive comparison. If the specified format value is not an +upper case \s-1TFORM\s0 value, then a case-insensitive check is made on the +column name. This means that, in the examples above, \*(L"X=%3d\*(R" will refer +to the X (bit) datatype, while \*(L"x=%3d\*(R" will refer to the X column: +.PP +.Vb 1 +\& [sh] fundisp \-f "X=%3d" snr.ev "x y" +.Ve +.PP +.Vb 5 +\& X Y +\& -------- -------- +\& 546 201 +\& 548 201 +\& ... +.Ve +.PP +.Vb 1 +\& [sh] fundisp \-f "x=%3d" snr.ev "x y" +.Ve +.PP +.Vb 5 +\& X Y +\& --- -------- +\& 546 201 +\& 548 201 +\& ... +.Ve +.PP +As a rule, therefore, it is best always to specify the column name in +lower case and \s-1TFORM\s0 data types in upper case. +.PP +The \fB\-f [format]\fR will change the format for a single execution +of fundisp. You also can use the \fB\s-1FUN_FORMAT\s0\fR envronment variable +to change the format for all invocations of fundisp. The format of this +environment variable's value is identical to that used with +the \fB\-f\fR switch. This global value can be overridden in +individual cases by use of the \fB\-f [format]\fR switch. +.PP +Caveats: Please also note that it is the user's responsibility to +match the format specifier to the column data type correctly. Also +note that, in order to maintain visual alignment between names and +columns, the column name will be truncated (on the left) if the +format width is less than the length of the name. However, truncation +is not performed if the output is in \s-1RDB\s0 format (using the \-T switch). +.PP +[An older-style format string is supported but deprecated. It +consists of space-delimited C format statements for all data types, +specified in the following order: +.PP +.Vb 1 +\& double float int short byte string bit. +.Ve +.PP +This order of the list is based on the assumption that people generally +will want to change the float formats. +.PP +If \*(L"\-\*(R" is entered instead of a format statement for a given data type, the +default format is used. Also, the format string can be terminated without +specifying all formats, and defaults will be used for the rest of the +list. Note that you must supply a minimum field width, i.e., \*(L"%6d\*(R" and +\&\*(L"%\-6d\*(R" are legal, \*(L"%d\*(R" is not legal. +.PP +By using \-f [format], you can change the double and short formats like this: +.PP +.Vb 1 +\& [sh] fundisp \-f "22.11f - - 3d" snr.ev "time x y" +.Ve +.PP +.Vb 5 +\& TIME X Y +\& ---------------------- --- --- +\& 79494546.56818075478 546 201 +\& 79488769.94469174743 548 201 +\& ... +.Ve +.PP +\&\s-1NB:\s0 This format is deprecated and will be removed in a future release.] +.PP +The \fB\-F[c]\fR switch can be used to specify a (single\-character) +column separator (where the default is a space). Note that column +formatting will almost certainly also add spaces to pad individual +columns to the required width. These can be removed with a program +such as sed, at the cost of generating unaligned columns. For example: +.PP +fundisp \-F',' snr.ev'[cir 512 512 .1]' + X, Y, \s-1PHA\s0, \s-1PI\s0, \s-1TIME\s0, \s-1DX\s0, \s-1DY\s0 + 512, 512, 6, 7, 79493997.45854475, 578, 574 + 512, 512, 8, 9, 79494575.58943175, 579, 573 + 512, 512, 5, 6, 79493631.03866175, 578, 575 + 512, 512, 5, 5, 79493290.86521725, 578, 575 + 512, 512, 8, 9, 79493432.00990875, 579, 573 +.PP +fundisp \-F',' snr.ev'[cir 512 512 .1]' | sed 's/ *, */,/g' + X,Y,PHA,PI,TIME,DX,DY + 512,512,6,7,79493997.45854475,578,574 + 512,512,8,9,79494575.58943175,579,573 + 512,512,5,6,79493631.03866175,578,575 + 512,512,5,5,79493290.86521725,578,575 + 512,512,8,9,79493432.00990875,579,573 +.PP +fundisp \-f \*(L"x=%3d y=%3d pi=%1d pha=%1d time=%20.11f dx=%3d dy=%3d\*(R" \-F',' snr.ev'[cir 512 512 .1]' | sed 's/ *, */,/g' + X,Y,A,I,TIME,DX,DY +\&\-\-\-,\-\-\-,\-,\-,\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-,\-\-\-,\-\-\- +512,512,6,7,79493997.45854474604,578,574 +512,512,8,9,79494575.58943174779,579,573 +512,512,5,6,79493631.03866174817,578,575 +512,512,5,5,79493290.86521725357,578,575 +512,512,8,9,79493432.00990875065,579,573 +.PP +If the \fB\-T\fR (rdb table) switch is used, the output will conform +to starbase/rdb data base format: tabs will be inserted between +columns rather than spaces. This format is not available when +displaying image pixels (except in conjunction with the \fB\-l\fR +switch). +.PP +Finally, note that \fBfundisp\fR can be used to create column filters from +the auxiliary tables in a \s-1FITS\s0 file. For example, the following shell code +will generate a good-time interval (\s-1GTI\s0) filter for X\-ray data files that +contain a standard \s-1GTI\s0 extension: +.PP +.Vb 3 +\& #!/bin/sh +\& sed '1,/---- .*/d +\& /^$/,$d' | awk 'tot>0{printf "||"};{printf "time="$1":"$2; tot++}' +.Ve +.PP +If this script is placed in a file called \*(L"mkgti\*(R", it can be used in a +command such as: +.PP +.Vb 1 +\& fundisp foo.fits"[GTI]" | mkgti > gti.filter +.Ve +.PP +The resulting filter file can then be used in various funtools programs: +.PP +.Vb 1 +\& funcnts foo.fits"[@gti.filter]" ... +.Ve +.PP +to process only the events in the good-time intervals. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages |