Skip to content

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):

with f in kilohertz. C is fixed by putting the peak of W at 0 dB, so the companion exposure function has its minimum at the weighted threshold . 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 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 ( for the five groups), against C recomputed as the peak of W for all three parameter sets, and against the published 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(
frequency_hz: NumericArrayLike,
group: Literal['LF', 'MF', 'HF', 'VHF', 'PW', 'OW', 'PA', 'OA', 'SI', 'PCW', 'OCW', 'PCA', 'OCA'],
*,
guidance: Literal['nmfs-2024', 'nmfs-2018', 'southall-2019'] = '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. One of "LF", "MF", "HF", "VHF", "PW", "OW", "PA", "OA", "SI", "PCW", "OCW", "PCA" or "OCA".
guidance "nmfs-2024" (default, current), "nmfs-2018" or "southall-2019".

Returns: An AuditoryWeightingResult.

Raises

Exception When
ValueError If an input is invalid.
TypeError if group or guidance is not a text, or frequency_hz holds a text or a value that is not a real number.
AuditoryWeightingResult(
frequencies: NDArray[np.float64],
weighting: NDArray[np.float64],
exposure_function: NDArray[np.float64],
parameters: WeightingParameters,
guidance: Literal['nmfs-2024', 'nmfs-2018', 'southall-2019'],
group: Literal['LF', 'MF', 'HF', 'VHF', 'PW', 'OW', 'PA', 'OA', 'SI', 'PCW', 'OCW', 'PCA', 'OCA'],
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 ().
exposure_function Exposure function , in dB (the frequency-dependent TTS-onset level).
parameters The WeightingParameters used.
guidance The guidance version. One of "nmfs-2024", "nmfs-2018" or "southall-2019".
group Hearing-group code. One of "LF", "MF", "HF", "VHF", "PW", "OW", "PA", "OA", "SI", "PCW", "OCW", "PCA" or "OCA".
weighted_tts_onset , the minimum of the exposure function, in dB.
AuditoryWeightingResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the weighting function versus frequency.

Parameters

Name Description
language The language of the labels: "en" or "es".
exposure_criteria(
group: Literal['LF', 'MF', 'HF', 'VHF', 'PW', 'OW', 'PA', 'OA', 'SI', 'PCW', 'OCW', 'PCA', 'OCA'],
*,
guidance: Literal['nmfs-2024', 'nmfs-2018', 'southall-2019'] = '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. One of "LF", "MF", "HF", "VHF", "PW", "OW", "PA", "OA", "SI", "PCW", "OCW", "PCA" or "OCA".
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.
TypeError if group or guidance is not a text.
ExposureCriteria(
group: Literal['LF', 'MF', 'HF', 'VHF', 'PW', 'OW', 'PA', 'OA', 'SI', 'PCW', 'OCW', 'PCA', 'OCA'],
guidance: Literal['nmfs-2024', 'nmfs-2018', 'southall-2019'],
*,
impulsive: bool,
tts_sel: float | None,
injury_sel: float | None,
tts_peak_spl: float | None,
injury_peak_spl: float | None,
injury_label: Literal['PTS', 'AUD INJ'],
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. One of "LF", "MF", "HF", "VHF", "PW", "OW", "PA", "OA", "SI", "PCW", "OCW", "PCA" or "OCA".
guidance The guidance version. One of "nmfs-2024", "nmfs-2018" or "southall-2019".
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(
guidance: Literal['nmfs-2024', 'nmfs-2018', 'southall-2019'] = 'nmfs-2024',
) -> tuple[Literal['LF', 'MF', 'HF', 'VHF', 'PW', 'OW', 'PA', 'OA', 'SI', 'PCW', 'OCW', 'PCA', 'OCA'], ...]

Hearing-group codes defined by a guidance version.

Parameters

Name Description
guidance One of WEIGHTING_GUIDANCE. One of "nmfs-2024", "nmfs-2018" or "southall-2019".

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

Raises

Exception When
ValueError If the version is unknown.
TypeError if guidance is not a text.
weighted_exposure(
band_sel: NumericArrayLike,
group: Literal['LF', 'MF', 'HF', 'VHF', 'PW', 'OW', 'PA', 'OA', 'SI', 'PCW', 'OCW', 'PCA', 'OCA'],
*,
frequencies_hz: NumericArrayLike,
guidance: Literal['nmfs-2024', 'nmfs-2018', 'southall-2019'] = 'nmfs-2024',
impulsive: bool = True,
n_events: int | np.integer[Any] = 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 (, 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
frequencies_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. One of "LF", "MF", "HF", "VHF", "PW", "OW", "PA", "OA", "SI", "PCW", "OCW", "PCA" or "OCA".
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, .
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.
TypeError if peak_spl is not a single number, n_events is a flag, a text or an array where a count goes, or group or guidance is not a text, or band_sel or frequencies_hz holds a text or a value that is not a real number.
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: Literal['nmfs-2024', 'nmfs-2018', 'southall-2019'],
group: Literal['LF', 'MF', 'HF', 'VHF', 'PW', 'OW', 'PA', 'OA', 'SI', 'PCW', 'OCW', 'PCA', 'OCA'],
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 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. One of "nmfs-2024", "nmfs-2018" or "southall-2019".
group Hearing-group code. One of "LF", "MF", "HF", "VHF", "PW", "OW", "PA", "OA", "SI", "PCW", "OCW", "PCA" or "OCA".
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.

property

The ExposureCriteria compared against.

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

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.

property

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

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

Plot the unweighted and weighted band spectra with the criteria.

Parameters

Name Description
language The language of the labels: "en" or "es".

Constant (tuple).

WEIGHTING_GUIDANCE = ('nmfs-2024', 'nmfs-2018', 'southall-2019')
weighting_parameters(
group: Literal['LF', 'MF', 'HF', 'VHF', 'PW', 'OW', 'PA', 'OA', 'SI', 'PCW', 'OCW', 'PCA', 'OCA'],
*,
guidance: Literal['nmfs-2024', 'nmfs-2018', 'southall-2019'] = 'nmfs-2024',
) -> WeightingParameters

Weighting/exposure parameters of one hearing group.

Parameters

Name Description
group Hearing-group code as used by guidance, as written. One of "LF", "MF", "HF", "VHF", "PW", "OW", "PA", "OA", "SI", "PCW", "OCW", "PCA" or "OCA".
guidance One of WEIGHTING_GUIDANCE. One of "nmfs-2024", "nmfs-2018" or "southall-2019".

Returns: The WeightingParameters row.

Raises

Exception When
TypeError If group or guidance is not a text.
ValueError If the version or the group is unknown.
WeightingParameters(
group: Literal['LF', 'MF', 'HF', 'VHF', 'PW', 'OW', 'PA', 'OA', 'SI', 'PCW', 'OCW', 'PCA', 'OCA'],
guidance: Literal['nmfs-2024', 'nmfs-2018', 'southall-2019'],
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. One of "LF", "MF", "HF", "VHF", "PW", "OW", "PA", "OA", "SI", "PCW", "OCW", "PCA" or "OCA".
guidance The guidance version the row comes from. One of "nmfs-2024", "nmfs-2018" or "southall-2019".
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.