<!-- canonical: https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/annoyance/ -->
Source: https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/annoyance/

Psychoacoustic annoyance (PA) after Fastl & Zwicker.

Psychoacoustic annoyance combines four hearing sensations -- loudness,
sharpness, fluctuation strength and roughness -- into a single figure that
tracks annoyance ratings from listening experiments. The model is due to
Widmann (1992) and is given in Fastl & Zwicker, *Psychoacoustics: Facts and
Models* (Equations 16.2-16.4):

$$
PA = N_5 \left( 1 + \sqrt{w_S^2 + w_{FR}^2} \right) \tag{Eq. 16.2}
$$

with the percentile loudness `N5` in sone and the two loudness-weighted
terms

$$
w_S = (S - 1.75) \cdot 0.25 \cdot \log_{10}(N_5 + 10) \quad \text{for } S > 1.75~\text{acum, else } 0 \tag{Eq. 16.3}
$$

$$
w_{FR} = \frac{2.18}{N_5^{0.4}} \left( 0.4 F + 0.6 R \right) \tag{Eq. 16.4}
$$

describing sharpness `S` (acum) and the joint influence of fluctuation
strength `F` (vacil) and roughness `R` (asper). Note the "1 +" sits
*outside* the radical (Fastl & Zwicker 2006, Eq. (16.2), p. 328). There is
no ISO standard for PA; the formula is exact, verified against a
hand-computed worked tuple, and matches the combination implemented by the
open SQAT reference implementation.

[`psychoacoustic_annoyance`](/phonometry/reference/api/psychoacoustics/annoyance/#psychoacoustic_annoyance) evaluates the model from the four quantities
directly. [`psychoacoustic_annoyance_from_signal`](/phonometry/reference/api/psychoacoustics/annoyance/#psychoacoustic_annoyance_from_signal) is a convenience that
derives them from a calibrated pressure signal using the library's existing
models -- N5/S from ISO 532-1 Zwicker loudness and DIN 45692 sharpness, R from
ECMA-418-2 roughness and F from [`fluctuation_strength`](/phonometry/reference/api/psychoacoustics/fluctuation-strength/#fluctuation_strength). That composite mixes model families (Zwicker N5/S,
Sottek R, Osses F); the original PA model was calibrated with Zwicker-family
sensations, so the signal convenience is an engineering estimate, while
[`psychoacoustic_annoyance`](/phonometry/reference/api/psychoacoustics/annoyance/#psychoacoustic_annoyance) is the exact model.

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

## psychoacoustic_annoyance

```python
psychoacoustic_annoyance(
    n5: float,
    sharpness: float,
    fluctuation_strength: float,
    roughness: float,
) -> PsychoacousticAnnoyanceResult
```

Psychoacoustic annoyance from the four hearing sensations (16.2-16.4).

$PA = N_5 (1 + \sqrt{w_S^2 + w_{FR}^2})$ with the loudness-weighted
sharpness term `wS` (Equation 16.3) and the fluctuation/roughness term
`wFR` (Equation 16.4). The sharpness term is zero for
$S \le 1.75$ acum.

**Parameters**

| Name | Description |
| :--- | :--- |
| `n5` | Percentile loudness `N5`, in sone (the loudness exceeded 5 % of the time; [`n5`](/phonometry/reference/api/psychoacoustics/zwicker/#zwickerloudness)). |
| `sharpness` | Sharpness `S`, in acum (DIN 45692). |
| `fluctuation_strength` | Fluctuation strength `F`, in vacil. |
| `roughness` | Roughness `R`, in asper (ECMA-418-2). |

**Returns:** A [`PsychoacousticAnnoyanceResult`](/phonometry/reference/api/psychoacoustics/annoyance/#psychoacousticannoyanceresult).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If any quantity is negative or non-finite. |

## psychoacoustic_annoyance_from_signal

```python
psychoacoustic_annoyance_from_signal(
    x: SignalInput,
    fs: int | None = None,
    *,
    field: Literal['free', 'diffuse'] = 'free',
    calibration_factor: float | None = None,
) -> PsychoacousticAnnoyanceResult
```

Psychoacoustic annoyance from a calibrated pressure signal (convenience).

Derives the four sensations from the library's models and combines them
with [`psychoacoustic_annoyance`](/phonometry/reference/api/psychoacoustics/annoyance/#psychoacoustic_annoyance): `N5` from the ISO 532-1 Zwicker
time-varying loudness, `S` from DIN 45692 sharpness, `R` from
ECMA-418-2 roughness and `F` from
[`fluctuation_strength`](/phonometry/reference/api/psychoacoustics/fluctuation-strength/#fluctuation_strength).

:::note
This composite mixes model families (Zwicker `N5`/`S`, Sottek
`R`, Osses `F`); the PA model was calibrated with Zwicker-family
sensations, so treat the signal convenience as an engineering estimate.
For exact, reproducible results pass the four quantities to
[`psychoacoustic_annoyance`](/phonometry/reference/api/psychoacoustics/annoyance/#psychoacoustic_annoyance) directly.

`field` selects the sound field for the loudness, sharpness and
roughness front-ends; the fluctuation strength `F` is always computed
in the free field, because the Osses 2016 model has no diffuse-field
variant (see [`fluctuation_strength`](/phonometry/reference/api/psychoacoustics/fluctuation-strength/#fluctuation_strength)).
:::

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Calibrated sound-pressure signal (1-D), in Pa after `calibration_factor`. Accepts a [`phonometry.io.Signal`](/phonometry/reference/api/io/io/#signal), which is where that calibration comes from without arithmetic: all four sensations are level-dependent models, so an uncalibrated record is read as if one digital unit were one pascal and every one of them comes out wrong by however far that is from true. |
| `fs` | Sample rate, in Hz. Required for a bare array; a [`Signal`](/phonometry/reference/api/io/io/#signal) brings its own, and an explicit value that disagrees with it raises. |
| `field` | `'free'` (default) or `'diffuse'` sound field for the loudness/sharpness/roughness front-ends (`F` is always free-field). |
| `calibration_factor` | Digital-units-to-Pa factor applied to `x`. An explicit value wins over the one a Signal carries. |

**Returns:** A [`PsychoacousticAnnoyanceResult`](/phonometry/reference/api/psychoacoustics/annoyance/#psychoacousticannoyanceresult).

## PsychoacousticAnnoyanceResult

```python
PsychoacousticAnnoyanceResult(
    annoyance: float,
    n5: float,
    sharpness: float,
    fluctuation_strength: float,
    roughness: float,
    w_s: float,
    w_fr: float,
)
```

Psychoacoustic annoyance and its contributing terms (Fastl & Zwicker).

**Attributes**

| Name | Description |
| :--- | :--- |
| `annoyance` | Psychoacoustic annoyance `PA` (Equation 16.2), dimensionless. |
| `n5` | Percentile loudness `N5` used, in sone. |
| `sharpness` | Sharpness `S` used, in acum. |
| `fluctuation_strength` | Fluctuation strength `F` used, in vacil. |
| `roughness` | Roughness `R` used, in asper. |
| `w_s` | Sharpness term `wS` (Equation 16.3). |
| `w_fr` | Fluctuation/roughness term `wFR` (Equation 16.4). |

### PsychoacousticAnnoyanceResult.plot()

```python
PsychoacousticAnnoyanceResult.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes
```

Plot the PA value and the `wS` / `wFR` term contributions.