Octave Module

Module for working with octaves.

The following is an example on how to use acoustic_toolbox.octave.Octave.

.. literalinclude:: ../../examples/example_octave.py

Attributes

frequency_of_band `module-attribute`

frequency_of_band = exact_center_frequency

Calculate the center frequency for a given band index.

band_of_frequency `module-attribute`

band_of_frequency = index_of_frequency

Calculate the band index for a given frequency.

Classes

Octave

Octave(
    fraction=1,
    interval=None,
    fmin=None,
    fmax=None,
    unique: bool = False,
    reference=REFERENCE_FREQUENCY,
)

Class to calculate octave center frequencies.

ATTRIBUTE	DESCRIPTION
`reference`	Reference center frequency $f_{c,0}$.
`fraction`	Fraction of octave.
`interval`	Interval.
`fmin`	Minimum frequency of a range.
`fmax`	Maximum frequency of a range.
`unique`	Whether or not to calculate the requested values for every value of `interval`.
`reference`	Reference frequency.

RAISES	DESCRIPTION
`AttributeError`	If `interval` is not `None` and `fmin` or `fmax` is not `None`.

Source code in acoustic_toolbox/octave.py

def __init__(
    self,
    fraction=1,
    interval=None,
    fmin=None,
    fmax=None,
    unique: bool = False,
    reference=REFERENCE,
):
    """Initialize the Octave class.

    Raises:
      AttributeError: If ``interval`` is not ``None`` and ``fmin`` or ``fmax`` is not ``None``.
    """
    self.reference = reference
    self.fraction = fraction

    if (interval is not None) and (fmin is not None or fmax is not None):
        raise AttributeError("Cannot specify both interval and fmin/fmax")
    self._interval = np.asarray(interval)
    self._fmin = fmin
    self._fmax = fmax
    self.unique = unique

Attributes

fmin `property` `writable`

fmin

Minimum frequency of an interval.

fmax `property` `writable`

fmax

Maximum frequency of an interval.

interval `property` `writable`

interval

Interval.

n `property`

Return band n for a given frequency.

center `property`

center: float

Return center frequency $f_c$.

RETURNS	DESCRIPTION
`float`	Center frequency calculated as: $$ f_c = f_{ref} \cdot 2^{n/N} \cdot 10^{\frac{3}{10N}} $$

bandwidth `property`

bandwidth

Bandwidth of bands.

\[ B = f_u - f_l \]

lower `property`

lower: float

Lower frequency limits of bands.

RETURNS	DESCRIPTION
`float`	Lower frequency calculated as: $$ f_l = f_c \cdot 2^{\frac{-1}{2N}} $$

upper `property`

upper

Upper frequency limits of bands.

RETURNS	DESCRIPTION
`float`	Upper frequency calculated as: $$ f_u = f_c \cdot 2^{\frac{1}{2N}} $$

See Also

upper_frequency.

Functions

index_of_frequency

index_of_frequency(
    frequency,
    fraction=1,
    ref=REFERENCE_FREQUENCY,
    G=OCTAVE_FREQUENCY_RATIO,
) -> int | ndarray

Calculate the band index for a given frequency.

The index of the center frequency is given by

\[ x = \text{round}\left(b \frac{\log(f/f_r)}{\log(G)}\right) \]

See equation 6 of the standard.

Note

This equation is not part of the standard. However, it follows from exact_center_frequency.

PARAMETER	DESCRIPTION
`frequency`	Frequencies $f$
`fraction`	Bandwidth designator $b$. DEFAULT: `1`
`ref`	Reference frequency. DEFAULT: `REFERENCE_FREQUENCY`
`G`	Octave frequency ratio $G$. DEFAULT: `OCTAVE_FREQUENCY_RATIO`

RETURNS	DESCRIPTION
`int \| ndarray`	Band indices $x$

Source code in acoustic_toolbox/standards/iec_61260_1_2014.py

