streamobs.background.resource_builder module

streamobs.background.resource_builder module#

Builder for precomputed background color–magnitude diagram (CMD) resources.

class streamobs.background.resource_builder.BackgroundResourceBuilder(survey_name='lsst', release=None, surveys=None, rng=None, **kwargs)[source]#

Bases: object

Build precomputed CMD histogram grids for fast background generation.

Drives BackgroundCatalogInjector on uniform surveys (no dust, constant magnitude limits) at a 2-D meshgrid of (maglim_b2, maglim_b1) pairs (b1 = bands[0], b2 = bands[1]). The resulting 2-D color–magnitude histograms are stored via BackgroundStorage and later consumed by LightBackgroundGenerator.

Parameters:

  • survey_name (str, optional) – Survey identifier (e.g. 'lsst').

  • release (str, optional) – Survey release string (e.g. 'yr5').

  • rng (numpy.random.Generator, int, or None, optional) – Random generator (or seed) used when the input catalog has no positions and ra/dec must be sampled. Pass a seed for reproducible background resources.

  • **kwargs – Forwarded to create_survey().

Examples

>>> builder = BackgroundResourceBuilder('lsst', release='yr5')
>>> builder.build(
...     catalog_stars=df_stars,
...     catalog_galaxies=df_gals,
...     bands=('g', 'r'),
...     maglim_min=24.0,
...     maglim_max=27.0,
...     maglim_step=0.5,
...     max_delta=1.0,
...     area_ref_deg2=100.0,
... )
>>> storage = BackgroundStorage(survey_name='lsst', release='yr5')
>>> builder.save(storage)
build(catalog_stars=None, catalog_galaxies=None, bands=('g', 'r'), maglim_min=23.5, maglim_max=27.5, maglim_step=0.5, max_delta=1.0, n_bins_color=125, n_bins_mag=125, color_range=(-0.5, 2.0), mag_range=(16.0, 28.0), area_ref_deg2=None, source_type='both', verbose=True, **kwargs)[source]#

Build CMD histograms for all (maglim_b2, maglim_b1) grid configurations.

For each combination of source type and magnitude limit pair, injects the catalog into a uniform (no-dust, constant-maglim) survey and computes a 2-D histogram of (color, mag_ref_band).

Parameters:

  • catalog_stars (pd.DataFrame or str, optional) – True stellar catalog. Required when source_type is 'stars' or 'both'.

  • catalog_galaxies (pd.DataFrame or str, optional) – True galaxy catalog. Required when source_type is 'galaxies' or 'both'.

  • bands (tuple of str, optional) – Two band names (bands[0], bands[1]) where color = bands[0] − bands[1] and bands[1] is the reference magnitude axis. Default ('g', 'r').

  • maglim_min (float, optional) – Minimum magnitude limit for the grid. Default 23.5.

  • maglim_max (float, optional) – Maximum magnitude limit for the grid. Default 27.0.

  • maglim_step (float, optional) – Step size between grid values. Default 0.5.

  • max_delta (float, optional) – Keep only pairs with |maglim_b2 − maglim_b1| < max_delta. Default 1.0.

  • n_bins_color (int, optional) – Number of color histogram bins. Default 125.

  • n_bins_mag (int, optional) – Number of magnitude histogram bins. Default 125.

  • color_range (tuple of float, optional) – (min, max) of the color axis. Default (-0.5, 2.0).

  • mag_range (tuple of float, optional) – (min, max) of the magnitude axis. Default (16.0, 28.0).

  • area_ref_deg2 (float, optional) – Sky area of the reference simulation in deg².

  • source_type (str, optional) – 'stars', 'galaxies', or 'both'. Default 'both'.

  • **kwargs – Forwarded to the catalog injector.

Return type:

self

classmethod load(storage: BackgroundStorage, source_type='both', bands=('g', 'r'), **kwargs) → BackgroundResourceBuilder[source]#

Load precomputed resources from disk into a new builder instance.

Parameters:

  • storage (BackgroundStorage) – Storage backend to read from.

  • source_type (str, optional) – Which source types to load. Default 'both'.

  • bands (tuple of str, optional) – Band names used when the resources were saved. Default ('g', 'r').

Returns:

Populated instance with resources filled.

Return type:

BackgroundResourceBuilder

save(storage: BackgroundStorage, source_type='both', **kwargs)[source]#

Persist the built resources to disk via storage.

Parameters:

  • storage (BackgroundStorage) – Storage backend to use.

  • source_type (str, optional) – Which source types to save. Default 'both'.

  • **kwargs – Forwarded to BackgroundStorage.save_data().

Contents