jwspecabund.direct

Direct T_e method for ionic and total abundances.

Uses PyNEB for the atomic physics: electron temperature from auroral-to-nebular line ratios, electron density from density-sensitive doublets, and ionic abundances via getIonAbundance().

References

DESI DR2 (arXiv:2601.02463) T_e-T_e relation
Osterbrock & Ferland (2006) for Case B recombination

Functions

`Te_int_from_high`(Te_high[, relation])	Derive T_e(intermediate) from T_e(high) for the S²⁺ zone.
`Te_low_from_high`(Te_high[, relation])	Derive T_e(low) from T_e(high) using an empirical T_e-T_e relation.
`ciii_ratio_at_density`(ne[, Te])	Predict the CIII] 1909/1907 flux ratio at a given electron density.
`compute_Te_NII`(flux_5756, flux_6585, ne)	Compute T_e(N+) from the [NII] auroral/nebular ratio.
`compute_Te_OIII`(flux_4363, flux_5007, ...)	Compute T_e(O++) from the [OIII] auroral/nebular ratio.
`compute_Te_OIII_1666`(flux_1666, flux_5007, ...)	Compute T_e(O++) from the [OIII] UV/optical ratio 1666/(5007+4959).
`compute_ionic_abundances`(fluxes, Te_high, ...)	Compute all available ionic abundances.
`compute_ne`(flux_line1, flux_line2[, ...])	Compute electron density from a density-sensitive doublet.
`compute_ne_ArIV`(flux_4711, flux_4740[, Te_guess])	Compute electron density from the [Ar IV] 4711/4740 ratio.
`compute_ne_CIII`(flux_1907, flux_1909[, Te_guess])	Compute electron density from the CIII] 1907/1909 ratio.
`compute_ne_NIV`(flux_1483, flux_1486[, Te_guess])	Compute electron density from the NIV] 1483/1486 ratio.
`compute_ne_SiIII`(flux_1883, flux_1892[, ...])	Compute electron density from the [Si III] 1883/1892 ratio.
`compute_total_abundances`(ionic[, logU, ...])	Derive total element abundances from ionic abundances + ICFs.
`heI_4714_over_4472`(Te, ne)	Predict the He I 4714 / He I 4472 recombination flux ratio.
`ne_zone_fallback`(zone, z)	Return the redshift-dependent electron-density fallback for a zone.
`niv_ratio_at_density`(ne[, Te])	Predict the NIV] 1483/1486 flux ratio at a given electron density.

jwspecabund.direct.Te_int_from_high(Te_high, relation='3_tier')[source]

Derive T_e(intermediate) from T_e(high) for the S²⁺ zone.

The intermediate-ionisation zone traces S²⁺ (23.3-34.8 eV) and is used for S²⁺ and Ar²⁺. Garnett (1992) gives t(S III) = 0.83 t(O III) + 0.17 (in 10⁴ K), i.e. T_int = 0.83 * T_high + 1700. This is the relation adopted by Martinez+2025 (arXiv:2510.21960) for the intermediate zone.

Parameters:

Te_high (float) – T_e(O++) in K.
relation (str) – "3_tier" (default), "classical" or "garnett" return the Garnett (1992) S III relation. Any other relation (e.g. "desi") returns None — no intermediate relation is defined, and callers fall back to the T_high/T_low midpoint as before.

Returns:

T_e(intermediate) in K, or None if the relation defines no intermediate zone.

Return type:

float or None

jwspecabund.direct.Te_low_from_high(Te_high, relation='3_tier')[source]

Derive T_e(low) from T_e(high) using an empirical T_e-T_e relation.

The low-ionisation zone traces O⁺/N⁺ (14.5-29.6 eV).

Parameters:

Te_high (float) – T_e(O++) in K.
relation (str) – "3_tier" (default) — Garnett (1992) O⁺ zone, as adopted by Martinez+2025 (arXiv:2510.21960): T_low = 0.70 * T_high + 3000. Pairs with Te_int_from_high() for the intermediate zone so the zones stay monotone (T_high >= T_int >= T_low). "classical" / "garnett" — alias of the Garnett (1992) low relation (identical to "3_tier" for the low zone). "desi" — DESI DR2 (arXiv:2601.02463): T_low = 0.648 * T_high + 3270.

Returns:

T_e(low) in K.

Return type:

float

jwspecabund.direct.ciii_ratio_at_density(ne, Te=10000.0)[source]

Predict the CIII] 1909/1907 flux ratio at a given electron density.

Useful for fixing the CIII] doublet ratio in the fitter when the density is assumed or known from another diagnostic.

Parameters:

ne (float) – Electron density in cm^-3.
Te (float) – Electron temperature in K (default 10^4).

Returns:

Expected F(1909) / F(1907) ratio.

Return type:

float

jwspecabund.direct.compute_Te_NII(flux_5756, flux_6585, ne)[source]

Compute T_e(N+) from the [NII] auroral/nebular ratio.

Parameters:

flux_5756 (float) – [NII] 5756 flux.
flux_6585 (float) – [NII] 6585 flux.
ne (float) – Electron density in cm^-3.

