104.2. Explore the Butler repository

104.2. Explore the Butler repository¶

For the Rubin Science Platform at data.lsst.cloud.
Data Release: Data Preview 2
Container Size: large
LSST Science Pipelines version: r30.0.9
Last verified to run: 2026-07-20
Repository: github.com/lsst/tutorial-notebooks

Learning objective: How to explore Butler collections, datasets, dimensions, and schema.

LSST data products: Butler dimension records (metadata)

Packages: lsst.daf.butler

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 Butler is LSST Science Pipelines middleware for managing, reading, and writing datasets.

As the interface between the pipelines and the data, it is often referred to as "middleware."

Butler-related documentation:

• pipelines middleware Frequently Asked Questions
• butler python module documentation

This tutorial demonstrates how to explore the Butler: how to discover what kind of data is accessible and its schema, which dimensions to use to query and retrieve datasets, and how to visualize metadata.

Related tutorials: The first 100-level Butler tutorial in this series provides a basic introduction to how to use the Butler; later tutorials in this series demonstrate advanced Butler queries.

1.1. Import packages¶

Import the Butler module from the lsst.daf.butler package, the display module from the lsst.afw package (for image display), and the sphgeom package for spherical geometry functions.

Also import numpy and modules from matplotlib.

In [1]:

from lsst.daf.butler import Butler
import lsst.sphgeom as sphgeom
import lsst.geom as geom
from lsst.utils.plotting import (get_multiband_plot_colors,
                                 get_multiband_plot_symbols,
                                 get_multiband_plot_linestyles)

import numpy as np
import matplotlib.pyplot as plt
import matplotlib.lines as mlines
from matplotlib.patches import Polygon

1.2. Define parameters and functions¶

Create an instance of the Butler with the repository and collection for DP2, and assert that it exists.

In [2]:

butler = Butler("dp2", collections="dp2")
assert butler is not None

Use the colorblind-friendly colortable tableau-colorblind10.

In [3]:

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

Define the standard colors and linestyles to represent LSST filters.

In [4]:

filter_names = ['u', 'g', 'r', 'i', 'z', 'y']
filter_colors = get_multiband_plot_colors()
filter_symbols = get_multiband_plot_symbols()
filter_linestyles = get_multiband_plot_linestyles()

2. Explore the Butler¶

Learn how to explore the datasets available via the Butler, and their properties.

2.1. Repositories and collections¶

Repositories are defined by data release (e.g., DP0.2, DP1, DP2).

In Section 1.2 above, the DP2 repository ("dp2") and collection ("dp2") were defined when the Butler was instantiated with butler = Butler("dp2", collections="dp2"). Any queries for data run with the Butler would look only in that collection.

Print the information about collection dp2.

In [5]:

butler.collections.query_info("dp2")

Out[5]:

[CollectionInfo(name='dp2', type=<CollectionType.CHAINED: 3>, doc='', children=('LSSTCam/runs/DRP/DP2/v30_0_8/stage4/tagged_pretty_nImage_ecliptic', 'LSSTCam/runs/DRP/DP2/v30_0_8_rc4/DM-55060/hips/dp2_hipsMakeRGBPrettyPictureOutput', 'LSSTCam/runs/DRP/DP2/v30_0_8/stage4/tagged_pretty_coadds_ecliptic', 'LSSTCam/runs/DRP/DP2/v30_0_7/stage4/tagged_pretty_coadds_nonecliptic', 'LSSTCam/runs/DRP/DP2/v30_0_8/DM-55060/deep_coadd_rewrite/20260618T031503Z', 'LSSTCam/runs/DRP/DP2/DM-55060/stage3', 'LSSTCam/runs/DRP/DP2/DM-55060/stage4', 'LSSTCam/runs/DRP/DP2/DM-53881/stage2', 'LSSTCam/runs/DRP/DP2/DM-53881/stage1', 'LSSTCam/runs/DRP/DP2/DM-53881/inputs'), parents=None, dataset_types=None)]

It is also possible to explore what other repositories and collections exist.

List all available repositories.

In [6]:

butler.get_known_repos()

Out[6]:

{'dp02', 'dp02-remote', 'dp1', 'dp2'}

Collections are groups of self-consistent datasets, e.g., the outputs of a processing run that uses a single set of calibrations.

Store a list of all collection names in all_collections.

In [7]:

all_collections = butler.collections.query("*")

Option to print all collections.

In [8]:

# for collection in all_collections:
#     print(collection)

In [9]:

del all_collections

2.2. Dataset types¶

Commonly-used image dataset types:

