201.18. Deep_coadd_input_summary table

201.18. Deep_coadd_input_summary table¶

For the Rubin Science Platform at data.lsst.cloud.
Data Release: Data Preview 2
Container Size: Large
LSST Science Pipelines version: r30.0.11
Last verified to run: 2026-08-16
Repository: github.com/lsst/tutorial-notebooks
DOI: 10.11578/rubin/dc.20250909.20

Learning objective: To understand the contents of the deep_coadd_input_summary table and how to access it.

LSST data products: deep_coadd_input_summary, visit_detector_table, skyMap

Packages: lsst.daf.butler, lsst.geom

Credit: Originally developed by the Rubin Community Science team. Please consider acknowledging them if this notebook is used for the preparation of journal articles, software releases, or other notebooks.

Get Support: Everyone is encouraged to ask questions or raise issues in the Support Category of the Rubin Community Forum. Rubin staff will respond to all questions posted there.

1. Introduction¶

The deep_coadd_input_summary table provides a list of the visit detector images that contribute to each deep coadd. Note that the deep_coadd_input_summary table does not include information about which visit detector images contributed to each deep coadd cell. The deep_coadd_input_summary table is available only via the butler.

• butler table name: deep_coadd_input_summary
• columns: 7
• rows: 21,235,500

This notebook demonstrates how to access the deep_coadd_input_summary table, join it with the visit_detector_table to access additional metadata about each visit detector image, and make a plot illustrating the spatial overlap of a coadd patch with the corresponding input visit detector images.

Related tutorials: 202.1. Deep coadds demonstrates how to access information about the visit detector images that contributed to each cell of a deep coadd.

1.1. Import packages¶

Import standard python packages numpy, matplotlib, itertools, and astropy.

From the lsst package, import modules for accessing the butler and for geometry from the LSST Science Pipelines (pipelines.lsst.io).

In [1]:

from lsst.daf.butler import Butler
import lsst.geom as geom

from astropy.table import join, unique

import matplotlib.pyplot as plt
import matplotlib.patches as patches

from itertools import cycle

import numpy as np

1.2. Define parameters and functions¶

Instantiate a Butler for DP2.

In [2]:

butler = Butler('dp2', collections="dp2")

Define the plotting color palette.

In [3]:

plt.style.use('seaborn-v0_8-colorblind')
prop_cycle = plt.rcParams['axes.prop_cycle']
colors = prop_cycle.by_key()['color']

2. Columns¶

A schema is not yet published for deep_coadd_input_summary. The table contains one row per visit detector image per deep coadd that the visit detector image contributes to. The columns are:

• tract: ID number of the top level, 'tract', within the standard LSST skymap
• patch: ID number of the second level, 'patch', within the standard LSST skymap
• visit: visit ID number
• detector: detector ID number
• weight: dimensionless weight for the visit detector image when building the deep coadd, which is built using a weighted mean of the relevant visit detector images
• goodpix: number of pixels from the visit detector image that overlap the coadd patch
• band: name of the band used to take the visit detector image

3. Data access¶

The deep_coadd_input_summary table is only available via Butler.

Show that the only dimension for the deep_coadd_input_summary table is the skymap.

In [4]:

butler.get_dataset_type('deep_coadd_input_summary')

Out[4]:

DatasetType('deep_coadd_input_summary', {skymap}, ArrowAstropy)

In [5]:

butler.get_dataset_type('deep_coadd_input_summary').dimensions.required

Out[5]:

{skymap}

3.1. Read in the table¶

There is only one dataset of dataset type deep_coadd_input_summary, which is the full table.

In [6]:

dataset_refs = butler.query_datasets("deep_coadd_input_summary")
len(dataset_refs)

Out[6]:

1

Read in the deep_coadd_input_summary table.

In [7]:

ref = dataset_refs[0]
deep_coadd_input_summary = butler.get(ref)

3.2. Examine the full table's contents¶

Sort the table and show the first 10 rows of the table.

In [8]:

deep_coadd_input_summary.sort(['tract', 'patch', 'visit', 'detector'])
deep_coadd_input_summary[0:10]

Out[8]:

Table length=10

tract	patch	visit	detector	weight	goodpix	band
int32	int32	int64	int32	float64	int32	str3
2054	0	2025090600470	45	0.0003874042573338706	4143707	i
2054	0	2025090600470	48	0.0003874042573338706	8423629	i
2054	0	2025090600470	49	0.0003874042573338706	664839	i
2054	0	2025102400143	137	0.0013865008561924266	12104010	i
2054	0	2025102400143	140	0.0013865008561924266	398861	i
2054	0	2025102400143	144	0.0013865008561924266	1047704	i
2054	1	2025090600470	48	0.00038877146327636426	4557158	i
2054	1	2025090600470	49	0.00038877146327636426	8037442	i
2054	1	2025090600470	51	0.00038877146327636426	77424	i
2054	1	2025090600470	52	0.00038877146327636426	757990	i

The number of unique visits in the deep_coadd_input_summary table is on the same order as the number of visits in the DP2 observational dataset, but somewhat smaller, for instance due to quality cuts restricting which visits can contribute to the coadds.

In [9]:

len(np.unique(deep_coadd_input_summary['visit']))

Out[9]:

16790

The number of unique tracts in the deep_coadd_input_summary table is nearly identical to the number of unique tracts within which DP2 deep coadds are available (2,191). The set of deep coadd tracts included in DP2 is a subset of the tracts included in the deep_coadd_input_summary table.

In [10]:

len(np.unique(deep_coadd_input_summary['tract']))

Out[10]:

2192

Compute the number of unique (tract, patch) pairs in the deep_coadd_input_summary table. This number is ~0.2% larger than the number of unique (tract, patch) pairs in the DP2 CoaddPatches table. The CoaddPatches set of unique (tract, patch) pairs is a subset of the deep_coadd_input_summary set of unique (tract, patch) pairs. The (tract, patch) pairs present in deep_coadd_input_summary but not included as deep coadds in DP2 generally have very low coverage, with most having only a single overlapping visit detector image.

In [11]:

len(unique(deep_coadd_input_summary, keys=['tract', 'patch']))

Out[11]:

197420

Print the list of unique bands in the deep_coadd_input_summary table. This matches the list of six LSST filters.

In [12]:

np.unique(deep_coadd_input_summary['band'])

Out[12]:

<Column name='band' dtype='str3' length=6>

g

i

r

u

y

z

The histogram of goodpix values is peaked toward relatively low goodpix because the sky area within which a detector center could land such that it has a small overlap with the patch footprint is larger than the sky area in which a detector center could land while having a large overlap with the patch footprint. This distribution also serves as an illustration that visits are distributed and oriented randomly with respect to the coadd footprints. The goodpix distribution extends up to values of ~14.5 million pixels, which makes sense given that each LSST detector has roughly 4000x4000 = 16 million pixels.

In [13]:

plt.hist(deep_coadd_input_summary['goodpix'], bins=np.arange(0, 16e6, 1e5))
plt.xlabel('number of detector pixels overlapping deep coadd patch')
plt.ylabel('number of occurrences')
plt.show()

Figure 1: Histogram of goodpix column values within the full deep_coadd_input_summary table. The histogram peak occurs at a goodpix value well below the total number of pixels contained in a full visit detector image.

3.3. Visualize coadd inputs for one tract¶

Consider an r-band deep coadd patch in the Extended Chandra Deep Field South (ECDFS). Determine the tract and patch numbers within the LSST skymap.

In [14]:

ra = 53.076
dec = -28.110
band = 'r'

point = geom.SpherePoint(ra * geom.degrees, dec * geom.degrees)

skymap = butler.get("skyMap", skymap="lsst_cells_v2", collections="skymaps")

tract_info = skymap.findTract(point)
tract_id = tract_info.tract_id

patch_info = tract_info.findPatch(point)
patch_index = patch_info.getSequentialIndex()

print(f"Tract: {tract_id}, Patch: {patch_index}")

Tract: 5063, Patch: 15

Downselect to the rows of the deep_coadd_input_summary table that represent visit detector images contributing to the r-band deep coadd for this patch.

In [15]:

ecdfs_patch_input_mask = (
    (deep_coadd_input_summary['tract'] == tract_id)
    & (deep_coadd_input_summary['patch'] == patch_index)
    & (deep_coadd_input_summary['band'] == band)
)
ecdfs_patch_input_summary = deep_coadd_input_summary[ecdfs_patch_input_mask]

Print the number of r-band visit detector images contributing to this deep coadd patch.

In [16]:

len(ecdfs_patch_input_summary)

Out[16]:

98

Clear memory associated with the full deep_coadd_input_summary table, as the full table is no longer needed within this notebook.

In [17]:

del deep_coadd_input_summary

3.3.1. Join to the VisitDetector table¶

Join the example ECDFS deep coadd patch's input table to the VisitDetector table in order to access additional metadata, such as detector (RA, Dec) coordinates, for each relevant visit detector image. Access the VisitDetector table via the butler.

In [18]:

dataset_refs = butler.query_datasets("visit_detector_table")
ref = dataset_refs[0]
visit_detector_table = butler.get(ref)

Join the example ECDFS deep coadd patch's input table to the VisitDetector table.

In [19]:

ecdfs_patch_input_summary.rename_column('visit', 'visitId')
ecdfs_patch_input_summary.rename_column('detector', 'detectorId')

joined_table = join(ecdfs_patch_input_summary, visit_detector_table,
                    keys=['visitId', 'detectorId'], join_type='left')

Clear memory associated with the full visit_detector_table, as the full table is no longer needed within this notebook.

In [20]:

del visit_detector_table

3.3.2. Plot overlap between deep coadd and input detectors¶

Create a rectangle representing the sky footprint of the chosen ECDFS deep coadd patch.

In [21]:

tract_info = skymap[tract_id]
patch_info = tract_info.getPatchInfo(patch_index)

wcs = patch_info.wcs
patch_box = patch_info.outer_bbox

pixel_corners = patch_box.getCorners()

sky_corners = [wcs.pixelToSky(geom.Point2D(pixel_pos)) for pixel_pos in pixel_corners]

ra_patch_corners = [sky_pos.getRa().asDegrees() for sky_pos in sky_corners]
dec_patch_corners = [sky_pos.getDec().asDegrees() for sky_pos in sky_corners]

vertices = list(zip(ra_patch_corners, dec_patch_corners))

patch_rect = patches.Polygon(
    vertices,
    closed=True,
    edgecolor='gray',
    facecolor='gray',
    alpha=0.3,
    linewidth=2,
    label='coadd patch footprint'
)

Plot the example ECDFS patch's footprint (gray rectangle) along with a subset of the input visit detector image boundaries (quadrilaterals of various colors). The use of [::6] below means select every 6th input visit detector image. All of the input visit detector image footprints have overlap with the deep coadd patch footprint, as expected.

In [22]:

plt.figure()

ax = plt.gca()

ax.add_patch(patch_rect)

input_detectors_to_plot = joined_table[::6]

color_iterator = cycle(colors)

for row in input_detectors_to_plot:
    vertices_detector = list(zip([row['llcra'], row['ulcra'], row['urcra'], row['lrcra']],
                                 [row['llcdec'], row['ulcdec'], row['urcdec'], row['lrcdec']]))
    detector_outline = patches.Polygon(
        vertices_detector,
        closed=True,
        edgecolor=next(color_iterator),
        facecolor='none',
        alpha=0.8,
        linewidth=1,
    )

    ax.add_patch(detector_outline)

plt.legend()
plt.xlim((53.3, 52.7))
plt.ylim((-28.5, -27.75))
plt.xlabel('RA (deg)')
plt.ylabel('Dec (deg)')

plt.show()

Figure 2: A coadd patch footprint in ECDFS (gray rectangle) with a subset of the overlapping r-band visit detector image boundaries overplotted (quadrilaterals of various colors). All visit detector image footprints have overlap with the coadd patch footprint.