CellCoadd#

class lsst.images.cells.CellCoadd(image, *, mask=None, variance=None, mask_fractions=None, noise_realizations=(), mask_schema=None, sky_projection=None, band=None, psf, aperture_corrections=None, patch=None, provenance=None, backgrounds=None)#

Bases: MaskedImage

A coadd comprised of cells on a regular grid.

Parameters:

image (Image) – The main image plane. If this has a SkyProjection, it will be used for all planes unless a sky_projection is passed separately.
mask (Mask | None, default: None) – A bitmask image that annotates the main image plane. Must have the same bounding box as image if provided. Any attached sky_projection is replaced (possibly by None).
variance (Image | None, default: None) – The per-pixel uncertainty of the main image as an image of variance values. Must have the same bounding box as image if provided, and its units must be the square of image.unit or None. Values default to 1.0. Any attached sky_projection is replaced (possibly by None).
mask_fractions (Mapping[str, Image] | None, default: None) – A mapping from an input-image mask plane name to an image of the weights sums of that plane.
noise_realizations (Sequence[Image], default: ()) – A sequence of images with Monte Carlo realizations of the noise in the coadd.
mask_schema (MaskSchema | None, default: None) – Schema for the mask plane. Must be provided if and only if mask is not provided.
sky_projection (Optional[SkyProjection[TractFrame]], default: None) – Projection that maps the pixel grid to the sky. Can only be None if a projection is already attached to image.
band (str | None, default: None) – Name of the band.
psf (CellPointSpreadFunction) – Effective point-spread function for the coadd. The missing cells reported by psf.bounds are assumed to apply to all image data for that cell as well (i.e. there is a PSF for a cell if and only if there is image data for that cell).
aperture_corrections (Mapping[str, CellField] | None, default: None) – Aperture corrections for different photometry algorithms.
patch (PatchDefinition | None, default: None) – Identifiers and geometry of the full patch, if the image is confined to a single patch. When present, the cell grid of the PSF and provenance (if provideD) must be the full patch grid, even if its bounds select a subset of that area.
provenance (CoaddProvenance | None, default: None) – Information about the images that went into the coadd.
backgrounds (BackgroundMap | None, default: None) – Background models associated with this image.

Attributes Summary

`absolute`	A proxy object for slicing a generalized image using absolute pixel coordinates.
`aperture_corrections`	Aperture corrections for different photometry algorithms (`dict` [`str`, `CellField`]).
`astropy_wcs`	An Astropy WCS for this image's pixel array.
`backgrounds`	A mapping of backgrounds associated with this image (`BackgroundMap`).
`band`	Name of the band (`str` or `None`).
`bbox`	The bounding box shared by all three image planes (`Box`).
`bounds`	The grid of cells that overlap this coadd and a set of missing cells (`CellGridBounds`).
`butler_dataset`	The butler dataset reference for this image (`lsst.daf.butler.SerializedDatasetRef` \| `None`).
`butler_provenance`	The butler inputs and ID of the task quantum that produced this dataset (`lsst.daf.butler.DatasetProvenance` \| `None`).
`fits_wcs`	An Astropy FITS WCS for this image's pixel array.
`grid`	The grid of cells that overlap this coadd (`CellGrid`).
`image`	The main image plane (`Image`).
`local`	A proxy object for slicing a generalized image using "local" or "array" pixel coordinates.
`mask`	The mask plane (`Mask`).
`mask_fractions`	A mapping from an input-image mask plane name to an image of the weights sums of that plane (`Mapping` [`str`, `Image`]).
`metadata`	Arbitrary flexible metadata associated with the image (`dict`).
`noise_realizations`	A sequence of images with Monte Carlo realizations of the noise in the coadd (`Sequence` [`Image`]).
`patch`	Identifiers and geometry of the full patch, if the image is confined to a single patch (`PatchDefinition`).
`provenance`	Information about the images that went into the coadd (`CoaddProvenance` or `None`).
`psf`	Effective point-spread function for the coadd (`CellPointSpreadFunction`).
`sky_projection`	The projection that maps the pixel grid to the sky (`SkyProjection` [`TractFrame`]).
`skymap`	Name of the skymap (`str`).
`tract`	ID of the tract (`int`).
`unit`	The units of the image plane (`astropy.units.Unit`).
`variance`	The variance plane (`Image`).
`yx0`	The coordinates of the first pixel in the array (`YX` [`int`]).

Methods Summary

`apply_background`(name)	Subtract the background with the given name, modifying the image in place.
`bbox_from_sky_circle`(center, radius[, clip])	Calculate the bounding box on this image corresponding to a circular region on the sky.
`copy`()	Deep-copy the coadd.
`from_hdu_list`(hdu_list, *[, fits_wcs_frame])	Reconstruct a `MaskedImage` from a cut-down `lsst.images` FITS HDU list.
`from_legacy`(legacy, *[, unit, plane_map, ...])	Convert from an `lsst.afw.image.MaskedImage` instance.
`from_legacy_cell_coadd`(legacy, *[, ...])	Convert from a `lsst.cell_coadds.MultipleCellCoadd` instance.
`read`(path, **kwargs)	Read an instance of this class from a file.
`read_legacy`(uri, *[, preserve_quantization, ...])	Read a FITS file written by `lsst.afw.image.MaskedImage.writeFits`.
`serialize`(archive)	Serialize the image to an output archive.
`to_legacy`([copy, plane_map])	Convert to a `lsst.afw.image.Exposure` instance.
`to_legacy_cell_coadd`([copy, plane_map])	Convert to a `lsst.cell_coadds.MultipleCellCoadd` instance.
`write`(path, **kwargs)	Write this object to a file.

Attributes Documentation

absolute#

A proxy object for slicing a generalized image using absolute pixel coordinates.

Notes

In this convention, the first row and column of the pixel grid is bbox.start. A subimage and its parent image share the same absolute pixel coordinate system, and most lsst.images types (e.g. Box, SkyProjection, PointSpreadFunction) operate exclusively in this system.

Note that astropy.wcs and numpy.ndarray are not aware of the bbox.start offset that defines tihs coordinates system; use local slicing for indices obtained from those.

mask#

The mask plane (Mask).

Assigning a new Mask (for example one returned by add_planes) replaces the mask plane. The new mask must share this image’s bounding box; its sky projection is replaced with the image’s.

mask_fractions#: A mapping from an input-image mask plane name to an image of the weights sums of that plane (Mapping [str, Image]).

metadata#

Arbitrary flexible metadata associated with the image (dict).

Notes

Metadata is shared with subimages and other views. It can be disconnected by reassigning to a copy explicitly:

image.metadata = image.metadata.copy()

noise_realizations#: A sequence of images with Monte Carlo realizations of the noise in the coadd (Sequence [Image]).

patch#: Identifiers and geometry of the full patch, if the image is confined to a single patch (PatchDefinition).

provenance#: Information about the images that went into the coadd (CoaddProvenance or None).

psf#: Effective point-spread function for the coadd (CellPointSpreadFunction).

sky_projection#: The projection that maps the pixel grid to the sky (SkyProjection [TractFrame]).

skymap#: Name of the skymap (str).

tract#: ID of the tract (int).

unit#: The units of the image plane (astropy.units.Unit).

variance#: The variance plane (Image).

yx0#: The coordinates of the first pixel in the array (YX [int]).

Methods Documentation

apply_background(name)#

Subtract the background with the given name, modifying the image in place.

If name is None, restore the original background.

Parameters:: name (str | None) – Name of the background to subtract, or None to restore the original background.
Return type:: None

bbox_from_sky_circle(center, radius, clip=False)#

Calculate the bounding box on this image corresponding to a circular region on the sky.

Parameters:

