Skip to content

hearing.noise_induced_hearing_loss

Estimation of noise-induced hearing loss (ISO 1999:2013).

Implements the noise-induced permanent threshold shift (NIPTS) of a noise-exposed population and its combination with the age-related threshold into the hearing threshold level associated with age and noise (HTLAN), over the six audiometric frequencies 500 Hz to 6000 Hz.

The median NIPTS for exposure durations of 10 to 40 years is (clause 6.3.1, Formula 2, with the values u, v, L0 of Table 1), extrapolated below 10 years by Formula 3. The statistical distribution about the median is two half-Gaussians whose spreads du (worse than the median) and dl (better) follow Formulae 6/7 with the coefficients of Table 3; a population fractile is with z the standard-normal quantile (clause 6.3.2, Formulae 4/5, Table 2), clamped at zero. The HTLAN combines the age component H (HTLA, database A = ISO 7029) with the noise component N by (clause 6.1, Formula 1).

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

age_and_noise_threshold(
htla: float | np.floating[Any] | np.integer[Any],
nipts_value: float | np.floating[Any] | np.integer[Any],
) -> float
age_and_noise_threshold(
htla: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
nipts_value: NumericArrayLike,
) -> NDArray[np.float64]
age_and_noise_threshold(
htla: float | np.floating[Any] | np.integer[Any],
nipts_value: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
age_and_noise_threshold(
htla: NumericArrayLike,
nipts_value: NumericArrayLike,
) -> float | NDArray[np.float64]

Combine the age and noise components by Formula (1) (clause 6.1).

, the hearing threshold level associated with age and noise. The formula “is applicable only to corresponding percentage values of H’, H and N”, so both components must be taken at the same population percentage.

Exposed separately from htlan because clause 6.2 lets the user supply their own HTLA database: 6.2.3 recommends a database B collected on a control population of the country under consideration, and 6.2.4 makes the choice between databases A and B depend on the question being answered. Feeding such a database here combines it with the library’s NIPTS.

Parameters

Name Description
htla Age-associated hearing threshold level H, in dB.
nipts_value Noise-induced permanent threshold shift N, in dB.

Returns: The combined threshold H', in dB. A float when htla and nipts_value are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError if htla or nipts_value holds a text or a value that is not a real number.
htlan(
age: float,
sex: Literal['male', 'female'],
l_ex: float,
exposure_duration_years: float,
fractile: float = 0.5,
frequencies: NumericArrayLike | None = None,
) -> HTLANResult

Hearing threshold level associated with age and noise (clause 6.1).

Combines the age component H (HTLA from database A, evaluated from ISO 7029:2017, the edition ISO 1999:2013 references undated in 6.2.2, at the same population fractile) with the noise component N (the NIPTS at that fractile) by Formula (1): . The formula applies to corresponding percentage values, so the same fractile drives both components.

Parameters

Name Description
age Listener age, in years (at least 18, the ISO 7029 lower limit).
sex "male" or "female".
l_ex Noise exposure level normalized to 8 h, L_EX,8h, in dB.
exposure_duration_years Exposure duration, in years.
fractile Population fractile in (0, 1) applied to both components.
frequencies Optional subset of the audiometric frequencies, in hertz; None uses all six (500 Hz to 6000 Hz).

Returns: An HTLANResult with htla, nipts, threshold and .plot().

Raises

Exception When
ValueError for an age below 18, an unknown sex, a non-positive duration, a fractile outside (0, 1), or an unknown frequency.
TypeError if age or fractile is not a single number, or sex is not a text, or frequencies holds a text or a value that is not a real number.

The noise component inherits the validated-domain checks of nipts, so exposure conditions outside the standard’s stated ranges raise a NoiseInducedHearingLossWarning and the .report() fiche prints the extrapolation caveat.

HTLANResult(
age: float,
sex: Literal['male', 'female'],
l_ex: float,
exposure_duration_years: float,
fractile: float,
frequencies: NDArray[np.float64],
htla: NDArray[np.float64],
nipts: NDArray[np.float64],
threshold: NDArray[np.float64],
)

Hearing threshold level associated with age and noise (clause 6.1).

All arrays are in dB and aligned with frequencies.

Attributes

Name Description
age Listener age, in years.
sex "male" or "female".
l_ex Noise exposure level normalized to 8 h, in dB.
exposure_duration_years Exposure duration, in years.
fractile Population fractile (0-1) applied to both components.
frequencies Audiometric frequencies, in hertz.
htla Age component H (HTLA, database A, evaluated from ISO 7029:2017, the edition ISO 1999:2013 references undated in 6.2.2).
nipts Noise component N (NIPTS at fractile).
threshold Combined HTLAN .
HTLANResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the age, noise and combined threshold components over frequency.

Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
HTLANResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render an HTLAN hearing-threshold prediction fiche to a PDF.

Writes a one-page statistical-prediction report of the hearing threshold level associated with age and noise (ISO 1999:2013 clause 6.1): a prediction-basis line, an optional metadata header, a per-audiometric-frequency table of the age component H, the noise component N and the combined threshold beside the result’s own plot, the boxed representative threshold averaged over the 2/3/4 kHz hearing-handicap set with the listener/exposure conditions, and a statistical-prediction note. The fiche is a population estimate, not a clinical diagnosis of any individual.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata supplying the header identity (client is the company, specimen the worker(s)/group, test_room the workplace) and, via requirement, a maximum acceptable representative HTLAN in dB that adds a PASS/FAIL verdict (a lower threshold is better).
engine Rendering back end; only "reportlab" is supported.
verbose When True, the table adds the compression term H*N/120.
language "en" (default) or "es".

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is not "reportlab" or language is unknown.
ImportError If reportlab, matplotlib or svglib is not installed (the [report] and [plot] extras).
nipts(
l_ex: float,
exposure_duration_years: float,
fractile: float = 0.5,
frequencies: NumericArrayLike | None = None,
) -> NIPTSResult

Noise-induced permanent threshold shift (ISO 1999:2013, clause 6.3).

Returns, per audiometric frequency, the median NIPTS N50 (Formula 2, extrapolated below 10 years by Formula 3), the upper/lower spreads du/dl (Formulae 6/7) and the NIPTS at the requested population fractile (Formulae 4/5): N50 + z * spread where z is the standard-normal quantile of fractile and the spread is the upper one for z >= 0 (worse than the median) or the lower one otherwise, clamped at zero.

Parameters

Name Description
l_ex Noise exposure level normalized to a nominal 8 h working day, L_EX,8h, in dB.
exposure_duration_years Exposure duration, in years (> 0; the standard establishes 10-40 years and extrapolates 1-10 years by Formula 3, below 1 year the result is a further extrapolation).
fractile Population fractile in the open interval (0, 1); 0.5 gives the median. The reliable range of the standard is 0.05-0.95.
frequencies Optional subset of the audiometric frequencies, in hertz; None uses all six (500 Hz to 6000 Hz).

Returns: A NIPTSResult with the distribution and .plot().

Raises

Exception When
ValueError for a level or a duration that is not finite, a non-positive duration, a fractile outside (0, 1), or an unknown frequency.
TypeError if exposure_duration_years, fractile or l_ex is not a single number, or frequencies holds a text or a value that is not a real number.

Outside the standard’s validated domain (durations of 1 to 40 years, fractiles of 0.05 to 0.95, exposure levels up to 100 dB) the computation still runs but a NoiseInducedHearingLossWarning marks the result as an extrapolation, and the .report() fiche prints the matching caveat.

NIPTSResult(
l_ex: float,
exposure_duration_years: float,
fractile: float,
frequencies: NDArray[np.float64],
median: NDArray[np.float64],
value: NDArray[np.float64],
spread_upper: NDArray[np.float64],
spread_lower: NDArray[np.float64],
)

Noise-induced permanent threshold shift (ISO 1999:2013, clause 6.3).

All arrays are in dB and aligned with frequencies.

Attributes

Name Description
l_ex Noise exposure level normalized to 8 h, L_EX,8h, in dB.
exposure_duration_years Exposure duration, in years.
fractile Population fractile of value (0-1); the fraction of the population with a smaller shift, so 0.9 is the most-susceptible 10 %.
frequencies Audiometric frequencies, in hertz.
median Median NIPTS N50 (Formula 2/3).
value NIPTS at fractile (Formula 4/5), clamped at zero.
spread_upper Upper half-Gaussian spread du (Formula 6).
spread_lower Lower half-Gaussian spread dl (Formula 7).
NIPTSResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the NIPTS spectrum with the fractile band over frequency.

Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
NIPTSResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render a NIPTS hearing-loss prediction fiche to a PDF.

Writes a one-page statistical-prediction report of the noise-induced permanent threshold shift (ISO 1999:2013 clause 6.3): a prediction-basis line, an optional metadata header (company, worker(s)/group, workplace, date), a per-audiometric-frequency table of the median N50 and the NIPTS at the chosen population fractile beside the result’s own spectrum plot, the boxed representative shift averaged over the 2/3/4 kHz hearing-handicap set with the exposure conditions (L_EX,8h, exposure years, fractile), and a statistical-prediction note. The fiche is a population estimate, not a clinical diagnosis of any individual.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata supplying the header identity (client is the company, specimen the worker(s)/group, test_room the workplace) and, via requirement, a maximum acceptable representative NIPTS in dB that adds a PASS/FAIL verdict (a lower shift is better).
engine Rendering back end; only "reportlab" is supported.
verbose When True, the table adds the upper/lower spread columns (du/dl).
language "en" (default) or "es".

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is not "reportlab" or language is unknown.
ImportError If reportlab, matplotlib or svglib is not installed (the [report] and [plot] extras).

Warns when an ISO 1999 prediction leaves the standard’s validated domain.