sheap.Core.CoreDataStructures module

Core Data Structures

This module defines the core data classes used across sheap to describe spectral lines, grouped regions, fitting outputs, per‑profile constraints, and per‑kind fitting limits.

Exposed classes

  • SpectralLine — a single (or composite) emission/absorption component.

  • SheapModel — a container of lines with profile functions, parameter maps, and convenient subsetting/grouping utilities.

  • SheapResult — a structured record of a completed fit (parameters, uncertainties, residuals, χ², etc.).

  • ProfileConstraintSet — per‑profile initial values and bounds.

  • FittingLimits — canonical velocity/shift/amplitude limits by kind.

Main Features

  • Dataclass APIs with typed fields and .to_dict() helpers.

  • Region‑level table view (as_df()), filtering, grouping, and safe subsetting that preserves global↔local parameter index mappings.

  • Lazy assembly of fused profile functions for fast evaluation with JAX.

  • Seamless attachment of fitted parameter matrices and uncertainties.

Notes

  • Arrays may be NumPy or JAX arrays; fused profile evaluation is JAX‑friendly.

  • Global parameter indices are preserved when subsetting regions so results can be traced back to the original packed parameter vector.

class SheapModel(lines, profile_functions=<factory>, profile_names=<factory>, params_dict=<factory>, profile_params_index_list=<factory>, params=None, uncertainty_params=None)[source]

Bases: object

Holds SpectralLines + (optionally) their profile functions & parameters. You can slice/filter/group arbitrarily, and still recover both the original (“global”) and per‐subset (“local”) parameter mappings.

Parameters:

  • lines (List[SpectralLine])

  • profile_functions (List[Callable])

  • profile_names (List[str])

  • params_dict (Dict[str, int])

  • profile_params_index_list (List[List[int]])

  • params (ndarray | None)

  • uncertainty_params (ndarray | None)

lines: List[SpectralLine]
profile_functions: List[Callable]
profile_names: List[str]
params_dict: Dict[str, int]
profile_params_index_list: List[List[int]]
params: ndarray | None = None
uncertainty_params: ndarray | None = None
original_idx: List[int]
global_profile_params_index_list: List[List[int]]
attach_profiles(profile_functions, profile_names, params, uncertainty_params, profile_params_index_list, params_dict)[source]

Supply the full fit‐machinery. Must provide exactly one profile & name per line, and a params_dict mapping each param_name->col.

Parameters:

  • profile_functions (List[Callable])

  • profile_names (List[str])

  • params (ndarray)

  • uncertainty_params (ndarray)

  • profile_params_index_list (List[List[int]])

  • params_dict (Dict[str, int])

Return type:

None

property combined_profile: Callable[[ndarray, ndarray], ndarray]
property flat_param_indices_global: ndarray

All the global parameter columns (original indices), in order.

property flat_param_indices_local: ndarray

All the local parameter columns (subset indices), in order.

as_df()[source]

Local‐index DataFrame with columns including orig_idx, kind, component, etc.

Return type:

pandas.DataFrame

filter(**conds)[source]
Return type:

SheapModel

group_by(field)[source]
Parameters:

field (str)

Return type:

Dict[Any, SheapModel]

param_subdict()[source]

Map each param name → its column in this instance’s params, using the local flattened indices.

Return type:

Dict[str, ndarray]

unique(field)[source]
Parameters:

field (str)

Return type:

List[Any]

property regions: List[Any]
property components: List[Any]
property subregions: List[Any]
property elements: List[Any]
characteristics()[source]
Return type:

Dict[str, Any]

class SheapResult(region_list, fitting_routine=None, params=None, uncertainty_params=None, mask=None, constraints=None, profile_functions=None, profile_names=None, loss=None, profile_params_index_list=None, initial_params=None, scale=None, params_dict=None, outer_limits=None, inner_limits=None, model_keywords=None, source=None, dependencies=None, free_params=None, residuals=None, chi2_red=None, posterior=None, fitkwargs=None, elapsed_time=None, params_class=None)[source]

Bases: object

Container for the results of a SHEAP spectral-region fit.

This class stores the optimized fit parameters, associated metadata, model configuration, diagnostics, posterior information, and the reconstructed SheapModel object associated with a fitted spectral region.