• deep_coadd
• visit_image

Commonly-used catalog dataset types:

• object
• source

Uncomment and execute the following cell to print a long list of every possible dataset type.

Warning: The butler.registry module used below is being deprecated, but the functionality to queryDatasetTypes will be made available elsewhere.

Warning: The queryDatasetTypes function returns every type that has ever been named or defined, and is not a list of dataset types that are currently populated and available.

In [10]:

# butler.registry.queryDatasetTypes()

Option to print only the dataset types with coadd in their name.

In [11]:

# butler.registry.queryDatasetTypes('*coadd*')

Option to print the dataset types with map in their name.

In [12]:

# butler.registry.queryDatasetTypes('*map*')

Option to print the dataset types with object in their name.

In [13]:

# butler.registry.queryDatasetTypes('*object*')

2.3. Dimensions and elements¶

The dimensions and elements are the properties of a dataset type that can be constrained in a Butler query.

Commonly-used dimensions:

• band
• tract
• patch
• visit
• detector

Commonly-used element:

• visit_detector_region

Print the full lists of dimensions and elements.

In [14]:

print(butler.dimensions.getStaticDimensions())

{band, healpix1, healpix2, healpix3, healpix4, healpix5, healpix6, healpix7, healpix8, healpix9, healpix10, healpix11, healpix12, healpix13, healpix14, healpix15, healpix16, healpix17, htm1, htm2, htm3, htm4, htm5, htm6, htm7, htm8, htm9, htm10, htm11, htm12, htm13, htm14, htm15, htm16, htm17, htm18, htm19, htm20, htm21, htm22, htm23, htm24, instrument, skymap, ssp_hypothesis_table, day_obs, detector, group, physical_filter, ssp_balanced_index, ssp_hypothesis_bundle, subfilter, tract, visit_system, exposure, patch, visit}

In [15]:

print(butler.dimensions.getStaticElements())

{band, healpix1, healpix2, healpix3, healpix4, healpix5, healpix6, healpix7, healpix8, healpix9, healpix10, healpix11, healpix12, healpix13, healpix14, healpix15, healpix16, healpix17, htm1, htm2, htm3, htm4, htm5, htm6, htm7, htm8, htm9, htm10, htm11, htm12, htm13, htm14, htm15, htm16, htm17, htm18, htm19, htm20, htm21, htm22, htm23, htm24, instrument, skymap, ssp_hypothesis_table, day_obs, detector, group, physical_filter, ssp_balanced_index, ssp_hypothesis_bundle, subfilter, tract, visit_system, exposure, patch, visit, visit_definition, visit_detector_region, visit_system_membership}

Show that the dimensions for the deep_coadd dataset type are band, skymap, tract, patch, and that the returned format for images is CellCoadd.

In [16]:

butler.get_dataset_type('deep_coadd')

Out[16]:

DatasetType('deep_coadd', {band, skymap, tract, patch}, CellCoadd)

Print each dimension key using the dimensions.data_coordinate_keys attribute.

In [17]:

dataset_type = butler.get_dataset_type('deep_coadd')
for dimension in dataset_type.dimensions.data_coordinate_keys:
    print(dimension)

band
skymap
tract
patch

2.3.1. Required dimensions¶

Some dimensions are redundant, like band and physical_filter, or day_obs and visit. Print the full set of dimensions for the source dataset type, and then only the subset of required dimensions.

In [18]:

dataset_type = butler.get_dataset_type('source')

print('All dimensions:')
for dimension in dataset_type.dimensions.data_coordinate_keys:
    print(dimension)

print('\nRequired dimensions:')
for dimension in dataset_type.dimensions.required:
    print(dimension)

All dimensions:
instrument
visit
band
day_obs
physical_filter

Required dimensions:
instrument
visit

In [19]:

del dataset_type

2.4. Schema¶

The set of dimensions for a given dataset type have schema which define how a Butler query for a given dataset type can be constructed.

Print the schema for each dimension of the deep_coadd dataset type.

In [20]:

dataset_type = butler.get_dataset_type('deep_coadd')
for dimension in dataset_type.dimensions.data_coordinate_keys:
    print('dimension = ', dimension)
    print(butler.dimensions[dimension].schema)
    print(' ')

dimension =  band
band:
  name: string

dimension =  skymap
skymap:
  name: string
  hash: hash
    A hash of the skymap's parameters.
  tract_max: int
    Maximum ID for tracts in this skymap, exclusive.
  patch_nx_max: int
    Number of patches in the x direction in each tract.
  patch_ny_max: int
    Number of patches in the y direction in each tract.

dimension =  tract
tract:
  skymap: string
  id: int
  region: region

dimension =  patch
patch:
  skymap: string
  tract: int
  id: int
  cell_x: int
    Which column this patch occupies in the tract's grid of patches.
  cell_y: int
    Which row this patch occupies in the tract's grid of patches.
  region: region

The output above shows, for example, that a query for deep_coadd images can be constrained by the tract and patch id values (unique integers), or with region (see example in Section 3.1).

Option to print the schema for each dimension of the source dataset type.

In [21]:

# dataset_type = butler.get_dataset_type('source')
# for dimension in dataset_type.dimensions.data_coordinate_keys:
#     print('dimension = ', dimension)
#     print(butler.dimensions[dimension].schema)
#     print(' ')

Option to print the schema for the object table.

In [22]:

# dataset_type = butler.get_dataset_type('object')
# for dimension in dataset_type.dimensions.data_coordinate_keys:
#     print('dimension = ', dimension)
#     print(butler.dimensions[dimension].schema)
#     print(' ')

2.5. Dimension records¶

Return all records for a given dimension in the collection (i.e., all unique instruments, bands, tracts, patches, visits, detectors).

Print all unique instruments in the collection, and see that DP2 contains only LSSTCam data.

In [23]:

butler.query_dimension_records('instrument')

Out[23]:

[instrument.RecordClass(name='LSSTCam', visit_max=7050123199999, visit_system=2, exposure_max=7050123199999, detector_max=1000, class_name='lsst.obs.lsst.LsstCam')]

Print all unique bands (filters) in the collection, and see that the LSST filters ugrizy are all included.

In [24]:

butler.query_dimension_records('band')

Out[24]:

[band.RecordClass(name='g~nd'),
 band.RecordClass(name='z'),
 band.RecordClass(name='grid'),
 band.RecordClass(name='grid~nd'),
 band.RecordClass(name='z~nd'),
 band.RecordClass(name='streak'),
 band.RecordClass(name='sparsegrid'),
 band.RecordClass(name='spot~nd'),
 band.RecordClass(name='unknown'),
 band.RecordClass(name='sparsegrid~nd'),
 band.RecordClass(name='y~nd'),
 band.RecordClass(name='white~nd'),
 band.RecordClass(name='r'),
 band.RecordClass(name='ellipses'),
 band.RecordClass(name='g'),
 band.RecordClass(name='spot'),
 band.RecordClass(name='u'),
 band.RecordClass(name='i~nd'),
 band.RecordClass(name='i'),
 band.RecordClass(name='streak~nd'),
 band.RecordClass(name='u~nd'),
 band.RecordClass(name='y'),
 band.RecordClass(name='ellipses~nd'),
 band.RecordClass(name='r~nd'),
 band.RecordClass(name='white')]

Print the unique tracts in the DP2 collection, and see that there are 37876 of them. Use the keyword argument limit=None to ensure that the full result set is returned.

In [25]:

all_tracts = butler.query_dimension_records('tract', limit=None)
all_tract_ids = []
for tract in all_tracts:
    all_tract_ids.append(tract.id)
print('Number of DP2 tracts: ', len(all_tract_ids))
del all_tracts, all_tract_ids

Number of DP2 tracts:  18938

Options to get all visit or all detector ids.

In [26]:

# all_visits = butler.query_dimension_records('visit', limit=None)
# all_visit_ids = []
# for visit in all_visits:
#     all_visit_ids.append(visit.id)
# print('Number of DP2 visits: ', len(all_visit_ids))
# del all_visits, all_visit_ids

In [27]:

# all_detectors = butler.query_dimension_records('detector', limit=None)
# all_detector_ids = []
# for detector in all_detectors:
#     all_detector_ids.append(detector.id)
# print('Number of DP2 detectors: ', len(all_detector_ids))
# print(all_detector_ids)
# del all_detectors, all_detector_ids

2.6. DataIds¶

The dataId is a dictionary in which the keys are dimensions, and the values uniquely identify a data product of a given dataset type.

In Section 2.3., the dimensions of a deep_coadd were shown to be band, skymap, tract, and patch. The dataId for a unique deep_coadd image is a dictionary that contains the values for each dimension (key), such as:

dataId = {"band": "r", "skymap": "lsst_cells_v2", "tract": 5063, "patch": 15}

Option to print all unique dataId values for instrument, band, and tract. This returns similar lists as in Section 2.5 above.

In [28]:

# butler.query_data_ids('instrument')

In [29]:

# butler.query_data_ids('band')

Tracts are defined for a particular skymap.

In [30]:

# butler.query_data_ids('tract', skymap='lsst_cells_v2', limit=10)

2.7. Skymap, tract, and patch¶

The skymap defines the all-sky tesselation of tracts and patches for the deep coadd images.

Use the Butler's get_dataset_type function to show that the dimension for the skyMap dataset type is just skymap, and that the returned format for the skymap is SkyMap.

In [31]:

butler.get_dataset_type("skyMap")

Out[31]:

DatasetType('skyMap', {skymap}, SkyMap)

Show the schema for the skymap.

In [32]:

dataset_type = butler.get_dataset_type('skyMap')
for dimension in dataset_type.dimensions.data_coordinate_keys:
    print('dimension = ', dimension)
    print(butler.dimensions[dimension].schema)
    print(' ')

dimension =  skymap
skymap:
  name: string
  hash: hash
    A hash of the skymap's parameters.
  tract_max: int
    Maximum ID for tracts in this skymap, exclusive.
  patch_nx_max: int
    Number of patches in the x direction in each tract.
  patch_ny_max: int
    Number of patches in the y direction in each tract.

Return all skymap records for DP2: there is only one, lsst_cells_v2.

In [33]:

butler.query_dimension_records('skymap')

Out[33]:

[skymap.RecordClass(name='lsst_cells_v2', hash=b'\xa5\xf1\x1eV\x15\x05\xdck$\xec\x8fN\xf5G\xbcY.\x82\x99\xda', tract_max=18938, patch_nx_max=10, patch_ny_max=10)]

Retrieve the skymap from the butler.

In [34]:

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

Option to print the help for skymap.

In [35]:

# help(skymap)

Print all methods available for the returned skymap.

In [36]:

for tmp in dir(skymap):
    if tmp[0] != '_':
        print(tmp)

ConfigClass
SKYMAP_DATASET_TYPE_NAME
SKYMAP_RUN_COLLECTION_NAME
config
findAllTracts
findClosestTractPatchList
findTract
findTractIdArray
findTractPatchList
generateTract
getRaDecRange
getRingIndices
getSha1
logSkyMapInfo
register
updateSha1

A few of these methods are particularly useful.

Print the minimum and maximum RA and Dec covered by a given tract.

In [37]:

tract = skymap.getRaDecRange(5063)
tract

Out[37]:

(Angle(52.258064516129039, degrees),
 Angle(53.917050691244235, degrees),
 Angle(-28.264462809917354, degrees),
 Angle(-26.776859504132226, degrees))

Print the tract and patch for RA, Dec = $53.000, -28.015$ deg.

In [38]:

ra = 53.000
dec = -28.015
point = geom.SpherePoint(ra*geom.degrees, dec*geom.degrees)
tract = skymap.findTract(point)
patch = tract.findPatch(point)
print(tract.tract_id, patch.getSequentialIndex())
del ra, dec, tract, patch

5063 25

Tracts and patches overlap. Get all overlapping tracts and patches.

In [39]:

tplist = skymap.findTractPatchList([point])

Display the list of tracts and patches, tplist, and see that one tract and two patches overlap the coordinates.

In [40]:

tplist

Out[40]:

[(TractInfo(id=5063, ctrCoord=[0.5326332312997893, 0.7090801040994212, -0.46206844394039615]),
  (PatchInfo(index=Index2D(x=5, y=1), innerBBox=(minimum=(15000, 3000), maximum=(17999, 5999)), outerBBox=(minimum=(14850, 2850), maximum=(18149, 6149)), cellInnerDimensions=(150, 150), cellBorder=0, numCellsPerPatchInner=22),
   PatchInfo(index=Index2D(x=5, y=2), innerBBox=(minimum=(15000, 6000), maximum=(17999, 8999)), outerBBox=(minimum=(14850, 5850), maximum=(18149, 9149)), cellInnerDimensions=(150, 150), cellBorder=0, numCellsPerPatchInner=22)))]

Print the tract and two patch ids for all that overlap the provided coordinates.

In [41]:

for tmp in tplist:
    tract = tmp[0]
    patches = tmp[1]
    for patch in patches:
        print(tract.getId(), patch.getSequentialIndex())

5063 15
5063 25

In [42]:

del point, tplist, skymap

3. Visualize Butler metadata¶

3.1. Tract and patch boundaries¶

Use the skymap and deep_coadd metadata to draw tract and patch boundaries.

Retrieve all the tract and patch dimension records for all tracts and patches within 1 degree of RA, Dec = $53.000, -28.015$ deg. Those coordinates are near the center of the Extended Chandra Deep Field South (ECDFS).

