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

Data class to store results from spectral region fitting.

Parameters:

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

region_list

List of spectral line configurations.

Type:: List[SpectralLine]

params

Optimized parameters from fitting.

Type:: Optional[jnp.ndarray]

uncertainty_params

Estimated uncertainties for each parameter.

Type:: Optional[jnp.ndarray]

mask

Mask used during the fitting process.

Type:: Optional[jnp.ndarray]

profile_functions

Functions describing each spectral profile.

Type:: Optional[List[Callable]]

profile_names

Names of spectral profiles used in fitting.

Type:: Optional[List[str]]

loss

Values of the loss function during optimization.

Type:: Optional[List]

profile_params_index_list

Indices mapping profile parameters.

Type:: Optional[List]

initial_params

Initial guess parameters before fitting.

Type:: Optional[jnp.ndarray]

scale

scale used for normalization.

Type:: Optional[jnp.ndarray]

params_dict

Mapping from parameter names to indices.

Type:: Optional[Dict[str, int]]

outer_limits

Outer wavelength limits of the fitting region.

Type:: Optional[List]

inner_limits

Inner wavelength limits defining the region of interest.

Type:: Optional[List]

model_keywords

Additional keywords for model configuration.

Type:: Optional[dict]

kind_list

Unique types of spectral lines (computed post-init).

Type:: List[str]

constraints same as constrains from fit

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]

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