Background

.gitignore

@@ -128,9 +128,15 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
+# Claude Code settings (local only)
+.claude/
+
 # Surveys files
 data/surveys/*
 data/others/*
+
+# Background resources (precomputed CMD grids — built locally, not tracked)
+data/background/
 .DS_Store
 # External reference repos (design references only, not part of streamobs)
 /survey_systematics_in_LSST_streams/
@@ -148,6 +154,9 @@ scripts/roman/script_to_notebook.py
 build_*_nb.py
 scripts/**/build_*_nb.py
 
+# local-only development notebooks
+notebooks/dev.ipynb
+
 artifacts/
 # Staged data archive for upload (built by bin/build_data_archive.py)
 /archive/

docs/source/background.md

@@ -0,0 +1,50 @@
+# Generating background
+
+`streamobs` provides two complementary ways to generate a background catalog
+(stars and/or galaxies) for a stream realization.
+
+| Method | Speed | Requirements |
+|--------|-------|--------------|
+| `'light'` | Fast | Precomputed CMD resource files |
+| `'full'` | Slow | True background catalogs |
+
+## Quick start — light method
+
+```python
+from streamobs.surveys import Survey
+from streamobs.background import Background
+
+survey = Survey.load('lsst', release='yr5')
+bg = Background(survey, source_type='both', method='light')
+
+catalog = bg.generate(
+    phi1_limits=(-20, 20),
+    phi2_limits=(-2, 2),
+    gc_frame=frame,          # gala GreatCircleICRSFrame
+)
+```
+
+## Stars only or galaxies only
+
+```python
+bg_stars = Background(survey, source_type='stars', method='light')
+bg_gals  = Background(survey, source_type='galaxies', method='light')
+```
+
+## Full injection method
+
+Requires a DataFrame of true background objects for each population:
+
+```python
+bg = Background(
+    survey,
+    method='full',
+    source_type='both',
+    catalog_stars=df_true_stars,
+    catalog_galaxies=df_true_galaxies,
+)
+catalog = bg.generate(phi1_limits=(-20, 20), phi2_limits=(-2, 2))
+```
+
+See [build_background_resources.md](build_background_resources.md) to learn
+how to build or rebuild the resource files used by the light method.

docs/source/build_background_resources.md

@@ -0,0 +1,70 @@
+# Building background resources (developer guide)
+
+The **light background method** reads precomputed color–magnitude diagram
+(CMD) histograms from parquet files stored in `data/background/`.  These
+files are not tracked by git and must be built locally (or provided by the
+package maintainers).
+
+## What the resources are
+
+For each combination of ``(source_type, bands)``, one parquet file is
+stored with a long-format table:
+
+```
+maglim_r | maglim_g | color_center | mag_center | count | n_ref | area_ref_deg2
+```
+
+Each row represents one cell of a 2-D CMD histogram at a specific magnitude
+limit pair.  The generator looks up the nearest ``(maglim_r, maglim_g)``
+entry at runtime and samples from it.
+
+## How to build resources
+
+### 1. Prepare input catalogs
+
+You need a DataFrame of **true** (pre-observation) positions and magnitudes
+for stars and/or galaxies.  These catalogs are not part of `streamobs` and
+must be supplied by the developer.
+
+```python
+import pandas as pd
+df_stars = pd.read_parquet('/path/to/true_stars.parquet')
+df_galaxies = pd.read_parquet('/path/to/true_galaxies.parquet')
+```
+
+### 2. Run the builder
+
+```python
+from streamobs.background import BackgroundResourceBuilder, BackgroundStorage
+
+builder = BackgroundResourceBuilder(survey_name='lsst', release='yr5')
+builder.build(
+    catalog_stars=df_stars,
+    catalog_galaxies=df_galaxies,
+    bands=('g', 'r'),
+    maglim_ref_values=[25.0, 25.5, 26.0, 26.5, 27.0],
+    delta_range=(-1.0, 1.0),
+    delta_step=0.1,
+    source_type='both',
+)
+```
+
+### 3. Save to disk
+
+```python
+storage = BackgroundStorage(survey_name='lsst', release='yr5')
+builder.save(storage)
+```
+
+Files are written to `data/background/lsst_yr5/` — one parquet per
+``(source_type, bands)`` combination, e.g. `stars_gr.parquet`.
+
+## File naming convention
+
+`BackgroundStorage.get_path(source_type, bands)` returns the full path:
+
+```
+data/background/{survey_name}_{release}/{source_type}_{bands_str}.parquet
+```
+
+Example: `data/background/lsst_yr5/galaxies_gr.parquet`.

docs/source/index.rst

@@ -103,10 +103,17 @@ Documentation Contents
    surveys/Roman
 
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Background generation
+
+   background
+   build_background_resources
+
 .. toctree::
    :maxdepth: 2
    :caption: For developers
-   
+
    modifying_streamobs
    new_survey
    update_data

pytest.ini

@@ -27,6 +27,7 @@ markers =
     observed: marks tests for injection utilities
     model: marks tests for model functionality
     utils: marks tests for utility functions
+    background: marks tests for the background subpackage
 
 # Minimum Python version
 minversion = 3.8

streamobs/__init__.py

@@ -1,2 +1,10 @@
 #!/usr/bin/env python
 """Nothing to see here."""
+
+from .background import (
+    Background,
+    BackgroundCatalogInjector,
+    BackgroundResourceBuilder,
+    BackgroundStorage,
+    LightBackgroundGenerator,
+)

streamobs/background/__init__.py

@@ -0,0 +1,39 @@
+"""
+Background generation for stellar stream analysis.
+
+This subpackage provides two complementary pipelines:
+
+- **Full injection** (:class:`BackgroundCatalogInjector`): runs a known
+  catalog of true stars or galaxies through the complete
+  :class:`~streamobs.observed.StreamInjector` pipeline.
+- **Light generation** (:class:`LightBackgroundGenerator`): samples from
+  precomputed binned color–magnitude distributions stored by
+  :class:`BackgroundStorage`, giving fast per-pixel background realizations
+  without re-running the full injection.
+
+The top-level :class:`Background` class wraps both modes and lets users
+generate stars-only, galaxies-only, or combined backgrounds.
+
+Typical usage — light method with default bundled resources::
+
+    from streamobs.surveys import Survey
+    from streamobs.background import Background
+
+    survey = Survey.load('lsst', release='yr5')
+    bg = Background(survey, source_type='both', method='light')
+    catalog = bg.generate(phi1_limits=(-20, 20), phi2_limits=(-2, 2), gc_frame=frame)
+"""
+
+from .background import Background
+from .catalog_injector import BackgroundCatalogInjector
+from .generator import LightBackgroundGenerator
+from .resource_builder import BackgroundResourceBuilder
+from .storage import BackgroundStorage
+
+__all__ = [
+    "Background",
+    "BackgroundCatalogInjector",
+    "BackgroundResourceBuilder",
+    "BackgroundStorage",
+    "LightBackgroundGenerator",
+]