Skip to content

underwater.sources.pile_driving_noise

Radiated underwater sound from percussive pile driving (ISO 18406:2017).

Percussive pile driving radiates a train of impulsive acoustic pulses, one per hammer strike. ISO 18406 characterises them with:

  • single_strike_sel: the single-strike sound exposure level SEL_ss of one pulse (Formulae 3-4), reusing the 1 µPa²·s reference.
  • cumulative_sel / cumulative_sel_identical: the cumulative sound exposure level over N strikes (Formulae 8-9); for N identical strikes .
  • pile_strike_metrics: a PileStrikeResult bundling the single-strike SEL, the peak sound pressure level, the SPL/Leq and the 90 %-energy pulse duration for one recorded strike, with a .plot().
  • strike_sel_spectrum: the same single-strike SEL resolved into fractional-octave bands (ISO 18406 6.4.2.2), the input a marine-mammal assessment needs: feed it to weighted_exposure to obtain the weighted cumulative SEL of a piling campaign and its margin against the regulatory injury and TTS criteria.

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

cumulative_sel(single_sels: NumericArrayLike) -> float

Cumulative sound exposure level over N strikes (ISO 18406 Formulae 8-9).

, the energy sum of the per-strike single-strike SELs.

Parameters

Name Description
single_sels Per-strike single-strike SELs, in dB re 1 µPa²·s.

Returns: Cumulative SEL, in dB re 1 µPa²·s.

Raises

Exception When
ValueError If the sequence is empty or non-finite.
TypeError if single_sels holds a text or a value that is not a real number.
cumulative_sel_identical(
sel_ss: float,
n_strikes: int | np.integer[Any],
) -> float

Cumulative SEL of n_strikes identical strikes: .

Parameters

Name Description
sel_ss Single-strike SEL, in dB re 1 µPa²·s.
n_strikes Number of (identical) strikes, .

Returns: Cumulative SEL, in dB re 1 µPa²·s.

Raises

Exception When
ValueError If n_strikes is not a whole number .
TypeError if sel_ss is not a single number, or n_strikes is a flag, a text or an array where a count goes.
pile_strike_metrics(
pressure_pa: Signal | NumericArrayLike,
fs: float | None = None,
) -> PileStrikeResult

Full per-strike pile-driving metrics (ISO 18406).

Bundles the single-strike SEL, the peak sound pressure level, the SPL/Leq and the 90 %-energy pulse duration of one recorded hammer strike.

Parameters

Name Description
pressure_pa Sound-pressure time series of one strike (1-D), in Pa. Accepts a phonometry.io.Signal, whose calibration is applied to the samples: this quantity is a pressure, and the underwater reference of 1 uPa changes what the decibel is counted from, not what the samples have to be in.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.

Returns: A PileStrikeResult.

Raises

Exception When
ValueError If the inputs are invalid.
PileStrikeResult(
single_strike_sel: float,
peak_spl: float,
spl: float,
pulse_duration_s: float,
pressure_pa: Signal | NDArray[np.float64],
fs: float,
)

Per-strike pile-driving metrics (ISO 18406).

Attributes

Name Description
single_strike_sel Single-strike SEL, in dB re 1 µPa²·s.
peak_spl Zero-to-peak sound pressure level, in dB re 1 µPa.
spl Sound pressure level (Leq over the record), in dB re 1 µPa.
pulse_duration_s 90 %-energy pulse duration, in s.
pressure_pa The strike pressure waveform, in Pa, in the type it arrived as: a Signal when the input was one (carrying calibration_factor=1.0 when it was calibrated), a bare array otherwise.
fs Sample rate, in Hz.
PileStrikeResult.plot(
ax: None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> tuple[Axes, Axes]
PileStrikeResult.plot(
ax: Axes,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the strike waveform and its cumulative energy.

Parameters

Name Description
language The language of the labels: "en" or "es".
single_strike_sel(
pressure_pa: Signal | NumericArrayLike,
fs: float | None = None,
) -> float

Single-strike sound exposure level SEL_ss (ISO 18406 Formulae 3-4).

The sound exposure level of one hammer-strike pulse, integrated over the pulse, in dB re 1 µPa²·s.

Parameters

Name Description
pressure_pa Sound-pressure time series of one strike (1-D), in Pa. Accepts a phonometry.io.Signal, whose calibration is applied to the samples: this quantity is a pressure, and the underwater reference of 1 uPa changes what the decibel is counted from, not what the samples have to be in.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.

Returns: Single-strike SEL, in dB re 1 µPa²·s.

Raises

Exception When
ValueError If the inputs are invalid.
strike_sel_spectrum(
pressure_pa: Signal | NumericArrayLike,
fs: float | None = None,
*,
fraction: int | np.integer[Any] = 3,
limits: tuple[float, float] = (10.0, 20000.0),
) -> StrikeSELSpectrum

Band-resolved single-strike sound exposure level.

The sound exposure is split between fractional-octave bands by integrating the discrete power spectrum over each band (Parseval), so the energy sum of the returned band levels reproduces the broadband single_strike_sel of the same record to within the energy that falls outside limits.

Bands narrower than the FFT bin spacing fs/n contain no bin and are reported as -inf dB (see StrikeSELSpectrum); the result can be handed straight to weighted_exposure.

Parameters

Name Description
pressure_pa Sound-pressure time series of one strike (1-D), in Pa. Accepts a phonometry.io.Signal, whose calibration is applied to the samples: this quantity is a pressure, and the underwater reference of 1 uPa changes what the decibel is counted from, not what the samples have to be in.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
fraction Bandwidth fraction: 1 (octave) or 3 (one-third octave).
limits Lower and upper band-centre limits, in Hz.

Returns: A StrikeSELSpectrum.

Raises

Exception When
TypeError If limits is not a sequence, or holds a text or anything else that is not a number, or fraction is a bool, a text or an array rather than a whole number.
ValueError If the inputs are invalid: a fraction other than 1 or 3, limits that are not a finite, increasing, positive pair, or a pressure or sampling rate the analysis cannot take.
StrikeSELSpectrum(
frequencies: NDArray[np.float64],
band_sel: NDArray[np.float64],
total_sel: float,
broadband_sel: float,
fraction: int,
fs: float,
)

Single-strike sound exposure level resolved into fractional-octave bands.

Attributes

Name Description
frequencies Nominal band centre frequencies, in Hz.
band_sel Per-band single-strike SEL, in dB re 1 µPa²·s. A band that contains no discrete-spectrum bin (which happens whenever the band is narrower than the FFT bin spacing fs/n, i.e. in the lowest bands of a short record) holds no energy at all and is reported as -inf, the level of zero exposure. That is the neutral element of an energy sum, so such bands pass straight through weighted_exposure without contributing.
total_sel Energy sum of band_sel over the covered bands, in dB re 1 µPa²·s.
broadband_sel The broadband single-strike SEL of the whole record, in dB re 1 µPa²·s (equal to total_sel when the bands span the signal’s whole occupied spectrum).
fraction Bandwidth fraction (1 for octaves, 3 for one-third octaves).
fs Sample rate, in Hz.
StrikeSELSpectrum.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the per-band single-strike SEL.

Parameters

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