jwspecabund.martinez25_icf

Density-dependent ICFs and logU diagnostics from Martinez+2025.

Bicubic surface fits to Cloudy photoionization models for five N/O ionisation correction factors and two ionisation parameter diagnostics, each evaluated on a grid of electron densities (10^2 to 10^6 cm^-3).

References

Martinez, M. A., Berg, D. A., et al. 2025, arXiv:2510.21960.

Table 3 (ionisation parameter fits) and Table 4 (ICF fits).

Berg, D. A., et al. 2025, arXiv:2511.13591.

Recommended 6-step procedure for UV N/O abundance determinations.

The bicubic surface is:

f(x, y) = A + Bx + Cy + Dxy + Ex^2 + Fy^2 + Gxy^2 + Hyx^2 + Ix^3 + Jy^3

where x and y depend on the diagnostic (see individual function docstrings).

Functions

compute_NO_martinez25(ionic, logU, Z_Zsun[, ne])

Compute total N/O using the best available Martinez+2025 ICF.

compute_NO_martinez25_locked(ionic, logU, ...)

Compute N/O using a specific Martinez+25 ICF (no cascade).

icf_NpNpp_OpOpp(logU, Z_Zsun[, ne])

ICF 4: N/O = ((N+ + N2+)/(O+ + O2+)) x ICF.

icf_NpOp(logU, Z_Zsun[, ne])

ICF 1: N/O = (N+/O+) x ICF.

icf_NppNppp_Opp(logU, Z_Zsun[, ne])

ICF 5: N/O = ((N2+ + N3+)/O2+) x ICF.

icf_NppOpp(logU, Z_Zsun[, ne])

ICF 2: N/O = (N2+/O2+) x ICF.

icf_NpppOpp(logU, Z_Zsun[, ne])

ICF 3: N/O = (N3+/O2+) x ICF.

log_U_from_N43(log_N43, Z_Zsun[, ne])

Compute log(U_high) from the N43 diagnostic.

log_U_from_O32(log_O32, Z_Zsun[, ne])

Compute log(U_int) from the O32 diagnostic.
jwspecabund.martinez25_icf.compute_NO_martinez25(ionic, logU, Z_Zsun, ne=100.0)[source]

Compute total N/O using the best available Martinez+2025 ICF.

Selects the ICF based on which ionic abundances are present, with the following priority (most to least preferred):

  1. ICF 5: (N2+ + N3+)/O2+ — pure UV, best at high logU

  2. ICF 4: (N+ + N2+)/(O+ + O2+) — mixed UV+optical

  3. ICF 2: N2+/O2+ — UV only, single ion

  4. ICF 1: N+/O+ — classical optical

  5. ICF 3: N3+/O2+ — large corrections, least preferred

Parameters:

  • ionic (dict) – Ionic abundance dict, e.g. {"O+/H+": val, "O++/H+": val, "N+/H+": val, "N++/H+": val, "N+++/H+": val}.

  • logU (float) – Ionisation parameter log(U).

  • Z_Zsun (float) – Gas-phase metallicity in solar units.

  • ne (float) – Electron density in cm^-3 (default 100).

Returns:

(N/O, icf_name) where icf_name identifies the ICF used (e.g. "NppNppp_Opp"). Returns (None, None) if no suitable ionic abundances are available.

Return type:

tuple

jwspecabund.martinez25_icf.compute_NO_martinez25_locked(ionic, logU, Z_Zsun, ne, icf_name)[source]

Compute N/O using a specific Martinez+25 ICF (no cascade).

Parameters:

  • ionic (dict) – Ionic abundance dict.

  • logU (float) – Ionisation parameter log(U).

  • Z_Zsun (float) – Gas-phase metallicity in solar units.

  • ne (float) – Electron density in cm^-3.

  • icf_name (str) – ICF name to use, e.g. "NppNppp_Opp" for ICF 5.

Returns:

N/O value, or None if the required ions are not available.

Return type:

float or None

jwspecabund.martinez25_icf.icf_NpNpp_OpOpp(logU, Z_Zsun, ne=100.0)[source]

ICF 4: N/O = ((N+ + N2+)/(O+ + O2+)) x ICF.

Parameters:

  • logU (float) – Ionisation parameter log(U).

  • Z_Zsun (float) – Gas-phase metallicity in solar units.

  • ne (float) – Electron density in cm^-3 (default 100).

