sheap.MasterSampler.MasterSampler module

MasterSampler

Post–fitting interface for extracting physical parameters and running posterior sampling on spectral models.

This module defines MasterSampler, which acts as a high-level wrapper around results from Sheapectral or SheapResult. It provides multiple strategies to handle parameters after fitting:

• Single best-fit mode Extract physical quantities (flux, FWHM, EQW, luminosity, etc.) directly from the optimized parameters with propagated uncertainties.

• Monte Carlo mode Generate pseudo-random realizations of parameters around the covariance matrix for uncertainty propagation.

• Pseudo Monte Carlo mode Fast approximate sampler for posterior parameter exploration.

• MCMC mode (NumPyro) Full Bayesian sampling of the posterior distribution using Hamiltonian Monte Carlo / NUTS.

Key Features

• Organizes parameter arrays, constraints, and dependencies after a fit.

• Provides consistent access to spectra, masks, scaling factors, and model functions.

• Computes luminosity distances given redshifts and a cosmology.

• Interfaces with downstream tools (AfterFitParams) to compute line and continuum physical properties.

• Exposes convenience methods:

  • MasterSampler.sample_single()

  • MasterSampler.montecarlosampler()

  • MasterSampler.sample_pseudomontecarlosampler()

  • MasterSampler.sample_mcmc()

Notes

• By default, cosmology is set to FlatLambdaCDM(H0=70, Om0=0.3).

• Bolometric corrections and single-epoch estimators are loaded from sheap.Utils.Constants.

• This module will eventually centralize routines now duplicated in samplers and parameter estimation helpers.

class MasterSampler(sheap=None, sheapresult=None, spectra=None, z=None, cosmo=None, BOL_CORRECTIONS=None, SINGLE_EPOCH_ESTIMATORS=None, C_KMS=299792.458)

Bases: object

Computes best-fit physical parameters and uncertainties for spectral regions. Provides Monte Carlo and MCMC posterior sampling.

Parameters:

• sheap (Sheapectral, optional) – Configured Sheapectral instance with fit results.

• sheapresult (SheapResult, optional) – SheapResult object containing parameters, uncertainties, and metadata.

• spectra (jnp.ndarray, optional) – Normalized spectra array, shape (n_objects, 3, n_pixels).

• z (jnp.ndarray, optional) – Redshift array for each object.

• cosmo (astropy.cosmology instance, optional) – Cosmology for distance calculations; defaults to FlatLambdaCDM(H0=70, Om0=0.3).

• BOL_CORRECTIONS (dict, optional) – Bolometric correction factors; defaults from module constant.

• SINGLE_EPOCH_ESTIMATORS (dict, optional) –

  Single-epoch estimators; defaults from module constant. : float, optional

  Speed of light constant; defaults from module constant.

spec

Spectra array used for estimation.

Type:

jnp.ndarray

z

Redshifts for each spectrum.

Type:

jnp.ndarray

params

Best-fit parameter values.

Type:

jnp.ndarray

uncertainty_params

Uncertainty estimates for parameters.

Type:

jnp.ndarray

cosmo

Cosmology object for computing distances.

Type:

?

d

Luminosity distances corresponding to z (in cm).

Type:

?

BOL_CORRECTIONS

Bolometric correction lookup.

Type:

dict

SINGLE_EPOCH_ESTIMATORS

Single-epoch parameter estimators.

Type:

dict

C_KMS

Speed of light.

Type:

float

sample_montecarlo(num_samples=2000, key_seed=0, summarize=True, extra_products=True)

Run Monte Carlo sampling of physical parameters.

sample_mcmc(n_random=0, num_warmup=500, num_samples=1000, summarize=True, extra_products=True)

Run MCMC sampling via NumPyro.

sample_single(extra_products=True)

Compute parameter estimates without posterior sampling.

_from_sheap(sheap)

Initialize internal state from a Sheapectral object.

_from_sheapresult(result, spectra, z)

Initialize internal state from SheapResult and spectra.

sample_pseudomontecarlosampler(num_samples=2000, key_seed=0, summarize=True)

Run pseudomontecarlosamplerparameter sampling.

Parameters:

• num_samples (int, optional) – Number of samples to draw.

• key_seed (int, optional) – Seed for random number generator.

• summarize (bool, optional) – If True, summarize posterior distributions.

• extra_products (bool, optional) – Whether to return additional derived products.

Returns:

Array of samples and dictionary of summarized statistics.

Return type:

full_samples, summary_dict

montecarlosampler(num_samples=2000, key_seed=0, summarize=True, return_only_draws=False, frac_box_sigma=0.02, k_sigma=0.3)

Run montecarlosampler sampling.

Parameters:

• num_samples (int, optional) – Number of samples to draw.

• key_seed (int, optional) – Seed for random number generator.

• summarize (bool, optional) – If True, summarize posterior distributions.

• extra_products (bool, optional) – Whether to return additional derived products.

Returns:

Array of samples and dictionary of summarized statistics.

Return type:

full_samples, summary_dict

sample_mcmc(n_random=0, num_warmup=500, num_samples=1000, summarize=True)

Run MCMC sampling using NumPyro.

Parameters:

• n_random (int, optional) – Number of random initial chains.

• num_warmup (int, optional) – Number of warmup steps.

• num_samples (int, optional) – Number of MCMC samples.

• summarize (bool, optional) – If True, summarize the chains.

• extra_products (bool, optional) – Include extra derived products.

Returns:

Array of MCMC samples and dictionary of statistics.

Return type:

full_chain, summary_dict

sample_single(summarize=True)

Compute parameter estimates and uncertainties without sampling.

Parameters:

extra_products (bool, optional) – Include additional derived products.

Returns:

Dictionary of parameter estimates and uncertainties.

Return type:

summary_dict