In [43]:

region = sphgeom.Region.from_ivoa_pos("CIRCLE 53.000 -28.015 1.0")
tract_dimrecs = butler.query_dimension_records("tract",
                                               where="tract.region OVERLAPS :region",
                                               bind={"region": region},
                                               skymap="lsst_cells_v2",
                                               limit=None)
patch_dimrecs = butler.query_dimension_records("patch",
                                               where="patch.region OVERLAPS :region",
                                               bind={"region": region},
                                               skymap="lsst_cells_v2",
                                               limit=None)
print('Number of overlapping patches: ', len(patch_dimrecs))

Number of overlapping patches:  180

Define a color dictionary that assigns a color from the colortable to each tract.

In [44]:

color_dict = {}
for r, rec in enumerate(tract_dimrecs):
    color_dict[rec.dataId['tract']] = colors[r]
print(color_dict)

{4848: '#0072B2', 4849: '#009E73', 5062: '#D55E00', 5063: '#CC79A7', 5064: '#F0E442'}

The patch dimension records returned from the Butler include the region as a ConvexPolygon3D with four vertices.

Convert these vertices to 2D sky coordinates (RA and Dec), then use the Polygon module and the add_patch function to draw each patch in the figure, using a different color per patch.

In [45]:

fig, ax = plt.subplots(figsize=(6, 6))

for rec in patch_dimrecs:
    vertices = rec.region.getVertices()
    vertices_deg = []
    for vertex in vertices:
        vertices_deg.append([geom.SpherePoint(vertex).getRa().asDegrees(),
                             geom.SpherePoint(vertex).getDec().asDegrees()])
    polygon = Polygon(vertices_deg, closed=True, facecolor='None',
                      edgecolor=color_dict[rec.dataId['tract']])
    ax.add_patch(polygon)

ax.set_xlim(54.1, 52.1)
ax.set_ylim(-28.9, -27.1)
ax.set_xlabel('RA')
ax.set_ylabel('Dec')

handles = []
labels = []
for clr in color_dict:
    line = mlines.Line2D([], [], color=color_dict[clr], linestyle='-')
    handles.append(line)
    labels.append(clr)
plt.legend(loc='upper left', ncol=3, handles=handles, labels=labels)

plt.title('Tracts and patches that overlap ECDFS')
plt.show()

Figure 1: The boundaries of the 180 patches from the five different tracts that overlap the selected position within the ECDFS DP2 field.

In [46]:

del region, tract_dimrecs, patch_dimrecs

3.2. Visit dates¶

Plot the cumulative histogram of the number of visits in the ECDFS field over time, by filter.

Define the search region as in Section 3.1, above.

In [47]:

region = sphgeom.Region.from_ivoa_pos("CIRCLE 53.000 -28.015 1.0")

For each filter, return all visit dimension records that overlap the region. Create an array of the start times, in MJD, from every visit's timespan. Plot the cumulative distribution of start time to see how observations accumulated for ECDFS, per filter.

In [48]:

fig = plt.figure(figsize=(6, 4))
for band in filter_names:
    visit_dimrecs = butler.query_dimension_records("visit",
                                                   where="band.name = :band AND \
                                                   visit.region OVERLAPS :region",
                                                   bind={"band": band, "region": region})
    temp = []
    for visit in visit_dimrecs:
        temp.append(visit.timespan.begin.mjd)
    all_visit_begin_mjd = np.sort(np.asarray(temp, dtype='float'))
    temp_label = band + ' (' + str(len(visit_dimrecs)) + ')'

    use_bins = np.arange(np.min(all_visit_begin_mjd),
                         np.max(all_visit_begin_mjd), 1)
    n, bins, patches = plt.hist(all_visit_begin_mjd, bins=use_bins,
                                cumulative=True, histtype='step',
                                linewidth=2, alpha=0.7,
                                color=filter_colors[band],
                                label=temp_label)
    for patch in patches:
        patch.set_linestyle(filter_linestyles[band])

    del temp, all_visit_begin_mjd, temp_label, n, bins, patches

plt.legend(loc='upper left')
plt.xlabel('MJD')
plt.ylabel('Cumulative number of visits')
plt.show()

Figure 2: The total, cumulative number of visits by Modified Julian Date (MJD) for each filter.

Exercises for the learner¶

1. Print all dataset types with source in their name (Section 2.2).
2. Print each dimension key for dataset type visit_image (Section 2.3).
3. Show that seven patches from three tracts overlap coordinates RA, Dec = $53.84, -28.35$ deg.

In [ ]: