# Cross-Match

The cross-match is procedure which is looking for the equivalent objects in two tables. The equivalence is assigned on base of a metric (spherical distance). An index of equivalent rows of the tables is generated.

## Command

`munipack cross [..] file1 file2`

## Description

The cross-match is the procedure which searches tables for the equivalent objects on base of minimal spherical distance and optionally, on similar fluxes. Purpose of the match is looking for the objects in different catalogues, detected object on frame or two frames.

This utility cross-match implementation is follows the criteria for successful match:

- Spherical distance needs to be minimal and under a tolerance.
- Optionally, relative calibrated fluxes needs to be similar. (partially implemented)
- Optionally, the mutual correspondence is one to one. (not implemented yet)

For the first criterion, one computes the distance along great circle of spherical coordinates. which must be equal under given tolerance. The tolerance is a parameter and must be provided. The method looks plain, but is very powerful and in sparse star fields works very well.

Visual double stars (stars are angular near) has rare occurrence but can confuse the distance criterion, especially when theirs coordinates are load down by statistical errors. In this case, the comparison of fluxes can be helpful.

The algorithm compares coordinates computed at the same epoch (the same time) which can be differ from catalogue positions by proper motion of the objects. The algorithm is used:

- For known epoch (time), the coordinates are computed.
- The epoch is determined from EPOCH parameter of the catalogue (FITS keyword), when is not provided, one is set to 2000.00 year.
- When proper motions are not set, the coordinates are used directly.

The proper motion of stars is usually small and one is often omitted. But sometimes, one can be important for heavy crowded star fields or fast stars.

This utility is just public interface to internal procedures for cross-match. The same code is used internally for all catalogue to frame matching.

## Parameters

`--tol`
  tolerance of uncertainty of coordinates of objects in degrees
`--ftol`
  relative errors for flux ratios, default = 1
`--col-ra`
  Right Ascension column in catalogue
`--col-dec`
  Declination column in catalogue
`--col-pm-ra`
  Proper motion in Right Ascension column in catalogue
`--col-pm-dec`
  Proper motion in Declination column in catalogue
`--col-mag`
  Magnitude-like column in catalogue

The parameter `--tol` is by default set to machine precision (which will be not too useful). Therefore the parameter is practically mandatory.

The parameters `--col-ra,--col-dec` are mandatory. When any from `--col-pm-ra,--col-pm-dec,--col-pm-mag` missing, the corresponding criterion is not used.

See Common options for input/output file names.

## Data Format

Results of cross-matching are stored in a FITS table with two columns only. Every column represents the index of object in corresponding file. In the first column, indexes of second files are stored. In second column, the indexes of first objects are stored. Zero value means no correspondence has been found. Number of rows is maximum of both tables.

Keywords FILE1,FILE2 in FITS header points to filenames of input tables.

## Examples

Lets have already calibrated frame `T_Phe_000003.fits` and we are doing cross-match with a catalogue:

    $ munipack cross --tol 5e-4 --col-ra RA,RAJ2000 --col-dec DEC,DEJ2000 \
           T_Phe_000003.fits cone.fits

## See Also

Common options