Skip to main content
`Ctrl`+`K`

# match_coordinates_sky

astropy.coordinates.match_coordinates_sky(matchcoord, catalogcoord, nthneighbor=1, storekdtree='kdtree_sky')

  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`.

  Parameters:
    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 `python: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 `python: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.

  Returns:
    idx `python:int` `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` [:ref: ‘length’]

      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.

  Notes

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