diff options
Diffstat (limited to 'funtools/man/man1/funtable.1')
| -rw-r--r-- | funtools/man/man1/funtable.1 | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/funtools/man/man1/funtable.1 b/funtools/man/man1/funtable.1 new file mode 100644 index 0000000..fe3b7ac --- /dev/null +++ b/funtools/man/man1/funtable.1 @@ -0,0 +1,356 @@ +.\" 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 "funtable 1" +.TH funtable 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +funtable \- copy selected rows from a Funtools file to a FITS binary table +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBfuntable\fR [\-a] [\-i|\-z] [\-m] [\-s cols] <iname> <oname> [columns] +.SH "OPTIONS" +.IX Header "OPTIONS" +.Vb 5 +\& \-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 +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBfuntable\fR selects rows from the specified +\&\s-1FITS\s0 Extension +(binary table only) of a \s-1FITS\s0 file, or from a non-FITS raw event +file, and writes those rows to a \s-1FITS\s0 binary table file. It also +will create a \s-1FITS\s0 binary table from an image or a raw array file. +.PP +The first argument to the program specifies the \s-1FITS\s0 file, raw event +file, or raw array file. If \*(L"stdin\*(R" is specified, data are read from +the standard input. Use Funtools Bracket +Notation to specify \s-1FITS\s0 extensions, and filters. The second +argument is the output \s-1FITS\s0 file. If \*(L"stdout\*(R" is specified, the \s-1FITS\s0 +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: +.PP +.Vb 1 +\& "column1 column1 ... columnN" +.Ve +.PP +The \fBfuntable\fR program generally is used to select rows from a +\&\s-1FITS\s0 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: +.PP +.Vb 13 +\& [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 +.Ve +.PP +The special column \fB$REGION\fR can be specified to write the +region id of each row: +.PP +.Vb 12 +\& [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 +.Ve +.PP +Here only rows with the proper fractional time and whose position also is +within one of the three annuli are written. +.PP +Columns can be excluded from display using a minus sign before the +column: +.PP +.Vb 12 +\& [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 +.Ve +.PP +All columns except the time column are written. +.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 \fI+\fR and \fI\-\fR can be used to activate and +de-activate \fIall\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 +Ordinarily, only the selected table is copied to the output file. In +a \s-1FITS\s0 binary table, it sometimes is desirable to copy all of the +other \s-1FITS\s0 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 \s-1EVENT\s0 table, +while the second command copies other extensions as well: +.PP +.Vb 2 +\& [sh] funtable "/proj/rd/data/snr.ev[EVENTS]" events.ev +\& [sh] funtable "/proj/rd/data/snr.ev[EVENTS+]" eventsandmore.ev +.Ve +.PP +If the input file is an image or a raw array file, then +\&\fBfuntable\fR will generate a \s-1FITS\s0 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 \*(L"X\*(R", \*(L"Y\*(R", and +\&\*(L"\s-1VALUE\s0\*(R". For each pixel in the image, a single row (event) is +generated with the \*(L"X\*(R" and \*(L"Y\*(R" columns assigned the dim1 and dim2 +values of the image pixel, respectively and the \*(L"\s-1VALUE\s0\*(R" column +assigned the value of the pixel. With sort of table, running +\&\fBfunhist\fR on the \*(L"\s-1VALUE\s0\*(R" column will give the same results as +running \fBfunhist\fR on the original image. +.PP +If the \fB\-i\fR (\*(L"individual\*(R" rows) switch is specified, then only +the \*(L"X\*(R" and \*(L"Y\*(R" 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, \fB\-i\fR 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.) +.PP +If the \fB\-s [col1 col2 ... coln]\fR (\*(L"sort\*(R") 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 +\&\fB_sort\fR program (included with funtools), which must be accessible +via your path. +.PP +For binary tables, the \fB\-m\fR (\*(L"multiple files\*(R") 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. +.PP +The separate output file names generated by the \fB\-m\fR 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: +.IP "\(bu" 4 +A \f(CW$n\fR 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: +.Sp +.Vb 1 +\& funtable \-m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo.goo_$n.fits' +.Ve +.Sp +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. +.IP "\(bu" 4 +If \f(CW$n\fR is not specified, then the region id will be placed before +the first dot (.) in the filename. Thus: +.Sp +.Vb 1 +\& funtable \-m input.fits'[cir(512,512,1);cir(520,520,1)...]' foo.evt.fits +.Ve +.Sp +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. +.IP "\(bu" 4 +If no dot is specified in the root output file name, then +the region id will be appended to the filename. Thus: +.Sp +.Vb 1 +\& funtable \-m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo_evt' +.Ve +.Sp +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. +.PP +The multiple file mechanism provide a simple way to generate +individual source data files with a single pass through the data. +.PP +By default, a new \s-1FITS\s0 file is created and the binary table is written +to the first extension. If the \fB\-a\fR (append) switch is specified, +the table is appended to an existing \s-1FITS\s0 file as a \s-1BINTABLE\s0 extension. +Note that the output \s-1FITS\s0 file must already exist. +.PP +If the \fB\-z\fR (\*(L"zero\*(R" pixel values) switch is specified and +\&\fB\-i\fR is not specified, then pixels having a zero value will +be output with their \*(L"\s-1VALUE\s0\*(R" column set to zero. Obviously, this +switch does not make sense when individual events are output. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages |