sheap.SheapModelBuilder.Utils module

SheapModelBuilder Utilities

Helpers for constructing parameter ties and grouping spectral lines into composite (SPAF) profiles used by the SheapModelBuilder pipeline.

Main Features

  • Fe ties: Build tied-parameter expressions for Fe regions based on

    element or subregion membership (fe_ties()).

  • Region ties: Generate coherent tie maps for narrow/broad components,

    optionally merging with known relations (_maketies()).

  • Index ties resolution: Flatten index-based dependencies into a simple

    (coefficient, free-index) mapping (flatten_index_ties()).

  • Line grouping (SPAF): Collapse multiple lines into grouped pseudo-lines

    with amplitude relations for compact modeling (group_lines()).

Notes

  • Tie expressions follow the naming scheme:

    {param}_{line_name}_{component}_{region}, e.g. center_Hbeta_1_broad or fwhm_OIIIc_1_narrow.

  • Amplitude handling may depend on your parameterization (e.g., logamp vs

    linear amplitude). If you moved to logarithmic amplitudes, ensure upstream tie generation is consistent with that convention.

  • The grouping logic supports modes "region", "subregion", and

    "element"; choose according to how you want lines fused.

default_known_tied_relations(include_balmer=True, include_forbidden=True)[source]
Parameters:

  • include_balmer (bool)

  • include_forbidden (bool)

Return type:

List[Tuple[Tuple[str, …], List[str]]]

fe_ties(entries, routine_fe_tied)[source]

Generate tied parameter expressions for Fe emission lines.

Parameters:

  • entries (list of SpectralLine) – Spectral line entries to be checked for Fe region membership.

  • routine_fe_tied (dict) – Dictionary with tie rules, e.g. {‘by’: ‘element’, ‘tied_params’: (‘center’, ‘fwhm’)}.

Returns:

Each inner list is a pair of tied parameter names [dependent, reference].

Return type:

list of list of str

flatten_index_ties(index_ties)[source]

Resolve index-based tie dependencies into coefficient + free parameter mapping.

Parameters:

index_ties (list of tuple) – Each entry is (target_idx, source_idx, operation, value).

Returns:

Mapping from target index to (coefficient, source index).

Return type:

dict

group_lines(lines, region, profile='gaussian', mode='region', known_tied_relations=[])[source]

Collapse multiple spectral lines into grouped pseudo-lines with SPAF profiles.

Parameters:

  • lines (list of SpectralLine) – Full list of lines in the region.

  • region (str) – Region name to group (e.g., “fe”, “narrow”).

  • profile (str, default "gaussian") – Base profile to assign to grouped line.

  • mode ({"region", "subregion", "element"}) – Grouping logic applied.

  • known_tied_relations (list, optional) – Amplitude tie relations to apply.

Returns:

Lines with some collapsed into SPAF composite profiles.

Return type:

list of SpectralLine