Coverage for python/lsst/images/_difference_image.py: 24%
204 statements
« prev ^ index » next coverage.py v7.16.0, created at 2026-09-30 04:21 -0700
1# This file is part of lsst-images.
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# Use of this source code is governed by a 3-clause BSD-style
10# license that can be found in the LICENSE file.
12from __future__ import annotations
14__all__ = ("DifferenceImage", "DifferenceImageSerializationModel", "DifferenceImageTemplateInfo")
16import logging
17import math
18import operator
19import uuid
20from collections.abc import Iterable, Mapping
21from types import EllipsisType
22from typing import TYPE_CHECKING, Any, ClassVar, Literal, cast
24import astropy.units
25import pydantic
26from astro_metadata_translator import ObservationInfo
28from ._backgrounds import BackgroundMap
29from ._geom import Bounds, Box, NoOverlapError
30from ._image import Image
31from ._mask import Mask, MaskPlane, MaskSchema, get_legacy_difference_image_mask_planes
32from ._observation_summary_stats import ObservationSummaryStats
33from ._polygon import Polygon
34from ._transforms import DetectorFrame, SkyProjection, TractFrame, Transform
35from ._visit_image import VisitImage, VisitImageSerializationModel
36from .aperture_corrections import (
37 ApertureCorrectionMap,
38)
39from .cameras import Detector
40from .convolution_kernels import ConvolutionKernel, ConvolutionKernelSerializationModel
41from .describe import DescribeOptions, FieldRole, Report, ReportField, ReportTable
42from .fields import Field
43from .psfs import (
44 PointSpreadFunction,
45)
46from .serialization import (
47 ArchiveReadError,
48 InputArchive,
49 InvalidParameterError,
50 MetadataValue,
51 OutputArchive,
52)
54if TYPE_CHECKING:
55 from lsst.daf.butler import DataId
57 try:
58 from lsst.afw.geom import SkyWcs as LegacySkyWcs
59 from lsst.afw.image import Exposure as LegacyExposure
60 from lsst.geom import Box2I as LegacyBox2I
61 from lsst.meas.algorithms import CoaddPsf as LegacyCoaddPsf
62 except ImportError:
63 type LegacyBox2I = Any # type: ignore[no-redef]
64 type LegacyExposure = Any # type: ignore[no-redef]
65 type LegacyCoaddPsf = Any # type: ignore[no-redef]
66 type LegacySkyWcs = Any # type: ignore[no-redef]
69class DifferenceImage(VisitImage):
70 """An image that is the PSF-matched difference of two other images.
72 Parameters
73 ----------
74 image
75 The main image plane. If this has a `SkyProjection`, it will be used
76 for all planes unless a ``sky_projection`` is passed separately.
77 mask
78 A bitmask image that annotates the main image plane. Must have the
79 same bounding box as ``image`` if provided. Any attached
80 ``sky_projection`` is replaced (possibly by `None`).
81 variance
82 The per-pixel uncertainty of the main image as an image of variance
83 values. Must have the same bounding box as ``image`` if provided, and
84 its units must be the square of ``image.unit`` or `None`.
85 Values default to ``1.0``. Any attached sky_projection is replaced
86 (possibly by `None`).
87 mask_schema
88 Schema for the mask plane. Must be provided if and only if ``mask`` is
89 not provided.
90 sky_projection
91 Projection that maps the pixel grid to the sky. Can only be `None` if
92 a ``sky_projection`` is already attached to ``image``.
93 bounds
94 The region where this image's pixels and other properties are valid.
95 If not provided, the bounding box of the image is used. Other
96 components (``psf``, ``sky_projection``, ``aperture_corrections``,
97 etc.) are assumed to have their own bounds which may or may not be the
98 same as the image bounds. If ``bounds`` extends beyond the image
99 bounding box, the intersection between ``bounds`` and the image
100 bounding box is used instead.
101 obs_info
102 General information about this visit in standardized form.
103 summary_stats
104 Summary statistics associated with this visit. Initialized to default
105 values if not provided.
106 photometric_scaling
107 Field that can be used to multiply a post-ISR image units to yield
108 calibrated image units. This may be a scaling that was already
109 applied (so dividing by it will recover the post-ISR units) or a
110 scaling that has not been applied, depending on ``image.unit``.
111 psf
112 Point-spread function model for this image, or an exception explaining
113 why it could not be read (to be raised if the PSF is requested later).
114 detector
115 Geometry and electronic information for the detector attached to this
116 image.
117 aperture_corrections : `dict` [`str`, `~fields.BaseField`]
118 Mapping from photometry algorithm name to the aperture correction for
119 that algorithm.
120 backgrounds
121 Background models associated with this image.
122 band
123 Name of the passband the image was observed with (this is a shorter,
124 less specific version of ``obs_info.physical_filter``).
125 kernel
126 The convolution kernel used to match the (warped) template to the
127 science image.
128 templates
129 Information about the template coadds that went into this difference
130 image.
131 metadata
132 Arbitrary flexible metadata to associate with the image.
134 Notes
135 -----
136 This class assumes that the difference has been performed on the pixel
137 grid of the 'science image' (i.e. a single observation, like `VisitImage`),
138 and most of the attributes of `DifferenceImage` correspond to the science
139 image. The 'template image' is assumed to be comprised of one or more
140 resampled coadd images stitched together.
142 The `DifferenceImage` class can also be used to represent the stitched
143 template itself; while this makes the naming a bit confusing, the type has
144 the right state to play this role.
145 """
147 def __init__(
148 self,
149 image: Image,
150 *,
151 mask: Mask | None = None,
152 variance: Image | None = None,
153 mask_schema: MaskSchema | None = None,
154 sky_projection: SkyProjection[DetectorFrame] | None = None,
155 bounds: Bounds | None = None,
156 obs_info: ObservationInfo | None = None,
157 summary_stats: ObservationSummaryStats | None = None,
158 photometric_scaling: Field | None = None,
159 psf: PointSpreadFunction | ArchiveReadError,
160 detector: Detector,
161 aperture_corrections: ApertureCorrectionMap | None = None,
162 backgrounds: BackgroundMap | None = None,
163 band: str,
164 kernel: ConvolutionKernel | None = None,
165 templates: Iterable[DifferenceImageTemplateInfo] | None = None,
166 metadata: dict[str, MetadataValue] | None = None,
167 ) -> None:
168 super().__init__(
169 image,
170 mask=mask,
171 variance=variance,
172 mask_schema=mask_schema,
173 sky_projection=sky_projection,
174 bounds=bounds,
175 obs_info=obs_info,
176 summary_stats=summary_stats,
177 photometric_scaling=photometric_scaling,
178 psf=psf,
179 detector=detector,
180 aperture_corrections=aperture_corrections,
181 backgrounds=backgrounds,
182 band=band,
183 metadata=metadata,
184 )
185 self._kernel = kernel
186 self._templates = list(templates) if templates is not None else None
188 @staticmethod
189 def _from_visit_image(
190 visit_image: VisitImage,
191 kernel: ConvolutionKernel | None,
192 templates: Iterable[DifferenceImageTemplateInfo] | None,
193 ) -> DifferenceImage:
194 return visit_image._transfer_metadata(
195 DifferenceImage(
196 visit_image.image,
197 mask=visit_image.mask,
198 variance=visit_image.variance,
199 sky_projection=visit_image.sky_projection,
200 bounds=visit_image.bounds,
201 obs_info=visit_image.obs_info,
202 summary_stats=visit_image.summary_stats,
203 photometric_scaling=visit_image.photometric_scaling,
204 psf=visit_image._psf, # get private attr to avoid triggering on ArchiveReadError early.
205 detector=visit_image.detector,
206 aperture_corrections=visit_image.aperture_corrections,
207 backgrounds=visit_image.backgrounds,
208 kernel=kernel,
209 templates=templates,
210 band=visit_image.band,
211 ),
212 )
214 @property
215 def kernel(self) -> ConvolutionKernel:
216 """The convolution kernel used to match the (warped) template
217 to the science image (`.convolution_kernels.ConvolutionKernel`).
218 """
219 if self._kernel is None:
220 raise AttributeError("This difference image does not have a kernel attached.")
221 return self._kernel
223 @kernel.setter
224 def kernel(self, kernel: ConvolutionKernel) -> None:
225 self._kernel = kernel
227 @kernel.deleter
228 def kernel(self) -> None:
229 self._kernel = None
231 @property
232 def templates(self) -> list[DifferenceImageTemplateInfo]:
233 """Information about the template coadds that went into this
234 difference image (`list` [`DifferenceImageTemplateInfo`]).
235 """
236 if self._templates is None: 236 ↛ 237line 236 didn't jump to line 237 because the condition on line 236 was never true
237 raise AttributeError("This difference image does not have any template information attached.")
238 return self._templates
240 @templates.setter
241 def templates(self, templates: Iterable[DifferenceImageTemplateInfo]) -> None:
242 self._templates = list(templates)
244 @templates.deleter
245 def templates(self) -> None:
246 self._templates = None
248 def __getitem__(self, bbox: Box | EllipsisType) -> DifferenceImage:
249 if bbox is ...:
250 return self
251 return self._from_visit_image(
252 super().__getitem__(bbox), kernel=self._kernel, templates=self._templates
253 )
255 def _describe(self, options: DescribeOptions = DescribeOptions(), /) -> Report:
256 """Return a `Report` describing this difference image.
258 Parameters
259 ----------
260 options : `DescribeOptions`, optional
261 Rendering options; forwarded to the base-class report.
262 """
263 report = super()._describe(options)
264 report.type_name = "DifferenceImage"
265 report.summary = f"DifferenceImage({self.image!s}, {list(self.mask.schema.names)})"
266 if options.brief:
267 return report
268 if self._templates: 268 ↛ 272line 268 didn't jump to line 272 because the condition on line 268 was always true
269 fields, table = DifferenceImageTemplateInfo._describe_templates(self._templates)
270 report.fields.extend(fields)
271 report.tables.append(table)
272 if self._kernel is not None: 272 ↛ 274line 272 didn't jump to line 274 because the condition on line 272 was always true
273 report.children["kernel"] = self._kernel._describe(options.for_child())
274 return report
276 def copy(self, *, copy_detector: bool = False) -> DifferenceImage:
277 """Deep-copy the difference image.
279 Parameters
280 ----------
281 copy_detector
282 Whether to deep-copy the `detector` attribute.
283 """
284 return self._from_visit_image(
285 super().copy(copy_detector=copy_detector), kernel=self._kernel, templates=self._templates
286 )
288 def convert_unit(
289 self,
290 unit: astropy.units.UnitBase = astropy.units.nJy,
291 copy: Literal["as-needed"] | bool = True,
292 copy_detector: bool = False,
293 ) -> DifferenceImage:
294 """Return an equivalent image with different pixel units.
296 Parameters
297 ----------
298 unit
299 The unit to transform to. This may be any of the following:
301 - any unit directly relatable to the current units via Astropy;
302 - any unit relatable to the product of the current units with the
303 `photometric_scaling` (i.e. if the current image is in
304 instrumental units but we know how to calibrate them)
305 - any unit relatable to the quotient of the current units with the
306 `photometric_scaling` (i.e. if the current image is in
307 calibrated units and we want to revert back to instrumental
308 units).
309 copy
310 Whether to copy the images and other components. If `True`, all
311 components that aren't controlled by some other argument will
312 always be deep-copied. If `False`, the operation will fail if the
313 image is not already in the right units. If ``as-needed``, only
314 the image and variance will be copied, and only if they are not
315 already in the right units.
316 copy_detector
317 Whether to deep-copy the `detector` attribute.
319 Returns
320 -------
321 `DifferenceImage`
322 An image with the given units.
323 """
324 return self._from_visit_image(
325 super().convert_unit(unit, copy=copy, copy_detector=copy_detector),
326 kernel=self._kernel,
327 templates=self._templates,
328 )
330 def serialize(self, archive: OutputArchive[Any]) -> DifferenceImageSerializationModel[Any]:
331 result = self._serialize_impl(DifferenceImageSerializationModel, archive)
332 if self._kernel is not None:
333 result.kernel = archive.serialize_direct("kernel", self._kernel.serialize)
334 else:
335 result.kernel = None
336 result.templates = self._templates
337 return result
339 @staticmethod
340 def _get_archive_tree_type[P: pydantic.BaseModel](
341 pointer_type: type[P],
342 ) -> type[DifferenceImageSerializationModel[P]]:
343 """Return the serialization model type for this object for an archive
344 type that uses the given pointer type.
345 """
346 return DifferenceImageSerializationModel[pointer_type] # type: ignore
348 @staticmethod
349 def from_legacy( # type: ignore[override]
350 legacy: LegacyExposure,
351 *,
352 unit: astropy.units.UnitBase | None = None,
353 plane_map: Mapping[str, MaskPlane] | None = None,
354 instrument: str | None = None,
355 visit: int | None = None,
356 ) -> DifferenceImage:
357 """Convert from an `lsst.afw.image.Exposure` instance.
359 Parameters
360 ----------
361 legacy
362 An `lsst.afw.image.Exposure` instance that will share image and
363 variance (but not mask) pixel data with the returned object.
364 unit
365 Units of the image. If not provided, the ``BUNIT`` metadata
366 key will be used, if available.
367 plane_map
368 A mapping from legacy mask plane name to the new plane name and
369 description. If `None` (default)
370 `get_legacy_visit_image_mask_planes` is used.
371 instrument
372 Name of the instrument. Extracted from the metadata if not
373 provided.
374 visit
375 ID of the visit. Extracted from the metadata if not provided.
376 """
377 if plane_map is None:
378 plane_map = get_legacy_difference_image_mask_planes()
379 return DifferenceImage._from_visit_image(
380 VisitImage.from_legacy(
381 legacy, unit=unit, plane_map=plane_map, instrument=instrument, visit=visit
382 ),
383 kernel=None,
384 templates=None,
385 )
387 def to_legacy(
388 self, *, copy: bool | None = None, plane_map: Mapping[str, MaskPlane] | None = None
389 ) -> LegacyExposure:
390 """Convert to an `lsst.afw.image.Exposure` instance.
392 Parameters
393 ----------
394 copy
395 If `True`, always copy the image and variance pixel data.
396 If `False`, return a view, and raise `TypeError` if the pixel data
397 is read-only (this is not supported by afw). If `None`, only copy
398 if the pixel data is read-only. Mask pixel data is always copied.
399 plane_map
400 A mapping from legacy mask plane name to the new plane name and
401 description. If `None` (default),
402 `get_legacy_visit_image_mask_planes` is used.
403 """
404 if plane_map is None:
405 plane_map = get_legacy_difference_image_mask_planes()
406 return super().to_legacy(copy=copy, plane_map=plane_map)
408 @staticmethod
409 def read_legacy( # type: ignore[override]
410 filename: str,
411 *,
412 preserve_quantization: bool = False,
413 plane_map: Mapping[str, MaskPlane] | None = None,
414 instrument: str | None = None,
415 visit: int | None = None,
416 component: Literal[
417 "bbox",
418 "image",
419 "mask",
420 "variance",
421 "sky_projection",
422 "psf",
423 "detector",
424 "photometric_scaling",
425 "obs_info",
426 "summary_stats",
427 "aperture_corrections",
428 ]
429 | None = None,
430 ) -> Any:
431 """Read a FITS file written by `lsst.afw.image.Exposure.writeFits`.
433 Parameters
434 ----------
435 filename
436 Full name of the file.
437 preserve_quantization
438 If `True`, ensure that writing the masked image back out again will
439 exactly preserve quantization-compressed pixel values. This causes
440 the image and variance plane arrays to be marked as read-only and
441 stores the original binary table data for those planes in memory.
442 If the `MaskedImage` is copied, the precompressed pixel values are
443 not transferred to the copy.
444 plane_map
445 A mapping from legacy mask plane name to the new plane name and
446 description. If `None` (default)
447 `get_legacy_visit_image_mask_planes` is used.
448 instrument
449 Name of the instrument. Read from the primary header if not
450 provided.
451 visit
452 ID of the visit. Read from the primary header if not
453 provided.
454 component
455 A component to read instead of the full image.
456 """
457 if plane_map is None:
458 plane_map = get_legacy_difference_image_mask_planes()
459 result = VisitImage.read_legacy(
460 filename,
461 preserve_quantization=preserve_quantization,
462 plane_map=plane_map,
463 instrument=instrument,
464 visit=visit,
465 component=component,
466 )
467 if component is None:
468 return DifferenceImage._from_visit_image(result, kernel=None, templates=None)
469 return result
472class DifferenceImageTemplateInfo(pydantic.BaseModel, ser_json_inf_nan="constants"):
473 """Information about how a template image contributed to a difference
474 image.
475 """
477 skymap: str = pydantic.Field(description="Name of the skymap that defines the tract/patch tiling.")
478 tract: int = pydantic.Field(description="ID of the tract (each tract is a different projection).")
479 patch: int = pydantic.Field(
480 description="ID of the patch (all patches within a tract share a projection)."
481 )
482 dataset_id: uuid.UUID = pydantic.Field(
483 description="Universally unique butler identifier for this template.",
484 )
485 dataset_run: str = pydantic.Field(description="Name of the butler RUN collection for this template.")
486 bounds: Polygon = pydantic.Field(
487 description=(
488 "The approximate intersection of the template and the science image, "
489 "in the science image's pixel coordinate system."
490 )
491 )
492 psf_shape_xx: float = pydantic.Field(description="Second moment of the effective PSF of the template.")
493 psf_shape_yy: float = pydantic.Field(description="Second moment of the effective PSF of the template.")
494 psf_shape_xy: float = pydantic.Field(description="Second moment of the effective PSF of the template.")
495 psf_shape_flag: bool = pydantic.Field(
496 description="Flag set if the second moments of the effective template PSF could not be computed."
497 )
499 @staticmethod
500 def from_legacy(
501 detector_frame: DetectorFrame,
502 legacy_template_psf: LegacyCoaddPsf,
503 legacy_template_metadata: Mapping[str, Any],
504 coadd_data_ids_by_uuid: Mapping[uuid.UUID, DataId],
505 coadd_dataset_type: str = "template_coadd",
506 log: logging.Logger | None = None,
507 ) -> list[DifferenceImageTemplateInfo]:
508 """Construct a list of template information structs from information
509 stored in a legacy stitched template image.
511 Parameters
512 ----------
513 detector_frame
514 Coordinate system and bounding box of the science image.
515 legacy_template_psf
516 The lazy-evaluation PSF model for the stitched template; used to
517 extract the tract and patch IDs of the coadds actually used and
518 their PSF models.
519 legacy_template_metadata
520 The FITS-style metadata of the stitched template; used to extract
521 butler UUIDs and RUN collection names for all *potential* input
522 coadds.
523 coadd_data_ids_by_uuid
524 A mapping from butler dataset ID to ``{tract, patch, band}`` data
525 ID for all coadds that may have contributed to the template. May
526 be a much larger superset of the needed datasets.
527 coadd_dataset_type
528 The name of the coadd template dataset type.
529 log
530 Logger to use for diagnostic messages.
531 """
532 from lsst.afw.geom import makeWcsPairTransform
534 n_inputs = legacy_template_metadata["LSST BUTLER N_INPUTS"]
535 butler_info: dict[tuple[int, int], tuple[uuid.UUID, str]] = {}
536 skymap: str | None = None
537 for n in range(n_inputs):
538 if legacy_template_metadata[f"LSST BUTLER INPUT {n} DATASETTYPE"] == coadd_dataset_type:
539 input_id = uuid.UUID(legacy_template_metadata[f"LSST BUTLER INPUT {n} ID"])
540 input_run = legacy_template_metadata[f"LSST BUTLER INPUT {n} RUN"]
541 input_data_id = coadd_data_ids_by_uuid[input_id]
542 if skymap is None:
543 skymap = cast(str, input_data_id["skymap"])
544 elif skymap != input_data_id["skymap"]:
545 raise RuntimeError("Cannot handle multiple skymaps in the inputs to a single template.")
546 butler_info[cast(int, input_data_id["tract"]), cast(int, input_data_id["patch"])] = (
547 input_id,
548 input_run,
549 )
550 result: list[DifferenceImageTemplateInfo] = []
551 # A "component" of this PSF is an input {tract, patch} coadd.
552 for n in range(legacy_template_psf.getComponentCount()):
553 tract = legacy_template_psf.getTract(n)
554 patch = legacy_template_psf.getPatch(n)
555 dataset_id, dataset_run = butler_info[tract, patch]
556 patch_bbox = Box.from_legacy(legacy_template_psf.getBBox(n))
557 coadd_frame = TractFrame(
558 skymap=skymap,
559 tract=tract,
560 # This bbox is supposed to be the full tract bbox, but this
561 # frame is just a temporary and we don't have access to that.
562 # (If this ever becomes not-a-temporary, we could add a skymap
563 # argument).
564 bbox=patch_bbox,
565 )
566 detector_to_coadd = Transform.from_legacy(
567 makeWcsPairTransform(
568 # CoaddPsf method names did not anticipate being used for
569 # detector-level templates, so this is confusing:
570 legacy_template_psf.getCoaddWcs(), # this is the template_detector WCS!
571 legacy_template_psf.getWcs(n), # this is the template_coadd WCS!
572 ),
573 detector_frame,
574 coadd_frame,
575 )
576 coadd_to_detector = detector_to_coadd.inverted()
577 try:
578 # We transform the detector bbox to each coadd frame, do the
579 # intersection there, and then transform the intersection back
580 # to the detector frame, because we do not trust detector WCSs
581 # beyond the detector bounding box; they can be polynomials
582 # that extrapolate badly. Coadd WCSs in contrast are simple
583 # projections.
584 tmp_bounds = (
585 Polygon.from_box(detector_frame.bbox)
586 .transform(detector_to_coadd)
587 .intersection(patch_bbox)
588 ).transform(coadd_to_detector)
589 # Unfortunately doing the intersection in the coadd coordinate
590 # system means the transformed intersection might not quite be
591 # contained by the detector bounding box, due to floating-point
592 # round-off error. Intersect one more time to tidy it up.
593 bounds = tmp_bounds.intersection(detector_frame.bbox)
594 assert isinstance(bounds, Polygon), (
595 "The operations above should not change the region's fundamental topology."
596 )
597 except NoOverlapError:
598 if log is not None:
599 log.exception(
600 "No overlap with tract=%s, patch=%s; skipping provenance for that template.",
601 tract,
602 patch,
603 )
604 continue
605 try:
606 psf_shape = legacy_template_psf.computeShape(bounds.centroid.to_legacy_float_point())
607 except Exception:
608 if log is not None:
609 log.exception(
610 "Could not compute PSF shape for template coadd with tract=%s, patch=%s", tract, patch
611 )
612 else:
613 raise
614 psf_shape = None
615 result.append(
616 DifferenceImageTemplateInfo(
617 skymap=skymap,
618 tract=tract,
619 patch=patch,
620 dataset_id=dataset_id,
621 dataset_run=dataset_run,
622 bounds=bounds,
623 psf_shape_xx=psf_shape.getIxx() if psf_shape is not None else math.nan,
624 psf_shape_yy=psf_shape.getIyy() if psf_shape is not None else math.nan,
625 psf_shape_xy=psf_shape.getIxy() if psf_shape is not None else math.nan,
626 psf_shape_flag=psf_shape is None,
627 )
628 )
629 result.sort(key=lambda item: (item.tract, item.patch))
630 return result
632 _HOISTABLE_REPORT_VALUES: ClassVar[tuple[tuple[str, str, str], ...]] = (
633 ("skymap", "skymap", "Skymap"),
634 ("dataset_run", "template run", "Run"),
635 )
636 """Template attributes a report shows once above the templates table when
637 every template carries the same one, as ``(attribute, field label, column
638 header)``.
640 A value belongs here when it is wide enough to crowd the table and usually
641 uniform across a difference image's templates, and when it does not
642 identify the row: see the notes on `_describe_templates`. Adding an
643 attribute here is all it takes to cover it; a value that turns out to vary
644 falls back to its column on its own.
645 """
647 def _report_psf_sigma(self) -> str:
648 """Return the determinant radius of a template's effective PSF,
649 formatted for a report cell.
651 Returns
652 -------
653 sigma : `str`
654 Determinant radius in pixels, or ``"n/a"`` where the second moments
655 do not describe an ellipse.
657 Notes
658 -----
659 This is the same quantity as `ObservationSummaryStats.psfSigma`, so the
660 template PSFs can be compared directly against the science image's.
661 """
662 if self.psf_shape_flag:
663 return "n/a"
664 determinant = self.psf_shape_xx * self.psf_shape_yy - self.psf_shape_xy**2
665 if not math.isfinite(determinant) or determinant <= 0.0:
666 return "n/a"
667 return f"{determinant**0.25:.3f}"
669 @staticmethod
670 def _describe_templates(
671 templates: list[DifferenceImageTemplateInfo],
672 ) -> tuple[list[ReportField], ReportTable]:
673 """Return the report elements describing a difference image's
674 templates.
676 Parameters
677 ----------
678 templates
679 Templates to describe; must not be empty.
681 Returns
682 -------
683 fields : `list` [ `~lsst.images.ReportField` ]
684 The `_HOISTABLE_REPORT_VALUES` that every template shares.
685 table : `~lsst.images.ReportTable`
686 One row per template.
688 Notes
689 -----
690 Some of what a template carries is usually, but not dependably, the
691 same for every template of one difference image, and is long enough to
692 crowd out the columns that do differ. Each such value is shown once
693 above the table where every template shares it, and stays a column
694 where they do not, so nothing is lost when the usual case does not
695 hold. `_HOISTABLE_REPORT_VALUES` lists them.
697 What identifies a row is never hoisted, however uniform it happens to
698 be. A detector overlapping a single tract gives every template the
699 same tract, but tract and patch together name the coadd a row
700 describes, and splitting that pair between a field and a column would
701 leave each row unable to say what it is.
702 """
703 fields: list[ReportField] = []
704 columns: list[str] = []
705 getters: list[Any] = []
706 for attribute, label, column in DifferenceImageTemplateInfo._HOISTABLE_REPORT_VALUES:
707 getter = operator.attrgetter(attribute)
708 values = {getter(template) for template in templates}
709 if len(values) == 1:
710 fields.append(ReportField(label=label, value=values.pop(), role=FieldRole.DERIVED))
711 else:
712 columns.append(column)
713 getters.append(getter)
714 columns.extend(["Tract", "Patch", "PSF \N{GREEK SMALL LETTER SIGMA}"])
715 getters.extend([lambda t: t.tract, lambda t: t.patch, DifferenceImageTemplateInfo._report_psf_sigma])
716 if any(template.psf_shape_flag for template in templates):
717 columns.append("PSF flag")
718 getters.append(lambda t: "set" if t.psf_shape_flag else "")
719 columns.append("Dataset ID")
720 getters.append(lambda t: t.dataset_id)
721 return fields, ReportTable(
722 title="Templates",
723 columns=columns,
724 rows=[[getter(template) for getter in getters] for template in templates],
725 )
728class DifferenceImageSerializationModel[P: pydantic.BaseModel](VisitImageSerializationModel[P]):
729 """A Pydantic model used to represent a serialized `DifferenceImage`."""
731 SCHEMA_NAME: ClassVar[str] = "difference_image"
732 SCHEMA_VERSION: ClassVar[str] = "1.1.0"
733 MIN_READ_VERSION: ClassVar[int] = 1
734 PUBLIC_TYPE: ClassVar[type] = DifferenceImage
736 kernel: ConvolutionKernelSerializationModel | None = pydantic.Field(
737 description="The convolution kernel used to match the (warped) template to the science image."
738 )
739 templates: list[DifferenceImageTemplateInfo] | None = pydantic.Field(
740 description="Information about the template coadds that went into this difference image"
741 )
743 def deserialize(
744 self, archive: InputArchive[Any], *, bbox: Box | None = None, **kwargs: Any
745 ) -> DifferenceImage:
746 if kwargs: 746 ↛ 747line 746 didn't jump to line 747 because the condition on line 746 was never true
747 raise InvalidParameterError(f"Unrecognized parameters for DifferenceImage: {set(kwargs.keys())}.")
748 kernel = self.kernel.deserialize(archive) if self.kernel is not None else None
749 return DifferenceImage._from_visit_image(
750 super().deserialize(archive, bbox=bbox), kernel=kernel, templates=self.templates
751 )
753 def deserialize_component(self, component: str, archive: InputArchive[Any], **kwargs: Any) -> Any:
754 if kwargs and component not in ("image", "mask", "variance", "masked_image"):
755 raise InvalidParameterError(
756 f"Unsupported parameters for DifferenceImage component {component}: {set(kwargs.keys())}."
757 )
758 return super().deserialize_component(component, archive, **kwargs)