center (SkyCoord) – The center of the circle, as a scalar astropy.coordinates.SkyCoord in any frame.
radius (Angle) – Radius of the circle, as a scalar astropy.coordinates.Angle.
clip (bool, default: False) – If True (False is default), clip pixel bounds when the circle extends outside the image. If False an exception is raised if any part of the circle is off the image.

Returns:

Bounding box enclosing the circle in this image’s pixel coordinates.

Return type:

Box

Raises:

NotContainedError – Raised if the requested region is entirely off the image or if any part of the region is off the image and clipping is False.
ValueError – Raised if center or radius is not scalar, or if this image has no sky projection.

copy()#

Deep-copy the coadd.

Return type:: CellCoadd

classmethod from_hdu_list(hdu_list, *, fits_wcs_frame=GeneralFrame(unit=Unit('pix'), frame_type='GENERAL'))#

Reconstruct a MaskedImage from a cut-down lsst.images FITS HDU list.

This assumes the PRIMARY, IMAGE, MASK, and VARIANCE HDUs written for the masked-image cut-outs produced by dax_images_cutout: a real lsst.images file with its JSON-tree, index, and any nested-archive HDUs dropped. The reconstructed object can be re-serialized as a normal lsst.images file (with schema and index) so it can be read with the full lsst.images infrastructure.

Parameters:

hdu_list (HDUList) – HDU list with IMAGE, MASK, and VARIANCE extensions and a primary HDU.
fits_wcs_frame (Frame | None, default: GeneralFrame(unit=Unit("pix"), frame_type='GENERAL')) – Pixel-grid Frame for the SkyProjection reconstructed from the FITS WCS. Defaults to a plain pixel frame; pass None to skip attaching a projection.

Returns:

The reconstructed masked image.

Return type:

MaskedImage

Raises:

ValueError – Raised if the MASK HDU has neither MSKN nor MP_ mask- plane cards, since the mask schema cannot then be reconstructed, or if hdu_list contains more than one MASK HDU (multiple MASK extensions, distinguished by EXTVER, are not handled here and would otherwise be silently dropped).

Notes

Both mask-plane conventions are supported: the self-describing MSKN/MSKM/MSKD cards written by lsst.images, and the legacy lsst.afw.image MP_* cards (as produced by dax_images_cutout from afw-written images). Legacy masks are mapped to a new schema with the same plane-guessing used by read_legacy.

Unlike read_legacy, the legacy MP_* mask-plane cards are kept (not stripped) for backwards compatibility, since this path reconstructs a file that may still be read by legacy tooling. They are re-indexed to the reshuffled schema so each MP_ bit matches the plane’s position in the written MSKN layout.

The headers of the HDUs in hdu_list are modified in place: the WCS and mask-schema cards interpreted here are stripped from the caller’s headers.

static from_legacy(legacy, *, unit=None, plane_map=None, sky_projection=None)#

Convert from an lsst.afw.image.MaskedImage instance.

Parameters:

legacy (TypeAliasType) – An lsst.afw.image.MaskedImage instance that will share image and variance (but not mask) pixel data with the returned object.
unit (UnitBase | None, default: None) – Units of the image.
plane_map (Mapping[str, MaskPlane] | None, default: None) – A mapping from legacy mask plane name to the new plane name and description. If not provided, the right legacy mask plane will be guessed, but this can depend on which mask planes the legacy mask actually has set.
sky_projection (Optional[SkyProjection[Any]], default: None) – Projection from pixels to xky.

Return type:

MaskedImage

static from_legacy_cell_coadd(legacy, *, plane_map=None, tract_info, bbox=None)#

Convert from a lsst.cell_coadds.MultipleCellCoadd instance.

Parameters:

