diff options
Diffstat (limited to 'funtools/doc/pod/funtable.pod')
-rw-r--r-- | funtools/doc/pod/funtable.pod | 296 |
1 files changed, 296 insertions, 0 deletions
diff --git a/funtools/doc/pod/funtable.pod b/funtools/doc/pod/funtable.pod new file mode 100644 index 0000000..d4e8475 --- /dev/null +++ b/funtools/doc/pod/funtable.pod @@ -0,0 +1,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 |