Skip to main content
`Ctrl`+`K`

# join_skycoord

astropy.table.join_skycoord(distance, distance_func='search_around_sky')

  Helper function to join on SkyCoord columns using distance matching.

  This function is intended for use in `table.join()` to allow performing a table join where the key columns are both `SkyCoord` objects, matched by computing the distance between points and accepting values below `distance`.

  The distance cross-matching is done using either `search_around_sky` or `search_around_3d`, depending on the value of `distance_func`. The default is `'search_around_sky'`.

  One can also provide a function object for `distance_func`, in which case it must be a function that follows the same input and output API as `search_around_sky`. In this case the function will be called with `(skycoord1, skycoord2, distance)` as arguments.

  Parameters:
    distance `Quantity` [:ref: ‘angle’, :ref: ‘length’]

      Maximum distance between points to be considered a join match. Must have angular or distance units.

    distance_func `python:str` or python:function

      Specifies the function for performing the cross-match based on `distance`. If supplied as a string this specifies the name of a function in `astropy.coordinates`. If supplied as a function then that function is called directly.

  Returns:
    join_func python:function

      Function that accepts two `SkyCoord` columns (col1, col2) and returns the tuple (ids1, ids2) of pair-matched unique identifiers.

  Examples

  This example shows an inner join of two `SkyCoord` columns, taking any sources within 0.2 deg to be a match. Note the new `sc_id` column which is added and provides a unique source identifier for the matches.

      >>> from astropy.coordinates import SkyCoord
      >>> import astropy.units as u
      >>> from astropy.table import Table, join_skycoord
      >>> from astropy import table

      >>> sc1 = SkyCoord([0, 1, 1.1, 2], [0, 0, 0, 0], unit='deg')
      >>> sc2 = SkyCoord([0.5, 1.05, 2.1], [0, 0, 0], unit='deg')

      >>> join_func = join_skycoord(0.2 * u.deg)
      >>> join_func(sc1, sc2)  # Associate each coordinate with unique source ID
      (array([3, 1, 1, 2]), array([4, 1, 2]))

      >>> t1 = Table([sc1], names=['sc'])
      >>> t2 = Table([sc2], names=['sc'])
      >>> t12 = table.join(t1, t2, join_funcs={'sc': join_skycoord(0.2 * u.deg)})
      >>> print(t12)  # Note new `sc_id` column with the IDs from join_func()
      sc_id   sc_1    sc_2
            deg,deg deg,deg
      ----- ------- --------
          1 1.0,0.0 1.05,0.0
          1 1.1,0.0 1.05,0.0
          2 2.0,0.0  2.1,0.0