104.1. Get started with the Butler#

104_1_Get_started_with_the_butler

104.1. Get started with the Butler¶

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.

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

Why use the Butler?

The Butler enables users to both search for and retrieve data based on its properties (sky location, band, date) without having to understand how the data files are formatted or where they're stored.

It was designed and built to interface seamlessly with the LSST Science Pipelines.

When to use the Butler.

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

It is necessary to use the Butler when running LSST Science Pipelines tasks on images (e.g., re-running source detection and measurement, creating custom coadds).

For most other use cases, the Table Access Protocol (TAP) and Simple Image Access (SIA) services are recommended for catalog and image data access.

This tutorial only demonstrates how to create an instance of the Butler and how use it - in a very simple and basic way - to search for and retrieve an image.

Related tutorials: The 100-level tutorials in this Butler series demonstrate advanced Butler use, such as exploring the Butler collections, dimensions, and schema, and making advanced queries for image and catalog data products.

The 100-level tutorials on image display have more on using Firefly. The 200-level tutorials on coadded and visit images have more on these data products (e.g., the pixel data and metadata).

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:

repository dp2
collection dp2

It is not necessary to understand how repositories and collections work, or where or how the DP2 data is stored - the Butler takes care of that for the user.

Instantiate a Butler for DP2 and assert that it exists.

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 (where relevant).

To find and retrieve an image using the Butler:

Choose the type of image (e.g., visit image, deep coadd image).
Define query constraints (e.g., coordinate, band, time of observation).
Query the Butler for data that meets the constraints.
Use the Butler to retrieve an image.

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.000
dec = -28.015
band = 'r'

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

Note: How to figure out that band.name and patch.region can be used in a Butler query is demonstrated in the next tutorial in this series. A patch is defined in Section 4, below.

In [5]:

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

band.name = 'r' AND patch.region OVERLAPS POINT(53.0, -28.015)

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

Store the returned dataset references in dataset_refs.

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.image(deep_coadd)
afw_display.setMaskTransparency(100)

Clean up.

In [9]:

del query, dataset_refs, deep_coadd

4. Retrieve images by dataId¶

The dataId is a dictionary, the components of which uniquely identify a data product of a given dataset type.

If the components of a dataId are already known, data products can be retrieved from the Butler without a query.

4.1. Deep coadd images¶

The deep_coadd images are uniquely identified by their band (filter), tract, patch, and the skymap.

The necessary dataId components for a deep_coadd are:

band: An LSST filter ($u$, $g$, $r$, $i$, $z$, or $y$).
tract: A subsection of the all-sky tesselation of the LSST sky map (2.8 sq. deg).
patch: A subsection of a tract, about the size of an LSSTCam detector (0.028 sq. deg).
skymap: The all-sky tesselation of LSST tracts and patches.

Patches and tracts overlap at their edges. In Section 3.1, two deep coadd images are returned as containing the search coordinates because those coordinates are near the edge of two adjacent patches.

Re-execute the query from Section 3.1, and print the dataIds for the two dataset references.

In [10]:

ra = 53.000
dec = -28.015
band = "r"
dataset_refs = butler.query_datasets("deep_coadd",
                                     where="band.name = :band AND \
                                     patch.region OVERLAPS POINT(:ra, :dec)",
                                     bind={"band": band, "ra": ra, "dec": dec},
                                     order_by=["tract", "patch", "band"])
for ref in dataset_refs:
    print(ref.dataId)

{band: 'r', skymap: 'lsst_cells_v2', tract: 5063, patch: 15}
{band: 'r', skymap: 'lsst_cells_v2', tract: 5063, patch: 25}

Retrieve an image by passing the components of the dataId as keyword arguments.

In [11]:

deep_coadd = butler.get("deep_coadd", band="r", tract=5063, patch=15,
                        skymap="lsst_cells_v2")

Option: define the dataId as a dictionary, dataId, and pass it to the butler.get statement.

In [12]:

dataId = {"band": "r", "skymap": "lsst_cells_v2", "tract": 5063, "patch": 15}
deep_coadd = butler.get("deep_coadd", dataId=dataId)

Option to display the image, same as in Section 3.1.

In [13]:

# afw_display.image(deep_coadd)
# afw_display.setMaskTransparency(100)

In [14]:

del deep_coadd

4.3. Retrieving image components only¶

Image components (e.g., the sky_projection, mask, psf, etc.) can be retrieved without the pixel data.

For example, retrieve only the sky_projection.

In [15]:

coadd_sky_projection = butler.get("deep_coadd.sky_projection", dataId=dataId)

In [16]:

coadd_sky_projection

Out[16]:

<lsst.images._transforms._sky_projection.SkyProjection at 0x7b6b4c56e470>

In [17]:

del coadd_sky_projection

In [ ]: