underwater.bioacoustics.weighting

Regulatory auditory weighting and exposure criteria for marine mammals.

Noise-exposure assessments weight a spectrum by a hearing-group filter before comparing it with a threshold. The filter is the same band-pass form in all current guidance (NMFS 2018 Equation 1, Southall et al. 2019 Equation 2):

W (f) = C + 10 lo g_{10} \frac{( f / f _{1} ) ^{2 a}}{[ 1 + ( f / f _{1} ) ^{2} ] ^{a} [ 1 + ( f / f _{2} ) ^{2} ] ^{b}}

with f in kilohertz. C is fixed by putting the peak of W at 0 dB, so the companion exposure function $E (f) = K - 10 lo g_{10} (\dots) = K + C - W (f)$ has its minimum at the weighted threshold $T_{w} = K + C$ . Only the parameter table changes between guidance versions, so the version is explicit in the API and is carried on every result object:

"nmfs-2024" — NOAA Fisheries, Updated Technical Guidance, version 3.0 (October 2024), Table 5 and Table ES3. The default: it supersedes the 2018 revision, uses $b = 5$ for every group, renames the groups to the Southall scheme (LF/HF/VHF cetaceans, PW/OW in water, PA/OA in air) and replaces “PTS onset” with “auditory injury (AUD INJ) onset”.
"nmfs-2018" — the 2018 revision, version 2.0, Table 3 and Table ES3. Still cited by assessments already in flight.
"southall-2019" — Southall et al., Aquatic Mammals 45(2), Tables 5, 6 and 7, the peer-reviewed criteria; adds sirenians (SI) and both in-air carnivore groups. Numerically identical to NMFS 2018 on the five shared groups.

Group names are not portable between versions. NMFS 2018 calls the mid-frequency cetaceans MF and the porpoise-type group HF; NMFS 2024 and Southall call the same two HF and VHF. Each guidance version only accepts its own codes.

The module exposes the weighting itself (auditory_weighting), the published thresholds (exposure_criteria) and the assessment chain (weighted_exposure), which weights a band spectrum, accumulates it over a number of events and reports the exceedance of each applicable criterion.

Implemented clean-room from the three documents; validated against the worked example of NMFS (2018) Appendix D ( $W (1 kHz)$ for the five groups), against C recomputed as the peak of W for all three parameter sets, and against the published $T_{w} = K + C$ and injury = TTS + 20 dB identities.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

auditory_weighting

auditory_weighting(
    frequency_hz: NDArray[np.float64] | list[float] | float,
    group: str,
    *,
    guidance: str = 'nmfs-2024',
) -> AuditoryWeightingResult

Auditory weighting function W(f) of a marine-mammal hearing group.

Parameters

Name	Description
`frequency_hz`	Frequency or frequencies, in Hz (strictly positive).
`group`	Hearing-group code as used by `guidance`.
`guidance`	`"nmfs-2024"` (default, current), `"nmfs-2018"` or `"southall-2019"`.

Returns: An AuditoryWeightingResult.

Raises

Exception	When
ValueError	If an input is invalid.

AuditoryWeightingResult

AuditoryWeightingResult(
    frequencies: NDArray[np.float64],
    weighting: NDArray[np.float64],
    exposure_function: NDArray[np.float64],
    parameters: WeightingParameters,
    guidance: str,
    group: str,
    weighted_tts_onset: float,
)

Auditory weighting and exposure functions of one hearing group.

Attributes

Name	Description
`frequencies`	Frequencies, in Hz.
`weighting`	Weighting-function amplitude `W(f)`, in dB ( $\leq 0$ ).
`exposure_function`	Exposure function $E (f) = K + C - W (f)$ , in dB (the frequency-dependent TTS-onset level).
`parameters`	The `WeightingParameters` used.
`guidance`	The guidance version.
`group`	Hearing-group code.
`weighted_tts_onset`	$T_{w} = K + C$ , the minimum of the exposure function, in dB.

AuditoryWeightingResult.plot()

AuditoryWeightingResult.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Plot the weighting function versus frequency.

exposure_criteria

exposure_criteria(
    group: str,
    *,
    guidance: str = 'nmfs-2024',
    impulsive: bool = False,
) -> ExposureCriteria

Published TTS and injury onset criteria of a hearing group.

Parameters

Name	Description
`group`	Hearing-group code as used by `guidance`.
`guidance`	`"nmfs-2024"` (default), `"nmfs-2018"` or `"southall-2019"`.
`impulsive`	Return the impulsive-noise criteria (dual metric: a weighted SEL and an unweighted peak SPL) instead of the non-impulsive ones.

Returns: An ExposureCriteria.

Raises

Exception	When
ValueError	If the version or the group is unknown.

ExposureCriteria

ExposureCriteria(
    group: str,
    guidance: str,
    *,
    impulsive: bool,
    tts_sel: float | None,
    injury_sel: float | None,
    tts_peak_spl: float | None,
    injury_peak_spl: float | None,
    injury_label: str,
    sel_reference: str,
    peak_reference: str,
    source: str,
)

Published TTS and injury (PTS / AUD INJ) onset criteria for one group.

Sound exposure levels are weighted; peak sound pressure levels are unweighted (“flat”), as every source states. None means the criterion is not published by that guidance version.

Attributes

Name	Description
`group`	Hearing-group code.
`guidance`	The guidance version.
`impulsive`	Whether these are the impulsive-noise criteria.
`tts_sel`	Weighted TTS-onset sound exposure level, in dB.
`injury_sel`	Weighted injury-onset (PTS / AUD INJ) SEL, in dB.
`tts_peak_spl`	Unweighted TTS-onset peak SPL, in dB.
`injury_peak_spl`	Unweighted injury-onset peak SPL, in dB.
`injury_label`	`"PTS"` or `"AUD INJ"`, as the source names it.
`sel_reference`	Human-readable SEL reference of the group.
`peak_reference`	Human-readable peak-SPL reference of the group.
`source`	Table the numbers come from.

hearing_groups

hearing_groups(guidance: str = 'nmfs-2024') -> tuple[str, ...]

Hearing-group codes defined by a guidance version.

Parameters

Name	Description
`guidance`	One of `WEIGHTING_GUIDANCE`.

Returns: The group codes, in the order the source tabulates them.

Raises

Exception	When
ValueError	If the version is unknown.

weighted_exposure

weighted_exposure(
    frequency_hz: NDArray[np.float64] | list[float],
    band_sel: NDArray[np.float64] | list[float],
    group: str,
    *,
    guidance: str = 'nmfs-2024',
    impulsive: bool = True,
    n_events: int = 1,
    peak_spl: float | None = None,
) -> WeightedExposureResult

Weight a band spectrum, accumulate it and compare it with the criteria.

The per-band single-event sound exposure levels are weighted with auditory_weighting, summed on an energy basis and accumulated over n_events identical events ( $+ 10 lo g_{10} N$ , the ISO 18406 Formula 9 identity used by cumulative_sel_identical). The result is compared with the group’s TTS and injury onset criteria; the peak sound pressure level, if supplied, is compared unweighted, as the dual-metric rule requires.

Parameters

Name	Description
`frequency_hz`	Band centre frequencies, in Hz (1-D, positive).
`band_sel`	Per-band single-event SEL, in dB re 1 µPa²·s (or dB re (20 µPa)²·s for an in-air group); same shape. `-inf` is accepted for a band that carries no energy, which is what `strike_sel_spectrum` returns for bands narrower than its FFT bin spacing; such a band adds nothing to the energy sum. Both input arrays are copied, so the result never aliases the caller’s data.
`group`	Hearing-group code as used by `guidance`.
`guidance`	`"nmfs-2024"` (default), `"nmfs-2018"` or `"southall-2019"`.
`impulsive`	Compare against the impulsive criteria (the default, the case for pile driving and air guns).
`n_events`	Number of identical accumulated events, $\geq 1$ .
`peak_spl`	Unweighted zero-to-peak sound pressure level of the loudest single event, in dB; enables the peak-SPL half of the dual metric.

Returns: A WeightedExposureResult.

Raises

Exception	When
ValueError	If an input is invalid.

WeightedExposureResult

WeightedExposureResult(
    frequencies: NDArray[np.float64],
    band_sel: NDArray[np.float64],
    weighting: NDArray[np.float64],
    weighted_band_sel: NDArray[np.float64],
    unweighted_sel: float,
    weighted_sel: float,
    cumulative_sel: float,
    peak_spl: float | None,
    n_events: int,
    sel_margin: float | None,
    tts_margin: float | None,
    peak_margin: float | None,
    tts_peak_margin: float | None,
    *,
    guidance: str,
    group: str,
    impulsive: bool,
)

