# underwater.sources.ship_traffic_noise

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/reference/api/underwater/ship-traffic-noise/
Language: en
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-07-15
Updated: 2026-11-11T17:49:24Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Predicted source-level spectrum of shipping traffic (semi-empirical models).

---

Predicted source-level spectrum of shipping traffic (semi-empirical models).

When no measured spectrum is available, the underwater radiated-noise source
level of a ship can be *estimated* from readily available traffic parameters
(vessel class, speed, length) with published semi-empirical models. This module
implements three, selectable through `model`:

* `"jomopans-echo"`: the JOMOPANS-ECHO reference spectrum (MacGillivray &
  de Jong 2021), per **vessel class** with class reference speeds; validated
  against 1862 source-level measurements (ECHO programme), σ ≈ 6 dB. Default.
* `"randi"`: the RANDI 3.1 semi-empirical model, an "average ship" baseline
  spectrum scaled by speed and length.
* `"wales-heitmeyer"`: the Wales & Heitmeyer (2002) ensemble merchant-ship
  spectrum (no speed/length dependence), valid 30 Hz-1200 Hz.

All three return an equivalent-monopole source spectral-density level (dB re
1 µPa²/Hz at 1 m, source depth 6 m) and the decidecade-band source level
(dB re 1 µPa m). The predicted spectrum can be used as the `shipping` input of
[`phonometry.underwater.sources.ambient_noise.ocean_ambient_noise`](https://docs.jmrp.io/phonometry/reference/api/underwater/ambient-noise/#ocean_ambient_noise) or placed at range
with [`phonometry.underwater.propagation.propagation_loss`](https://docs.jmrp.io/phonometry/reference/api/underwater/closed-form/#propagation_loss).

Source (clean-room, implemented from the equations, validated against the
authors' own Excel reference implementation, File S1): MacGillivray, A.;
de Jong, C. (2021), "A Reference Spectrum Model for Estimating Source Levels of
Marine Shipping Based on Automated Identification System Data", J. Mar. Sci.
Eng. 9(4), 369, https://doi.org/10.3390/jmse9040369 (CC-BY), which also
reproduces RANDI 3.1 [Breeding et al.] and Wales & Heitmeyer (2002).

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

## ship_source_spectrum

```python
ship_source_spectrum(
    speed_kt: float = 12.0,
    *,
    length_m: float = 100.0,
    vessel_class: Literal['bulker', 'containership', 'cruise', 'dredger', 'fishing', 'government/research', 'naval', 'other', 'passenger', 'recreational', 'tanker', 'tug', 'vehicle carrier'] = 'containership',
    model: Literal['jomopans-echo', 'randi', 'wales-heitmeyer'] = 'jomopans-echo',
    frequencies: NumericArrayLike | None = None,
) -> ShipTrafficSpectrum
```

Predicted underwater source-level spectrum of a ship.

**Parameters**

| Name | Description |
| :--- | :--- |
| `speed_kt` | Vessel speed, in knots (used by `"jomopans-echo"` and `"randi"`; ignored by `"wales-heitmeyer"`). |
| `length_m` | Vessel length, in metres (used by `"jomopans-echo"` and `"randi"`; ignored by `"wales-heitmeyer"`). |
| `vessel_class` | JOMOPANS-ECHO vessel class (see [`VESSEL_CLASSES`](https://docs.jmrp.io/phonometry/reference/api/underwater/ship-traffic-noise/#vessel_classes)); used only by `"jomopans-echo"`. One of `"bulker"`, `"containership"`, `"cruise"`, `"dredger"`, `"fishing"`, `"government/research"`, `"naval"`, `"other"`, `"passenger"`, `"recreational"`, `"tanker"`, `"tug"` or `"vehicle carrier"`. |
| `model` | `"jomopans-echo"` (default), `"randi"` or `"wales-heitmeyer"`. |
| `frequencies` | Frequencies, in Hz; defaults to the decidecade bands 10 Hz-31.5 kHz of the JOMOPANS-ECHO validation range. |

**Returns:** A [`ShipTrafficSpectrum`](https://docs.jmrp.io/phonometry/reference/api/underwater/ship-traffic-noise/#shiptrafficspectrum).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `model`/`vessel_class` is unknown or an input is invalid. |
| TypeError | if `length_m` or `speed_kt` is not a single number, or `frequencies` holds a text or a value that is not a real number, or `model` or `vessel_class` is not a text. |

## ShipTrafficSpectrum

```python
ShipTrafficSpectrum(
    frequencies: NDArray[np.float64],
    source_psd: NDArray[np.float64],
    band_level: NDArray[np.float64],
    model: Literal['jomopans-echo', 'randi', 'wales-heitmeyer'],
    vessel_class: Literal['bulker', 'containership', 'cruise', 'dredger', 'fishing', 'government/research', 'naval', 'other', 'passenger', 'recreational', 'tanker', 'tug', 'vehicle carrier'] | None,
    speed_kt: float | None,
    length_m: float | None,
)
```

Predicted ship source-level spectrum.

**Attributes**

| Name | Description |
| :--- | :--- |
| `frequencies` | Frequencies, in Hz. |
| `source_psd` | Source pressure spectral-density level, in dB re 1 µPa²/Hz at 1 m (equivalent monopole). |
| `band_level` | Decidecade-band source level, in dB re 1 µPa m (`source_psd` plus $10 \log_{10}(0.231 f)$). |
| `model` | The model used. One of `"jomopans-echo"`, `"randi"` or `"wales-heitmeyer"`. |
| `vessel_class` | The vessel class (JOMOPANS-ECHO only; else `None`). One of `"bulker"`, `"containership"`, `"cruise"`, `"dredger"`, `"fishing"`, `"government/research"`, `"naval"`, `"other"`, `"passenger"`, `"recreational"`, `"tanker"`, `"tug"` or `"vehicle carrier"`. |
| `speed_kt` | Speed used, in knots (`None` if the model ignores it). |
| `length_m` | Length used, in metres (`None` if the model ignores it). |

### ShipTrafficSpectrum.plot()

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

Plot the predicted source spectral-density level versus frequency.

**Parameters**

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

## VESSEL_CLASSES

*Constant* (`tuple`).

```python
VESSEL_CLASSES = ('bulker', 'containership', 'cruise', 'dredger', 'fishing', 'government/research', 'naval', 'other', 'passenger', 'recreational', 'tanker', 'tug', 'vehicle carrier')
```
