CATPAIR - Pair two catalogues

Description:

Pair two catalogues to create a new output catalogue. The input catalogues are paired on the basis of similar two-dimensional coordinates. The coordinates may be either celestial spherical- polar or Cartesian. An index join method is used.

catpair is a powerful and flexible application. See SUN/190 for a full description.

Usage:

catpair

Parameters:

PRIMARY = CHARACTER (read)

The name of the primary input catalogue.

SECOND = CHARACTER (read)

The name of the secondary input catalogue. This catalogue must be sorted on the second column to be used in the pairing. Usually this column will be the Declination or Y coordinate.

OUTPUT = CHARACTER (read)

The name of the output paired catalogue. A catalogue with this name must not already exist.

CRDTYP = CHARACTER (read)

The type of coordinates to be paired. The possibilities are either Cartesian coordinates (`C') or celestial spherical-polar coordinates (`S') such as Right Ascension and Declination.

PCRD1 = CHARACTER (read)

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 = CHARACTER (read)

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 = CHARACTER (read)

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 = CHARACTER (read)

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 = CHARACTER (read)

The 'critical distance'; the maximum separation for two objects to be considered pairs. It may be either a constant, the name of a column in the primary catalogue or an expression involving columns in the primary catalogue.

PRTYP = CHARACTER (read)

The `type of pairing' required, that is the set of rows from the two input catalogues are to be retained in the output catalogue. Briefly, the options are: C - common, P - primary, M - mosaic, R - primrej or A - allrej. See SUN/190 for more details.

MULTP = LOGICAL (read)

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.

MULTS = LOGICAL (read)

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.

ALLCOL = LOGICAL (read)

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.

SPCOL = LOGICAL (read)

Flag indicating whether special columns giving details of the paired objects are to be included in the output catalogue. If SPCOL is set to TRUE the following columns are included: SEPN, the separation of the paired primary and secondary objects; PMULT, the number of matches in the primary; SMULT, the number of matches in the seconary.

PRMPAR = LOGICAL (read)

Specify whether the parameters of the primary are to be copied to the output catalogue.

SECPAR = LOGICAL (read)

Specify whether the parameters of the secondary are to be copied to the output catalogue.

PTEXT = CHARACTER (read)

Specify whether any textual information associated with the primary is to be copied to the output catalogue. The options are: A - all (create a duplicate of the primary header as comments), C - just copy comments (and history) or N - none.

STEXT = CHARACTER (read)

Specify whether any textual information associated with the secondary is to be copied to the output catalogue. The options are: A - all (create a duplicate of the secondary header as comments), C - just copy comments (and history) or N - none.

TEXT = CHARACTER (read)

Specify whether a set of comments describing the specification of the pairing pairing is written to the output catalogue. The options are: Y - write comments (default), N - do not write comments.

COLBUF = CHARACTER (read)

Name for the individual columns to be included in the output catalogue. Enter 'END' to finish.

QUIET = LOGICAL (read)

Operate in quiet mode where warnings are suppressed. The permitted values are: TRUE - quiet mode, FALSE - verbose mode.

Examples:

catpair

Answer the numerous prompts and pair two catalogues.

catpair spcol=true

Answer the numerous prompts and pair two catalogues. The output catalogue of paired objects will contain three additional columns containing details for the paired objects.

catpair text=n

Answer the numerous prompts and pair two catalogues, but specify that a summary of the pairing specification is not to be written as comments to the output catalogue.

Notes:

catpair is intended for the case where the primary catalogue is a relatively small list of target objects which is being paired with a larger secondary catalogue. It will still work if the primary is a large catalogue, but it is not optimised for this case and will take some time. Conversely, the size of the secondary catalogue is largely immaterial.

Pitfalls

Ensure that the secondary catalogue is sorted on the second pairing column. Usually this column will be the Declination or Y coordinate. If the secondary is not suitably sorted then use application catsort to sort it.

Prior Requirements

The secondary catalogue must be sorted on the second pairing coordinate. Usually this coordinate will be the Declination or Y coordinate. If the secondary is not suitably sorted then use application catsort to sort it.