astropy.coordinates.match_coordinates_sky(matchcoord, catalogcoord, nthneighbor=1, storekdtree='kdtree_sky')[source] [edit on github]

Finds the nearest on-sky matches of a coordinate or coordinates in a set of catalog coordinates.

This finds the on-sky closest neighbor, which is only different from the 3-dimensional match if distance is set in either matchcoord or catalogcoord.

matchcoord : BaseCoordinateFrame or SkyCoord

The coordinate(s) to match to the catalog.

catalogcoord : BaseCoordinateFrame or SkyCoord

The base catalog in which to search for matches. Typically this will be a coordinate object that is an array (i.e., catalogcoord.isscalar == False)

nthneighbor : int, optional

Which closest neighbor to search for. Typically 1 is desired here, as that is correct for matching one set of coordinates to another. The next likely use case is 2, for matching a coordinate catalog against itself (1 is inappropriate because each point will find itself as the closest match).

storekdtree : bool or str, optional

If a string, will store the KD-Tree used for the computation in the catalogcoord in catalogcoord.cache with the provided name. This dramatically speeds up subsequent calls with the same catalog. If False, the KD-Tree is discarded after use.

idx : integer array

Indices into catalogcoord to get the matched points for each matchcoord. Shape matches matchcoord.

sep2d : Angle

The on-sky separation between the closest match for each matchcoord and the matchcoord. Shape matches matchcoord.

dist3d : Quantity

The 3D distance between the closest match for each matchcoord and the matchcoord. Shape matches matchcoord. If either matchcoord or catalogcoord don’t have a distance, this is the 3D distance on the unit sphere, rather than a true distance.


This function requires SciPy to be installed or it will fail.