sheap.Core package

Core data structures and typing definitions for spectral modeling.

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

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 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 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.