Photerr

photerr — photometric error modeling

You're helping a user work with photerr, a library for simulating realistic photometric errors for LSST/Rubin, Euclid, and Roman surveys. The package extends the Ivezic (2019) point-source error model to low-SNR regimes and extended sources, computing errors in flux space rather than magnitude space.

Install: pip install photerr (requires Python ≥ 3.10, NumPy ≥ 1.23, pandas ≥ 1.4)

Citation: Crenshaw et al. 2024, AJ, 168, 80

Core concepts

• Input: a pandas DataFrame with columns named for each photometric band, containing true source magnitudes.
• Output: a DataFrame with the same columns containing simulated observed magnitudes (true + noise), plus error columns.
• Noise is drawn in flux space; errors are Gaussian and include a systematic floor (sigmaSys=0.005 mag by default).
• Non-detections are flagged with np.inf by default (configurable).

Survey models

from photerr import (
    LsstErrorModel,
    EuclidErrorModel, EuclidDeepErrorModel,
    RomanErrorModel, RomanWideErrorModel, RomanDeepErrorModel,
)

Basic usage

import pandas as pd
from photerr import LsstErrorModel

# Catalog of true magnitudes
catalog = pd.DataFrame({
    "u": [23.5, 24.0], "g": [23.2, 24.1],
    "r": [23.0, 23.9], "i": [22.9, 23.8],
    "z": [22.8, 23.7], "y": [22.7, 23.6],
})

errModel = LsstErrorModel()
obs = errModel(catalog, random_state=42)
# obs has the same band columns (observed noisy magnitudes) plus
# u_err, g_err, ... error columns; non-detections are np.inf

Key parameters

All parameters can be overridden at construction time as keyword args. Dict values are per-band; a scalar applies to all bands.

Common customisations

# Year-1 depth
errModel = LsstErrorModel(nYrObs=1)

# Custom limiting magnitudes
errModel = LsstErrorModel(m5={"u": 23.5, "g": 24.0})

# Double errors in u and y (sensitivity study)
errModel = LsstErrorModel(scale={"u": 2.0, "y": 2.0})

# Rename bands to match catalog column names
errModel = LsstErrorModel(renameDict={"u": "lsst_u", "g": "lsst_g"})

Limiting magnitudes

# 5σ coadded depth (default)
m5 = errModel.getLimitingMags()

# Single-visit, 1σ
m1_single = errModel.getLimitingMags(nSigma=1, coadded=False)

# Extended source with 1-arcsec aperture
m5_ext = errModel.getLimitingMags(aperture=1.0)

Non-detection handling

# Default: flag non-detections as np.inf
errModel = LsstErrorModel(sigLim=0, ndMode="flag")

# Replace non-detections with the limiting magnitude
errModel = LsstErrorModel(sigLim=1, ndMode="sigLim")

# Keep only > 5σ detections; flag the rest
errModel = LsstErrorModel(sigLim=5, ndMode="flag")

Extended sources (galaxies)

The catalog must include galaxy half-light radii columns (major, minor in arcsec by default, overridable with majorCol/minorCol).

galaxy_catalog = pd.DataFrame({
    "u": [24.0], "g": [23.8], "r": [23.5],
    "i": [23.3], "z": [23.1], "y": [23.0],
    "major": [0.5],   # half-light radius (arcsec)
    "minor": [0.4],
})

# AUTO: aperture scales with galaxy size (Rubin-like)
errModel = LsstErrorModel(extendedType="auto")

# GAAP: Gaussian-aperture-and-PSF (KiDS-like)
errModel = LsstErrorModel(extendedType="gaap")

obs = errModel(galaxy_catalog)

Multi-survey comparison

from photerr import LsstErrorModel, EuclidErrorModel, RomanDeepErrorModel

models = {
    "LSST": LsstErrorModel(nYrObs=10),
    "Euclid": EuclidErrorModel(),
    "Roman deep": RomanDeepErrorModel(),
}
for name, m in models.items():
    print(name, m.getLimitingMags())

Notes

• errModel(catalog) returns a new DataFrame; it does not modify the input.
• Pass random_state for reproducibility.
• LsstErrorModel is an alias for LsstErrorModelV2; LsstErrorModelV1 uses the older single-visit depth calculation.
• The ErrorModel and ErrorParams base classes are available for building custom survey models.