Parameters:

  • region_list (list of SpectralLine) – List of spectral-line configurations used to define the fitted region. This is used to initialize the internal SheapModel.

  • fitting_routine (dict or None, optional) – Dictionary describing the fitting routine used to obtain the result.

  • params (jax.numpy.ndarray or None, optional) – Optimized model parameters.

  • uncertainty_params (jax.numpy.ndarray or None, optional) – Estimated uncertainties associated with params.

  • mask (jax.numpy.ndarray or None, optional) – Mask used during the fitting process. The convention should match the one used by the fitting routine.

  • constraints (jax.numpy.ndarray or None, optional) – Constraint array used during the fit. This should correspond to the constraints generated by the fitting setup.

  • profile_functions (list of callable or None, optional) – Profile functions used to evaluate the spectral model.

  • profile_names (list of str or None, optional) – Names of the profile functions used in the model.

  • loss (list or None, optional) – Loss values recorded during the optimization.

  • profile_params_index_list (list or None, optional) – Index mapping between spectral profiles and their corresponding parameter positions.

  • initial_params (jax.numpy.ndarray or None, optional) – Initial parameter values before optimization.

  • scale (jax.numpy.ndarray or None, optional) – Normalization scale applied to the data or model during fitting.

  • params_dict (dict of str to int or None, optional) – Mapping between parameter names and their index positions in the parameter array.

  • outer_limits (list or None, optional) – Outer wavelength limits used to define the full fitting region.

  • inner_limits (list or None, optional) – Inner wavelength limits used to define the primary region of interest.

  • model_keywords (dict or None, optional) – Additional keyword arguments used to configure the spectral model.

  • source (dict or None, optional) – Metadata describing the input source or spectrum.

  • dependencies (list or None, optional) – List describing parameter dependencies, ties, or linked relations.

  • free_params (jax.numpy.ndarray or None, optional) – Boolean or index array identifying the free parameters in the fit.

  • residuals (jax.numpy.ndarray or None, optional) – Residuals between the observed spectrum and the fitted model.

  • chi2_red (jax.numpy.ndarray or None, optional) – Reduced chi-squared value or values associated with the fit.

  • posterior (dict or None, optional) – Posterior samples or posterior-summary information, when available.

  • fitkwargs (list of dict or None, optional) – Keyword arguments used for one or more fitting steps.

  • elapsed_time (list of dict or None, optional) – Timing information for the different fitting stages.

  • params_class (object or None, optional) – Optional parameter-class object associated with the fit.

sheapmodel

Model object initialized from region_list and populated with the fitted profiles, parameters, uncertainties, profile names, profile parameter indices, and parameter dictionary.

Type:

SheapModel

Notes

The SheapModel instance is created automatically during __post_init__. Profile information is attached using SheapModel.attach_profiles.

The to_dict method uses dataclasses.asdict(), so nested dataclass fields are recursively converted to dictionaries.

region_list: List[SpectralLine]
fitting_routine: dict | None = None
params: jnp.ndarray | None = None
uncertainty_params: jnp.ndarray | None = None
mask: jnp.ndarray | None = None
constraints: jnp.ndarray | None = None
profile_functions: List[Callable] | None = None
profile_names: List[str] | None = None
loss: List | None = None
profile_params_index_list: List | None = None
initial_params: jnp.ndarray | None = None
scale: jnp.ndarray | None = None
params_dict: Dict[str, int] | None = None
outer_limits: List | None = None
inner_limits: List | None = None
model_keywords: dict | None = None
source: dict | None = None
dependencies: List | None = None
free_params: jnp.ndarray | None = None
residuals: jnp.ndarray | None = None
chi2_red: jnp.ndarray | None = None
posterior: dict | None = None
fitkwargs: List[Dict] | None = None
elapsed_time: List[Dict] | None = None
params_class: Optional = None
to_dict()[source]

Convert the result object into a dictionary.

Returns:

Dictionary representation of the dataclass fields.

Return type:

dict

class FittingLimits(upper_fwhm_kms, lower_fwhm_kms, init_fwhm_kms=None, vshift_kms=None, max_amplitude=None, references=None)[source]

Bases: object

Stores FWHM and shift limits for a line component kind.