Returns:

ICF value (multiplicative correction to (N++N2+)/(O++O2+)).

Return type:

float

Notes

Combines optical (N+, O+) and UV (N2+, O2+) ionic abundances. Martinez+2025 Table 4, row 4.

jwspecabund.martinez25_icf.icf_NpOp(logU, Z_Zsun, ne=100.0)[source]

ICF 1: N/O = (N+/O+) x ICF.

Parameters:

  • logU (float) – Ionisation parameter log(U).

  • Z_Zsun (float) – Gas-phase metallicity in solar units.

  • ne (float) – Electron density in cm^-3 (default 100).

Returns:

ICF value (multiplicative correction to N+/O+).

Return type:

float

Notes

At low density (ne ~ 100), the correction is small (< 10%); at high density (ne ~ 10^6), can overestimate N/O by up to 40%. Martinez+2025 Table 4, row 1.

jwspecabund.martinez25_icf.icf_NppNppp_Opp(logU, Z_Zsun, ne=100.0)[source]

ICF 5: N/O = ((N2+ + N3+)/O2+) x ICF.

Parameters:

  • logU (float) – Ionisation parameter log(U).

  • Z_Zsun (float) – Gas-phase metallicity in solar units.

  • ne (float) – Electron density in cm^-3 (default 100).

Returns:

ICF value (multiplicative correction to (N2++N3+)/O2+).

Return type:

float

Notes

Pure UV diagnostic. Most robust at log(U) > -2.75 with corrections < 5%. Recommended when both NIII] and NIV] are detected. Martinez+2025 Table 4, row 5.

jwspecabund.martinez25_icf.icf_NppOpp(logU, Z_Zsun, ne=100.0)[source]

ICF 2: N/O = (N2+/O2+) x ICF.

Parameters:

  • logU (float) – Ionisation parameter log(U).

  • Z_Zsun (float) – Gas-phase metallicity in solar units.

  • ne (float) – Electron density in cm^-3 (default 100).

Returns:

ICF value (multiplicative correction to N2+/O2+).

Return type:

float

Notes

Overestimates N/O at low logU, underestimates at high logU. Martinez+2025 Table 4, row 2.

jwspecabund.martinez25_icf.icf_NpppOpp(logU, Z_Zsun, ne=100.0)[source]

ICF 3: N/O = (N3+/O2+) x ICF.

Parameters:

  • logU (float) – Ionisation parameter log(U).

  • Z_Zsun (float) – Gas-phase metallicity in solar units.

  • ne (float) – Electron density in cm^-3 (default 100).

Returns:

ICF value (multiplicative correction to N3+/O2+).

Return type:

float

Notes

The bicubic surface returns log(ICF); this function exponentiates to return the ICF itself. N3+/O2+ alone underestimates N/O by 100–15000%. Martinez+2025 Table 4, row 3.

jwspecabund.martinez25_icf.log_U_from_N43(log_N43, Z_Zsun, ne=100.0)[source]

Compute log(U_high) from the N43 diagnostic.

Parameters:

  • log_N43 (float) – log10(NIV] 1486 / NIII] 1750).

  • Z_Zsun (float) – Gas-phase metallicity in solar units.

  • ne (float) – Electron density in cm^-3 (default 100).

Returns:

log(U_high).

Return type:

float

Notes

Valid for 0.05 <= Z/Zsun <= 0.4, -3.0 <= log(N43) <= 0.5. N43 is density-insensitive — recommended over O32 when NIV] and NIII] are available (Martinez+2025 Section 4.2). Martinez+2025 Table 3 (lower).

jwspecabund.martinez25_icf.log_U_from_O32(log_O32, Z_Zsun, ne=100.0)[source]

Compute log(U_int) from the O32 diagnostic.

Parameters:

  • log_O32 (float) – log10([OIII] 5007 / [OII] 3727).

  • Z_Zsun (float) – Gas-phase metallicity in solar units.

  • ne (float) – Electron density in cm^-3 (default 100).

Returns:

log(U_int).

Return type:

float

Notes

Valid for 0.05 <= Z/Zsun <= 0.4, -1.0 <= log(O32) <= 2.5. O32 is density-sensitive; prefer N43 when available. Martinez+2025 Table 3 (upper).