`jwspecabund` — chemical abundances

jwspecabund turns a FitResult (from jwspecfit) or an MCMCResult (from jwspecmcmc) into element abundances: 12 + log(O/H), log(N/O), log(C/O), log(S/O), log(Ne/O), log(Ar/O), with electron temperatures, densities, and dust attenuation.

Basic usage

import jwspecabund

abund = jwspecabund.compute_abundances(result, z=6.0)
print(abund.summary())

Pipeline

compute_abundances runs five stages in order:

1 — Dust correction

A_V is derived from the multi-Balmer decrement. The anchor is the denominator line; only Balmer lines bluer than the anchor (and above snr_balmer) are ratioed against it, and the per-line A_V values are combined as an inverse-variance weighted mean. So:

balmer_anchor="HBETA" (default) uses Hγ/Hβ, Hδ/Hβ, H9/Hβ, H10/Hβ — Hα is excluded (it’s redder than Hβ).
balmer_anchor="Ha" uses every other Balmer line (Hβ/Hα, Hγ/Hα, Hδ/Hα, H9/Hα, H10/Hα) — i.e. all of them that pass the SNR cut.

Anchor on Hα when you want Hα included; on Hβ when you want only the bluer Balmer series:

abund = jwspecabund.compute_abundances(
    result, z=2.5,
    balmer_anchor="Ha",    # or "HBETA" (default)
    dust_law="salim",       # or "cardelli"
)

A per-line A_V is computed against the anchor, then an inverse-variance weighted mean is returned. You can also supply Av= directly to skip the derivation entirely, or dust_correct=False to turn dust off.

Forcing a single Balmer pair. To derive A_V from exactly one decrement — and ignore lower-SNR Balmer lines — pass balmer_pair:

abund = jwspecabund.compute_abundances(
    result, z=6.0,
    balmer_pair=("Ha", "HBETA"),   # A_V from Hα/Hβ only
    dust_law="cardelli",
)
print(f"A_V = {abund.Av:.3f} ± {abund.Av_err:.3f}")

balmer_pair=(numerator, denominator) accepts ladder names "Ha", "HBETA", "HGAMMA", "HDELTA", "H9", "H10"; the intrinsic Case-B ratio is looked up automatically. It overrides balmer_anchor / snr_balmer for the A_V step and is ignored when Av= is supplied. A_V is still applied as a single point value (the abundance error is not widened by the A_V uncertainty), but both abund.Av and abund.Av_err (the formal error of the chosen pair) are reported. If either line is missing or non-positive, A_V falls back to 0 with Av_err = nan — check for 0.000 ± nan when looping over objects. The same single-pair calculation is available standalone as compute_Av_balmer_pair().

All line fluxes are then corrected at each line’s own rest wavelength — the correction is fully wavelength-dependent.

Note

A_V is held constant across MCMC draws by default. When the input is an MCMCResult, the single A_V derived above is applied once to every posterior draw (the Balmer-propagated A_V error is reported on the result but not marginalised into the abundance posteriors). To marginalise over A_V instead — each draw dust-corrected with its own A_V sample — opt in by passing Av_err=<value> explicitly (and optionally Av_prior="gaussian" or "uniform").

2 — Electron density

Three-zone density from whatever ratios are available:

Zone	Diagnostic	Fallback
Low-ionisation	[S II] 6718/6732	[O II] 3726/3729, else 300 cm⁻³
Mid-ionisation	C III] 1907/1909	—
High-ionisation	N IV] 1483/1486	mid-zone, else low-zone

Each zone can be forced manually:

abund = jwspecabund.compute_abundances(
    result, z=6.0,
    ne_low_override=500.0,
    ne_mid_override=2.0e4,
    ne_high_override=1.0e5,
)

3 — Method selection

Method	Triggered when	What it does
`"direct"`	[O III] 4363 detected (SNR ≥ `snr_auroral`)	T_e from [O III] 4363 / (5007 + 4959); ionic abundances via PyNEB
`"direct"` (UV)	4363 absent, O III] 1666 detected	T_e from 1666 / (5007 + 4959); larger 7.5 eV gap → more sensitive
`"strong_line"`	No auroral line available	Sanders+25 simultaneous polynomial across O3, O2, R23, O32
`"forward"`	Requested explicitly	Cullen+25 Bayesian forward model, sampling T_e, n_e, log U, ionic abundances

4 — Ionic and total abundances

For the direct method, PyNEB computes O⁺/H⁺, O²⁺/H⁺, N⁺/H⁺, C⁺/H⁺, C²⁺/H⁺, Ne²⁺/H⁺, S⁺/H⁺, S²⁺/H⁺, Ar²⁺/H⁺, Ar³⁺/H⁺. ICFs convert ionic to total:

N/O — Martinez+25 (multiple tiers auto-selected, override via icf_tier=)
C/O — Garnett+97
S/O, Ne/O, Ar/O — Izotov+06

5 — T_e-T_e relation

When only the high-ionisation T_e is measured, the low-ionisation T_e comes from:

"desi" (default) — DESI DR2 calibration
"classical" — Garnett 1992

Result fields

Field	Description
`OH`, `OH_err`	12 + log(O/H) and uncertainty
`NO`, `CO`, `SO`, `NeO`, `ArO` (+`_err`)	Element ratios
`Te_high`, `Te_low` (+`_err`)	Electron temperatures (K)
`ne`, `ne_low`, `ne_mid`, `ne_high`	Electron densities (cm⁻³)
`Av`, `Av_err`	Dust attenuation
`logU`, `logU_err`	Ionisation parameter
`ionic`	Dict of ionic abundance ratios
`icf_method`, `NO_icf_name`	ICF scheme and tier used for N/O
`OH_posterior`, `NO_posterior`	Full posterior arrays (MC / MCMC)
`method`	`"direct"` / `"strong_line"` / `"forward"`

Lyα escape fraction

When Lyα is present, the intrinsic flux is predicted from the dust-corrected Balmer lines via Case B, and the escape fraction f_esc = F_obs(Lyα) / F_int(Lyα) is returned with MC propagation of A_V uncertainty:

print(abund.lya_f_esc)       # median
print(abund.lya_f_esc_err)   # (lo, hi)

See Chemical Abundance Methodology for the full derivation.

jwspecabund — chemical abundances