204.1. Calibration frames

204.1. Calibration frames¶

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

Learning objective: To understand and access the calibration images (bias, dark, and flat frames).

LSST data products: bias, dark, and flat

Packages: lsst.daf.butler, lsst.afw.display

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 process of Instrument Signature Removal (ISR; also called "image reduction") uses bias, dark, and flat field calibration frames as part of the process to transform raw images into visit images.

Bias images: An exposure obtained with zero exposure time to measure the pedestal level of counts applied during readout.

Dark frames: An exposure obtained with a nonzero exposure time but with no illumination (shutter closed) to measure the detector's response to the thermal energy in the camera.

Flat fields: An exposure taken with even illumination across the field to measure pixel response variations.

Related tutorials: See the 200-level tutorial on visit images, and the 100-level tutorials on how to use the Butler.

1.1. Import packages¶

Import the Rubin data Butler and the afw.display package to retrieve and display calibration images.

In [1]:

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

1.2. Define parameters and functions¶

Instantiate the Butler.

In [2]:

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

Set the display backend to Firefly.

In [3]:

afwDisplay.setDefaultBackend('firefly')

Define the visit and detector identifiers to obtain calibration frames for.

In [4]:

my_visit = 2024120700527
my_detector = 0

2. Data access¶

The calibration frames are only accessible via the Butler.

Show the Butler dimensions for each calibration frame type. Notice that only the flat frames are by band (by filter).

In [5]:

for frame_type in ['raw', 'bias', 'dark', 'flat']:
    print(' ')
    print(frame_type)
    print(butler.get_dataset_type(frame_type))
    print('Required dimensions: ', butler.get_dataset_type(frame_type).dimensions.required)

raw
DatasetType('raw', {band, instrument, day_obs, detector, group, physical_filter, exposure}, Exposure)
Required dimensions:  {instrument, detector, exposure}

bias
DatasetType('bias', {instrument, detector}, ExposureF, isCalibration=True)
Required dimensions:  {instrument, detector}

dark
DatasetType('dark', {instrument, detector}, ExposureF, isCalibration=True)
Required dimensions:  {instrument, detector}

flat
DatasetType('flat', {band, instrument, detector, physical_filter}, ExposureF, isCalibration=True)
Required dimensions:  {instrument, detector, physical_filter}

2.1. Retrieve and display frames¶

Retrieve the raw exposure, and the bias, dark, and flat frames, all for the same visit and display them in separate frames with Firefly.

In [6]:

raw = butler.get("raw", exposure=my_visit, detector=my_detector)
afw_display = afwDisplay.Display(frame=1)
afw_display.image(raw.image)

In [7]:

bias = butler.get("bias", visit=my_visit, detector=my_detector)
afw_display = afwDisplay.Display(frame=2)
afw_display.image(bias)

In [8]:

dark = butler.get("dark", visit=my_visit, detector=my_detector)
afw_display = afwDisplay.Display(frame=3)
afw_display.image(dark)

In [9]:

flat = butler.get("flat", visit=my_visit, detector=my_detector)
afw_display = afwDisplay.Display(frame=4)
afw_display.image(flat)

3. Pixel data¶

The bias, dark, and flat frames have their image plane and a variance plane.

There is also a mask plane but it is unpopulated. The mask plane of the raw image is used in processing.

3.1. Image plane¶

Pixel data in units of ADU (analog-digital units).

Print the minimum, maximum, mean, and standard deviation of the pixel values from the image planes of the bias, dark, and flat frames.

In [10]:

print('image     min       max            mean     std     ')
print('----------------------------------------------------')
print(f"bias  {np.min(bias.image.array):7.2f}  {np.max(bias.image.array):9.2f} \
       {np.mean(bias.image.array):7.2f}  {np.std(bias.image.array):7.2f}")
print(f"dark  {np.min(dark.image.array):7.2f}  {np.max(dark.image.array):9.2f} \
       {np.mean(dark.image.array):7.2f}  {np.std(dark.image.array):7.2f}")
print(f"flat  {np.min(flat.image.array):7.2f}  {np.max(flat.image.array):9.2f} \
       {np.mean(flat.image.array):7.2f}  {np.std(flat.image.array):7.2f}")

image     min       max            mean     std
----------------------------------------------------
bias   -46.09  120480.11           0.41    51.03
dark   -17.15    8557.23           0.02     9.15
flat    -0.33       8.82           1.01     0.02

3.2. Variance plane¶

Pixel data in units of ADU^2 (analog-digital units squared).

Print the minimum, mean, and maximum pixel value from the image planes of the bias, dark, and flat frames.

In [11]:

print('image    min            mean        max  ')
print('-----------------------------------------')
print(f"bias  {np.min(bias.variance.array):7.2f} \
       {np.mean(bias.variance.array):7.2f}  {np.max(bias.variance.array):11.2f}")
print(f"dark  {np.min(dark.variance.array):7.2f} \
       {np.mean(dark.variance.array):7.2f}  {np.max(dark.variance.array):11.2f}")
print(f"flat  {np.min(flat.variance.array):7.2f} \
       {np.mean(flat.variance.array):7.2f}  {np.max(flat.variance.array):11.2f}")

image    min            mean        max
-----------------------------------------
bias     0.20           4.46   2585303.25

dark     0.00           0.25    185063.16
flat     0.00           0.00         0.24

3.3. No mask frame¶

Show that the mask frame is unpopulated (all zero values).

In [12]:

print('bias ', np.min(bias.mask.array),
      np.mean(bias.mask.array), np.max(bias.mask.array))
print('dark ', np.min(dark.mask.array),
      np.mean(dark.mask.array), np.max(dark.mask.array))
print('flat ', np.min(flat.mask.array),
      np.mean(flat.mask.array), np.max(flat.mask.array))

bias  0 0.0 0
dark  0 0.0 0
flat  0 0.0 0

4. Metadata¶

The bias, dark, and flat frames are of type ExposureF and come with header information.

4.1. Header¶

The informational equivalent of a FITS image header is the metadata.

Get the metadata for the bias, dark, or flat.

In [13]:

metadata = bias.getMetadata()
# metadata = dark.getMetadata()
# metadata = flat.getMetadata()

Option to display the long list of metadata.

In [14]:

# metadata

Convert the metadata to a python dictionary.

In [15]:

md_dict = metadata.toDict()

Show any metadata key that contains the string 'UNIT' or 'MJD'.

In [16]:

temp = 'UNIT'
# temp = 'MJD'
for key in md_dict.keys():
    if key.find(temp) >= 0:
        print(key)

BUNIT
LSST ISR UNITS
LSST ISR OVERSCAN SERIAL UNITS
LSST ISR READNOISE UNITS
LSST ISR OVERSCAN PARALLEL UNITS

Print the 'BUNIT'.

In [17]:

md_dict['BUNIT']

Out[17]:

'adu'

Clean up.

In [18]:

del md_dict, metadata

4.2. Bounding box¶

The bounding box defines the extent (corners) of the image.

Get the bounding box; use the bias frame for this example.

In [19]:

bbox = bias.getBBox()

In [20]:

bbox

Out[20]:

Box2I(corner=Point2I(0, 0), dimensions=Extent2I(4072, 4000))

Print the start and end pixels in the X and Y dimensions.

In [21]:

print(bbox.beginX, bbox.beginY)
print(bbox.endX, bbox.endY)

0 0
4072 4000

Clean up.

In [22]:

del bbox

In [ ]: