Ir al contenido

speech.sii

La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.

Speech Intelligibility Index (SII) per ANSI S3.5-1997 (R2017).

Implements all four band procedures of ANSI S3.5-1997, American National Standard Methods for the Calculation of the Speech Intelligibility Index:

  • method="critical-band": 21 critical bands, 100 Hz to 9500 Hz (Table 1).
  • method="equally-contributing": 17 equally-contributing critical bands, 300 Hz to 6400 Hz (Table 2).
  • method="one-third-octave": 18 one-third-octave bands, 160 Hz to 8000 Hz (Table 3). The library default.
  • method="octave": 6 octave bands, 177 Hz to 11314 Hz (Table 4).

From an equivalent speech spectrum level, an equivalent noise spectrum level and an equivalent hearing threshold, every procedure runs the same chain: the self-speech masking, the upward spread of masking, the equivalent internal noise and disturbance, the level-distortion factor and the band-audibility function, whose importance-weighted sum is the index SII in [0, 1] (clause 6). Only the band table and the geometry of the spread of masking change from procedure to procedure: the critical-band and equally-contributing procedures spread the masking between tabulated band limits, the one-third-octave procedure between band centre frequencies, and the octave-band procedure omits the spread entirely (its bands are already wider than the spread being modelled).

The band-importance functions, the standard speech spectrum levels by vocal effort and the reference internal noise spectrum levels are the standard’s own tabulated constants (Tables 1 to 4). Spectrum levels are as defined in clauses 3.11 and 3.55.

The implementation reproduces the reference implementation SII.C of ASA Working Group S3-79 (the committee that maintains ANSI S3.5) to double precision on all eight of its official test cases (CB.TST, CB_1.TST, ECB.TST, ECB_1.TST, TO.TST, TO_1.TST, OCTAVE.TST and OCTAVE_1.TST, two per procedure, the _1 variants exercising an alternative band-importance function; CB_1.TST and ECB_1.TST are the same confirmation twice, so the eight are seven independent ones), and computes the Annex C worked examples with the working group’s official errata applied (see docs/ERRATA.md).

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

Constant (tuple).

SII_METHODS = ('critical-band', 'equally-contributing', 'one-third-octave', 'octave')
sii_procedure(
method: Literal['critical-band', 'equally-contributing', 'one-third-octave', 'octave'] = 'one-third-octave',
) -> SIIProcedure

Build the plottable band table of an ANSI S3.5-1997 band procedure.

Parameters

Name Description
method The band procedure, one of SII_METHODS. One of "critical-band", "equally-contributing", "one-third-octave" or "octave".

Returns: A frozen SIIProcedure carrying the band centre frequencies, band limits, band-importance function, reference internal noise spectrum level and normal-effort standard speech spectrum level of that procedure.

Raises

Exception When
ValueError for an unknown procedure name.
TypeError if method is not a text.
SIIProcedure(
method: Literal['critical-band', 'equally-contributing', 'one-third-octave', 'octave'],
frequencies: NDArray[np.float64],
band_edges: NDArray[np.float64],
band_importance: NDArray[np.float64],
internal_noise: NDArray[np.float64],
speech_spectrum: NDArray[np.float64],
)

The tabulated band table of one ANSI S3.5-1997 band procedure.

Bundles the normative constants of one of the standard’s four band procedures (Tables 1 to 4) so they can be inspected and drawn with plot. Build it with sii_procedure; the frozen instance is a plottable view of the tabulated constants and runs none of the SII maths.

Attributes

Name Description
method The procedure name, one of SII_METHODS. One of "critical-band", "equally-contributing", "one-third-octave" or "octave".
frequencies Nominal band centre frequencies, in hertz.
band_edges Band limits, in hertz; one value more than the number of bands, so band i runs from band_edges[i] to band_edges[i+1].
band_importance Band-importance function Ii for average speech material. It sums to one, except for the equally-contributing procedure, whose printed 0.0588 per band sums to 0.9996.
internal_noise Reference internal noise spectrum level Xi, in dB SPL.
speech_spectrum Standard speech spectrum level Ui for normal vocal effort, in dB SPL.
SIIProcedure.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the band-importance function of the procedure versus frequency.

Draws the band-importance function Ii as a step over the band limits, so procedures with different band counts and widths can be overlaid on the same logarithmic frequency axis and compared directly.

Requires matplotlib (the [plot] extra); returns the Axes and never calls plt.show.

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the step plot call.

Returns: The axes.

SIIResult(
sii: float,
band_audibility: NDArray[np.float64],
band_importance: NDArray[np.float64],
frequencies: NDArray[np.float64],
speech_spectrum: NDArray[np.float64],
disturbance: NDArray[np.float64],
masking: NDArray[np.float64],
level_distortion: NDArray[np.float64],
method: Literal['critical-band', 'equally-contributing', 'one-third-octave', 'octave'] = 'one-third-octave',
)

Result of a Speech Intelligibility Index computation (ANSI S3.5-1997).

Attributes

Name Description
sii The overall Speech Intelligibility Index in [0, 1] (clause 6).
band_audibility Per-band audibility function Ai (clause 5.8).
band_importance Per-band importance function Ii used (the procedure’s own table, or the alternative function supplied).
frequencies Band centre frequencies of the procedure, in hertz.
speech_spectrum Equivalent speech spectrum level Ei' per band.
disturbance Equivalent disturbance spectrum level Di (clause 5.6).
masking Equivalent masking spectrum level Zi (clause 5.4).
level_distortion Per-band level-distortion factor Li in [0, 1] (clause 5.7), unity until the speech spectrum level rises above the standard normal-effort spectrum by more than 10 dB.
method The band procedure used, one of SII_METHODS. One of "critical-band", "equally-contributing", "one-third-octave" or "octave".

Raises

Exception When
ValueError If the per-band quantities disagree, method is not one of SII_METHODS, or any quantity is not finite.
SIIResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the per-band audibility weighted by importance, with the SII.

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

Parameters

Name Description
language The language of the labels: "en" or "es".
SIIResult.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 ANSI S3.5-1997 speech-intelligibility-index fiche to a PDF.

Writes a one-page speech-audibility report: a standard-basis line naming the band procedure, an optional metadata header block, a per-band table over that procedure’s bands (the equivalent speech spectrum Ei', the band-importance function Ii and the band-audibility function Ai) beside the audibility and importance-weighted contribution bars (the result’s own plot), the boxed SII = X single number, an optional verdict row and a footer with the fixed disclaimer.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata; None produces a bare fiche (body, result and disclaimer only). A supplied requirement is read as the minimum required SII (a higher SII passes).
engine Rendering back end; only "reportlab" is supported.
verbose When True, the left table adds the equivalent disturbance spectrum level Di column (clause 5.6).
language Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is not "reportlab" or language is not a supported language.
ImportError If reportlab is not installed (the [report] extra), or matplotlib is missing for the embedded figure (the [plot] extra).
speech_intelligibility_index(
speech_spectrum: Literal['normal', 'raised', 'loud', 'shout'] | NumericArrayLike,
noise_spectrum: NumericArrayLike | None = None,
*,
threshold: NumericArrayLike | None = None,
method: Literal['critical-band', 'equally-contributing', 'one-third-octave', 'octave'] = 'one-third-octave',
band_importance: NumericArrayLike | None = None,
) -> SIIResult

Speech Intelligibility Index (ANSI S3.5-1997, any of the four methods).

All spectra are equivalent spectrum levels (clauses 3.11/3.55) sampled at the band centres of the chosen procedure: 18 one-third-octave bands from 160 Hz to 8000 Hz by default, or the 21 critical bands, the 17 equally-contributing critical bands or the 6 octave bands.

Parameters

Name Description
speech_spectrum Equivalent speech spectrum level Ei', in dB SPL. A vocal-effort name ("normal", "raised", "loud" or "shout") selects the corresponding standard speech spectrum; only "normal" is tabulated outside the one-third-octave procedure. A name is a str: a text in any other form (a bytes, a text among the levels) is refused, and not read as the levels it spells.
noise_spectrum Equivalent noise spectrum level Ni', in dB SPL; None uses a quiet field (-80 dB in every band).
threshold Equivalent hearing threshold Ti', in dB HL; None uses normal hearing (0 in every band).
method The band procedure, one of SII_METHODS: "critical-band" (21 bands, Table 1), "equally-contributing" (17 bands, Table 2), "one-third-octave" (18 bands, Table 3, the default) or "octave" (6 bands, Table 4).
band_importance Alternative band-importance function Ii, one value per band, replacing the procedure’s tabulated function (the standard’s Annex B tabulates functions for specific speech test materials); None uses the tabulated average-speech function.

Returns: An SIIResult with the overall index and its .plot().

Raises

Exception When
ValueError if a spectrum has the wrong length or carries a non-finite value, or the method or effort name is unknown.
TypeError if method is not a text, speech_spectrum is neither a vocal-effort name nor numbers (a bytes, None, a text among the levels), or a spectrum, the threshold or the band importance holds a text, a complex value or anything that is not a number, or band_importance or noise_spectrum holds a text or a value that is not a real number.
standard_speech_spectra(
vocal_efforts: Literal['normal', 'raised', 'loud', 'shout'] | Sequence[Literal['normal', 'raised', 'loud', 'shout']] = ('normal', 'raised', 'loud', 'shout'),
) -> StandardSpeechSpectrum

Build the plottable ANSI S3.5-1997 standard speech spectra (Table 3).

Collects the standard speech spectrum level Ui of the requested vocal efforts (via standard_speech_spectrum) into a StandardSpeechSpectrum that exposes .plot(). The band levels are unchanged; this is a thin, plottable wrapper around the existing function, which still returns the bare per-band array.

Parameters

Name Description
vocal_efforts A single vocal-effort name or a sequence of names, each one of "normal", "raised", "loud" or "shout". Defaults to the full family in the Table 3 order.

Returns: A frozen StandardSpeechSpectrum.

Raises

Exception When
ValueError for an unknown vocal effort, or an empty selection.
TypeError if an entry of vocal_efforts is not a text.
standard_speech_spectrum(
vocal_effort: Literal['normal', 'raised', 'loud', 'shout'] = 'normal',
) -> NDArray[np.float64]

Standard speech spectrum level by vocal effort (ANSI S3.5-1997 Table 3).

Parameters

Name Description
vocal_effort One of "normal", "raised", "loud", "shout".

Returns: The 18-band equivalent speech spectrum level Ui, in dB SPL.

Raises

Exception When
ValueError for an unknown vocal effort.
TypeError if vocal_effort is not a text.
StandardSpeechSpectrum(
frequencies: NDArray[np.float64],
vocal_efforts: tuple[Literal['normal', 'raised', 'loud', 'shout'], ...],
levels: NDArray[np.float64],
)

The ANSI S3.5-1997 standard speech spectra by vocal effort (Table 3).

Bundles the standard speech spectrum level Ui of one or more vocal efforts (ANSI S3.5-1997 Table 3) over the 18 one-third-octave bands, so the spectra can be drawn with plot. Build it with standard_speech_spectra; the frozen instance is a thin, plottable wrapper and re-runs none of the maths (the band levels are the tabulated constants that standard_speech_spectrum returns).

Attributes

Name Description
frequencies The 18 one-third-octave band centre frequencies, in hertz (160 Hz to 8000 Hz).
vocal_efforts The vocal efforts carried, in order; each one of "normal", "raised", "loud" or "shout".
levels The standard speech spectrum level Ui, in dB SPL, as a (len(vocal_efforts), 18) array; row i is the spectrum for vocal_efforts[i].
StandardSpeechSpectrum.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the standard speech spectrum level versus frequency band.

Draws the standard speech spectrum level (dB SPL) over the 18 one-third-octave bands (160 Hz to 8000 Hz) on a categorical band axis; each vocal effort in vocal_efforts is one labelled line, so the whole spectrum lifting with vocal effort reads at a glance.

Requires matplotlib (the [plot] extra); returns the Axes and never calls plt.show.

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the per-effort plot calls.

Returns: The axes.