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,
    criteria: ExposureCriteria,
    sel_margin: float | None,
    tts_margin: float | None,
    peak_margin: float | None,
    tts_peak_margin: float | None,
    exceeds_injury: bool,
    exceeds_tts: bool,
    guidance: str,
    group: str,
)

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).
`criteria`	The `ExposureCriteria` compared against.
`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.
`exceeds_injury`	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.
`exceeds_tts`	Whether any TTS-onset criterion is reached, on the same `margin >= 0` convention as `exceeds_injury`.
`guidance`	The guidance version.
`group`	Hearing-group code.

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