def index_of_frequency(
    frequency, fraction=1, ref=REFERENCE_FREQUENCY, G=OCTAVE_FREQUENCY_RATIO
) -> int | np.ndarray:
    r"""Calculate the band index for a given frequency.

    The index of the center frequency is given by

    $$
    x = \text{round}\left(b \frac{\log(f/f_r)}{\log(G)}\right)
    $$

    See equation 6 of the standard.

    Note:
        This equation is not part of the standard.
        However, it follows from [`exact_center_frequency`](acoustic_toolbox.standards.iec_61260_1_2014.exact_center_frequency).

    Args:
        frequency: Frequencies $f$
        fraction: Bandwidth designator $b$.
        ref: Reference frequency.
        G: Octave frequency ratio $G$.

    Returns:
        Band indices $x$
    """
    fraction = np.asarray(fraction)
    uneven = (fraction % 2).astype("bool")
    return (
        np.round((2.0 * fraction * np.log(frequency / ref) / np.log(G) - 1.0))
        / 2.0
        * np.logical_not(uneven)
        + uneven
        * np.round(fraction * np.log(frequency / ref) / np.log(G)).astype("int16")
    ).astype("int16")

exact_center_frequency

exact_center_frequency(
    frequency=None,
    fraction=1,
    n=None,
    ref=REFERENCE_FREQUENCY,
)

Exact center frequency.

PARAMETER	DESCRIPTION
`frequency`	Frequency within the band. DEFAULT: `None`
`fraction`	Band designator. DEFAULT: `1`
`n`	Index of band. DEFAULT: `None`
`ref`	Reference frequency. DEFAULT: `REFERENCE_FREQUENCY`

RETURNS	DESCRIPTION
	Exact center frequency for the given frequency or band index.

See Also

Source code in acoustic_toolbox/octave.py

def exact_center_frequency(frequency=None, fraction=1, n=None, ref=REFERENCE):
    """Exact center frequency.

    Args:
      frequency: Frequency within the band.
      fraction: Band designator.
      n: Index of band.
      ref: Reference frequency.

    Returns:
      Exact center frequency for the given frequency or band index.

    See Also:
      - [acoustic_toolbox.standards.iec_61260_1_2014.exact_center_frequency][acoustic_toolbox.standards.iec_61260_1_2014.exact_center_frequency]
      - [acoustic_toolbox.standards.iec_61260_1_2014.index_of_frequency][acoustic_toolbox.standards.iec_61260_1_2014.index_of_frequency]
    """
    if frequency is not None:
        n = iec_61260_1_2014.index_of_frequency(frequency, fraction=fraction, ref=ref)
    return iec_61260_1_2014.exact_center_frequency(n, fraction=fraction, ref=ref)

nominal_center_frequency

nominal_center_frequency(
    frequency=None, fraction=1, n=None
)

Nominal center frequency.

Note

Contrary to the other functions this function silently assumes 1000 Hz reference frequency.

PARAMETER	DESCRIPTION
`frequency`	Frequency within the band. DEFAULT: `None`
`fraction`	Band designator. DEFAULT: `1`
`n`	Index of band. DEFAULT: `None`

RETURNS	DESCRIPTION
	The nominal center frequency for the given frequency or band index.

See Also

Source code in acoustic_toolbox/octave.py

def nominal_center_frequency(frequency=None, fraction=1, n=None):
    """Nominal center frequency.

    Note:
      Contrary to the other functions this function silently assumes 1000 Hz reference frequency.

    Args:
      frequency: Frequency within the band.
      fraction: Band designator.
      n: Index of band.

    Returns:
      The nominal center frequency for the given frequency or band index.

    See Also:
      - [acoustic_toolbox.standards.iec_61260_1_2014.exact_center_frequency][acoustic_toolbox.standards.iec_61260_1_2014.exact_center_frequency]
      - [acoustic_toolbox.standards.iec_61260_1_2014.nominal_center_frequency][acoustic_toolbox.standards.iec_61260_1_2014.nominal_center_frequency]


    """
    center = exact_center_frequency(frequency, fraction, n)
    return iec_61260_1_2014.nominal_center_frequency(center, fraction)

lower_frequency

lower_frequency(
    frequency=None,
    fraction=1,
    n=None,
    ref=REFERENCE_FREQUENCY,
) -> float | ndarray

Lower band-edge frequency.

