=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
