Coverage for python/lsst/analysis/tools/actions/keyedData/calcDistances.py: 18%
90 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-07-06 04:18 -0700
1# This file is part of analysis_tools.
2#
3# Developed for the LSST Data Management System.
4# This product includes software developed by the LSST Project
5# (https://www.lsst.org).
6# See the COPYRIGHT file at the top-level directory of this distribution
7# for details of code ownership.
8#
9# This program is free software: you can redistribute it and/or modify
10# it under the terms of the GNU General Public License as published by
11# the Free Software Foundation, either version 3 of the License, or
12# (at your option) any later version.
13#
14# This program is distributed in the hope that it will be useful,
15# but WITHOUT ANY WARRANTY; without even the implied warranty of
16# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17# GNU General Public License for more details.
18#
19# You should have received a copy of the GNU General Public License
20# along with this program. If not, see <https://www.gnu.org/licenses/>.
21__all__ = ("CalcRelativeDistances",)
23import astropy.units as u
24import numpy as np
25import pandas as pd
26from astropy.coordinates import SkyCoord
27from lsst.pex.config import Field
29from ...interfaces import KeyedData, KeyedDataAction, KeyedDataSchema, Vector
32class CalcRelativeDistances(KeyedDataAction):
33 """Calculate relative distances in a matched catalog.
35 Given a catalog of matched sources from multiple visits, this finds all
36 pairs of objects at a given separation, then calculates the separation of
37 their component source measurements from the individual visits. The RMS of
38 these is used to calculate the astrometric relative repeatability metric,
39 AMx, while the overall distribution of separations is used to compute the
40 ADx and AFx metrics.
41 """
43 groupKey = Field[str](doc="Column key to use for forming groups", default="obj_index")
44 visitKey = Field[str](doc="Column key to use for matching visits", default="visit")
45 raKey = Field[str](doc="RA column key", default="coord_ra")
46 decKey = Field[str](doc="Dec column key", default="coord_dec")
47 annulus = Field[float](doc="Radial distance of the annulus in arcmin", default=5.0)
48 width = Field[float](doc="Width of annulus in arcmin", default=2.0)
49 threshAD = Field[float](doc="Threshold in mas for AFx calculation.", default=20.0)
50 threshAF = Field[float](
51 doc="Percentile of differences that can vary by more than threshAD.", default=10.0
52 )
54 def getInputSchema(self) -> KeyedDataSchema:
55 return (
56 (self.groupKey, Vector),
57 (self.raKey, Vector),
58 (self.decKey, Vector),
59 (self.visitKey, Vector),
60 )
62 def __call__(self, data: KeyedData, **kwargs) -> KeyedData:
63 """Run the calculation.
65 Parameters
66 ----------
67 data: KeyedData
68 Catalog of data including coordinate, visit, and object group
69 information.
70 Returns
71 -------
72 distanceParams: `dict`
73 Dictionary of the calculated arrays and metrics with the following
74 keys:
75 - ``rmsDistances`` : Per-object rms of separations (`np.array`).
76 - ``separationResiduals`` : All separations minus per-object median
77 (`np.array`)
78 - ``AMx`` : AMx metric (`float`).
79 - ``ADx`` : ADx metric (`float`).
80 - ``AFx`` : AFx metric (`float`).
81 """
82 D = self.annulus * u.arcmin
83 width = self.width * u.arcmin
84 annulus = (D + (width / 2) * np.array([-1, +1])).to(u.radian)
86 df = pd.DataFrame(
87 {
88 "groupKey": data[self.groupKey],
89 "coord_ra": data[self.raKey],
90 "coord_dec": data[self.decKey],
91 "visit": data[self.visitKey],
92 }
93 )
95 meanRa = df.groupby("groupKey")["coord_ra"].aggregate("mean")
96 meanDec = df.groupby("groupKey")["coord_dec"].aggregate("mean")
98 catalog = SkyCoord(meanRa.to_numpy() * u.degree, meanDec.to_numpy() * u.degree)
99 idx, idxCatalog, d2d, d3d = catalog.search_around_sky(catalog, annulus[1])
100 inAnnulus = d2d > annulus[0]
101 idx = idx[inAnnulus]
102 idxCatalog = idxCatalog[inAnnulus]
104 rmsDistances = []
105 sepResiduals = []
106 for id in range(len(meanRa)):
107 match_inds = idx == id
108 match_ids = idxCatalog[match_inds & (idxCatalog != id)]
109 if match_ids.sum() == 0:
110 continue
112 object_srcs = df.loc[df["groupKey"] == meanRa.index[id]]
114 object_visits = object_srcs["visit"].to_numpy()
115 object_ras = (object_srcs["coord_ra"].to_numpy() * u.degree).to(u.radian).value
116 object_decs = (object_srcs["coord_dec"].to_numpy() * u.degree).to(u.radian).value
117 if len(object_srcs) <= 1:
118 continue
119 object_srcs = object_srcs.set_index("visit")
120 object_srcs.sort_index(inplace=True)
122 for id2 in match_ids:
123 match_srcs = df.loc[df["groupKey"] == meanRa.index[id2]]
124 match_visits = match_srcs["visit"].to_numpy()
125 match_ras = (match_srcs["coord_ra"].to_numpy() * u.degree).to(u.radian).value
126 match_decs = (match_srcs["coord_dec"].to_numpy() * u.degree).to(u.radian).value
128 separations = matchVisitComputeDistance(
129 object_visits, object_ras, object_decs, match_visits, match_ras, match_decs
130 )
132 if len(separations) > 1:
133 rmsDist = np.std(separations, ddof=1)
134 rmsDistances.append(rmsDist)
135 if len(separations) > 2:
136 sepResiduals.append(separations - np.median(separations))
138 if len(rmsDistances) == 0:
139 AMx = np.nan * u.marcsec
140 else:
141 AMx = (np.median(rmsDistances) * u.radian).to(u.marcsec)
143 if len(sepResiduals) <= 1:
144 AFx = np.nan * u.percent
145 ADx = np.nan * u.marcsec
146 absDiffSeparations = np.array([]) * u.marcsec
147 else:
148 sepResiduals = np.concatenate(sepResiduals)
149 absDiffSeparations = (abs(sepResiduals - np.median(sepResiduals)) * u.radian).to(u.marcsec)
150 afThreshhold = 100.0 - self.threshAF
151 ADx = np.percentile(absDiffSeparations, afThreshhold)
152 AFx = 100 * np.mean(np.abs(absDiffSeparations) > self.threshAD * u.marcsec) * u.percent
154 distanceParams = {
155 "rmsDistances": (np.array(rmsDistances) * u.radian).to(u.marcsec).value,
156 "separationResiduals": absDiffSeparations.value,
157 "AMx": AMx.value,
158 "ADx": ADx.value,
159 "AFx": AFx.value,
160 }
162 return distanceParams
165def matchVisitComputeDistance(visit_obj1, ra_obj1, dec_obj1, visit_obj2, ra_obj2, dec_obj2):
166 """Calculate obj1-obj2 distance for each visit in which both objects are
167 seen.
169 For each visit shared between visit_obj1 and visit_obj2, calculate the
170 spherical distance between the obj1 and obj2. visit_obj1 and visit_obj2 are
171 assumed to be unsorted. This function was borrowed from faro.
173 Parameters
174 ----------
175 visit_obj1 : scalar, list, or numpy.array of int or str
176 List of visits for object 1.
177 ra_obj1 : scalar, list, or numpy.array of float
178 List of RA in each visit for object 1. [radians]
179 dec_obj1 : scalar, list or numpy.array of float
180 List of Dec in each visit for object 1. [radians]
181 visit_obj2 : list or numpy.array of int or str
182 List of visits for object 2.
183 ra_obj2 : list or numpy.array of float
184 List of RA in each visit for object 2. [radians]
185 dec_obj2 : list or numpy.array of float
186 List of Dec in each visit for object 2. [radians]
187 Results
188 -------
189 list of float
190 spherical distances (in radians) for matching visits.
191 """
192 distances = []
193 visit_obj1_idx = np.argsort(visit_obj1)
194 visit_obj2_idx = np.argsort(visit_obj2)
195 j_raw = 0
196 j = visit_obj2_idx[j_raw]
197 for i in visit_obj1_idx:
198 while (visit_obj2[j] < visit_obj1[i]) and (j_raw < len(visit_obj2_idx) - 1):
199 j_raw += 1
200 j = visit_obj2_idx[j_raw]
201 if visit_obj2[j] == visit_obj1[i]:
202 if np.isfinite([ra_obj1[i], dec_obj1[i], ra_obj2[j], dec_obj2[j]]).all():
203 distances.append(sphDist(ra_obj1[i], dec_obj1[i], ra_obj2[j], dec_obj2[j]))
204 return distances
207def sphDist(ra_mean, dec_mean, ra, dec):
208 """Calculate distance on the surface of a unit sphere.
210 This function was borrowed from faro.
212 Parameters
213 ----------
214 ra_mean : `float`
215 Mean RA in radians.
216 dec_mean : `float`
217 Mean Dec in radians.
218 ra : `numpy.array` [`float`]
219 Array of RA in radians.
220 dec : `numpy.array` [`float`]
221 Array of Dec in radians.
222 Notes
223 -----
224 Uses the Haversine formula to preserve accuracy at small angles.
225 Law of cosines approach doesn't work well for the typically very small
226 differences that we're looking at here.
227 """
228 # Haversine
229 dra = ra - ra_mean
230 ddec = dec - dec_mean
231 a = np.square(np.sin(ddec / 2)) + np.cos(dec_mean) * np.cos(dec) * np.square(np.sin(dra / 2))
232 dist = 2 * np.arcsin(np.sqrt(a))
234 # This is what the law of cosines would look like
235 # dist = np.arccos(np.sin(dec1)*np.sin(dec2) +
236 # np.cos(dec1)*np.cos(dec2)*np.cos(ra1 - ra2))
238 # This will also work, but must run separately for each element
239 # whereas the numpy version will run on either scalars or arrays:
240 # sp1 = geom.SpherePoint(ra1, dec1, geom.radians)
241 # sp2 = geom.SpherePoint(ra2, dec2, geom.radians)
242 # return sp1.separation(sp2).asRadians()
244 return dist