Returns:

T_e(N+) in K.

Return type:

float

jwspecabund.direct.compute_Te_OIII(flux_4363, flux_5007, flux_4959, ne)[source]

Compute T_e(O++) from the [OIII] auroral/nebular ratio.

Uses PyNEB getTemDen() on the O++ atom with the standard diagnostic ratio [OIII] 4363 / ([OIII] 5007 + [OIII] 4959).

Parameters:

flux_4363 (float) – [OIII] 4363 flux.
flux_5007 (float) – [OIII] 5007 flux.
flux_4959 (float) – [OIII] 4959 flux.
ne (float) – Electron density in cm^-3.

Returns:

T_e(O++) in K.

Return type:

float

jwspecabund.direct.compute_Te_OIII_1666(flux_1666, flux_5007, flux_4959, ne)[source]

Compute T_e(O++) from the [OIII] UV/optical ratio 1666/(5007+4959).

Uses the O III] 1666 Å intercombination line (5→2 transition) as a UV auroral diagnostic when [OIII] 4363 is unavailable or low-SNR. The emissivity ratio 1666/(5007+4959) is monotonically increasing with T_e and more temperature-sensitive than 4363/(5007+4959) due to the larger energy gap (7.5 eV vs 2.8 eV).

Parameters:

flux_1666 (float) – O III] 1666 flux (dust-corrected).
flux_5007 (float) – [OIII] 5007 flux (dust-corrected).
flux_4959 (float) – [OIII] 4959 flux (dust-corrected).
ne (float) – Electron density in cm^-3.

Returns:

T_e(O++) in K.

Return type:

float

jwspecabund.direct.compute_ionic_abundances(fluxes, Te_high, Te_low, ne, ne_mid=None, ne_high=None, Te_int=None, ne_Opp=None)[source]

Compute all available ionic abundances.

Parameters:

fluxes (dict) – Dust-corrected emission-line fluxes keyed by line name. Must include "HBETA" for normalisation.
Te_high (float) – T_e(O++) in K.
Te_low (float) – T_e(O+/N+) in K.
ne (float) – Electron density in cm^-3 (low-ionisation zone).
ne_mid (float, optional) – Electron density for the intermediate-ionisation zone (cm^-3). Traced by CIII] 1907/1909 (~24 eV). If None, defaults to ne. Used for O²⁺, Ne²⁺, C²⁺, N²⁺, S²⁺, Ar²⁺. O²⁺ and Ne²⁺ use this intermediate-zone density (not ne_high): the [OIII] 5007/Hβ and [NeIII] 3869/Hβ abundances are density- insensitive below ~10⁴–10⁵ cm⁻³, and CIII] (24–48 eV) overlaps the O²⁺ zone (35–55 eV), whereas NIV] (47–77 eV) traces more highly-ionised gas. This decouples O²⁺/Ne²⁺ from the noisy high-ionisation N IV] density.
ne_high (float, optional) – Electron density for the high-ionisation zone (cm^-3). Traced by NIV] 1483/1486 (~47 eV). If None, defaults to ne_mid. Used for N³⁺, N⁴⁺, C³⁺.
Te_int (float, optional) – Intermediate-zone (S²⁺) electron temperature in K, used for S²⁺ and Ar²⁺. If None (default), the legacy 0.5*(Te_high + Te_low) midpoint is used.
ne_Opp (float, optional) – Electron density for the O²⁺/Ne²⁺ zone (cm^-3), preferentially from [Ar IV] 4711/4740 (Martinez+2025 Table 2). If None (default), falls back to ne_mid (CIII] → ne), preserving the previous behaviour.

Returns:

Ionic abundances, e.g. {"O+/H+": val, "O++/H+": val, ...}.

Return type:

dict

jwspecabund.direct.compute_ne(flux_line1, flux_line2, doublet='SII', Te_guess=15000.0)[source]

Compute electron density from a density-sensitive doublet.

Parameters:

flux_line1 (float) – Flux of the blue member (e.g. [SII] 6718 or [OII] 3726).
flux_line2 (float) – Flux of the red member (e.g. [SII] 6732 or [OII] 3729).
doublet (str) – "SII" (default) or "OII".
Te_guess (float) – Electron temperature guess in K (default 10^4).

Returns:

Electron density n_e in cm^-3.

Return type:

float

jwspecabund.direct.compute_ne_ArIV(flux_4711, flux_4740, Te_guess=15000.0)[source]

Compute electron density from the [Ar IV] 4711/4740 ratio.

Probes the high-ionisation zone (Ar³⁺, 40.7-59.8 eV), overlapping the O²⁺ zone, so it is the preferred density for O²⁺ (Martinez+2025 Table 2). flux_4711 must be the He I-deblended [Ar IV] 4711 flux (see heI_4714_over_4472()); the raw fitted ArIV_4713 line is blended with He I 4714.

Parameters:

flux_4711 (float) – Deblended [Ar IV] 4711 flux.
flux_4740 (float) – [Ar IV] 4740 flux.
Te_guess (float) – Electron temperature guess in K (default 1.5e4).

Returns:

Electron density n_e in cm^-3.

Return type:

float

jwspecabund.direct.compute_ne_CIII(flux_1907, flux_1909, Te_guess=15000.0)[source]

Compute electron density from the CIII] 1907/1909 ratio.

Probes the intermediate-ionisation zone.

Parameters:

flux_1907 (float) – CIII] 1907 flux.
flux_1909 (float) – CIII] 1909 flux.
Te_guess (float) – Electron temperature guess in K (default 10^4).

Returns:

Electron density n_e in cm^-3.

Return type:

float

jwspecabund.direct.compute_ne_NIV(flux_1483, flux_1486, Te_guess=15000.0)[source]

Compute electron density from the NIV] 1483/1486 ratio.

Probes the high-ionisation zone.

Parameters:

flux_1483 (float) – NIV] 1483 flux.
flux_1486 (float) – NIV] 1486 flux.
Te_guess (float) – Electron temperature guess in K (default 10^4).

Returns:

Electron density n_e in cm^-3.

Return type:

float

jwspecabund.direct.compute_ne_SiIII(flux_1883, flux_1892, Te_guess=15000.0)[source]

Compute electron density from the [Si III] 1883/1892 ratio.

A UV density diagnostic (Si²⁺, 16-33 eV). Used as the low-ionisation density fallback for O⁺/N⁺ when the optical [SII]/[OII] doublets are out of coverage (e.g. high-z UV-only stacks; Martinez+2025 Table 2 list n_e(Si²⁺) for the low/intermediate zone).

Parameters:

flux_1883 (float) – [Si III] 1883 flux.
flux_1892 (float) – Si III] 1892 flux.
Te_guess (float) – Electron temperature guess in K (default 1.5e4).

Returns:

Electron density n_e in cm^-3.

Return type:

float

jwspecabund.direct.compute_total_abundances(ionic, logU=None, Z_Zsun=None, ne=None, icf_method='auto', ionic_upper_limits=None, _lock_NO_icf=None)[source]

Derive total element abundances from ionic abundances + ICFs.

Parameters:

ionic (dict) – Ionic abundance dict from compute_ionic_abundances().
logU (float, optional) – Ionisation parameter log(U). Required for Martinez+25 ICFs.
Z_Zsun (float, optional) – Gas-phase metallicity in solar units. Required for Martinez+25 ICFs.
ne (float, optional) – Electron density in cm^-3 for Martinez+25 ICF density interpolation.
icf_method (str) – "auto" (default): use Martinez+25 for N/O when logU is provided, fall back to Izotov+06 otherwise. "martinez25": force Martinez+25 ICFs (requires logU and Z_Zsun). "izotov06": use Izotov+06 ICFs only. "direct_sum": sum all detected nitrogen ions directly (Topping+2024, Yanagisawa+2025, Cameron+2023). Tiered fallback: Tier 1 (N⁺ + N²⁺ + N³⁺) / (O⁺ + O²⁺), Tier 2/3 (N²⁺ + N³⁺) / O²⁺, Tier 4 Izotov+06 optical fallback.
ionic_upper_limits (dict[str, float] | None)
_lock_NO_icf (str | None)

Returns:

Total abundance ratios: "O/H", "N/O", "S/O", "Ne/O", "Ar/O", "C/O", "N/O_UV" as available. When Martinez+25 is used, also includes "NO_icf_name" and "icf_method" keys.

Return type:

dict

jwspecabund.direct.heI_4714_over_4472(Te, ne)[source]

Predict the He I 4714 / He I 4472 recombination flux ratio.

Used to deblend the [Ar IV] 4711 line from the He I 4714 line that falls in the same fitted feature (ArIV_4713). The He I 4714 contribution is estimated as ratio * F(HEI_4472) and subtracted:

F([Ar IV] 4711) = F(ArIV_4713) - ratio * F(HEI_4472).

The ratio is computed from PyNEB He I recombination emissivities (Storey & Hummer 1995) rather than hard-coded, so it tracks the assumed T_e and n_e (~0.11 at 10⁴ K to ~0.18 at 2x10⁴ K).

Parameters:

Te (float) – Electron temperature in K.
ne (float) – Electron density in cm^-3.

Returns:

Expected F(He I 4714) / F(He I 4472).

Return type:

float

jwspecabund.direct.ne_zone_fallback(zone, z)[source]

Return the redshift-dependent electron-density fallback for a zone.

Parameters:

zone (str) – "low", "mid" or "high".
z (float) – Source redshift.

Returns:

Fallback electron density in cm^-3.

Return type:

float

jwspecabund.direct.niv_ratio_at_density(ne, Te=10000.0)[source]

Predict the NIV] 1483/1486 flux ratio at a given electron density.

Useful for fixing the NIV doublet ratio in the fitter when the density is known from another diagnostic (e.g. CIII]).

Parameters:

ne (float) – Electron density in cm^-3.
Te (float) – Electron temperature in K (default 10^4).

Returns:

Expected F(1483) / F(1486) ratio.

Return type:

float