PARAMETER	DESCRIPTION
`frequency`	Frequency within the band. DEFAULT: `None`
`fraction`	Band designator. DEFAULT: `1`
`n`	Index of band. DEFAULT: `None`
`ref`	Reference frequency. DEFAULT: `REFERENCE_FREQUENCY`

RETURNS	DESCRIPTION
`float \| ndarray`	Lower band-edge frequency for the given frequency or band index.

See Also

Source code in acoustic_toolbox/octave.py

def lower_frequency(
    frequency=None, fraction=1, n=None, ref=REFERENCE
) -> float | np.ndarray:
    """Lower band-edge frequency.

    Args:
      frequency: Frequency within the band.
      fraction: Band designator.
      n: Index of band.
      ref: Reference frequency.

    Returns:
      Lower band-edge frequency for the given frequency or band index.

    See Also:
      - [acoustic_toolbox.standards.iec_61260_1_2014.exact_center_frequency][acoustic_toolbox.standards.iec_61260_1_2014.exact_center_frequency]
      - [acoustic_toolbox.standards.iec_61260_1_2014.lower_frequency][acoustic_toolbox.standards.iec_61260_1_2014.lower_frequency]
    """
    center = exact_center_frequency(frequency, fraction, n, ref=ref)
    return iec_61260_1_2014.lower_frequency(center, fraction)

upper_frequency

upper_frequency(
    frequency=None,
    fraction=1,
    n=None,
    ref=REFERENCE_FREQUENCY,
) -> float | ndarray

Upper band-edge frequency.

PARAMETER	DESCRIPTION
`frequency`	Frequency within the band. DEFAULT: `None`
`fraction`	Band designator. DEFAULT: `1`
`n`	Index of band. DEFAULT: `None`
`ref`	Reference frequency. DEFAULT: `REFERENCE_FREQUENCY`

RETURNS	DESCRIPTION
`float \| ndarray`	Upper band-edge frequency for the given frequency or band index.

See Also

Source code in acoustic_toolbox/octave.py

def upper_frequency(
    frequency=None, fraction=1, n=None, ref=REFERENCE
) -> float | np.ndarray:
    """Upper band-edge frequency.

    Args:
      frequency: Frequency within the band.
      fraction: Band designator.
      n: Index of band.
      ref: Reference frequency.

    Returns:
      Upper band-edge frequency for the given frequency or band index.

    See Also:
      - [acoustic_toolbox.standards.iec_61260_1_2014.exact_center_frequency][acoustic_toolbox.standards.iec_61260_1_2014.exact_center_frequency]
      - [acoustic_toolbox.standards.iec_61260_1_2014.upper_frequency][acoustic_toolbox.standards.iec_61260_1_2014.upper_frequency]
    """
    center = exact_center_frequency(frequency, fraction, n, ref=ref)
    return iec_61260_1_2014.upper_frequency(center, fraction)

:::

ATTRIBUTE	DESCRIPTION
`reference`	Reference center frequency \(f_{c,0}\).
`fraction`	Fraction of octave.
`interval`	Interval.
`fmin`	Minimum frequency of a range.
`fmax`	Maximum frequency of a range.
`unique`	Whether or not to calculate the requested values for every value of `interval`.
`reference`	Reference frequency.

PARAMETER	DESCRIPTION
`frequency`	Frequencies \(f\)
`fraction`	Bandwidth designator \(b\). DEFAULT: `1`
`ref`	Reference frequency. DEFAULT: `REFERENCE_FREQUENCY`
`G`	Octave frequency ratio \(G\). DEFAULT: `OCTAVE_FREQUENCY_RATIO`

Octave Module

Attributes

frequency_of_band module-attribute

band_of_frequency module-attribute

Classes

Octave

Attributes

fmin property writable

fmax property writable

interval property writable

n property

center property

bandwidth property

lower property

upper property

Functions

Functions

index_of_frequency

exact_center_frequency

nominal_center_frequency

lower_frequency

upper_frequency

frequency_of_band `module-attribute`

band_of_frequency `module-attribute`

fmin `property` `writable`

fmax `property` `writable`

interval `property` `writable`

n `property`

center `property`

bandwidth `property`

lower `property`

upper `property`