Weighted exposure of a spectrum against a hearing group’s criteria.

Attributes

Name	Description
`frequencies`	Band centre frequencies, in Hz.
`band_sel`	Per-band single-event sound exposure level, in dB.
`weighting`	Weighting-function amplitude at each band, in dB.
`weighted_band_sel`	`band_sel + W(f)` per band, in dB.
`unweighted_sel`	Energy sum of `band_sel`, in dB.
`weighted_sel`	Energy sum of `weighted_band_sel`, in dB.
`cumulative_sel`	`weighted_sel` plus $10 lo g_{10} (N)$ for the `n_events` accumulated events, in dB.
`peak_spl`	The unweighted peak sound pressure level supplied, in dB (`None` when not given).
`n_events`	Number of accumulated events (e.g. hammer strikes).
`sel_margin`	`cumulative_sel - injury_sel`, in dB (`None` when the criterion is not published); positive means the criterion is exceeded.
`tts_margin`	`cumulative_sel - tts_sel`, in dB (or `None`).
`peak_margin`	`peak_spl - injury_peak_spl`, in dB (or `None`).
`tts_peak_margin`	`peak_spl - tts_peak_spl`, in dB (or `None`) — the peak-SPL half of the dual metric on the TTS side, which can trip `exceeds_tts` on its own.
`guidance`	The guidance version.
`group`	Hearing-group code.
`impulsive`	Whether the impulsive criteria were compared against.

The published criteria (criteria) are read from the guidance, the group and impulsive, so an assessment cannot be built against other criteria.

WeightedExposureResult.criteria

property

The ExposureCriteria compared against.

Returns: exposure_criteria of group under guidance, impulsive or not.

WeightedExposureResult.exceeds_injury

property

Whether any injury-onset criterion is reached.

The test is margin >= 0, so an exposure landing exactly on the criterion counts as exceeding it; the criteria are onset thresholds and the precautionary reading is the one an assessment wants.

WeightedExposureResult.exceeds_tts

property

Whether any TTS-onset criterion is reached, on the same margin >= 0 convention.

WeightedExposureResult.plot()

WeightedExposureResult.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Plot the unweighted and weighted band spectra with the criteria.

WEIGHTING_GUIDANCE

Constant (tuple).

WEIGHTING_GUIDANCE = ('nmfs-2024', 'nmfs-2018', 'southall-2019')

weighting_parameters

weighting_parameters(
    group: str,
    *,
    guidance: str = 'nmfs-2024',
) -> WeightingParameters

Weighting/exposure parameters of one hearing group.

Parameters

Name	Description
`group`	Hearing-group code as used by `guidance` (case-insensitive).
`guidance`	One of `WEIGHTING_GUIDANCE`.

Returns: The WeightingParameters row.

Raises

Exception	When
ValueError	If the version or the group is unknown.

WeightingParameters

WeightingParameters(
    group: str,
    guidance: str,
    description: str,
    a: float,
    b: float,
    f1_khz: float,
    f2_khz: float,
    c_db: float,
    c_db_as_printed: float,
    k_db: float,
    *,
    in_air: bool,
    hearing_range_hz: tuple[float, float] | None,
)

Auditory weighting and exposure function parameters for one group.

Attributes

Name	Description
`group`	Hearing-group code as used by its own guidance version.
`guidance`	The guidance version the row comes from.
`description`	Plain-language name of the hearing group.
`a`	Low-frequency exponent `a`.
`b`	High-frequency exponent `b`.
`f1_khz`	Low-frequency transition `f1`, in kHz.
`f2_khz`	High-frequency transition `f2`, in kHz.
`c_db`	Gain `C` that puts the peak of `W` at 0 dB, in dB.
`c_db_as_printed`	`C` exactly as printed in the source table, in dB (differs from `c_db` only for the NMFS 2024 otariid row).
`k_db`	Exposure-function constant `K`, in dB.
`in_air`	Whether the group’s reference is 20 µPa (in air).
`hearing_range_hz`	Generalised hearing range of the group, in Hz, or `None`. Only the NMFS documents tabulate one (their Table ES1); Southall et al. do not, and the field is `None` for those rows rather than borrowed from elsewhere.

Created and maintained by José Manuel Requena Plens ORCID All projects