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