# psychoacoustics.loudness.contours

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

Canonical: https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/contours/
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:27Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Normal equal-loudness-level contours per ISO 226:2023.

---

Normal equal-loudness-level contours per ISO 226:2023.

Implements Formula (1) (clause 4.1: SPL of a pure tone from its loudness
level) and Formula (2) (clause 4.2: the inverse) with the Table 1 (p. 4)
parameters at the 29 preferred third-octave frequencies of ISO 266.

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

## equal_loudness_contour

```python
equal_loudness_contour(phon: float) -> LoudnessContour
```

Normal equal-loudness-level contour (ISO 226:2023 Formula 1).

Returns the sound pressure levels of pure tones judged equally loud as
a 1 kHz tone at `phon` dB SPL, at the 29 preferred third-octave
frequencies of Table 1.

Validity (clause 4.1): 20 phon to 90 phon between 20 Hz and 4 kHz, and
up to 80 phon between 5 kHz and 12.5 kHz; above 80 phon the returned
contour therefore stops at 4 kHz.

**Parameters**

| Name | Description |
| :--- | :--- |
| `phon` | Loudness level in phons (20 to 90). |

**Returns:** The frequencies in Hz and the levels in dB re 20 uPa, as a [`LoudnessContour`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/contours/#loudnesscontour).

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | if `phon` is not a single number. |

## equal_loudness_contours

```python
equal_loudness_contours(
    phons: Sequence[float] = (20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0, 90.0),
    *,
    frequencies: NumericArrayLike | None = None,
) -> EqualLoudnessContours
```

Build the ISO 226:2023 equal-loudness-level contour family.

Evaluates [`equal_loudness_contour`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/contours/#equal_loudness_contour) at each level in `phons` and
[`hearing_threshold`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/contours/#hearing_threshold), and bundles them into an
[`EqualLoudnessContours`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/contours/#equalloudnesscontours) result that exposes `.plot()`. The maths
is unchanged; this is a thin, plottable wrapper around the existing
functions.

**Parameters**

| Name | Description |
| :--- | :--- |
| `phons` | Loudness levels of the contours, in phon; each must be in the 20 phon to 90 phon validity range of Formula (1). Defaults to the classic family from 20 phon to 90 phon in 10 phon steps. |
| `frequencies` | Frequency grid in Hz; `None` (default) uses the 29 preferred third-octave frequencies of Table 1. Any value given must be one of those preferred frequencies (the standard specifies no interpolation between them). |

**Returns:** An [`EqualLoudnessContours`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/contours/#equalloudnesscontours).

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | if `frequencies` holds a text or a value that is not a real number. An element of `phons` is refused the same way when it is not one real number. |

## EqualLoudnessContours

```python
EqualLoudnessContours(
    frequencies: NDArray[np.float64],
    phons: tuple[float, ...],
    contours: NDArray[np.float64],
    threshold: NDArray[np.float64],
)
```

The ISO 226:2023 normal equal-loudness-level contour family.

Bundles a set of equal-loudness contours (ISO 226:2023 Formula 1) with
the threshold of hearing (Table 1) over a shared frequency grid, so the
iconic chart can be drawn with `plot`.

`frequencies` is the frequency grid in Hz (by default the 29 preferred
third-octave frequencies of Table 1). `phons` lists the loudness levels
of the contours, in phon. `contours` holds the sound pressure levels in
dB re 20 uPa as a `(len(phons), len(frequencies))` array, row `i` being
the contour for `phons[i]`; entries the standard does not define are
`nan` (Formula 1 is valid only up to 4 kHz above 80 phon, so those rows
stop at 4 kHz). `threshold` is the threshold of hearing T_f in dB re
20 uPa on the same grid.

### EqualLoudnessContours.plot()

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

Plot the equal-loudness contour family with the hearing threshold.

Draws sound pressure level in dB against a logarithmic frequency axis:
one line per loudness level in `phons`, plus the threshold of
hearing. Requires matplotlib (the `[plot]` extra);
returns the `Axes`.

**Parameters**

| Name | Description |
| :--- | :--- |
| `ax` | Existing axes to draw on, or `None` to create a figure. |
| `language` | Label language, `"en"` (default) or `"es"`. |
| `kwargs` | Forwarded to the contour `plot` calls. |

**Returns:** The axes.

## hearing_threshold

```python
hearing_threshold() -> LoudnessContour
```

Threshold of hearing T_f (ISO 226:2023 Table 1).

**Returns:** The frequencies in Hz and the threshold levels in dB re 20 uPa, as a [`LoudnessContour`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/contours/#loudnesscontour).

## loudness_level

```python
loudness_level(spl: float, frequency: float) -> float
```

Loudness level of a pure tone (ISO 226:2023 Formula 2).

**Parameters**

| Name | Description |
| :--- | :--- |
| `spl` | Sound pressure level of the tone in dB re 20 uPa. |
| `frequency` | Tone frequency in Hz; must be one of the 29 preferred third-octave frequencies of Table 1 (the standard specifies no interpolation between them). |

**Returns:** Loudness level in phons. Values outside 20-90 phon (80 above 4 kHz) are extrapolations the standard labels as informative only.

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | if `frequency` or `spl` is not a single number. |

## LoudnessContour

```python
LoudnessContour(
    frequencies: NDArray[np.float64],
    levels: NDArray[np.float64],
    phon: float | None,
)
```

A curve of pure-tone levels over the ISO 226 frequencies.

What [`equal_loudness_contour`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/contours/#equal_loudness_contour) and [`hearing_threshold`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/contours/#hearing_threshold) return:
the frequencies and the levels, named, where a `(frequencies, spl)`
tuple used to be unpacked by position.

**Attributes**

| Name | Description |
| :--- | :--- |
| `frequencies` | The preferred third-octave frequencies of Table 1, in Hz. |
| `levels` | The sound pressure level of the tone at each, in dB re 20 uPa. |
| `phon` | The loudness level of the contour, in phon, or `None` for the threshold of hearing $T_f$, which is not a contour of Formula (1). |

### LoudnessContour.plot()

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

Plot the levels against frequency on a logarithmic axis.

**Parameters**

| Name | Description |
| :--- | :--- |
| `ax` | Existing axes, or `None` to create a figure. |
| `language` | Label language, `"en"` (default) or `"es"`. |
| `kwargs` | Forwarded to the contour curve. |

**Returns:** The axes.
