a
ߙfb Q @ sz d Z ddlZddlmZ ddlmZ ddlm Z ddl
m Z g dZ dd
d Z
dd
dZdddZdddZdddZdS )zB
This module contains functions for matching coordinate catalogs.
N )UnitSphericalRepresentation)units)Angle)SkyCoord)match_coordinates_3dmatch_coordinates_skysearch_around_3dsearch_around_sky kdtree_3dc C s |j st|dk rtdt||}t| tr>| j|dd} n
| |} |jjj }| jj
|}| dt
|jd f}t
|j rtd||j|\}} |dkr|dddf }| dddf } || | }
| |jdd |
| |jdd | fS ) a?
Finds the nearest 3-dimensional matches of a coordinate or coordinates in
a set of catalog coordinates.
This finds the 3-dimensional closest neighbor, which is only different
from the on-sky distance if ``distance`` is set in either ``matchcoord``
or ``catalogcoord``.
Parameters
----------
matchcoord : `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord`
The coordinate(s) to match to the catalog.
catalogcoord : `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.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``, as 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 : int array
Indices into ``catalogcoord`` to get the matched points for each
``matchcoord``. Shape matches ``matchcoord``.
sep2d : `~astropy.coordinates.Angle`
The on-sky separation between the closest match for each ``matchcoord``
and the ``matchcoord``. Shape matches ``matchcoord``.
dist3d : `~astropy.units.Quantity` ['length']
The 3D distance between the closest match for each ``matchcoord`` and
the ``matchcoord``. Shape matches ``matchcoord``.
Notes
-----
This function requires `SciPy `_ to be installed
or it will fail.
r CThe catalog for coordinate matching cannot be a scalar or length-0.FZmerge_attributes z0Matching coordinates cannot contain NaN entries.N)isscalarlen
ValueError_get_cartesian_kdtree
isinstancer transform_to cartesianxunitxyztoreshapenpprodshapeisnanvalueanyZqueryT
separation)
matchcoord catalogcoord nthneighbor storekdtreekdtZcatunitZmatchxyzZ matchflatxyzZdistidxsep2d r+ ;lib/python3.9/site-packages/astropy/coordinates/matching.pyr s" .
r
kdtree_skyc C s |j st|dk rtdt| tr4| j|dd}n
| |}|jt}| |}|jt}| |}|j
||}t ||||\} }
} t|jtst|jts||
|} t|tr|j
| |j
|< n|du r|j
d |j
d< | |
| fS )a
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 : `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord`
The coordinate(s) to match to the catalog.
catalogcoord : `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.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.
Returns
-------
idx : int array
Indices into ``catalogcoord`` to get the matched points for each
``matchcoord``. Shape matches ``matchcoord``.
sep2d : `~astropy.coordinates.Angle`
The on-sky separation between the closest match for each
``matchcoord`` and the ``matchcoord``. Shape matches ``matchcoord``.
dist3d : `~astropy.units.Quantity` ['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.
r r Fr
Tkdtree)r r r r r r data represent_asr
realize_framecachegetr
separation_3dstr) r$ r% r& r' ZnewmatchZ match_ureprZ
newmatch_uZ cat_ureprZnewcat_ur) r* Zsep3dr+ r+ r, r ^ s( 0
r c C sZ |j std| j s|j r"tdt| dks:t|dkrntjg tdtjg tdtg tjt g | j
j fS t ||}|j
jj }| |} t | ||d}||}g }g } t|||D ]&\}
} | D ]} ||
| | qqtj|td}tj| td} |jdkr*tg tj}
t g | j
j }n$| | || }
| | || }|| |
|fS )a
Searches for pairs of points that are at least as close as a specified
distance in 3D space.
This is intended for use on coordinate objects with arrays of coordinates,
not scalars. For scalar coordinates, it is better to use the
``separation_3d`` methods.
Parameters
----------
coords1 : `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord`
The first set of coordinates, which will be searched for matches from
``coords2`` within ``seplimit``. Cannot be a scalar coordinate.
coords2 : `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord`
The second set of coordinates, which will be searched for matches from
``coords1`` within ``seplimit``. Cannot be a scalar coordinate.
distlimit : `~astropy.units.Quantity` ['length']
The physical radius to search within.
storekdtree : bool or str, optional
If a string, will store the KD-Tree used in the search with the name
``storekdtree`` in ``coords2.cache``. This speeds up subsequent calls
to this function. If False, the KD-Trees are not saved.
Returns
-------
idx1 : int array
Indices into ``coords1`` that matches to the corresponding element of
``idx2``. Shape matches ``idx2``.
idx2 : int array
Indices into ``coords2`` that matches to the corresponding element of
``idx1``. Shape matches ``idx1``.
sep2d : `~astropy.coordinates.Angle`
The on-sky separation between the coordinates. Shape matches ``idx1``
and ``idx2``.
dist3d : `~astropy.units.Quantity` ['length']
The 3D distance between the coordinates. Shape matches ``idx1`` and
``idx2``. The unit is that of ``coords1``.
Notes
-----
This function requires `SciPy `_
to be installed or it will fail.
If you are using this function to search in a catalog for matches around
specific points, the convention is for ``coords2`` to be the catalog, and
``coords1`` are the points to search around. While these operations are
mathematically the same if ``coords1`` and ``coords2`` are flipped, some of
the optimizations may work better if this convention is obeyed.
In the current implementation, the return values are always sorted in the
same order as the ``coords1`` (so ``idx1`` is in ascending order). This is
considered an implementation detail, though, so it could change in a future
release.
z.distlimit must be a scalar in search_around_3dzOne of the inputs to search_around_3d is a scalar. search_around_3d is intended for use with array coordinates, not scalars. Instead, use ``coord1.separation_3d(coord2) < distlimit`` to find the coordinates near a scalar coordinate.r Zdtype) forceunit)r r r r arrayintr udegQuantitydistancer r r r r Zto_value enumeratequery_ball_treeappendsizer# r4 )coords1coords2Z distlimitr' kdt2Zcunitkdt1didxs1idxs2imatchesmatchd2dsd3dsr+ r+ r, r s8 7
r c C s& |j std| j s|j r"tdt| dks:t|dkr|jjtjkrPtj}n| jj}tjg t dtjg t dt
g tj t g |fS |
|} | jt}| |}t||}|r|j|r|j| }n>|jt} || }
t|
|}|r ||j|du rdn|< dtt
|d j} g } g }
t||| D ]*\}}|D ]}| | |
| qHq`_
to be installed or it will fail.
In the current implementation, the return values are always sorted in the
same order as the ``coords1`` (so ``idx1`` is in ascending order). This is
considered an implementation detail, though, so it could change in a future
release.
z.seplimit must be a scalar in search_around_skyzOne of the inputs to search_around_sky is a scalar. search_around_sky is intended for use with array coordinates, not scalars. Instead, use ``coord1.separation(coord2) < seplimit`` to find the coordinates near a scalar coordinate.r r6 Tr. g @) r r r r= r r: Zdimensionless_unscaledr r8 r9 r r; r< r r/ r0 r r1 r r2 r3 Zsinr r> r? r@ rA r# r4 )rB rC Zseplimitr' ZdistunitZurepr1Zucoords1rE rD Zurepr2Zucoords2rrG rH rI rJ rK rL rM r+ r+ r, r
sX 4
r
r. c C sd ddl m} ddlm} z
|j}W n tyB |d |j}Y n0 |du rPd}t|tr| j
|d}|durt||st d| d n.t||r|}d}n|sd}nt d
t| |du rP|du r| j j
}n| j j
|}|d t|jd f}t|j rtd z||jjd
d
d}W n t yN ||jj}Y n0 |r`|| j |< |S )a
This is a utility function to retrieve (and build/cache, if necessary)
a 3D cartesian KD-Tree from various sorts of astropy coordinate objects.
Parameters
----------
coord : `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord`
The coordinates to build the KD-Tree for.
attrname_or_kdt : bool or str or KDTree
If a string, will store the KD-Tree used for the computation in the
``coord``, in ``coord.cache`` with the provided name. If given as a
KD-Tree, it will just be used directly.
forceunit : unit or None
If a unit, the cartesian coordinates will convert to that unit before
being put in the KD-Tree. If None, whatever unit it's already in
will be used
Returns
-------
kdt : `~scipy.spatial.cKDTree` or `~scipy.spatial.KDTree`
The KD-Tree representing the 3D cartesian representation of the input
coordinates.
r )warn)spatialzNC-based KD tree not found, falling back on (much slower) python implementationTr. NzThe `attrname_or_kdt` "z" is not a scipy KD tree!z/Invalid `attrname_or_kdt` argument for KD-Tree:r z/Catalog coordinates cannot contain NaN entries.F)Z
compact_nodesZ
balanced_tree)warningsrP ZscipyrQ ZcKDTree ExceptionKDTreer r5 r2 r3 TypeErrorr r r r r r r r r r! r r" ) ZcoordZattrname_or_kdtr7 rP rQ rT r( ZcartxyzZflatxyzr+ r+ r, r sF
r )r r )r r- )r )r- )r. N)__doc__Znumpyr Zrepresentationr Zastropyr r: r Zsky_coordinater __all__r r r r
r r+ r+ r+ r, s
L
W
g