batsurvey-catmux HEADAS help file

NAME

batsurvey-catmux

USAGE

batsurvey-catmux infile outfile keycolumn

DESCRIPTION

batsurvey-catmux is a convenience tool which will split a FITS binary table into different files based the value of a "key" column within the table.

This task may be used for BAT catalog files, to split one file with many different sources, into many files with one source each. However, this task will work with any generic FITS file where multiple selections are desired.

The "key" column is the column which is used to decide which output file a row will be assigned. The output file name can be constructed using the "key" value if necessary. For BAT catalogs, the best "key" column is the catalog ID number, or CATNUM. However, it is also possible to use the NAME column. The output file name can be a single file name, or a template constructed using C-style "printf" syntax. The "key" column value will be substitued into the template for each row.

For example, consider a catalog file of the following structure:

    == myrun.cat ==
    CATNUM     NAME    RATE  ....
      1        XYZ     123.4
      1        XYZ     120.5
      2        ABC      21.2
      3        WWW      -1.9

If keycolumn=CATNUM and outfile="myrun%03d.cat", then the output of the task would be three files. The files would be:

    == myrun001.cat ==
    CATNUM     NAME    RATE  ....
      1        XYZ     123.4
      1        XYZ     120.5

and

    == myrun002.cat ==
    CATNUM     NAME    RATE  ....
      2        ABC      21.2

and

    == myrun003.cat ==
    CATNUM     NAME    RATE  ....
      3        WWW      -1.9

The file myrun001.cat has two entries because there were two entries in the original file which matched '1'. The other files only have one entry because '2' and '3' matched only one row each.

IMPORTANT NOTE: the default is clobber=NO, which will cause data to be APPENDED to named files, if they already exist.

batsurvey-catmux has some filtering and transformation capabilities. It is possible to exclude certain from the process using the 'exclude' parameter. If a "key" value is listed in the 'exclude' list, then columns which match that value will not be written to an output file. For example, if exclude=3 in the above example, then myrun003.cat would not be created.

It is also possible redirect one or more key values to a different file using the translate map. The translate_map is a list of transformations of "a" to "b" where "a" and "b" are "key" values. If any column values match "a" then the rows are actually written to an output file given by substituting "b" into the template. For example, if translate_map="3->2", then the fourth row of the table would be written to myrun002.dat, and myrun003.dat would not be created. The user can specify the transformations either as a comma separated list, such as "a->b,c->d,e->f", or as a text file with one transformation per line. In this example, if "key" values of a, c, or e are found in the input table, then they are transformed to b, d, and f respectively.

batsurvey-catmux will attempt to protect against special characters in the "key" column. If a key has a character that matches any of these special characters: ][!$%^&*;(){}<>?|/\ or a white space, then that character will be replaced by an underscore. Note that this also means that the 'outfile' parameter may not contain spaces.

PARAMETERS

infile [filename]: Input file name. The file will typically be a BAT catalog file, but in fact it can be any binary FITS table, as long as it has the required "key" column.
outfile [filename]: Name of a single output file, or an output file template. It is possible that many files could be created, by substituting different "key" values into the outfile template. The template is formed by using C-style "printf" syntax. Examples: "myrun%003d.cat" will create myrun001.cat, myrun002.cat, myrun003.cat, ... Use "myrun%s.cat" if keycolumn is a string column. The outfile path may not contain spaces.
keycolumn [filename]: Name of the "key" column. It may be any numeric or string column which will be used to match rows to output files. Special characters will be replaced by the underscore character.
(exclude = NONE) [string]: Comma-separated list of "key" values to be ignored.
(translate_map = NONE) [string]: Specify a list of transformations to "key" values, or NONE for no transformations. This parameter should be a comma-separated list of transformations of the form "a->b,c->d,e->f". Alternately the user can give the transformations in a text file, one transformation per line, specified with the form "@filename.txt".
(clobber = NO) [boolean]: If the output file already exists, then setting clobber=NO will APPEND to the existing file. If "clobber = yes" then existing files will be overwritten with new ones.
(chatter = 2) [integer, 0 - 5]: Controls the amount of informative text written to standard output. Setting chatter = 1 produces a basic summary of the task actions; chatter = 2 (default) additionally prints a summary of input parameters; chatter = 5 prints debugging information.
(history = YES) [boolean]: If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the task parameters that were used to produce the output file.

EXAMPLES

1. Split a BAT catalog apart by catalog number. Output files will be named myrun001.cat, myrun002.cat and so on. Catalog values of -1 are ignored, and values are 500 are stored in a file myrun999.cat.

   batsurvey-catmux myrun.cat myrun%03d.cat CATNUM exclude=-1 translate_map="500->999"

LAST MODIFIED