legacy (TypeAliasType) – A lsst.cell_coadds.MultipleCellCoadd instance to convert.
plane_map (Mapping[str, MaskPlane] | None, default: None) – A mapping from legacy mask plane name to the new plane name and description.
tract_info (TypeAliasType) – Information about the full tract.
bbox (Box | None, default: None) – Bounding box of the image. The default is to include just the bounding box of the valid cells, which may not cover a full patch.

Return type:

CellCoadd

classmethod read(path, **kwargs)#

Read an instance of this class from a file.

A thin convenience wrapper around lsst.images.serialization.read_archive that fixes the expected in-memory type to this class. The container format is inferred from path’s extension.

Parameters:

path (str | ParseResult | ResourcePath | Path) – File to read; convertible to lsst.resources.ResourcePath.
**kwargs (Any) – Forwarded to read_archive (e.g. bbox to read a subimage).

Return type:

Self

static read_legacy(uri, *, preserve_quantization=False, plane_map=None, component=None, fits_wcs_frame=None)#

Read a FITS file written by lsst.afw.image.MaskedImage.writeFits.

Parameters:

uri (str | ParseResult | ResourcePath | Path) – URI or file name.
preserve_quantization (bool, default: False) – If True, ensure that writing the masked image back out again will exactly preserve quantization-compressed pixel values. This causes the image and variance plane arrays to be marked as read-only and stores the original binary table data for those planes in memory. If the MaskedImage is copied, the precompressed pixel values are not transferred to the copy.
plane_map (Mapping[str, MaskPlane] | None, default: None) – A mapping from legacy mask plane name to the new plane name and description. If not provided, the right legacy mask plane will be guessed, but this can depend on which mask planes the legacy mask actually has set.
component (Optional[Literal['image', 'mask', 'variance']], default: None) – A component to read instead of the full image.
fits_wcs_frame (Frame | None, default: None) – If not None and the HDU containing the image plane has a FITS WCS, attach a SkyProjection to the returned masked image by converting that WCS. When component is one of "image", "mask", or "variance", a FITS WCS from the component HDU is used instead (all three should have the same WCS).

Return type:

Any

serialize(archive)#

Serialize the image to an output archive.

Parameters:: archive (OutputArchive[Any]) – Archive to write to.
Return type:: CellCoaddSerializationModel

to_legacy(copy=None, plane_map=None)#

Convert to a lsst.afw.image.Exposure instance.

Parameters:

copy (bool | None, default: None) – If True, always copy the image and variance pixel data. If False, return a view, and raise TypeError if the pixel data is read-only (this is not supported by afw). If None, only copy if the pixel data is read-only. Mask pixel data is always copied.
plane_map (Mapping[str, MaskPlane] | None, default: None) – A mapping from legacy mask plane name to the new plane name and description.

Returns:

A legacy representation of the coadd. This will have its wcs, psf, filter, photoCalib, and metadata components set. The apCorrMap component is not set, because there is no true lsst.afw.math.BoundedField representation for cell-coadd aperture corrections, and the coaddInputs component is not set because that data structure cannot fully capture cell-coadd provenance.

Return type:

lsst.afw.image.Exposure

Notes

This method requires the provenance attribute to have been populated at construction.

to_legacy_cell_coadd(copy=None, plane_map=None)#

Convert to a lsst.cell_coadds.MultipleCellCoadd instance.

Parameters:

copy (bool | None, default: None) – If True, always copy the image and variance pixel data. If False, return a view, and raise TypeError if the pixel data is read-only (this is not supported by afw). If None, only copy if the pixel data is read-only. Mask pixel data is always copied.
plane_map (Mapping[str, MaskPlane] | None, default: None) – A mapping from legacy mask plane name to the new plane name and description.

Return type:

TypeAliasType

write(path, **kwargs)#

Write this object to a file.

A thin convenience wrapper around lsst.images.serialization.write_archive. The container format is chosen from path’s extension.

Parameters:

path (str) – Destination file path. Must not already exist.
**kwargs (Any) – Forwarded to write_archive (e.g. compression_options and compression_seed for FITS).

Return type:

None