streamobs.model module

Models for simulating streams.

class streamobs.model.BackgroundModel(config, **kwargs)

Bases: StreamModel

Background model.

class streamobs.model.ConfigurableModel(config, **kwargs)

Bases: object

Baseclass for models built from configs.

class streamobs.model.DensityModel(config, **kwargs)

Bases: ConfigurableModel

Density along the stream; samples phi1 positions.

sample(size, rng=None)

Draw phi1 samples.

Parameters:

• size (int) – Number of samples.

• rng (numpy.random.Generator, optional) – Random number generator for reproducible sampling. A fresh, unseeded generator is used if omitted.

Returns:

Sampled phi1 values.

Return type:

numpy.ndarray

class streamobs.model.DistanceModel(config, **kwargs)

Bases: ConfigurableModel

class streamobs.model.IsochroneModel(config, **kwargs)

Bases: ConfigurableModel

Isochrone wrapper using ugali for CMD sampling.

Two configuration forms are supported:

• Single-survey (legacy): the isochrone section carries the ugali factory keys directly (name, survey, age, z, band_1, band_2, …). sample() returns (mag_band_1, mag_band_2) and reproduces the previous behaviour exactly.

• Multi-survey: a surveys mapping {survey_name: {survey, band_1, band_2}} plus shared keys (name, age, z, …) at the top level. One ugali isochrone is built per survey from the same stellar population, so a single shared draw of initial masses (sample_masses()) is interpolated into every survey’s bands — giving the same physical star consistent magnitudes across surveys. sample() returns {(survey, band): apparent_mag}.

Roman bands are always converted from Vega to AB (see ROMAN_VEGA_TO_AB); other bands pass through unchanged.

create_isochrone(config)

Construct the underlying ugali isochrone(s) from configuration.

Both configuration forms are normalized to a single {namespace: factory_cfg} mapping and built through the same loop — a legacy flat config simply becomes a one-entry mapping — so there is no separate single- vs. multi-survey code path.

Parameters:

config (dict) – Isochrone factory configuration. A surveys key selects the multi-survey form; otherwise the single-survey (legacy) form is used.

sample(nstars, distance_modulus, rng=None, masses=None, **kwargs)

Sample apparent magnitudes for every (survey, band).

A single shared set of initial masses is interpolated into each survey’s bands, so the same physical star is consistent across surveys. The masses are drawn from the shared IMF (sample_masses()) unless supplied via masses.

Parameters:

• nstars (int) – Number of stars (and the required length of masses if given).

• distance_modulus (float or array-like) – Distance modulus per star (broadcast if scalar).

• rng (numpy.random.Generator, optional) – Used only when masses is None.

• masses (array-like, optional) – Initial stellar masses to use directly — e.g. an external simulation’s masses — instead of drawing from the IMF. Must have length nstars.

Returns:

{(survey_name, band): apparent_magnitude_array} and the initial masses used (shape (nstars,)).

Return type:

dict, numpy.ndarray

sample_masses(nstars, rng=None, mass_min=None, mass_steps=None)

Draw nstars initial stellar masses from the shared isochrone IMF.

The masses are drawn once from the primary isochrone’s mass PDF and are meant to be interpolated into each survey’s bands, so the same physical star gets consistent magnitudes across surveys.

Parameters:

• nstars (int) – Number of stars to draw (returns exactly this many).

• rng (numpy.random.Generator, optional) – Random number generator (a default one is created if omitted).

• mass_min (float, int, optional) – Passed to the ugali isochrone sampler.

• mass_steps (float, int, optional) – Passed to the ugali isochrone sampler.

Returns:

Initial masses, shape (nstars,).

Return type:

numpy.ndarray

class streamobs.model.SplineStreamModel(config, **kwargs)

Bases: StreamModel

Spline-based stream model with linear-density component.

class streamobs.model.StreamModel(config, **kwargs)

Bases: ConfigurableModel

High-level object for the various components of the stream model.

complete_catalog(catalog, columns_to_add=None, size=None, inplace=False, save_path=None, verbose=True, dist=None, rng=None)

Complete only the requested columns in a catalog.

This method takes an input catalog (or a desired size when no catalog is provided) and fills in only the requested stream-model columns while preserving pre-existing non-null values. Columns are generated using the configured sub-models (density, track, distance modulus, isochrone, velocity) and only if those capabilities are available.

Pre-existing values are never overwritten: for every column only the missing (absent or NaN) rows are filled. In particular, supplying some of an isochrone’s bands and requesting the others fills only the missing bands and leaves the provided ones untouched.

Parameters:

• catalog (pandas.DataFrame or str or dict or None) – Input catalog. If a string, it is interpreted as a CSV filepath to read. If a dict, it will be converted to a DataFrame. If None, size must be provided to create an empty frame of that length.

• columns_to_add (sequence of str or None, optional) – The columns to ensure in the output. Valid entries are {‘phi1’,’phi2’,’dist’,’mu1’,’mu2’,’rv’} plus the isochrone magnitude columns (<survey>_<band>_true). If None, all valid columns supported by the configured model are considered.

• size (int or None, optional) – Required when catalog is None or an empty table; ignored otherwise.

• inplace (bool, default False) – If True and a DataFrame or CSV path is provided, modify that object in place (for CSV, overwrite the input file).

• save_path (str or None, optional) – If provided, write the completed catalog to this CSV path.

• verbose (bool, default True) – If True, print progress/status messages.

• dist (float or array-like or None, optional) – Distance modulus to use directly instead of sampling one from the distance_modulus sub-model. A scalar is broadcast to every row that needs a dist value; an array must have one entry per row. When given, phi1 and a distance_modulus model are not required to fill magnitudes. Only missing dist rows are set.

• rng (numpy.random.Generator, optional) – Random number generator shared across every sub-model call in this method, so passing the same seed reproduces an identical completed catalog. A fresh, unseeded generator is created (and not shared with other calls) if omitted.

Returns:

The completed catalog. If inplace is True and a DataFrame was provided, the same object is returned after modification.

Return type:

pandas.DataFrame

Raises:

ValueError – If size is required but not provided, or when dependencies are missing (e.g., requesting ‘phi2’ without available ‘phi1’).

Notes

• Dependencies: ‘phi2’ and ‘dist’ require ‘phi1’. Magnitudes require ‘dist’ and an isochrone model. Velocities require ‘phi1’ and a velocity model.

• Existing non-null values are preserved: only the missing rows are filled for phi1/phi2/dist, the magnitude columns, and the shared mass column (supplying some bands and requesting others fills only the missing ones, colour-consistently). Velocities are the exception — mu1/mu2/rv are recomputed for the whole columns to keep kinematic coherence across rows.

• When catalog is a CSV path and inplace is True, the original file is overwritten.

sample(size, rng=None, seed=None)

Sample stream stars and derived quantities.

Parameters:

• size (int) – Number of stars to generate.

• rng (numpy.random.Generator, optional) – Random number generator shared across every sub-model so the same seed reproduces an identical catalog. A fresh, unseeded generator is created (and not shared with other calls) if omitted.

Returns:

Columns include: phi1, phi2, dist, mu1, mu2, rv, and the isochrone magnitude columns <survey>_<band>_true (per survey/band). Some may be None if the sub-model is absent.

Return type:

pandas.DataFrame

class streamobs.model.TrackModel(config, **kwargs)

Bases: ConfigurableModel

Transverse track model; samples phi2 given phi1.

sample(x, rng=None)

Sample phi2 at given phi1 positions x.

Parameters:

• x (array-like) – phi1 positions where to sample phi2.

• rng (numpy.random.Generator, optional) – Random number generator for reproducible sampling. A fresh, unseeded generator is used if omitted.

Returns:

Sampled phi2 values.

Return type:

numpy.ndarray

class streamobs.model.VelocityModel(config, **kwargs)

Bases: ConfigurableModel

Placeholder for velocity model.

sample(phi1, rng=None)

Placeholder