Light method#

The light method generates background catalogs directly from precomputed color–magnitude diagram (CMD) grids without re-running the injection pipeline. It is the default method and is recommended for most use cases.

How it works#

For each HEALPix pixel in the requested sky region:

Effective magnitude limit — The observed magnitude limit combined with dust absorption to obtain the effective magnitude limit:

\[m_{\mathrm{eff}} = m_{\mathrm{lim}}(\mathrm{pixel}) - A_{\mathrm{band}} \cdot E(B-V)(\mathrm{pixel})\]

This maps the real per-pixel depth to the nearest pre-built grid point. When two surveys cover the two bands, each survey’s depth and dust map are queried independently for its own band.
Bilinear CMD interpolation — The CMD histogram grid is stored at a discrete 2-D lattice of (maglim_b2, maglim_b1) pairs (reference band × color band). The generator bilinearly interpolates the four surrounding grid points to obtain a CMD at the exact effective magnitude limits of the pixel.
Poisson sampling — The CMD histogram is stored as a density (counts per deg²). The expected number of objects for a pixel is obtained by multiplying by the pixel area (in deg²) and drawing from a Poisson distribution. Objects are then sampled from the interpolated CMD histogram.
Position sampling — Positions are drawn uniformly within the pixel and converted to great-circle coordinates (phi1, phi2).

Output#

The output is a tuple (catalog, meta):

catalog — DataFrame with per-survey magnitude columns (e.g. lsst_yr4_g_obs, roman_dc2_F158_obs) and a source_type column. Column names follow the <namespace>_<band>_obs convention used throughout streamobs.
meta — dict with the following keys:

Key	Content
`nside`	HEALPix resolution used for position sampling
`namespaces`	List of survey namespaces in canonical band order, e.g. `['lsst_yr4', 'roman_dc2']`
`bands`	List of band names in canonical order, e.g. `['g', 'F158']`
`band1`	First (color) band name
`band2`	Second (reference/magnitude) band name
`color_edges`	Color bin edges from the CMD grid
`mag_edges`	Magnitude bin edges from the CMD grid

What the light method gives you

Spatial distribution correlated with survey depth and dust.
Magnitude distribution consistent with the survey selection function.

What it does not give you (use the injection method for these)

Per-object magnitude errors or noise.
More than two photometric bands.

Advantages and limitations#


Fast	No injection pipeline per pixel — CMD lookup + sampling only.
No truth catalogs needed	Resource files are provided by the survey developer.
Accounts for depth variation	Effective maglim is computed per pixel.
Accounts for dust	Extinction is folded into the effective magnitude limit.
No magnitude error columns	Errors are not in the output, but their effect is included in the CMD distribution.
Two bands only	The CMD is 2-D; additional bands require full injection.
Multi-survey	The two bands can come from different surveys (one per band).

Single-survey usage#

from streamobs.surveys import Survey
from streamobs.background import Background

survey = Survey.load('lsst', release='yr4')
bg = Background(survey, source_type='both', method='light', bands=('g', 'r'))

catalog, meta = bg.generate(
    phi1_limits=(-20, 20),
    phi2_limits=(-2, 2),
    gc_frame=frame,
    nside=4096,    # HEALPix resolution; auto-capped to maglim map resolution
)

Multi-survey usage#

Pass a list of two surveys — one per CMD band. The canonical band order is determined automatically.

from streamobs.surveys import Survey
from streamobs.background import Background

lsst  = Survey.load('lsst',  release='yr4')
roman = Survey.load('roman', release='dc2')

bg = Background(
    surveys=[lsst, roman],
    source_type='stars',
    method='light',
    bands=('g', 'F158'),   # lsst covers g, roman covers F158
)

catalog, meta = bg.generate(
    phi1_limits=(-20, 20),
    phi2_limits=(-2, 2),
    gc_frame=frame,
    nside=4096,
)
# meta['namespaces'] == ['lsst_yr4', 'roman_dc2']
# catalog columns: lsst_yr4_g_obs, roman_dc2_F158_obs, source_type

The resource files must exist for the requested survey combination. See build_background_resources for how to build them.

Light method

Contents