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-12 12:23 -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",) 

22 

23import astropy.units as u 

24import numpy as np 

25import pandas as pd 

26from astropy.coordinates import SkyCoord 

27from lsst.pex.config import Field 

28 

29from ...interfaces import KeyedData, KeyedDataAction, KeyedDataSchema, Vector 

30 

31 

32class CalcRelativeDistances(KeyedDataAction): 

33 """Calculate relative distances in a matched catalog. 

34 

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 """ 

42 

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 ) 

53 

54 def getInputSchema(self) -> KeyedDataSchema: 

55 return ( 

56 (self.groupKey, Vector), 

57 (self.raKey, Vector), 

58 (self.decKey, Vector), 

59 (self.visitKey, Vector), 

60 ) 

61 

62 def __call__(self, data: KeyedData, **kwargs) -> KeyedData: 

63 """Run the calculation. 

64 

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) 

85 

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 ) 

94 

95 meanRa = df.groupby("groupKey")["coord_ra"].aggregate("mean") 

96 meanDec = df.groupby("groupKey")["coord_dec"].aggregate("mean") 

97 

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] 

103 

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 

111 

112 object_srcs = df.loc[df["groupKey"] == meanRa.index[id]] 

113 

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) 

121 

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 

127 

128 separations = matchVisitComputeDistance( 

129 object_visits, object_ras, object_decs, match_visits, match_ras, match_decs 

130 ) 

131 

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)) 

137 

138 if len(rmsDistances) == 0: 

139 AMx = np.nan * u.marcsec 

140 else: 

141 AMx = (np.median(rmsDistances) * u.radian).to(u.marcsec) 

142 

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 

153 

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 } 

161 

162 return distanceParams 

163 

164 

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. 

168 

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. 

172 

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 

205 

206 

207def sphDist(ra_mean, dec_mean, ra, dec): 

208 """Calculate distance on the surface of a unit sphere. 

209 

210 This function was borrowed from faro. 

211 

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)) 

233 

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)) 

237 

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() 

243 

244 return dist