Provided by: stilts_3.1.5-1_all bug

NAME

       stilts-tmatchn - Crossmatches multiple tables using flexible criteria

SYNOPSIS

       stilts tmatchn [nin=<count>] [ifmtN=<in-format>] [inN=<tableN>] [icmdN=<cmds>]
                      [ocmd=<cmds>]
                      [omode=out|meta|stats|count|cgi|discard|topcat|samp|tosql|gui] [out=<out-
                      table>] [ofmt=<out-format>] [multimode=pairs|group] [iref=<table-index>]
                      [matcher=<matcher-name>] [params=<match-params>] [tuning=<tuning-params>]
                      [valuesN=<expr-list>] [joinN=default|match|nomatch|always]
                      [fixcols=none|dups|all] [suffixN=<label>] [progress=none|log|profile]

DESCRIPTION

       tmatchn  performs  efficient  and  flexible  crossmatching between multiple tables. It can
       match rows on the basis of their relative position in the sky, or alternatively using many
       other  criteria  such  as  separation in in some isotropic or anisotropic Cartesian space,
       identity of a key value, or some combination of these; the full range of match criteria is
       dicussed in SUN/256.

       Since  the  match  criteria  define  what counts as a match between two objects, it is not
       immediately obvious what is meant by a multi-table match. In fact the command can work  in
       one of two distinct modes, controlled by the multimode parameter. In pairs mode, one table
       (by default the first input table) is designated the reference  table,  and  pair  matches
       between  each  of  the  other  tables and that one are identified. In group mode groups of
       objects from all the input tables are identified, as discussed in SUN/256.  Currently,  in
       both  cases  an  output  matched  row  cannot contain more than one object from each input
       table. Options for output of multiple rows per input table per match may be forthcoming in
       future releases if there is demand.

       tmatchn  is intended for use with more than two input tables - see tmatch1 and tmatch2 for
       1- and 2-table crossmatching respectively.

OPTIONS

       nin=<count>
              The number of input tables for this task. For each of the input tables N there will
              be associated parameters ifmtN, inN and icmdN.

       ifmtN=<in-format>
              Specifies  the  format  of  input table #N as specified by parameter inN. The known
              formats are listed in SUN/256. This flag can be used if you know what  format  your
              table is in. If it has the special value (auto) (the default), then an attempt will
              be made to detect the format of the table automatically. This cannot always be done
              correctly  however,  in  which  case the program will exit with an error explaining
              which formats were attempted.

       inN=<tableN>
              The location of input table #N. This may take one of the following forms:

                * A filename.

                * A URL.

                * The special value "-", meaning standard input. In this case  the  input  format
                  must  be  given explicitly using the ifmtN parameter. Note that not all formats
                  can be streamed in this way.

                * A system command line with either a "<"  character  at  the  start,  or  a  "|"
                  character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline
                  and reads from its standard output. This will probably only work  on  unix-like
                  systems.
               In  any  case,  compressed data in one of the supported compression formats (gzip,
              Unix compress or bzip2) will be decompressed transparently.

       icmdN=<cmds>
              Specifies processing to be performed on input table #N as  specified  by  parameter
              inN,  before  any  other processing has taken place. The value of this parameter is
              one or more of the filter commands described in SUN/256. If more than one is given,
              they  must  be  separated  by  semicolon  characters  (";").  This parameter can be
              repeated multiple times on the same command line to build up a list  of  processing
              steps.  The  sequence of commands given in this way defines the processing pipeline
              which is performed on the table.

              Commands may alteratively be supplied in an external file, by using the indirection
              character  '@'. Thus a value of "@filename" causes the file filename to be read for
              a list of filter commands to execute. The commands in the file may be separated  by
              newline characters and/or semicolons, and lines which are blank or which start with
              a '#' character are ignored.

       ocmd=<cmds>
              Specifies processing  to  be  performed  on  the  output  table,  after  all  other
              processing  has  taken  place.  The  value  of this parameter is one or more of the
              filter commands described in SUN/256. If more than  one  is  given,  they  must  be
              separated  by  semicolon  characters (";"). This parameter can be repeated multiple
              times on the same command line to build up a list of processing steps. The sequence
              of commands given in this way defines the processing pipeline which is performed on
              the table.

              Commands may alteratively be supplied in an external file, by using the indirection
              character  '@'. Thus a value of "@filename" causes the file filename to be read for
              a list of filter commands to execute. The commands in the file may be separated  by
              newline characters and/or semicolons, and lines which are blank or which start with
              a '#' character are ignored.

       omode=out|meta|stats|count|cgi|discard|topcat|samp|tosql|gui
              The mode in which the result table will be output. The default mode is  out,  which
              means  that  the  result  will  be  written as a new table to disk or elsewhere, as
              determined by the out and ofmt parameters. However, there are other  possibilities,
              which correspond to uses to which a table can be put other than outputting it, such
              as displaying metadata, calculating statistics, or populating a  table  in  an  SQL
              database.  For  some  values of this parameter, additional parameters (<mode-args>)
              are required to determine the exact behaviour.

              Possible values are

                * out

                * meta

                * stats

                * count

                * cgi

                * discard

                * topcat

                * samp

                * tosql

                * gui
               Use the help=omode flag or see SUN/256 for more information.

       out=<out-table>
              The location of the output table. This is usually a filename to write to. If it  is
              equal  to  the  special value "-" (the default) the output table will be written to
              standard output.

              This parameter must only be given if omode has its default value of "out".

       ofmt=<out-format>
              Specifies the format in which the output table will be written (one of the ones  in
              SUN/256 - matching is case-insensitive and you can use just the first few letters).
              If it has the special value "(auto)" (the default), then the output  filename  will
              be examined to try to guess what sort of file is required usually by looking at the
              extension. If it's not obvious from the filename what output format is intended, an
              error will result.

              This parameter must only be given if omode has its default value of "out".

       multimode=pairs|group
              Defines what is meant by a multi-table match. There are two possibilities:

                * pairs:  Each output row corresponds to a single row of the reference table (see
                  parameter iref) and contains entries from other tables which are  pair  matches
                  to  that.  If a reference table row matches multiple rows from one of the other
                  tables, only the best one is included.

                * group: Each output row corresponds to a group of entries from the input  tables
                  which  are  mutually  linked  by  pair  matches  between  them. This means that
                  although you can get from any entry to any other entry via  one  or  more  pair
                  matches,  there  is  no guarantee that any entry is a pair match with any other
                  entry. No table has privileged status in  this  case.  If  there  are  multiple
                  entries  from  a given table in the match group, an arbitrary one is chosen for
                  inclusion (there is no unique way to select the best).  See  SUN/256  for  more
                  discussion.
               In  the case of well-separated objects these modes will give the same results. For
              crowded fields however it will make a difference which is chosen.

              Note that which rows actually appear in the output is also influenced by the  joinN
              parameter.

       iref=<table-index>
              If  multimode=pairs  this parameter gives the index of the table in the input table
              list which is to serve as the reference table (the one which  must  be  matched  by
              other tables). Ignored in other modes.

              Row  ordering in the output table is usually tidiest if the default setting of 1 is
              used (i.e. if the first input table is used as the reference table).

       matcher=<matcher-name>
              Defines the nature of the matching that will be performed. Depending  on  the  name
              supplied, this may be positional matching using celestial or Cartesian coordinates,
              exact matching on the value of a  string  column,  or  other  things.  A  list  and
              explanation  of  the  available  matching algorithms is given in SUN/256. The value
              supplied for this parameter determines the meanings of the values required  by  the
              params, values* and tuning parameter(s).

       params=<match-params>
              Determines  the  parameters of this match. This is typically one or more tolerances
              such as error radii. It may contain zero  or  more  values;  the  values  that  are
              required depend on the match type selected by the matcher parameter. If it contains
              multiple values, they must be separated by spaces; values which contain a space can
              be 'quoted' or "quoted".

       tuning=<tuning-params>
              Tuning values for the matching process, if appropriate. It may contain zero or more
              values; the values that are permitted depend on the  match  type  selected  by  the
              matcher  parameter.  If  it  contains  multiple  values,  they must be separated by
              spaces; values which contain a space can be 'quoted' or "quoted". If this  optional
              parameter is not supplied, sensible defaults will be chosen.

       valuesN=<expr-list>
              Defines  the  values  from  table N which are used to determine whether a match has
              occurred. These will typically be coordinate values such as RA and Dec and  perhaps
              some  per-row  error  values  as  well,  though exactly what values are required is
              determined by the kind of match as determined by matcher. Depending on the kind  of
              match,  the  number  and  type  of  the values required will be different. Multiple
              values should be separated by whitespace; if  whitespace  occurs  within  a  single
              value it must be 'quoted' or "quoted". Elements of the expression list are commonly
              just column names, but may be algebraic expressions calculated from  zero  or  more
              columns as explained in SUN/256.

       joinN=default|match|nomatch|always
              Determines  which  rows  from  input  table N are included in the output table. The
              matching algorithm determines which of  the  rows  in  each  of  the  input  tables
              correspond  to  which rows in the other input tables, and this parameter determines
              what to do with that information.

              The default behaviour is that  a  row  will  appear  in  the  output  table  if  it
              represents  a  match  of  rows  from  two  or more of the input tables. This can be
              altered on a per-input-table basis however  by  choosing  one  of  the  non-default
              options below:

                * match: Rows are included only if they contain an entry from input table N.

                * nomatch:  Rows  are  included  only  if they do not contain an entry from input
                  table N.

                * always: Rows are  included  if  they  contain  an  entry  from  input  table  N
                  (overrides any match and nomatch settings of other tables).

                * default: Input table N has no special effect on whether rows are included.

       fixcols=none|dups|all
              Determines  how  input  columns  are  renamed  before  use in the output table. The
              choices are:

                * none: columns are not renamed

                * dups: columns which would otherwise have duplicate names in the output will  be
                  renamed to indicate which table they came from

                * all: all columns will be renamed to indicate which table they came from
               If columns are renamed, the new ones are determined by suffix* parameters.

       suffixN=<label>
              If  the  fixcols  parameter  is set so that input columns are renamed for insertion
              into the output table, this parameter determines how the renaming is done. It gives
              a suffix which is appended to all renamed columns from table N.

       progress=none|log|profile
              Determines  whether  information  on  progress of the match should be output to the
              standard error stream as it progresses.  For  lengthy  matches  this  is  a  useful
              reassurance  and  can give guidance about how much longer it will take. It can also
              be useful as a performance diagnostic.

              The options are:

                * none: no progress is shown

                * log: progress information is shown

                * profile: progress information and limited time/memory profiling information are
                  shown

SEE ALSO

       stilts(1)

       If  the  package  stilts-doc  is installed, the full documentation SUN/256 is available in
       HTML format:
       file:///usr/share/doc/stilts-doc/sun256/index.html

VERSION

       STILTS version 3.1-5-debian

       This is the Debian version of Stilts, which lack the support  of  some  file  formats  and
       network protocols. For differences see
       file:///usr/share/doc/stilts/README.Debian

AUTHOR

       Mark Taylor (Bristol University)

                                             Mar 2017                           STILTS-TMATCHN(1)