jwspecfit.broad

Broad Balmer component fitting with BIC model selection.

Detects broad Hα and Hβ components by comparing narrow-only vs narrow+broad models using the Bayesian Information Criterion (BIC).

Functions

fit_with_broad(spectrum, z, *[, grating, R, ...])

Fit emission lines with optional BIC-selected broad components.

Classes

BroadFitResult(best_fit, selected_model, ...)

Result of broad component model selection.
class jwspecfit.broad.BroadFitResult(best_fit, selected_model, bic_narrow, bic_broad1, bic_broad2, bic_both, all_fits, bic_bootstrap=<factory>, oiii_selected='off', bic_oiii_off=nan, bic_oiii_broad1=nan, bic_oiii_broad2=nan, bic_oiii_both=nan, bic_oiii_bootstrap=<factory>, hei_selected='off', bic_hei_off=nan, bic_hei_broad1=nan, bic_hei_broad2=nan, bic_hei_both=nan, bic_hei_bootstrap=<factory>)[source]

Bases: object

Result of broad component model selection.

Parameters:
best_fit

The selected best-fit result.

Type:

FitResult

selected_model

Model name: "narrow", "broad1", "broad2", or "both".

Type:

str

bic_narrow

Median BIC for narrow-only model (from bootstrap when used).

Type:

float

bic_broad1

Median BIC for narrow + BROAD1 model (NaN if not attempted).

Type:

float

bic_broad2

Median BIC for narrow + BROAD2 model (NaN if not attempted).

Type:

float

bic_both

Median BIC for narrow + BROAD1 + BROAD2 model (NaN if not attempted).

Type:

float

all_fits

All fitted models for inspection.

Type:

dict[str, FitResult]

bic_bootstrap

Full BIC distributions from bootstrap iterations. Empty if bootstrap BIC was not run.

Type:

dict[str, np.ndarray]

all_fits: dict[str, FitResult]
best_fit: FitResult
bic_bootstrap: dict[str, ndarray]
bic_both: float
bic_broad1: float
bic_broad2: float
bic_hei_bootstrap: dict[str, ndarray]
bic_hei_both: float = nan
bic_hei_broad1: float = nan
bic_hei_broad2: float = nan
bic_hei_off: float = nan
bic_narrow: float
bic_oiii_bootstrap: dict[str, ndarray]
bic_oiii_both: float = nan
bic_oiii_broad1: float = nan
bic_oiii_broad2: float = nan
bic_oiii_off: float = nan
property chi2: float

Reduced chi-squared.

property constraints

Applied constraints.

property continuum: ndarray

Best-fit continuum.

property hei_broad_selected: bool

True if any HeI broad component was selected.

Type:

Convenience

hei_selected: str = 'off'
property line_names: list[str]

Ordered line names.

property lines: dict

Per-line results (delegates to best_fit.lines).

property model_flux: ndarray

Best-fit emission-line model.

property oiii_broad_selected: bool

True if any OIII broad component was selected.

Type:

Convenience

oiii_selected: str = 'off'
property params: ndarray

Best-fit parameter vector.

property residuals: ndarray

Fit residuals.

selected_model: str
property spectrum

Input spectrum.

property success: bool

Whether the optimiser converged.

jwspecfit.broad.fit_with_broad(spectrum, z, *, grating=None, R=None, lines=None, deg=2, fit_balmer_broad=False, fit_oiii_broad=False, fit_hei_broad=False, n_boot=1000, n_boot_bic=100, n_jobs=-1, snr_threshold=5.0, oiii_snr_threshold=5.0, hei_snr_threshold=5.0, bic_delta=6.0, sigma_factor=1.0, centroid_vmax=500.0, centroid_max_sigma=1.0, moving_average=False, tie_uv_doublets=True, tie_uv_centroids=True, tie_uv_widths=True, sigma_overrides=None, centroid_overrides=None, niv_doublet_ratio=None, ciii_doublet_ratio=None, _print_R=True)[source]

Fit emission lines with optional BIC-selected broad components.

Two independent BIC tests can be enabled:

  • Balmer broad (fit_balmer_broad): tests narrow vs. narrow + intermediate broad (FWHM 500–2000 km/s) vs. narrow + very broad (FWHM 2000–5000 km/s) vs. narrow + both. Gated by snr_threshold on Hα.

  • [OIII] broad (fit_oiii_broad): tests baseline vs. baseline + broad [OIII] 5007/4959 (outflow signature). Gated by oiii_snr_threshold on [OIII] 5007 / 4959.

The two tests are independent — both can be selected, only one, or neither.

Parameters:

  • spectrum (Spectrum) – Input spectrum.

  • z (float) – Source redshift.

  • grating (str, optional) – Grating name.

  • R (float or callable, optional) – Resolving power.

  • lines (list of str, optional) – Narrow line list. If None, auto-detected.

  • deg (int) – Continuum polynomial degree.

  • fit_balmer_broad (bool) – If True, run BIC model selection for a broad Balmer component (intermediate / very-broad / both). Default False — opt in only when you want to test for a BLR or outflow signature on Hα/Hβ.

  • fit_oiii_broad (bool) – If True, run an independent BIC test for a broad component on [OIII] 5007/4959. Decoupled from the Balmer test. Default False — opt in only when looking for outflow signatures.

  • fit_hei_broad (bool) – If True, run an independent BIC test for a broad component on all observable He I lines (5877/6680/4472/…). Within each tier all HeI broads share kinematics (anchored on first present). Default False.

  • n_boot (int) – Number of bootstrap iterations for flux uncertainties (default 1000).

  • n_boot_bic (int) – Number of bootstrap iterations for BIC model selection (default 100). Set to 0 for single-point BIC (legacy behaviour).

  • n_jobs (int) – Number of parallel jobs for bootstrap. -1 uses all cores, 1 runs sequentially. Default -1.

  • snr_threshold (float) – Minimum Hα SNR to attempt the Balmer broad fit (default 5.0).

  • oiii_snr_threshold (float) – Minimum [OIII] 5007 / 4959 SNR to attempt the OIII broad fit (default 5.0).

  • bic_delta (float) – ΔBIC threshold for accepting a more complex model (default 6.0).

  • hei_snr_threshold (float)

  • sigma_factor (float)

  • centroid_vmax (float)

  • centroid_max_sigma (float)

  • moving_average (bool | int)

  • tie_uv_doublets (bool)

  • tie_uv_centroids (bool)

  • tie_uv_widths (bool)

  • sigma_overrides (dict[str, tuple[float, float]] | None)

  • centroid_overrides (dict[str, tuple[float, float]] | None)

  • niv_doublet_ratio (float | None)

  • ciii_doublet_ratio (float | None)

  • _print_R (bool)

Return type:

BroadFitResult