103.1. Butler image access

103.1. Butler image access¶

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 use the Butler to access image data.

LSST data products: deep_coadd

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 the LSST Science Pipelines interface for managing, reading, and writing datasets.

It is recommended to use the Butler when accessing image data in the Notebook aspect.

This tutorial is a very short example of how to access images via the Butler.

Related tutorials: See the 100-level series on how to use the Butler for deeper explanations and demonstrations of the Butler's functionality.

1.1. Import packages¶

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

In [1]:

from lsst.daf.butler import Butler
import lsst.afw.display as afwDisplay

1.2. Define parameters and functions¶

Set afwDisplay to use Firefly, and define afw_display to show images in frame 1.

In [2]:

afwDisplay.setDefaultBackend("firefly")
afw_display = afwDisplay.Display(frame=1)

2. Create an instance of the Butler¶

Use the Butler function to instantiate a butler that is configured to access the Data Preview 2 (DP2) data release.

In [3]:

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

3. Query and retrieve images¶

The most common Butler image queries constrain the band (filter), sky location (coordinate), and/or time of observation.

The five types of images are:

• deep_coadd : stacks of multiple visit images
• template_coadd : stacks of the third best-seeing images
• visit_image : processed and calibrated image from one visit, by detector
• difference_image : the result of subtracting a template from a visit image
• raw : the exposure from camera readout

For Early DP2 only deep coadd images are available.

3.1. Deep coadd images¶

Dataset type name: deep_coadd.

Define an RA, Dec, and band (filter). These coordinates are in the ELAISS1 deep drilling field.

In [4]:

ra = 10.26
dec = -44.49

band = 'i'

Define a query string using the coordinates and band as search constraints.

In [5]:

query = """band.name = '{}' AND patch.region OVERLAPS POINT({}, {})
        """.format(band, ra, dec)
print(query)

band.name = 'i' AND patch.region OVERLAPS POINT(10.26, -44.49)

Use the butler.query_datasets function to search the Butler for deep_coadd images that match the search constraints of the defined query.

In [6]:

dataset_refs = butler.query_datasets("deep_coadd", where=query)

Use the butler.get function to retrieve the image associated with the first of the returned datasets.

In [7]:

deep_coadd = butler.get(dataset_refs[0])

Display the retrieved image in Firefly.

In [8]:

afw_display.mtv(deep_coadd)
afw_display.setMaskTransparency(100)

Clean up.

In [9]:

del query, dataset_refs, deep_coadd

In [ ]: