R: Sky matching

Sky Coordinate Matching {celestial} | R Documentation

## Sky matching

### Description

These functions allows the user to match a reference set of sky coordinates against a comparison set of sky coordinates. The match radius can be varied per source (all matches per source are given within this radius), and mutual best matches are also extracted. coordmatch should be used for finding multiple matches and coordmatchsing should be used when trying to find matches around a single source.

### Usage

    coordmatch(coordref, coordcompare, rad = 2, inunitref = "deg", inunitcompare = "deg",
    radunit = "asec", sep = ":", kstart = 10, ignoreexact = FALSE)
    coordmatchsing(RAref,Decref, coordcompare, rad=2, inunitref = "deg",
    inunitcompare="deg", radunit='asec', sep = ":", ignoreexact=FALSE)

### Arguments

`coordref` | For coordmatch this is the reference dataset, i.e. you want to find matches for each object in this catalogue. A two column matrix or data.frame, where column one is the RA and column two the Dec.
`coordcompare` | The comparison dataset, i.e. you want to find objects in this catalogue that match locations in coordref. A two column matrix or data.frame, where column one is the RA and column two the Dec.
`RAref` | For coordmatch sing this is the reference RA for the sinlge object of interest.
`Decref` | For coordmatch sing this is the reference Dec for the sinlge object of interest.
`rad` | The matching radius to use. If this is length one then the same radius is used for all objects, otherwise it must be the same length as the number of rows in coordref.
`inunitref` | The units of angular coordinate provided for coordref / RAref / Decref. Allowed options are deg for degress, rad for radians and sex for sexigesimal (i.e. HMS for RA and DMS for Deg).
`inunitcompare` | The units of angular coordinate provided for coordcompare. Allowed options are deg for degress, rad for radians and sex for sexigesimal (i.e. HMS for RA and DMS for Deg).
`radunit` | The unit type for the radius specified. Allowed options are deg for degress, amin for arc minutes, asec for arc seconds and rad for radians.
`sep` | If inunitref or inunitcompare is set to 'sex' then sep defines the separation type as detailed in `hms2deg` and `dms2deg`.
`kstart` | The number of matching nodes to attempt initial. The code iterates until all matches within the specified radius (rad) have been found, but it works faster if the kstart is close to the maximum number of matches for any coordref object.
`ignoreexact` | Shoudl exact matches be ignored in the output? This might be helpful when matching the same table against itself, where you have no interest in finding object matches with respect to themselves.

### Details

For coordmatch the main matching is done using nn2 that comes as part of the RANN package. coordmatch adds a large amount of sky coordinate oriented functionality beyond the simple implementation of nn2. For single object matches coordmatchsing should be used since it is substantially faster in this regime (making use of direct dot products).

### Value

The output of coordmatch is a list containing:

`ID` | The full matrix of matching IDs. The rows are ordered identically to coordref, and the ID value is the row position in coordcompare for the match.
`sep` | The full matrix of matching separations in the same units as radunit. The rows are ordered identically to coordref, and the sep value is the separation for each matrix location in the ID list object.
`Nmatch` | Nmatch is a vector giving the total number of matches for each coordref row.
`bestmatch` | A three column data.frame giving the best matching IDs. Only objects with at least one match are listed. Column 1 (refID) gives the row position from coordref and column 2 (compareID) gives the corresponding best matching row position in coordcompare. Column 3 (sep) gives the separation between the matched ref and compare positions in the same units as radunit.

The output of coordmatchsing is a list containing:

`ID` | The full vector of matching IDs. The ID values are the row positions in coordcompare for the match.
`sep` | The full vector of matching separations in the same units as radunit. The sep value is the separation for each vector location in the ID list object.
`Nmatch` | Total number of matches within the specified radius.
`bestmatch` | The best matching ID, where the ID value is the row position in coordcompare for the match.

### Author(s)

Aaron Robotham

### See Also

`hms2deg`, `dms2deg`, `sph2car`

### Examples

    set.seed(666)

    #Here we make objects in a virtual 1 square degree region

    mocksky=cbind(runif(1e3), runif(1e3))

    #Now we match to find all objects within an arc minute, ignoring self matches

    mockmatches=coordmatch(mocksky, mocksky, ignoreexact=TRUE, rad=1, radunit='amin')

    #Now we match to find all objects with varying match radii, ignoring self matches

    mockmatchesvary=coordmatch(mocksky, mocksky,ignoreexact=TRUE, rad=seq(0,1,length=1e3),
    radunit='amin')

[Package celestial version 1.4.1 Index]