Merge commit '23c7930d27fe11c4655e1291a07a821dbbaba78d' as 'funtools'

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