103.1. Butler image access

103.1. Butler image access¶

For the Rubin Science Platform at data.lsst.cloud.
Data Release: Data Preview 1
Container Size: large
LSST Science Pipelines version: r29.1.1
Last verified to run: 2025-06-21
Repository: github.com/lsst/tutorial-notebooks

Learning objective: How to use the Butler to access image data.

LSST data products: deep_coadd, visit_image

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 and Timespan modules from the lsst.daf.butler package, and the display module from the lsst.afw package (for image display). Also import the Time function from the astropy.time module.

In [1]:

from lsst.daf.butler import Butler, Timespan
import lsst.afw.display as afwDisplay
from astropy.time import Time

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 dafButler.Butler function to instantiate a butler that is configured to access the Data Preview 1 (DP1) data release.

In [3]:

butler = Butler("dp1", collections="LSSTComCam/DP1")
assert butler is not None

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 available 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

To search and retrieve the deep or template coadds is the same query format, so only deep_coadd images are used as an example in Section 3.1.

To search and retrieve the visit or difference images is the same query format, so only visit_images are used as an example in Section 3.2.

The queries for raw images are demonstrated in the 200-level tutorial on raw images.

3.1. Deep coadd images¶

Dataset type name: deep_coadd.

Define an RA, Dec, and band (filter). These coordinates are near the center of the Extended Chandra Deep Field South (ECDFS).

In [4]:

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

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 = 'r' AND patch.region OVERLAPS POINT(53.076, -28.11)

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

3.2. Visit images¶

Dataset type name: visit_image.

Use the same RA, Dec, and band as in Section 3.1.

Define a time span that is one night, early on in the series of observations with LSSTComCam.

Note: use International Atomic Time (Temps Atomique International; TAI) to define astropy times, as the butler uses (and expects) TAI times. Times can be defined as calendar dates or MJD, as in time1 and time2 below.

In [10]:

time1 = Time("2024-11-09T00:00:00.0", format="isot", scale="tai")
time2 = Time(60624.0, format="mjd", scale="tai")
timespan = Timespan(time1, time2)
del time1, time2

Search the Butler for visit_images that match the query constraints, this time using the Butler's bind functionality to create the query.

In [11]:

dataset_refs = butler.query_datasets("visit_image",
                                     where="band.name = :band AND \
                                     visit.timespan OVERLAPS :timespan AND \
                                     visit_detector_region.region OVERLAPS POINT(:ra, :dec)",
                                     bind={"band": band, "timespan": timespan,
                                           "ra": ra, "dec": dec},
                                     order_by=["visit.timespan.begin"])

Use the butler.get function to retrieve the visit_image for the first of the returned dataset references.

In [12]:

visit_image = butler.get(dataset_refs[0])

Display the retrieved image in Firefly.

In [13]:

afw_display.mtv(visit_image)
afw_display.setMaskTransparency(100)

Clean up.

In [14]:

del ra, dec, band, timespan, dataset_refs, visit_image

In [ ]: