Running catpair

To run catpair simply type:

catpair

By default catpair writes a summary of the pairing options specified as textual information in the output catalogue. This information is useful documentation of the pairing and you will usually want to retain it. However, you can specify that it is not to be written by specifying an extra item on the command line, as follows:

catpair  text=none

There must be one or more spaces between `catpair' and `text=none'. catpair has an option to include in the output catalogue three special columns containing additional details for the paired objects. These columns are described in Section , below. By default these additional columns are not created. To include them in the output catalogue type:

catpair  spcol=true

You must answer a fairly long series of prompts in order to specify the behaviour of catpair. These prompts are listed below, in the order in which they are issued by the program, together with a corresponding explanation. In this list the prompts are identified by the corresponding ADAM parameter name, which appears at the start of the prompt line.

PRIMARY

Enter the name of the primary input catalogue.

SECOND

Enter the name of the secondary input catalogue. This catalogue must be sorted on the second column to be used in the pairing (usually the $y$ or Declination coordinate).

OUTPUT

Enter the name of the output catalogue to contain the set of paired objects. A catalogue with this name must not already exist. catpair will automatically create the output catalogue in toto.

CRDTYP

(default = `S') Specify the type of coordinates which are to be used for the pairing. The possibilities are either Cartesian coordinates (`C') or celestial spherical-polar coordinates (`S') such as Right Ascension and Declination.

PCRD1

Enter the name of the column in the primary catalogue containing the first column to be used in the pairing. This column will usually be an $x$ coordinate or a Right Ascension.

PCRD2

Enter the name of the column in the primary catalogue containing the second column to be used in the pairing. This column will usually be a $y$ coordinate or a Declination.

SCRD1

Enter the name of the column in the secondary catalogue containing the first column to be used in the pairing. This column will usually be an $x$ coordinate or a Right Ascension.

SCRD2

Enter the name of the column in the secondary catalogue containing the second column to be used in the pairing. This column will usually be a $y$ coordinate or a Declination. The secondary catalogue must be sorted on this column.

PDIST

Enter the critical distance determining whether two objects, one in each catalogue, are considered pairs or not. If the actual separation of the two objects is less than or equal to this distance then they are considered pairs; if it is greater then they are not. In the simplest case this critical distance is a simple numeric value, such as twenty-three minutes of arc, constant for all the objects in the catalogues. However, it may also be a column in the primary catalogue (but not a column in the secondary) or an expression involving columns in the primary (see Section , below).

If the pairing coordinates are Cartesian then a constant critical distance would typically be specified as a simple decimal number, for example `23.0'. However, if they were celestial coordinates then it could be specified as any of the forms in which an angle can be input: a floating point number in radians, or a sexagesimal value in hours or degrees. In addition a special format is available in catpair in which the separation is given as a floating point number expressed in seconds of arc, immediately followed by the string `arcsec'. For example, a separation of twenty-three minutes of arc could be entered as any of the following values:

+00:23:00		(sexagesimal degrees)
1380.0arcsec		(seconds of arc)
00:01:31.99		(sexagesimal hours)
6.6904288E-3		(radians)

Note that the sign is necessary in the value in sexagesimal degrees to ensure that the value is interpreted as degrees, not hours. The examples in sexagesimal hours and radians are not particularly sensible here.

PRTYP

(default = `C') Select the `type of pairing' required, that is specify which set of rows from the two input catalogues are to be retained in the output catalogue. Briefly, the options are:

C

(COMMON) retain only the common or paired rows in the two catalogues,

M

(MOSAIC) retain all the rows in the primary and the unpaired rows in the secondary,

P

(PRIMARY) retain all the rows in the primary (for unpaired objects columns copied from the secondary are set to null).

R

(PRIMREJ) retain only the unpaired rows in the primary,

A

(ALLREJ) retain the unpaired rows in both the primary and the secondary.

These options are described in greater detail in Section , below.

MULTP

(default = `yes') Specify how multiple matches in the primary are to be handled. The options are either to retain the single closest match or to retain all the matches. The treatment of multiple matches is described in detail in Section , below.

MULTS

(default = `no') Specify how multiple matches in the secondary are to be handled. The options are either to retain the single closest match or to retain all the matches. The treatment of multiple matches is described in detail in Section , below.

ALLCOL

(default = `yes') Specify the set of columns to be retained in the output catalogue. The options are to either retain all the columns from both input catalogues or to retain specified columns from either input catalogue. If you are in doubt you should retain all the columns. This alternative is the `safest' and simplest, though it may result in the output catalogue containing columns which you do not need and consequently using more disk space than is strictly necessary.

If you choose to retain all the columns they are simply copied automatically from the input catalogue, without further intervention on your part. However, if you choose to specify the columns to retain you will subsequently be prompted for the names of the columns to be retained (and hence you must be prepared with this information). The details of specifying named input columns are described in Section , below.

If you choose to retain all the columns, the columns created in the output catalogue will have the same names (and other attributes) as the corresponding columns in the input catalogue. However, in the case where identically named columns in the primary and secondary catalogues would cause the output catalogue to contain two identically named columns, the names of the columns in the output catalogue are disambiguated by appending `_S' to the name of the column originating in the secondary.

PRMPAR

(default = `yes') Specify whether the parameters of the primary are to be copied to the output catalogue.

SECPAR

(default = `no') Specify whether the parameters of the secondary are to be copied to the output catalogue.

PTEXT

(default = `C') Specify what textual information associated with the primary is to be copied to the output catalogue. The options are: `A' - all, `C' - comments and history only and `N' - none.

STEXT

(default = `N') Specify what textual information associated with the secondary is to be copied to the output catalogue. The options are: `A' - all, `C' - comments and history only and `N' - none.