HR-eoQ v d Z ddlZddlmZ ddlmZ ddlm Z ddl
m Z g dZ dd
Z
dd Zdd
ZddZddZdS )zB
This module contains functions for matching coordinate catalogs.
N)units )Angle)UnitSphericalRepresentation)SkyCoord)match_coordinates_3dmatch_coordinates_skysearch_around_3dsearch_around_sky kdtree_3dc l |j st | dk rt d t || }t | t
r| |d } n| | } |j j j }| j j
| }| dt j |j dz f }t j |j rt d | |j | \ }} |dk r|dddf }| dddf } || | }
| |j dd |
| |j dd |z 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.Fmerge_attributes z0Matching coordinates cannot contain NaN entries.N)isscalarlen
ValueError_get_cartesian_kdtree
isinstancer transform_to cartesianxunitxyztoreshapenpprodshapeisnanvalueanyqueryT
separation)
matchcoord catalogcoord nthneighbor storekdtreekdtcatunitmatchxyz matchflatxyzdistidxsep2ds `_ 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+ newmatch match_urepr
newmatch_u cat_ureprnewcat_ur1 r2 sep3ds r3 r r j s d
L 1 1A 5 5 Q
*h'' 9 **<%*PP **<88 -,,-HIIK'' 44J !../JKKI)))44H
$((kBBK,Hk; C <$&ABB: hm%@ A A: S!//99 +s## @*2.*E ;'' '/~h'? 8$ u r4 c |j st d | j s|j rt d t | dk st | dk rmt j g t
t j g t
t
g t j t j g | j
j fS t || }|j
j j }| | } t | || }| | }g }g } t# | || D ]4\ }
} | D ],} | |
| | -5t j |t
}t j | t
} |j dk r:t
g t j }
t j g | j
j }nB| | || }
| | || }|| |
|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 dtype) forceunit)r r r r arrayintr udegQuantitydistancer r r r r to_value enumeratequery_ball_treeappendsizer' r= )coords1coords2 distlimitr+ kdt2cunitkdt1didxs1idxs2imatchesmatchd2dsd3dss r3 r
r
s1 n KIJJJ
7+
$
7||qCLLA - -
HRs # # # HRs # # # "ae
Jr7+0 1 1
!+ 6 6D $E
""7++G + G G GD 5!!A E E 4 4T1 = =>>
7 E LLOOO LL
HU# & & &E HU# & & &E zQR z"g . 344u~(( 88u~++GEN;; %t ##r4 c |j st d | j s|j rt d t | dk st | dk r|j j t
j k r
t
j }n | j j }t j g t t j g t t g t
j t j g | fS |
| } | j t }| | }t% || }|r(|j | r|j | }nV|j t } | | }
t% |
| }|r||j |du rdn|< dt j t | dz z j } g } g }
t/ | || D ]4\ }}|D ],}| | |
| -5t j | t } t j |
t }
| j dk rc|j j t
j k r
t
j }n | j j }t g t
j }t j g | }nn| | ||
} | | ||
}n*# t $ r dt j |dz z }Y nw xY w| |
||fS ) a
Searches for pairs of points that have an angular separation at least as
close as a specified angle.
This is intended for use on coordinate objects with arrays of coordinates,
not scalars. For scalar coordinates, it is better to use the ``separation``
methods.
Parameters
----------
coords1 : coordinate-like
The first set of coordinates, which will be searched for matches from
``coords2`` within ``seplimit``. Cannot be a scalar coordinate.
coords2 : coordinate-like
The second set of coordinates, which will be searched for matches from
``coords1`` within ``seplimit``. Cannot be a scalar coordinate.
seplimit : `~astropy.units.Quantity` ['angle']
The on-sky separation 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``.
If either ``coords1`` or ``coords2`` don't have a distance,
this is the 3D distance on the unit sphere, rather than a
physical distance.
Notes
-----
This function requires `SciPy `_
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 rF Tr7 g @) r r r rN r rK dimensionless_unscaledr rI rJ r rL rM r r8 r9 r r: r r; r< sinr# rP rQ rR rS r' r= )rT rU seplimitr+ distuniturepr1ucoords1rY rW urepr2ucoords2rr[ r\ r] r^ r_ r` ra s r3 r r 3 sY h KIJJJ
7+
"
7||qCLLA - - A$< < </HH ',H HRs # # # HRs # # # "ae
Jr8 $ $
""7++G \
&
&'B
C
CF$$V,,H ; 7 7D Sw}((55 S}[) **+FGG((00$X{;; SNRGMkT&9&9(({ K
RVE(OOc)
*
* *1A E E 4 4T1 = =>>
7 E LLOOO LL
HU# & & &E HU# & & &E zQ A$< < </HH ',HR z"h''u~(( 88 *5>//??DD * * * rvdSj)))DDD *
%t ##s !L9 9$M M r7 c j ddl m} ddlm} |j }n"# t
$ r |d |j }Y nw xY w|du rd}t |t rA| j
|d }|#t || st d| d n9t || r|}d}n$|sd}n t d
t | z ||
| j j
}n | j j
| }| d t! j |j d z f }t! j |j rt- d ||j j d
d
}n%# t $ r ||j j }Y nw xY w|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 implementationTr7 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)
compact_nodes
balanced_tree)warningsrn scipyro cKDTree ExceptionKDTreer r> r; r< TypeErrorr r r r r r r! r" r# r$ r r& ) coordattrname_or_kdtrH rn ro rv r, cartxyzflatxyzs r3 r r s3 0
$
$ " /3''
kooot44 ?:c6#:#:?T/TTT
OV , ,
=O@T@T T
{ o)GGo),,Y77G//1bggm&<&<&A"BCC
8GM " " & & ( ( P NOO O * & USSSCC * * * & ))CCC *
+'* O$ Js 55)F F$#F$)r r )r r5 )r )r5 )r7 N)__doc__numpyr astropyr rK r representationr sky_coordinater __all__r r r
r r r4 r3 r s
7 7 7 7 7 7 $ $ $ $ $ $ :EP P P Ph :F[ [ [ [ |h$ h$ h$ h$V@$ @$ @$ @$FR R R R R Rr4