Parameters:

  • upper_fwhm_kms (float)

  • lower_fwhm_kms (float)

  • init_fwhm_kms (float | None)

  • vshift_kms (float | None)

  • max_amplitude (float | None)

  • references (list | None)

upper_fwhm_kms

Maximum velocity FWHM (km/s).

Type:

float

lower_fwhm_kms

Minimum velocity FWHM (km/s).

Type:

float

vshift_kms

Maximum velocity shift (km/s).

Type:

float

max_amplitude

Maximum allowed amplitude.

Type:

float

upper_fwhm_kms: float
lower_fwhm_kms: float
init_fwhm_kms: float | None = None
vshift_kms: float | None = None
max_amplitude: float | None = None
references: list | None = None
classmethod from_dict(d)[source]

Create FittingLimits from a dictionary with keys matching the attributes.

Parameters:

d (Dict[str, float]) – Dictionary with keys: ‘upper_fwhm_kms’, ‘lower_fwhm_kms’, ‘vshift_kms’, ‘max_amplitude’.

Returns:

Instance created from the dictionary.

Return type:

FittingLimits

Raises:

ValueError – If any required key is missing from the dictionary.

class ProfileConstraintSet(init: 'List[float]', upper: 'List[float]', lower: 'List[float]', profile: 'str', param_names: 'List[str]', profile_fn: 'Optional[Callable]' = None)[source]

Bases: object

Parameters:

  • init (List[float])

  • upper (List[float])

  • lower (List[float])

  • profile (str)

  • param_names (List[str])

  • profile_fn (Callable | None)

init: List[float]
upper: List[float]
lower: List[float]
profile: str
param_names: List[str]
profile_fn: Callable | None = None
class SpectralLine(line_name, center=None, region=None, component=None, subregion=None, amplitude=None, element=None, profile=None, region_lines=None, amplitude_relations=None, subprofile=None, rarity=None, template_info=None)[source]

Bases: object

Represents a single spectral emission or absorption line component.

Parameters:

  • line_name (str or list of str) – Identifier(s) for the spectral line (e.g., ‘Halpha’), or for a composite region the region name plus component number.

  • center (float or list of float, optional) – Central wavelength(s) of the line in Angstroms.

  • region (str, optional) – Spatial region of the line, one of ‘narrow’, ‘broad’, ‘outflow’, or ‘fe’.

  • component (int, optional) – Integer identifier for this component within its region.

  • subregion (str, optional) – Element + spatial subregion tag, useful for complex templates (e.g. FeII sub‐regions).

  • amplitude (float or list of float, optional) – Initial or fixed amplitude(s) for the line(s).

  • element (str, optional) – Chemical identifier of the line (e.g., ‘H’, ‘FeII’).

  • profile (str, optional) – Name of the profile function to use (‘gaussian’, ‘lorentzian’, etc.).

  • region_lines (list of str, optional) – Explicit list of line identifiers included in a composite region.

  • amplitude_relations (list of list, optional) – Parameter‐tying definitions (e.g. fixed ratios) among amplitudes.

  • subprofile (str, optional) – Sub‐profile name for compound models (e.g. a secondary kernel).

  • rarity (str or list of str, optional) – Qualitative frequency label for the line (e.g. ‘common’, ‘rare’).

  • template_info (dict, optional) – Additional template metadata (e.g. for ‘hostmiles’ or ‘fetemplate’ profiles).

(all parameters become attributes of this dataclass)
to_dict()[source]

Convert the SpectralLine instance into a plain dictionary via asdict.

Return type:

dict

Examples

>>> line = SpectralLine(
...     line_name='Halpha',
...     center=6563.0,
...     region='narrow',
...     component=0,
...     profile='gaussian',
...     amplitude=1.0
... )
>>> d = line.to_dict()
>>> print(d['center'])
6563.0
line_name: str | List[str]
center: float | List[float] | None = None
region: str | None = None
component: int | None = None
subregion: str | None = None
amplitude: float | List[float] | None = None
element: str | None = None
profile: str | None = None
region_lines: List[str] | None = None
amplitude_relations: List[List] | None = None
subprofile: str | None = None
rarity: str | List[str] | None = None
template_info: Dict | None = None
to_dict()[source]

Convert the SpectralLine to a dictionary.

Returns:

A dict representation of all fields of the dataclass.

Return type:

dict