lsst.meas.algorithms  18.0.0-5-ga38416e7+7
loadReferenceObjects.py
Go to the documentation of this file.
1 #
2 # LSST Data Management System
3 #
4 # Copyright 2008-2017 AURA/LSST.
5 #
6 # This product includes software developed by the
7 # LSST Project (http://www.lsst.org/).
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 LSST License Statement and
20 # the GNU General Public License along with this program. If not,
21 # see <https://www.lsstcorp.org/LegalNotices/>.
22 #
23 
24 __all__ = ["getRefFluxField", "getRefFluxKeys", "LoadReferenceObjectsTask", "LoadReferenceObjectsConfig",
25  "ReferenceObjectLoader"]
26 
27 import abc
28 import itertools
29 
30 import astropy.time
31 import astropy.units
32 import numpy
33 
34 import lsst.geom
35 import lsst.afw.table as afwTable
36 import lsst.pex.config as pexConfig
37 import lsst.pex.exceptions as pexExceptions
38 import lsst.pipe.base as pipeBase
39 import lsst.pex.exceptions as pexExcept
40 import lsst.log
41 from lsst import geom
42 from lsst import sphgeom
43 from lsst.daf.base import PropertyList
44 
45 
46 def isOldFluxField(name, units):
47  """Return True if this name/units combination corresponds to an
48  "old-style" reference catalog flux field.
49  """
50  unitsCheck = units != 'nJy' # (units == 'Jy' or units == '' or units == '?')
51  isFlux = name.endswith('_flux')
52  isFluxSigma = name.endswith('_fluxSigma')
53  isFluxErr = name.endswith('_fluxErr')
54  return (isFlux or isFluxSigma or isFluxErr) and unitsCheck
55 
56 
58  """Return True if the units of all flux and fluxErr are correct (nJy).
59  """
60  for field in schema:
61  if isOldFluxField(field.field.getName(), field.field.getUnits()):
62  return False
63  return True
64 
65 
67  """"Return the format version stored in a reference catalog header.
68 
69  Parameters
70  ----------
71  refCat : `lsst.afw.table.SimpleCatalog`
72  Reference catalog to inspect.
73 
74  Returns
75  -------
76  version : `int` or `None`
77  Format version integer, or `None` if the catalog has no metadata
78  or the metadata does not include a "REFCAT_FORMAT_VERSION" key.
79  """
80  md = refCat.getMetadata()
81  if md is None:
82  return None
83  try:
84  return md.getScalar("REFCAT_FORMAT_VERSION")
85  except KeyError:
86  return None
87 
88 
89 def convertToNanojansky(catalog, log, doConvert=True):
90  """Convert fluxes in a catalog from jansky to nanojansky.
91 
92  Parameters
93  ----------
94  catalog : `lsst.afw.table.SimpleCatalog`
95  The catalog to convert.
96  log : `lsst.log.Log`
97  Log to send messages to.
98  doConvert : `bool`, optional
99  Return a converted catalog, or just identify the fields that need to be converted?
100  This supports the "write=False" mode of `bin/convert_to_nJy.py`.
101 
102  Returns
103  -------
104  catalog : `lsst.afw.table.SimpleCatalog` or None
105  The converted catalog, or None if ``doConvert`` is False.
106 
107  Notes
108  -----
109  Support for old units in reference catalogs will be removed after the
110  release of late calendar year 2019.
111  Use `meas_algorithms/bin/convert_to_nJy.py` to update your reference catalog.
112  """
113  # Do not share the AliasMap: for refcats, that gets created when the
114  # catalog is read from disk and should not be propagated.
115  mapper = lsst.afw.table.SchemaMapper(catalog.schema, shareAliasMap=False)
116  mapper.addMinimalSchema(lsst.afw.table.SimpleTable.makeMinimalSchema())
117  input_fields = []
118  output_fields = []
119  for field in catalog.schema:
120  oldName = field.field.getName()
121  oldUnits = field.field.getUnits()
122  if isOldFluxField(oldName, oldUnits):
123  units = 'nJy'
124  # remap Sigma flux fields to Err, so we can drop the alias
125  if oldName.endswith('_fluxSigma'):
126  name = oldName.replace('_fluxSigma', '_fluxErr')
127  else:
128  name = oldName
129  newField = lsst.afw.table.Field[field.dtype](name, field.field.getDoc(), units)
130  mapper.addMapping(field.getKey(), newField)
131  input_fields.append(field.field)
132  output_fields.append(newField)
133  else:
134  mapper.addMapping(field.getKey())
135 
136  fluxFieldsStr = '; '.join("(%s, '%s')" % (field.getName(), field.getUnits()) for field in input_fields)
137 
138  if doConvert:
139  newSchema = mapper.getOutputSchema()
140  output = lsst.afw.table.SimpleCatalog(newSchema)
141  output.extend(catalog, mapper=mapper)
142  for field in output_fields:
143  output[field.getName()] *= 1e9
144  log.info(f"Converted refcat flux fields to nJy (name, units): {fluxFieldsStr}")
145  return output
146  else:
147  log.info(f"Found old-style refcat flux fields (name, units): {fluxFieldsStr}")
148  return None
149 
150 
152  """This is a private helper class which filters catalogs by
153  row based on the row being inside the region used to initialize
154  the class.
155 
156  Parameters
157  ----------
158  region : `lsst.sphgeom.Region`
159  The spatial region which all objects should lie within
160  """
161  def __init__(self, region):
162  self.region = region
163 
164  def __call__(self, refCat, catRegion):
165  """This call method on an instance of this class takes in a reference
166  catalog, and the region from which the catalog was generated.
167 
168  If the catalog region is entirely contained within the region used to
169  initialize this class, then all the entries in the catalog must be
170  within the region and so the whole catalog is returned.
171 
172  If the catalog region is not entirely contained, then the location for
173  each record is tested against the region used to initialize the class.
174  Records which fall inside this region are added to a new catalog, and
175  this catalog is then returned.
176 
177  Parameters
178  ---------
179  refCat : `lsst.afw.table.SourceCatalog`
180  SourceCatalog to be filtered.
181  catRegion : `lsst.sphgeom.Region`
182  Region in which the catalog was created
183  """
184  if catRegion.isWithin(self.region):
185  # no filtering needed, region completely contains refcat
186  return refCat
187 
188  filteredRefCat = type(refCat)(refCat.table)
189  for record in refCat:
190  if self.region.contains(record.getCoord().getVector()):
191  filteredRefCat.append(record)
192  return filteredRefCat
193 
194 
196  """ This class facilitates loading reference catalogs with gen 3 middleware
197 
198  The middleware preflight solver will create a list of datarefs that may
199  possibly overlap a given region. These datarefs are then used to construct
200  and instance of this class. The class instance should then be passed into
201  a task which needs reference catalogs. These tasks should then determine
202  the exact region of the sky reference catalogs will be loaded for, and
203  call a corresponding method to load the reference objects.
204  """
205  def __init__(self, dataIds, butler, config, log=None):
206  """ Constructs an instance of ReferenceObjectLoader
207 
208  Parameters
209  ----------
210  dataIds : iterable of `lsst.daf.butler.DataIds`
211  An iterable object of DataSetRefs which point to reference catalogs
212  in a gen 3 repository
213  bulter : `lsst.daf.bulter.Butler`
214  A gen 3 butler instance
215  log : `lsst.log.Log`
216  Logger object used to write out messages. If `None` (default) the default
217  lsst logger will be used
218 
219  """
220  self.dataIds = dataIds
221  self.butler = butler
223  self.config = config
224 
225  @staticmethod
226  def _makeBoxRegion(BBox, wcs, BBoxPadding):
227  outerLocalBBox = geom.Box2D(BBox)
228  innerLocalBBox = geom.Box2D(BBox)
229 
230  # Grow the bounding box to make sure the spherical geometry bbox will contain
231  # the same region, as non-padded boxes may contain different regions because of optical distortion.
232  # Also create an inner region that is sure to be inside the bbox
233  outerLocalBBox.grow(BBoxPadding)
234  innerLocalBBox.grow(-1*BBoxPadding)
235 
236  # Handle the fact that the inner bounding box shrunk to a zero sized region in at least one
237  # dimension, in which case all reference catalogs must be checked fully against the input
238  # bounding box
239  if innerLocalBBox.getDimensions() == geom.Extent2D(0, 0):
240  innerSkyRegion = sphgeom.Box()
241  else:
242  innerBoxCorners = innerLocalBBox.getCorners()
243  innerSphCorners = [wcs.pixelToSky(corner).getVector() for corner in innerBoxCorners]
244 
245  innerSkyRegion = sphgeom.ConvexPolygon(innerSphCorners)
246 
247  # Convert the corners of the box to sky coordinates
248  outerBoxCorners = outerLocalBBox.getCorners()
249  outerSphCorners = [wcs.pixelToSky(corner).getVector() for corner in outerBoxCorners]
250 
251  outerSkyRegion = sphgeom.ConvexPolygon(outerSphCorners)
252 
253  return innerSkyRegion, outerSkyRegion, innerSphCorners, outerSphCorners
254 
255  def loadPixelBox(self, bbox, wcs, filterName=None, epoch=None, photoCalib=None, bboxPadding=100):
256  """Load reference objects that are within a pixel-based rectangular region
257 
258  This algorithm works by creating a spherical box whose corners correspond
259  to the WCS converted corners of the input bounding box (possibly padded).
260  It then defines a filtering function which will look at a reference
261  objects pixel position and accept objects that lie within the specified
262  bounding box.
263 
264  The spherical box region and filtering function are passed to the generic
265  loadRegion method which will load and filter the reference objects from
266  the datastore and return a single catalog containing all reference objects
267 
268  Parameters
269  ----------
270  bbox : `lsst.geom.box2I`
271  Box which bounds a region in pixel space
272  wcs : `lsst.afw.geom.SkyWcs`
273  Wcs object defining the pixel to sky (and inverse) transform for the space
274  of pixels of the supplied bbox
275  filterName : `str`
276  Name of camera filter, or None or blank for the default filter
277  epoch : `astropy.time.Time` (optional)
278  Epoch to which to correct proper motion and parallax,
279  or None to not apply such corrections.
280  photoCalib : None
281  Deprecated and ignored, only included for api compatibility
282  bboxPadding : `int`
283  Number describing how much to pad the input bbox by (in pixels), defaults
284  to 100. This parameter is necessary because optical distortions in telescopes
285  can cause a rectangular pixel grid to map into a non "rectangular" spherical
286  region in sky coordinates. This padding is used to create a spherical
287  "rectangle", which will for sure enclose the input box. This padding is only
288  used to determine if the reference catalog for a sky patch will be loaded from
289  the data store, this function will filter out objects which lie within the
290  padded region but fall outside the input bounding box region.
291 
292  Returns
293  -------
294  referenceCatalog : `lsst.afw.table.SimpleCatalog`
295  Catalog containing reference objects inside the specified bounding box
296 
297  Raises
298  ------
299  `lsst.pex.exception.RuntimeError`
300  Raised if no reference catalogs could be found for the specified region
301 
302  `lsst.pex.exception.TypeError`
303  Raised if the loaded reference catalogs do not have matching schemas
304  """
305  innerSkyRegion, outerSkyRegion, _, _ = self._makeBoxRegion(bbox, wcs, bboxPadding)
306 
307  def _filterFunction(refCat, region):
308  # Add columns to the reference catalog relating to center positions and use afwTable
309  # to populate those columns
310  refCat = self.remapReferenceCatalogSchema(refCat, position=True)
311  afwTable.updateRefCentroids(wcs, refCat)
312  # no need to filter the catalog if it is sure that it is entirely contained in the region
313  # defined by given bbox
314  if innerSkyRegion.contains(region):
315  return refCat
316  # Create a new reference catalog, and populate it with records which fall inside the bbox
317  filteredRefCat = type(refCat)(refCat.table)
318  centroidKey = afwTable.Point2DKey(refCat.schema['centroid'])
319  for record in refCat:
320  pixCoords = record[centroidKey]
321  if bbox.contains(geom.Point2I(pixCoords)):
322  filteredRefCat.append(record)
323  return filteredRefCat
324  return self.loadRegion(outerSkyRegion, filtFunc=_filterFunction, epoch=epoch, filterName=filterName)
325 
326  def loadRegion(self, region, filtFunc=None, filterName=None, epoch=None):
327  """ Load reference objects within a specified region
328 
329  This function loads the DataIds used to construct an instance of this class
330  which intersect or are contained within the specified region. The reference
331  catalogs which intersect but are not fully contained within the input region are
332  further filtered by the specified filter function. This function will return a
333  single source catalog containing all reference objects inside the specified region.
334 
335  Parameters
336  ----------
337  region : `lsst.sphgeom.Region`
338  This can be any type that is derived from `lsst.sphgeom.region` and should
339  define the spatial region for which reference objects are to be loaded.
340  filtFunc : callable
341  This optional parameter should be a callable object that takes a reference
342  catalog and its corresponding region as parameters, filters the catalog by
343  some criteria and returns the filtered reference catalog. If the value is
344  left as the default (None) than an internal filter function is used which
345  filters according to if a reference object falls within the input region.
346  filterName : `str`
347  Name of camera filter, or None or blank for the default filter
348  epoch : `astropy.time.Time` (optional)
349  Epoch to which to correct proper motion and parallax,
350  or None to not apply such corrections.
351 
352  Returns
353  -------
354  referenceCatalog : `lsst.afw.table.SourceCatalog`
355  Catalog containing reference objects which intersect the input region,
356  filtered by the specified filter function
357 
358  Raises
359  ------
360  `lsst.pex.exception.RuntimeError`
361  Raised if no reference catalogs could be found for the specified region
362 
363  `lsst.pex.exception.TypeError`
364  Raised if the loaded reference catalogs do not have matching schemas
365 
366  """
367  regionBounding = region.getBoundingBox()
368  self.log.info("Loading reference objects from region bounded by {}, {} lat lon".format(
369  regionBounding.getLat(), regionBounding.getLon()))
370  if filtFunc is None:
371  filtFunc = _FilterCatalog(region)
372  # filter out all the regions supplied by the constructor that do not overlap
373  overlapList = []
374  for dataId in self.dataIds:
375  # SphGeom supports some objects intersecting others, but is not symmetric,
376  # try the intersect operation in both directions
377  try:
378  intersects = dataId.region.intersects(region)
379  except TypeError:
380  intersects = region.intersects(dataId.region)
381 
382  if intersects:
383  overlapList.append(dataId)
384 
385  if len(overlapList) == 0:
386  raise pexExceptions.RuntimeError("No reference tables could be found for input region")
387 
388  firstCat = self.butler.get('ref_cat', overlapList[0])
389  refCat = filtFunc(firstCat, overlapList[0].region)
390  trimmedAmount = len(firstCat) - len(refCat)
391 
392  # Load in the remaining catalogs
393  for dataId in overlapList[1:]:
394  tmpCat = self.butler.get('ref_cat', dataId)
395 
396  if tmpCat.schema != firstCat.schema:
397  raise pexExceptions.TypeError("Reference catalogs have mismatching schemas")
398 
399  filteredCat = filtFunc(tmpCat, dataId.region)
400  refCat.extend(filteredCat)
401  trimmedAmount += len(tmpCat) - len(filteredCat)
402 
403  self.log.debug(f"Trimmed {trimmedAmount} out of region objects, leaving {len(refCat)}")
404  self.log.info(f"Loaded {len(refCat)} reference objects")
405 
406  if epoch is not None and "pm_ra" in refCat.schema:
407  # check for a catalog in a non-standard format
408  if isinstance(refCat.schema["pm_ra"].asKey(), lsst.afw.table.KeyAngle):
409  applyProperMotionsImpl(self.log, refCat, epoch)
410  else:
411  self.log.warn("Catalog pm_ra field is not an Angle; not applying proper motion")
412 
413  # Verify the schema is in the correct units and has the correct version; automatically convert
414  # it with a warning if this is not the case.
415  if not hasNanojanskyFluxUnits(refCat.schema) or not getFormatVersionFromRefCat(refCat) >= 1:
416  self.log.warn("Found version 0 reference catalog with old style units in schema.")
417  self.log.warn("run `meas_algorithms/bin/convert_refcat_to_nJy.py` to convert fluxes to nJy.")
418  self.log.warn("See RFC-575 for more details.")
419  refCat = convertToNanojansky(refCat, self.log)
420 
421  expandedCat = self.remapReferenceCatalogSchema(refCat, position=True)
422 
423  # Add flux aliases
424  self.addFluxAliases(expandedCat, self.config.defaultFilter, self.config.filterMap)
425 
426  # Ensure that the returned reference catalog is continuous in memory
427  if not expandedCat.isContiguous():
428  expandedCat = refCat.copy(deep=True)
429 
430  fluxField = getRefFluxField(schema=expandedCat.schema, filterName=filterName)
431  return pipeBase.Struct(refCat=expandedCat, fluxField=fluxField)
432 
433  def loadSkyCircle(self, ctrCoord, radius, filterName=None, epoch=None):
434  """Load reference objects that lie within a circular region on the sky
435 
436  This method constructs a circular region from an input center and angular radius,
437  loads reference catalogs which are contained in or intersect the circle, and
438  filters reference catalogs which intersect down to objects which lie within
439  the defined circle.
440 
441  Parameters
442  ----------
443  ctrCoord : `lsst.geom.SpherePoint`
444  Point defining the center of the circular region
445  radius : `lsst.geom.Angle`
446  Defines the angular radius of the circular region
447  filterName : `str`
448  Name of camera filter, or None or blank for the default filter
449  epoch : `astropy.time.Time` (optional)
450  Epoch to which to correct proper motion and parallax,
451  or None to not apply such corrections.
452 
453  Returns
454  -------
455  referenceCatalog : `lsst.afw.table.SourceCatalog`
456  Catalog containing reference objects inside the specified bounding box
457 
458  Raises
459  ------
460  `lsst.pex.exception.RuntimeError`
461  Raised if no reference catalogs could be found for the specified region
462 
463  `lsst.pex.exception.TypeError`
464  Raised if the loaded reference catalogs do not have matching schemas
465 
466  """
467  centerVector = ctrCoord.getVector()
468  sphRadius = sphgeom.Angle(radius.asRadians())
469  circularRegion = sphgeom.Circle(centerVector, sphRadius)
470  return self.loadRegion(circularRegion, filterName=filterName, epoch=None)
471 
472  def joinMatchListWithCatalog(self, matchCat, sourceCat):
473  """Relink an unpersisted match list to sources and reference
474  objects.
475 
476  A match list is persisted and unpersisted as a catalog of IDs
477  produced by afw.table.packMatches(), with match metadata
478  (as returned by the astrometry tasks) in the catalog's metadata
479  attribute. This method converts such a match catalog into a match
480  list, with links to source records and reference object records.
481 
482  Parameters
483  ----------
484  matchCat : `lsst.afw.table.BaseCatalog`
485  Unpersisted packed match list.
486  ``matchCat.table.getMetadata()`` must contain match metadata,
487  as returned by the astrometry tasks.
488  sourceCat : `lsst.afw.table.SourceCatalog`
489  Source catalog. As a side effect, the catalog will be sorted
490  by ID.
491 
492  Returns
493  -------
494  matchList : `lsst.afw.table.ReferenceMatchVector`
495  Match list.
496  """
497  return joinMatchListWithCatalogImpl(self, matchCat, sourceCat)
498 
499  @classmethod
500  def getMetadataBox(cls, bbox, wcs, filterName=None, photoCalib=None, epoch=None, bboxPadding=100):
501  """Return metadata about the load
502 
503  This metadata is used for reloading the catalog (e.g., for
504  reconstituting a normalised match list.)
505 
506  Parameters
507  ----------
508  bbox : `lsst.geom.Box2I`
509  Bounding bos for the pixels
510  wcs : `lsst.afw.geom.SkyWcs
511  WCS object
512  filterName : `str` or None
513  filterName of the camera filter, or None or blank for the default filter
514  photoCalib : None
515  Deprecated, only included for api compatibility
516  epoch : `astropy.time.Time` (optional)
517  Epoch to which to correct proper motion and parallax,
518  or None to not apply such corrections.
519  bboxPadding : `int`
520  Number describing how much to pad the input bbox by (in pixels), defaults
521  to 100. This parameter is necessary because optical distortions in telescopes
522  can cause a rectangular pixel grid to map into a non "rectangular" spherical
523  region in sky coordinates. This padding is used to create a spherical
524  "rectangle", which will for sure enclose the input box. This padding is only
525  used to determine if the reference catalog for a sky patch will be loaded from
526  the data store, this function will filter out objects which lie within the
527  padded region but fall outside the input bounding box region.
528  Returns
529  -------
530  md : `lsst.daf.base.PropertyList`
531  """
532  _, _, innerCorners, outerCorners = cls._makeBoxRegion(bbox, wcs, bboxPadding)
533  md = PropertyList()
534  for box, corners in zip(("INNER", "OUTER"), (innerCorners, outerCorners)):
535  for (name, corner) in zip(("UPPER_LEFT", "UPPER_RIGHT", "LOWER_LEFT", "LOWER_RIGHT"),
536  corners):
537  md.add(f"{box}_{name}_RA", geom.SpherePoint(corner).getRa().asDegrees(), f"{box}_corner")
538  md.add(f"{box}_{name}_DEC", geom.SpherePoint(corner).getDec().asDegrees(), f"{box}_corner")
539  md.add("SMATCHV", 1, 'SourceMatchVector version number')
540  filterName = "UNKNOWN" if filterName is None else str(filterName)
541  md.add('FILTER', filterName, 'filter name for photometric data')
542  # Calling str on the epoch is a workaround for code that never worked anyway and was not used
543  # see DM-17438
544  md.add('EPOCH', "NONE" if epoch is None else str(epoch), 'Epoch (TAI MJD) for catalog')
545  return md
546 
547  @staticmethod
548  def getMetadataCircle(coord, radius, filterName, photoCalib=None, epoch=None):
549  """Return metadata about the load
550 
551  This metadata is used for reloading the catalog (e.g. for reconstituting
552  a normalized match list.)
553 
554  Parameters
555  ----------
556  coord : `lsst.geom.SpherePoint`
557  ICRS center of a circle
558  radius : `lsst.geom.angle`
559  radius of a circle
560  filterName : `str` or None
561  filterName of the camera filter, or None or blank for the default filter
562  photoCalib : None
563  Deprecated, only included for api compatibility
564  epoch : `astropy.time.Time` (optional)
565  Epoch to which to correct proper motion and parallax,
566  or None to not apply such corrections.
567 
568  Returns
569  -------
570  md : `lsst.daf.base.PropertyList`
571  """
572  md = PropertyList()
573  md.add('RA', coord.getRa().asDegrees(), 'field center in degrees')
574  md.add('DEC', coord.getDec().asDegrees(), 'field center in degrees')
575  md.add('RADIUS', radius.asDegrees(), 'field radius in degrees, minimum')
576  md.add('SMATCHV', 1, 'SourceMatchVector version number')
577  filterName = "UNKNOWN" if filterName is None else str(filterName)
578  md.add('FILTER', filterName, 'filter name for photometric data')
579  md.add('EPOCH', "NONE" if epoch is None else epoch, 'Epoch (TAI MJD) for catalog')
580  return md
581 
582  @staticmethod
583  def addFluxAliases(refCat, defaultFilter, filterReferenceMap):
584  """This function creates a new catalog containing the information of the input refCat
585  as well as added flux columns and aliases between camera and reference flux.
586 
587  Parameters
588  ----------
589  refCat : `lsst.afw.table.SimpleCatalog`
590  Catalog of reference objects
591  defaultFilter : `str`
592  Name of the default reference filter
593  filterReferenceMap : `dict` of `str`
594  Dictionary with keys corresponding to a filter name, and values which
595  correspond to the name of the reference filter.
596 
597  Returns
598  -------
599  refCat : `lsst.afw.table.SimpleCatalog`
600  Reference catalog with columns added to track reference filters
601 
602  Raises
603  ------
604  `RuntimeError`
605  If specified reference filter name is not a filter specifed as a key in the
606  reference filter map.
607  """
608  refCat = ReferenceObjectLoader.remapReferenceCatalogSchema(refCat,
609  filterNameList=filterReferenceMap.keys())
610  aliasMap = refCat.schema.getAliasMap()
611 
612  if filterReferenceMap is None:
613  filterReferenceMap = {}
614  for filterName, refFilterName in itertools.chain([(None, defaultFilter)],
615  filterReferenceMap.items()):
616  if refFilterName:
617  camFluxName = filterName + "_camFlux" if filterName is not None else "camFlux"
618  refFluxName = refFilterName + "_flux"
619  if refFluxName not in refCat.schema:
620  raise RuntimeError("Unknown reference filter %s" % (refFluxName,))
621  aliasMap.set(camFluxName, refFluxName)
622 
623  refFluxErrName = refFluxName + "Err"
624  camFluxErrName = camFluxName + "Err"
625  aliasMap.set(camFluxErrName, refFluxErrName)
626 
627  return refCat
628 
629  @staticmethod
630  def remapReferenceCatalogSchema(refCat, *, filterNameList=None, position=False, photometric=False):
631  """This function takes in a reference catalog and creates a new catalog with additional
632  columns defined the remaining function arguments.
633 
634  Parameters
635  ----------
636  refCat : `lsst.afw.table.SimpleCatalog`
637  Reference catalog to map to new catalog
638 
639  Returns
640  -------
641  expandedCat : `lsst.afw.table.SimpleCatalog`
642  Deep copy of input reference catalog with additional columns added
643  """
644  mapper = afwTable.SchemaMapper(refCat.schema, True)
645  mapper.addMinimalSchema(refCat.schema, True)
646  mapper.editOutputSchema().disconnectAliases()
647  if filterNameList:
648  for filterName in filterNameList:
649  mapper.editOutputSchema().addField(f"{filterName}_flux",
650  type=numpy.float64,
651  doc=f"flux in filter {filterName}",
652  units="Jy"
653  )
654  mapper.editOutputSchema().addField(f"{filterName}_fluxErr",
655  type=numpy.float64,
656  doc=f"flux uncertanty in filter {filterName}",
657  units="Jy"
658  )
659 
660  if position:
661  mapper.editOutputSchema().addField("centroid_x", type=float, doReplace=True)
662  mapper.editOutputSchema().addField("centroid_y", type=float, doReplace=True)
663  mapper.editOutputSchema().addField("hasCentroid", type="Flag", doReplace=True)
664  mapper.editOutputSchema().getAliasMap().set("slot_Centroid", "centroid")
665 
666  if photometric:
667  mapper.editOutputSchema().addField("photometric",
668  type="Flag",
669  doc="set if the object can be used for photometric" +
670  "calibration",
671  )
672  mapper.editOutputSchema().addField("resolved",
673  type="Flag",
674  doc="set if the object is spatially resolved"
675  )
676  mapper.editOutputSchema().addField("variable",
677  type="Flag",
678  doc="set if the object has variable brightness"
679  )
680 
681  expandedCat = afwTable.SimpleCatalog(mapper.getOutputSchema())
682  expandedCat.setMetadata(refCat.getMetadata())
683  expandedCat.extend(refCat, mapper=mapper)
684 
685  return expandedCat
686 
687 
688 def getRefFluxField(schema, filterName=None):
689  """Get the name of a flux field from a schema.
690 
691  if filterName is specified:
692  return *filterName*_camFlux if present
693  else return *filterName*_flux if present (camera filter name matches reference filter name)
694  else throw RuntimeError
695  else:
696  return camFlux, if present,
697  else throw RuntimeError
698 
699  Parameters
700  ----------
701  schema : `lsst.afw.table.Schema`
702  Reference catalog schema.
703  filterName : `str`
704  Name of camera filter.
705 
706  Returns
707  -------
708  fluxFieldName : `str`
709  Name of flux field.
710 
711  Raises
712  ------
713  RuntimeError
714  If an appropriate field is not found.
715  """
716  if not isinstance(schema, afwTable.Schema):
717  raise RuntimeError("schema=%s is not a schema" % (schema,))
718  if filterName:
719  fluxFieldList = [filterName + "_camFlux", filterName + "_flux"]
720  else:
721  fluxFieldList = ["camFlux"]
722  for fluxField in fluxFieldList:
723  if fluxField in schema:
724  return fluxField
725 
726  raise RuntimeError("Could not find flux field(s) %s" % (", ".join(fluxFieldList)))
727 
728 
729 def getRefFluxKeys(schema, filterName=None):
730  """Return keys for flux and flux error.
731 
732  Parameters
733  ----------
734  schema : `lsst.afw.table.Schema`
735  Reference catalog schema.
736  filterName : `str`
737  Name of camera filter.
738 
739  Returns
740  -------
741  keys : `tuple` of (`lsst.afw.table.Key`, `lsst.afw.table.Key`)
742  Two keys:
743 
744  - flux key
745  - flux error key, if present, else None
746 
747  Raises
748  ------
749  RuntimeError
750  If flux field not found.
751  """
752  fluxField = getRefFluxField(schema, filterName)
753  fluxErrField = fluxField + "Err"
754  fluxKey = schema[fluxField].asKey()
755  try:
756  fluxErrKey = schema[fluxErrField].asKey()
757  except Exception:
758  fluxErrKey = None
759  return (fluxKey, fluxErrKey)
760 
761 
762 class LoadReferenceObjectsConfig(pexConfig.Config):
763  pixelMargin = pexConfig.RangeField(
764  doc="Padding to add to 4 all edges of the bounding box (pixels)",
765  dtype=int,
766  default=300,
767  min=0,
768  )
769  defaultFilter = pexConfig.Field(
770  doc="Default reference catalog filter to use if filter not specified in exposure; "
771  "if blank then filter must be specified in exposure",
772  dtype=str,
773  default="",
774  )
775  filterMap = pexConfig.DictField(
776  doc="Mapping of camera filter name: reference catalog filter name; "
777  "each reference filter must exist",
778  keytype=str,
779  itemtype=str,
780  default={},
781  )
782  requireProperMotion = pexConfig.Field(
783  doc="Require that the fields needed to correct proper motion "
784  "(epoch, pm_ra and pm_dec) are present?",
785  dtype=bool,
786  default=False,
787  )
788 
789 # The following comment block adds a link to this task from the Task Documentation page.
790 
796 
797 
798 class LoadReferenceObjectsTask(pipeBase.Task, metaclass=abc.ABCMeta):
799  r"""!Abstract base class to load objects from reference catalogs
800 
801  @anchor LoadReferenceObjectsTask_
802 
803  @section meas_algorithms_loadReferenceObjects_Contents Contents
804 
805  - @ref meas_algorithms_loadReferenceObjects_Purpose
806  - @ref meas_algorithms_loadReferenceObjects_Initialize
807  - @ref meas_algorithms_loadReferenceObjects_IO
808  - @ref meas_algorithms_loadReferenceObjects_Schema
809  - @ref meas_algorithms_loadReferenceObjects_Config
810 
811  @section meas_algorithms_loadReferenceObjects_Purpose Description
812 
813  Abstract base class for tasks that load objects from a reference catalog
814  in a particular region of the sky.
815 
816  Implementations must subclass this class, override the loadSkyCircle method,
817  and will typically override the value of ConfigClass with a task-specific config class.
818 
819  @section meas_algorithms_loadReferenceObjects_Initialize Task initialisation
820 
821  @copydoc \_\_init\_\_
822 
823  @section meas_algorithms_loadReferenceObjects_IO Invoking the Task
824 
825  @copydoc loadPixelBox
826 
827  @section meas_algorithms_loadReferenceObjects_Schema Schema of the reference object catalog
828 
829  Reference object catalogs are instances of lsst.afw.table.SimpleCatalog with the following schema
830  (other fields may also be present).
831  The units use astropy quantity conventions, so a 2 suffix means squared.
832  See also makeMinimalSchema.
833  - coord: ICRS position of star on sky (an lsst.geom.SpherePoint)
834  - centroid: position of star on an exposure, if relevant (an lsst.afw.Point2D)
835  - hasCentroid: is centroid usable? (a Flag)
836  - *referenceFilterName*_flux: brightness in the specified reference catalog filter (nJy)
837  Note: you can use astropy.units to convert from AB Magnitude to nJy:
838  `u.Magnitude(value, u.ABmag).to_value(u.nJy)`
839  - *referenceFilterName*_fluxErr (optional): brightness standard deviation (nJy);
840  omitted if no data is available; possibly nan if data is available for some objects but not others
841  - camFlux: brightness in default camera filter (nJy); omitted if defaultFilter not specified
842  - camFluxErr: brightness standard deviation for default camera filter;
843  omitted if defaultFilter not specified or standard deviation not available that filter
844  - *cameraFilterName*_camFlux: brightness in specified camera filter (nJy)
845  - *cameraFilterName*_camFluxErr (optional): brightness standard deviation
846  in specified camera filter (nJy); omitted if no data is available;
847  possibly nan if data is available for some objects but not others
848  - photometric (optional): is the object usable for photometric calibration? (a Flag)
849  - resolved (optional): is the object spatially resolved? (a Flag)
850  - variable (optional): does the object have variable brightness? (a Flag)
851  - coord_raErr: uncertainty in `coord` along the direction of right ascension (radian, an Angle)
852  = uncertainty in ra * cos(dec); nan if unknown
853  - coord_decErr: uncertainty in `coord` along the direction of declination (radian, an Angle);
854  nan if unknown
855 
856  The following are optional; fields should only be present if the
857  information is available for at least some objects.
858  Numeric values are `nan` if unknown:
859  - epoch: date of observation as TAI MJD (day)
860 
861  - pm_ra: proper motion along the direction of right ascension (rad/year, an Angle) = dra/dt * cos(dec)
862  - pm_dec: proper motion along the direction of declination (rad/year, and Angle)
863  - pm_raErr: uncertainty in `pm_ra` (rad/year)
864  - pm_decErr: uncertainty in `pm_dec` (rad/year)
865  - pm_ra_dec_Cov: covariance between pm_ra and pm_dec (rad2/year2)
866  - pm_flag: set if proper motion, error or covariance is bad
867 
868  - parallax: parallax (rad, an Angle)
869  - parallaxErr: uncertainty in `parallax` (rad)
870  - parallax_flag: set if parallax value or parallaxErr is bad
871 
872  - coord_ra_pm_ra_Cov: covariance between coord_ra and pm_ra (rad2/year)
873  - coord_ra_pm_dec_Cov: covariance between coord_ra and pm_dec (rad2/year)
874  - coord_ra_parallax_Cov: covariance between coord_ra and parallax (rad2/year)
875  - coord_dec_pm_ra_Cov: covariance between coord_dec and pm_ra (rad2/year)
876  - coord_dec_pm_dec_Cov: covariance between coord_dec and pm_dec (rad2/year)
877  - coord_dec_parallax_Cov: covariance between coord_dec and parallax (rad2/year)
878  - pm_ra_parallax_Cov: covariance between pm_ra and parallax (rad2/year)
879  - pm_dec_parallax_Cov: covariance between pm_dec and parallax (rad2/year)
880 
881  @section meas_algorithms_loadReferenceObjects_Config Configuration parameters
882 
883  See @ref LoadReferenceObjectsConfig for a base set of configuration parameters.
884  Most subclasses will add configuration variables.
885  """
886  ConfigClass = LoadReferenceObjectsConfig
887  _DefaultName = "LoadReferenceObjects"
888 
889  def __init__(self, butler=None, *args, **kwargs):
890  """Construct a LoadReferenceObjectsTask
891 
892  Parameters
893  ----------
894  butler : `lsst.daf.persistence.Butler`
895  Data butler, for access reference catalogs.
896  """
897  pipeBase.Task.__init__(self, *args, **kwargs)
898  self.butler = butler
899 
900  @pipeBase.timeMethod
901  def loadPixelBox(self, bbox, wcs, filterName=None, photoCalib=None, epoch=None):
902  """Load reference objects that overlap a rectangular pixel region.
903 
904  Parameters
905  ----------
906  bbox : `lsst.geom.Box2I` or `lsst.geom.Box2D`
907  Bounding box for pixels.
908  wcs : `lsst.afw.geom.SkyWcs`
909  WCS; used to convert pixel positions to sky coordinates
910  and vice-versa.
911  filterName : `str`
912  Name of filter, or `None` or `""` for the default filter.
913  This is used for flux values in case we have flux limits
914  (which are not yet implemented).
915  photoCalib : `lsst.afw.image.PhotoCalib` (optional)
916  Calibration, or `None` if unknown.
917  epoch : `astropy.time.Time` (optional)
918  Epoch to which to correct proper motion and parallax,
919  or None to not apply such corrections.
920 
921  Returns
922  -------
923  results : `lsst.pipe.base.Struct`
924  A Struct containing the following fields:
925  refCat : `lsst.afw.catalog.SimpleCatalog`
926  A catalog of reference objects with the standard
927  schema, as documented in the main doc string for
928  `LoadReferenceObjects`.
929  The catalog is guaranteed to be contiguous.
930  fluxField : `str`
931  Name of flux field for specified `filterName`.
932 
933  Notes
934  -----
935  The search algorithm works by searching in a region in sky
936  coordinates whose center is the center of the bbox and radius
937  is large enough to just include all 4 corners of the bbox.
938  Stars that lie outside the bbox are then trimmed from the list.
939  """
940  circle = self._calculateCircle(bbox, wcs)
941 
942  # find objects in circle
943  self.log.info("Loading reference objects using center %s and radius %s deg" %
944  (circle.coord, circle.radius.asDegrees()))
945  loadRes = self.loadSkyCircle(circle.coord, circle.radius, filterName, centroids=True)
946  refCat = loadRes.refCat
947  numFound = len(refCat)
948 
949  # trim objects outside bbox
950  refCat = self._trimToBBox(refCat=refCat, bbox=circle.bbox, wcs=wcs)
951  numTrimmed = numFound - len(refCat)
952  self.log.debug("trimmed %d out-of-bbox objects, leaving %d", numTrimmed, len(refCat))
953  self.log.info("Loaded %d reference objects", len(refCat))
954 
955  # make sure catalog is contiguous
956  if not refCat.isContiguous():
957  loadRes.refCat = refCat.copy(deep=True)
958 
959  return loadRes
960 
961  @abc.abstractmethod
962  def loadSkyCircle(self, ctrCoord, radius, filterName=None, epoch=None, centroids=False):
963  """Load reference objects that overlap a circular sky region.
964 
965  Parameters
966  ----------
967  ctrCoord : `lsst.geom.SpherePoint`
968  ICRS center of search region.
969  radius : `lsst.geom.Angle`
970  Radius of search region.
971  filterName : `str` (optional)
972  Name of filter, or `None` or `""` for the default filter.
973  This is used for flux values in case we have flux limits
974  (which are not yet implemented).
975  epoch : `astropy.time.Time` (optional)
976  Epoch to which to correct proper motion and parallax,
977  or None to not apply such corrections.
978  centroids : `bool` (optional)
979  Add centroid fields to the loaded Schema. ``loadPixelBox`` expects
980  these fields to exist.
981 
982  Returns
983  -------
984  results : `lsst.pipe.base.Struct`
985  A Struct containing the following fields:
986  refCat : `lsst.afw.catalog.SimpleCatalog`
987  A catalog of reference objects with the standard
988  schema, as documented in the main doc string for
989  `LoadReferenceObjects`.
990  The catalog is guaranteed to be contiguous.
991  fluxField : `str`
992  Name of flux field for specified `filterName`.
993 
994  Notes
995  -----
996  Note that subclasses are responsible for performing the proper motion
997  correction, since this is the lowest-level interface for retrieving
998  the catalog.
999  """
1000  return
1001 
1002  @staticmethod
1003  def _trimToBBox(refCat, bbox, wcs):
1004  """Remove objects outside a given pixel bounding box and set
1005  centroid and hasCentroid fields.
1006 
1007  Parameters
1008  ----------
1009  refCat : `lsst.afw.table.SimpleCatalog`
1010  A catalog of objects. The schema must include fields
1011  "coord", "centroid" and "hasCentroid".
1012  The "coord" field is read.
1013  The "centroid" and "hasCentroid" fields are set.
1014  bbox : `lsst.geom.Box2D`
1015  Pixel region
1016  wcs : `lsst.afw.geom.SkyWcs`
1017  WCS; used to convert sky coordinates to pixel positions.
1018 
1019  @return a catalog of reference objects in bbox, with centroid and hasCentroid fields set
1020  """
1021  afwTable.updateRefCentroids(wcs, refCat)
1022  centroidKey = afwTable.Point2DKey(refCat.schema["centroid"])
1023  retStarCat = type(refCat)(refCat.table)
1024  for star in refCat:
1025  point = star.get(centroidKey)
1026  if bbox.contains(point):
1027  retStarCat.append(star)
1028  return retStarCat
1029 
1030  def _addFluxAliases(self, schema):
1031  """Add aliases for camera filter fluxes to the schema.
1032 
1033  If self.config.defaultFilter then adds these aliases:
1034  camFlux: <defaultFilter>_flux
1035  camFluxErr: <defaultFilter>_fluxErr, if the latter exists
1036 
1037  For each camFilter: refFilter in self.config.filterMap adds these aliases:
1038  <camFilter>_camFlux: <refFilter>_flux
1039  <camFilter>_camFluxErr: <refFilter>_fluxErr, if the latter exists
1040 
1041  Parameters
1042  ----------
1043  schema : `lsst.afw.table.Schema`
1044  Schema for reference catalog.
1045 
1046  Throws
1047  ------
1048  RuntimeError
1049  If any reference flux field is missing from the schema.
1050  """
1051  aliasMap = schema.getAliasMap()
1052 
1053  def addAliasesForOneFilter(filterName, refFilterName):
1054  """Add aliases for a single filter
1055 
1056  Parameters
1057  ----------
1058  filterName : `str` (optional)
1059  Camera filter name. The resulting alias name is
1060  <filterName>_camFlux, or simply "camFlux" if `filterName`
1061  is `None` or `""`.
1062  refFilterName : `str`
1063  Reference catalog filter name; the field
1064  <refFilterName>_flux must exist.
1065  """
1066  camFluxName = filterName + "_camFlux" if filterName is not None else "camFlux"
1067  refFluxName = refFilterName + "_flux"
1068  if refFluxName not in schema:
1069  raise RuntimeError("Unknown reference filter %s" % (refFluxName,))
1070  aliasMap.set(camFluxName, refFluxName)
1071  refFluxErrName = refFluxName + "Err"
1072  if refFluxErrName in schema:
1073  camFluxErrName = camFluxName + "Err"
1074  aliasMap.set(camFluxErrName, refFluxErrName)
1075 
1076  if self.config.defaultFilter:
1077  addAliasesForOneFilter(None, self.config.defaultFilter)
1078 
1079  for filterName, refFilterName in self.config.filterMap.items():
1080  addAliasesForOneFilter(filterName, refFilterName)
1081 
1082  @staticmethod
1083  def makeMinimalSchema(filterNameList, *, addCentroid=False,
1084  addIsPhotometric=False, addIsResolved=False,
1085  addIsVariable=False, coordErrDim=2,
1086  addProperMotion=False, properMotionErrDim=2,
1087  addParallax=False, addParallaxErr=True):
1088  """Make a standard schema for reference object catalogs.
1089 
1090  Parameters
1091  ----------
1092  filterNameList : `list` of `str`
1093  List of filter names. Used to create <filterName>_flux fields.
1094  addIsPhotometric : `bool`
1095  If True then add field "photometric".
1096  addIsResolved : `bool`
1097  If True then add field "resolved".
1098  addIsVariable : `bool`
1099  If True then add field "variable".
1100  coordErrDim : `int`
1101  Number of coord error fields; must be one of 0, 2, 3:
1102 
1103  - If 2 or 3: add fields "coord_raErr" and "coord_decErr".
1104  - If 3: also add field "coord_radecErr".
1105  addProperMotion : `bool`
1106  If True add fields "epoch", "pm_ra", "pm_dec" and "pm_flag".
1107  properMotionErrDim : `int`
1108  Number of proper motion error fields; must be one of 0, 2, 3;
1109  ignored if addProperMotion false:
1110  - If 2 or 3: add fields "pm_raErr" and "pm_decErr".
1111  - If 3: also add field "pm_radecErr".
1112  addParallax : `bool`
1113  If True add fields "epoch", "parallax", "parallaxErr"
1114  and "parallax_flag".
1115  addParallaxErr : `bool`
1116  If True add field "parallaxErr"; ignored if addParallax false.
1117 
1118  Returns
1119  -------
1120  schema : `lsst.afw.table.Schema`
1121  Schema for reference catalog, an
1122  `lsst.afw.table.SimpleCatalog`.
1123 
1124  Notes
1125  -----
1126  Reference catalogs support additional covariances, such as
1127  covariance between RA and proper motion in declination,
1128  that are not supported by this method, but can be added after
1129  calling this method.
1130  """
1131  schema = afwTable.SimpleTable.makeMinimalSchema()
1132  if addCentroid:
1133  afwTable.Point2DKey.addFields(
1134  schema,
1135  "centroid",
1136  "centroid on an exposure, if relevant",
1137  "pixel",
1138  )
1139  schema.addField(
1140  field="hasCentroid",
1141  type="Flag",
1142  doc="is position known?",
1143  )
1144  for filterName in filterNameList:
1145  schema.addField(
1146  field="%s_flux" % (filterName,),
1147  type=numpy.float64,
1148  doc="flux in filter %s" % (filterName,),
1149  units="nJy",
1150  )
1151  for filterName in filterNameList:
1152  schema.addField(
1153  field="%s_fluxErr" % (filterName,),
1154  type=numpy.float64,
1155  doc="flux uncertainty in filter %s" % (filterName,),
1156  units="nJy",
1157  )
1158  if addIsPhotometric:
1159  schema.addField(
1160  field="photometric",
1161  type="Flag",
1162  doc="set if the object can be used for photometric calibration",
1163  )
1164  if addIsResolved:
1165  schema.addField(
1166  field="resolved",
1167  type="Flag",
1168  doc="set if the object is spatially resolved",
1169  )
1170  if addIsVariable:
1171  schema.addField(
1172  field="variable",
1173  type="Flag",
1174  doc="set if the object has variable brightness",
1175  )
1176  if coordErrDim not in (0, 2, 3):
1177  raise ValueError("coordErrDim={}; must be (0, 2, 3)".format(coordErrDim))
1178  if coordErrDim > 0:
1179  afwTable.CovarianceMatrix2fKey.addFields(
1180  schema=schema,
1181  prefix="coord",
1182  names=["ra", "dec"],
1183  units=["rad", "rad"],
1184  diagonalOnly=(coordErrDim == 2),
1185  )
1186 
1187  if addProperMotion or addParallax:
1188  schema.addField(
1189  field="epoch",
1190  type=numpy.float64,
1191  doc="date of observation (TAI, MJD)",
1192  units="day",
1193  )
1194 
1195  if addProperMotion:
1196  schema.addField(
1197  field="pm_ra",
1198  type="Angle",
1199  doc="proper motion in the right ascension direction = dra/dt * cos(dec)",
1200  units="rad/year",
1201  )
1202  schema.addField(
1203  field="pm_dec",
1204  type="Angle",
1205  doc="proper motion in the declination direction",
1206  units="rad/year",
1207  )
1208  if properMotionErrDim not in (0, 2, 3):
1209  raise ValueError("properMotionErrDim={}; must be (0, 2, 3)".format(properMotionErrDim))
1210  if properMotionErrDim > 0:
1211  afwTable.CovarianceMatrix2fKey.addFields(
1212  schema=schema,
1213  prefix="pm",
1214  names=["ra", "dec"],
1215  units=["rad/year", "rad/year"],
1216  diagonalOnly=(properMotionErrDim == 2),
1217  )
1218  schema.addField(
1219  field="pm_flag",
1220  type="Flag",
1221  doc="Set if proper motion or proper motion error is bad",
1222  )
1223 
1224  if addParallax:
1225  schema.addField(
1226  field="parallax",
1227  type=numpy.float64,
1228  doc="parallax",
1229  units="rad",
1230  )
1231  if addParallaxErr:
1232  schema.addField(
1233  field="parallaxErr",
1234  type=numpy.float64,
1235  doc="uncertainty in parallax",
1236  units="rad",
1237  )
1238  schema.addField(
1239  field="parallax_flag",
1240  type="Flag",
1241  doc="Set if parallax or parallax error is bad",
1242  )
1243  return schema
1244 
1245  def _calculateCircle(self, bbox, wcs):
1246  """Compute on-sky center and radius of search region.
1247 
1248  Parameters
1249  ----------
1250  bbox : `lsst.geom.Box2I` or `lsst.geom.Box2D`
1251  Pixel bounding box.
1252  wcs : `lsst.afw.geom.SkyWcs`
1253  WCS; used to convert pixel positions to sky coordinates.
1254 
1255  Returns
1256  -------
1257  results : `lsst.pipe.base.Struct`
1258  A Struct containing:
1259 
1260  - coord : `lsst.geom.SpherePoint`
1261  ICRS center of the search region.
1262  - radius : `lsst.geom.Angle`
1263  Radius of the search region.
1264  - bbox : `lsst.geom.Box2D`
1265  Bounding box used to compute the circle.
1266  """
1267  bbox = lsst.geom.Box2D(bbox) # make sure bbox is double and that we have a copy
1268  bbox.grow(self.config.pixelMargin)
1269  coord = wcs.pixelToSky(bbox.getCenter())
1270  radius = max(coord.separation(wcs.pixelToSky(pp)) for pp in bbox.getCorners())
1271  return pipeBase.Struct(coord=coord, radius=radius, bbox=bbox)
1272 
1273  def getMetadataBox(self, bbox, wcs, filterName=None, photoCalib=None, epoch=None):
1274  """Return metadata about the load.
1275 
1276  This metadata is used for reloading the catalog (e.g., for
1277  reconstituting a normalised match list.
1278 
1279  Parameters
1280  ----------
1281  bbox : `lsst.geom.Box2I` or `lsst.geom.Box2D`
1282  Pixel bounding box.
1283  wcs : `lsst.afw.geom.SkyWcs`
1284  WCS; used to convert pixel positions to sky coordinates.
1285  filterName : `str`
1286  Name of camera filter, or `None` or `""` for the default
1287  filter.
1288  photoCalib : `lsst.afw.image.PhotoCalib` (optional)
1289  Calibration, or `None` if unknown.
1290  epoch : `astropy.time.Time` (optional)
1291  Epoch to which to correct proper motion and parallax,
1292  or None to not apply such corrections.
1293 
1294  Returns
1295  -------
1296  metadata : lsst.daf.base.PropertyList
1297  Metadata about the load.
1298  """
1299  circle = self._calculateCircle(bbox, wcs)
1300  return self.getMetadataCircle(circle.coord, circle.radius, filterName, photoCalib)
1301 
1302  def getMetadataCircle(self, coord, radius, filterName, photoCalib=None, epoch=None):
1303  """Return metadata about the load.
1304 
1305  This metadata is used for reloading the catalog (e.g., for
1306  reconstituting a normalised match list.
1307 
1308  Parameters
1309  ----------
1310  coord : `lsst.geom.SpherePoint`
1311  ICRS center of the search region.
1312  radius : `lsst.geom.Angle`
1313  Radius of the search region.
1314  filterName : `str`
1315  Name of camera filter, or `None` or `""` for the default
1316  filter.
1317  photoCalib : `lsst.afw.image.PhotoCalib` (optional)
1318  Calibration, or `None` if unknown.
1319  epoch : `astropy.time.Time` (optional)
1320  Epoch to which to correct proper motion and parallax,
1321  or None to not apply such corrections.
1322 
1323  Returns
1324  -------
1325  metadata : lsst.daf.base.PropertyList
1326  Metadata about the load
1327  """
1328  md = PropertyList()
1329  md.add('RA', coord.getRa().asDegrees(), 'field center in degrees')
1330  md.add('DEC', coord.getDec().asDegrees(), 'field center in degrees')
1331  md.add('RADIUS', radius.asDegrees(), 'field radius in degrees, minimum')
1332  md.add('SMATCHV', 1, 'SourceMatchVector version number')
1333  filterName = "UNKNOWN" if filterName is None else str(filterName)
1334  md.add('FILTER', filterName, 'filter name for photometric data')
1335  md.add('EPOCH', "NONE" if epoch is None else epoch, 'Epoch (TAI MJD) for catalog')
1336  return md
1337 
1338  def joinMatchListWithCatalog(self, matchCat, sourceCat):
1339  """Relink an unpersisted match list to sources and reference
1340  objects.
1341 
1342  A match list is persisted and unpersisted as a catalog of IDs
1343  produced by afw.table.packMatches(), with match metadata
1344  (as returned by the astrometry tasks) in the catalog's metadata
1345  attribute. This method converts such a match catalog into a match
1346  list, with links to source records and reference object records.
1347 
1348  Parameters
1349  ----------
1350  matchCat : `lsst.afw.table.BaseCatalog`
1351  Unperisted packed match list.
1352  ``matchCat.table.getMetadata()`` must contain match metadata,
1353  as returned by the astrometry tasks.
1354  sourceCat : `lsst.afw.table.SourceCatalog`
1355  Source catalog. As a side effect, the catalog will be sorted
1356  by ID.
1357 
1358  Returns
1359  -------
1360  matchList : `lsst.afw.table.ReferenceMatchVector`
1361  Match list.
1362  """
1363  return joinMatchListWithCatalogImpl(self, matchCat, sourceCat)
1364 
1365  def applyProperMotions(self, catalog, epoch):
1366  """Apply proper motion correction to a reference catalog.
1367 
1368  Adjust position and position error in the ``catalog``
1369  for proper motion to the specified ``epoch``,
1370  modifying the catalong in place.
1371 
1372  Parameters
1373  ----------
1374  catalog : `lsst.afw.table.SimpleCatalog`
1375  Catalog of positions, containing:
1376 
1377  - Coordinates, retrieved by the table's coordinate key.
1378  - ``coord_raErr`` : Error in Right Ascension (rad).
1379  - ``coord_decErr`` : Error in Declination (rad).
1380  - ``pm_ra`` : Proper motion in Right Ascension (rad/yr,
1381  East positive)
1382  - ``pm_raErr`` : Error in ``pm_ra`` (rad/yr), optional.
1383  - ``pm_dec`` : Proper motion in Declination (rad/yr,
1384  North positive)
1385  - ``pm_decErr`` : Error in ``pm_dec`` (rad/yr), optional.
1386  - ``epoch`` : Mean epoch of object (an astropy.time.Time)
1387  epoch : `astropy.time.Time` (optional)
1388  Epoch to which to correct proper motion and parallax,
1389  or None to not apply such corrections.
1390  """
1391  if ("epoch" not in catalog.schema or "pm_ra" not in catalog.schema or "pm_dec" not in catalog.schema):
1392  if self.config.requireProperMotion:
1393  raise RuntimeError("Proper motion correction required but not available from catalog")
1394  self.log.warn("Proper motion correction not available from catalog")
1395  return
1396  applyProperMotionsImpl(self.log, catalog, epoch)
1397 
1398 
1399 def joinMatchListWithCatalogImpl(refObjLoader, matchCat, sourceCat):
1400  """Relink an unpersisted match list to sources and reference
1401  objects.
1402 
1403  A match list is persisted and unpersisted as a catalog of IDs
1404  produced by afw.table.packMatches(), with match metadata
1405  (as returned by the astrometry tasks) in the catalog's metadata
1406  attribute. This method converts such a match catalog into a match
1407  list, with links to source records and reference object records.
1408 
1409  Parameters
1410  ----------
1411  refObjLoader
1412  Reference object loader to use in getting reference objects
1413  matchCat : `lsst.afw.table.BaseCatalog`
1414  Unperisted packed match list.
1415  ``matchCat.table.getMetadata()`` must contain match metadata,
1416  as returned by the astrometry tasks.
1417  sourceCat : `lsst.afw.table.SourceCatalog`
1418  Source catalog. As a side effect, the catalog will be sorted
1419  by ID.
1420 
1421  Returns
1422  -------
1423  matchList : `lsst.afw.table.ReferenceMatchVector`
1424  Match list.
1425  """
1426  matchmeta = matchCat.table.getMetadata()
1427  version = matchmeta.getInt('SMATCHV')
1428  if version != 1:
1429  raise ValueError('SourceMatchVector version number is %i, not 1.' % version)
1430  filterName = matchmeta.getString('FILTER').strip()
1431  try:
1432  epoch = matchmeta.getDouble('EPOCH')
1433  except (pexExcept.NotFoundError, pexExcept.TypeError):
1434  epoch = None # Not present, or not correct type means it's not set
1435  if 'RADIUS' in matchmeta:
1436  # This is a circle style metadata, call loadSkyCircle
1437  ctrCoord = lsst.geom.SpherePoint(matchmeta.getDouble('RA'),
1438  matchmeta.getDouble('DEC'), lsst.geom.degrees)
1439  rad = matchmeta.getDouble('RADIUS') * lsst.geom.degrees
1440  refCat = refObjLoader.loadSkyCircle(ctrCoord, rad, filterName, epoch=epoch).refCat
1441  elif "INNER_UPPER_LEFT_RA" in matchmeta:
1442  # This is the sky box type (only triggers in the LoadReferenceObject class, not task)
1443  # Only the outer box is required to be loaded to get the maximum region, all filtering
1444  # will be done by the unpackMatches function, and no spatial filtering needs to be done
1445  # by the refObjLoader
1446  box = []
1447  for place in ("UPPER_LEFT", "UPPER_RIGHT", "LOWER_LEFT", "LOWER_RIGHT"):
1448  coord = lsst.geom.SpherePoint(matchmeta.getDouble(f"OUTER_{place}_RA"),
1449  matchmeta.getDouble(f"OUTER_{place}_DEC"),
1450  lsst.geom.degrees).getVector()
1451  box.append(coord)
1452  outerBox = sphgeom.ConvexPolygon(box)
1453  refCat = refObjLoader.loadRegion(outerBox, filterName=filterName, epoch=epoch).refCat
1454 
1455  refCat.sort()
1456  sourceCat.sort()
1457  return afwTable.unpackMatches(matchCat, refCat, sourceCat)
1458 
1459 
1460 def applyProperMotionsImpl(log, catalog, epoch):
1461  """Apply proper motion correction to a reference catalog.
1462 
1463  Adjust position and position error in the ``catalog``
1464  for proper motion to the specified ``epoch``,
1465  modifying the catalong in place.
1466 
1467  Parameters
1468  ----------
1469  log : `lsst.log.log`
1470  log object to write to
1471  catalog : `lsst.afw.table.SimpleCatalog`
1472  Catalog of positions, containing:
1473 
1474  - Coordinates, retrieved by the table's coordinate key.
1475  - ``coord_raErr`` : Error in Right Ascension (rad).
1476  - ``coord_decErr`` : Error in Declination (rad).
1477  - ``pm_ra`` : Proper motion in Right Ascension (rad/yr,
1478  East positive)
1479  - ``pm_raErr`` : Error in ``pm_ra`` (rad/yr), optional.
1480  - ``pm_dec`` : Proper motion in Declination (rad/yr,
1481  North positive)
1482  - ``pm_decErr`` : Error in ``pm_dec`` (rad/yr), optional.
1483  - ``epoch`` : Mean epoch of object (an astropy.time.Time)
1484  epoch : `astropy.time.Time` (optional)
1485  Epoch to which to correct proper motion and parallax,
1486  or None to not apply such corrections.
1487  """
1488  if "epoch" not in catalog.schema or "pm_ra" not in catalog.schema or "pm_dec" not in catalog.schema:
1489  log.warn("Proper motion correction not available from catalog")
1490  return
1491  if not catalog.isContiguous():
1492  raise RuntimeError("Catalog must be contiguous")
1493  catEpoch = astropy.time.Time(catalog["epoch"], scale="tai", format="mjd")
1494  log.debug("Correcting reference catalog for proper motion to %r", epoch)
1495  # Use `epoch.tai` to make sure the time difference is in TAI
1496  timeDiffsYears = (epoch.tai - catEpoch).to(astropy.units.yr).value
1497  coordKey = catalog.table.getCoordKey()
1498  # Compute the offset of each object due to proper motion
1499  # as components of the arc of a great circle along RA and Dec
1500  pmRaRad = catalog["pm_ra"]
1501  pmDecRad = catalog["pm_dec"]
1502  offsetsRaRad = pmRaRad*timeDiffsYears
1503  offsetsDecRad = pmDecRad*timeDiffsYears
1504  # Compute the corresponding bearing and arc length of each offset
1505  # due to proper motion, and apply the offset
1506  # The factor of 1e6 for computing bearing is intended as
1507  # a reasonable scale for typical values of proper motion
1508  # in order to avoid large errors for small values of proper motion;
1509  # using the offsets is another option, but it can give
1510  # needlessly large errors for short duration
1511  offsetBearingsRad = numpy.arctan2(pmDecRad*1e6, pmRaRad*1e6)
1512  offsetAmountsRad = numpy.hypot(offsetsRaRad, offsetsDecRad)
1513  for record, bearingRad, amountRad in zip(catalog, offsetBearingsRad, offsetAmountsRad):
1514  record.set(coordKey,
1515  record.get(coordKey).offset(bearing=bearingRad*lsst.geom.radians,
1516  amount=amountRad*lsst.geom.radians))
1517  # Increase error in RA and Dec based on error in proper motion
1518  if "coord_raErr" in catalog.schema:
1519  catalog["coord_raErr"] = numpy.hypot(catalog["coord_raErr"],
1520  catalog["pm_raErr"]*timeDiffsYears)
1521  if "coord_decErr" in catalog.schema:
1522  catalog["coord_decErr"] = numpy.hypot(catalog["coord_decErr"],
1523  catalog["pm_decErr"]*timeDiffsYears)
def getMetadataCircle(self, coord, radius, filterName, photoCalib=None, epoch=None)
def loadSkyCircle(self, ctrCoord, radius, filterName=None, epoch=None, centroids=False)
def loadPixelBox(self, bbox, wcs, filterName=None, epoch=None, photoCalib=None, bboxPadding=100)
def addFluxAliases(refCat, defaultFilter, filterReferenceMap)
static Schema makeMinimalSchema()
def loadSkyCircle(self, ctrCoord, radius, filterName=None, epoch=None)
def getMetadataBox(self, bbox, wcs, filterName=None, photoCalib=None, epoch=None)
def makeMinimalSchema(filterNameList, addCentroid=False, addIsPhotometric=False, addIsResolved=False, addIsVariable=False, coordErrDim=2, addProperMotion=False, properMotionErrDim=2, addParallax=False, addParallaxErr=True)
def getMetadataCircle(coord, radius, filterName, photoCalib=None, epoch=None)
def convertToNanojansky(catalog, log, doConvert=True)
def loadPixelBox(self, bbox, wcs, filterName=None, photoCalib=None, epoch=None)
static Log getDefaultLogger()
def loadRegion(self, region, filtFunc=None, filterName=None, epoch=None)
Abstract base class to load objects from reference catalogs.
def joinMatchListWithCatalogImpl(refObjLoader, matchCat, sourceCat)
def getMetadataBox(cls, bbox, wcs, filterName=None, photoCalib=None, epoch=None, bboxPadding=100)
def remapReferenceCatalogSchema(refCat, filterNameList=None, position=False, photometric=False)