Imaging Module

Plotting functions using matplotlib library.

Warning

You need to have matplotlib installed in order to use this module.

Attributes

TICKS_OCTAVE module-attribute

TICKS_OCTAVE = [
    "16",
    "31.5",
    "63",
    "125",
    "250",
    "500",
    "1000",
    "2000",
    "4000",
    "8000",
    "16000",
]

Octave center frequencies as strings.

TICKS_OCTAVE_KHZ module-attribute

TICKS_OCTAVE_KHZ = [
    "16",
    "31.5",
    "63",
    "125",
    "250",
    "500",
    "1k",
    "2k",
    "4k",
    "8k",
    "16k",
]

Octave center frequencies as strings. Uses kHz notation.

TICKS_THIRD_OCTAVE module-attribute

TICKS_THIRD_OCTAVE = [
    "12.5",
    "16",
    "20",
    "25",
    "31.5",
    "40",
    "50",
    "63",
    "80",
    "100",
    "125",
    "160",
    "200",
    "250",
    "315",
    "400",
    "500",
    "630",
    "800",
    "1000",
    "1250",
    "1600",
    "2000",
    "2500",
    "3150",
    "4000",
    "5000",
    "6300",
    "8000",
    "10000",
    "12500",
    "16000",
    "20000",
]

Third-octave center frequencies as strings.

TICKS_THIRD_OCTAVE_KHZ module-attribute

TICKS_THIRD_OCTAVE_KHZ = [
    "12.5",
    "16",
    "20",
    "25",
    "31.5",
    "40",
    "50",
    "63",
    "80",
    "100",
    "125",
    "160",
    "200",
    "250",
    "315",
    "400",
    "500",
    "630",
    "800",
    "1000",
    "1250",
    "1600",
    "2000",
    "2500",
    "3150",
    "4000",
    "5000",
    "6300",
    "8000",
    "10000",
    "12500",
    "16000",
    "20000",
]

Third-octave center frequencies as strings. Uses kHz notation.

Classes

OctaveBandScale

OctaveBandScale(axis, **kwargs)

Bases: ScaleBase

Octave band scale.

Source code in acoustic_toolbox/imaging.py

def __init__(self, axis, **kwargs):
    mscale.ScaleBase.__init__(self, axis)

ThirdBandScale

ThirdBandScale(axis, **kwargs)

Bases: ScaleBase

Third-octave band scale.

Source code in acoustic_toolbox/imaging.py

def __init__(self, axis, **kwargs):
    mscale.ScaleBase.__init__(self, axis)

Functions

plot_octave

plot_octave(
    data: ndarray,
    octaves: ndarray,
    axes: Axes | None = None,
    kHz: bool = False,
    xlabel: str | None = None,
    ylabel: str | None = None,
    title: str | None = None,
    separator: str | None = None,
    *args,
    **kwargs,
) -> list[Line2D]

Plot octave bands from data levels and octaves bands.

PARAMETER	DESCRIPTION
data	levels in a 1-D NumPy array. TYPE: ndarray
octaves	octaves in a 1-D NumPy array. Note that you can use acoustic_toolbox.bands.octave for this or manually enter all bands. TYPE: ndarray
axes	a matplotlib.axes object. TYPE: Axes | None DEFAULT: None
kHz	if True it shows "1k" or "2k" instead of "1000" or "2000" as TYPE: bool DEFAULT: False
xlabel	a str containing label for x axis. TYPE: str | None DEFAULT: None
ylabel	a str containing label for y axis. TYPE: str | None DEFAULT: None
title	a str containing title. TYPE: str | None DEFAULT: None
separator	a str defining the decimal separator. By default takes '.' or ',' values according to system settings (when separator is None). TYPE: str | None DEFAULT: None
*args	DEFAULT: ()
**kwargs	DEFAULT: {}

RETURNS	DESCRIPTION
list[Line2D]	A list of matplotlib.lines.Line2D objects.

See Also

matplotlib.axes.Axes.plot

Source code in acoustic_toolbox/imaging.py

def plot_octave(
    data: np.ndarray,
    octaves: np.ndarray,
    axes: Axes | None = None,
    kHz: bool = False,
    xlabel: str | None = None,
    ylabel: str | None = None,
    title: str | None = None,
    separator: str | None = None,
    *args,
    **kwargs,
) -> list[Line2D]:
    """Plot octave bands from `data` levels and `octaves` bands.

    Args:
      data: levels in a 1-D NumPy array.
      octaves: octaves in a 1-D NumPy array.
        Note that you can use [`acoustic_toolbox.bands.octave`][acoustic_toolbox.bands.octave]
        for this or manually enter all bands.
      axes: a `matplotlib.axes` object.
      kHz: if `True` it shows "1k" or "2k" instead of "1000" or "2000" as
      tick labels.
      xlabel: a `str` containing label for x axis.
      ylabel: a `str` containing label for y axis.
      title: a `str` containing title.
      separator: a `str` defining the decimal separator.  By default takes '.'
        or ',' values according to system settings (when separator is None).
      *args:
      **kwargs:

    Returns:
      A list of [`matplotlib.lines.Line2D`][matplotlib.lines.Line2D] objects.

    See Also:
      [`matplotlib.axes.Axes.plot`][matplotlib.axes.Axes.plot]
    """
    band_type = "octave"
    k_ticks = kHz
    return plot_bands(
        data,
        octaves,
        axes,
        band_type,
        k_ticks,
        xlabel,
        ylabel,
        title,
        separator,
        *args,
        **kwargs,
    )

plot_third

plot_third(
    data: ndarray,
    thirds: ndarray,
    axes: Axes | None = None,
    kHz: bool = False,
    xlabel: str | None = None,
    ylabel: str | None = None,
    title: str | None = None,
    separator: str | None = None,
    *args,
    **kwargs,
) -> list[Line2D]

Plot third octave bands from data levels and thirds bands.

PARAMETER	DESCRIPTION
data	levels in an 1-D NumPy array. TYPE: ndarray
thirds	thirds in an 1-D NumPy array. Note that you can use acoustic_toolbox.bands.third for this or manually enter all bands. TYPE: ndarray
axes	a matplotlib.axes object. TYPE: Axes | None DEFAULT: None
kHz	if True it shows "1k" or "2.5k" instead of "1000" or "2500" as tick labels. TYPE: bool DEFAULT: False
xlabel	a str containing label for x axis (optional). TYPE: str | None DEFAULT: None
ylabel	a str containing label for y axis (optional). TYPE: str | None DEFAULT: None
title	a str containing title (optional). TYPE: str | None DEFAULT: None
separator	a str defining the decimal separator. By default takes '.' or ',' values according to system settings (when separator is None). TYPE: str | None DEFAULT: None
*args	DEFAULT: ()
**kwargs	DEFAULT: {}

RETURNS	DESCRIPTION
list[Line2D]	A list of matplotlib.lines.Line2D objects.

See Also

matplotlib.axes.Axes.plot

Source code in acoustic_toolbox/imaging.py

def plot_third(
    data: np.ndarray,
    thirds: np.ndarray,
    axes: Axes | None = None,
    kHz: bool = False,
    xlabel: str | None = None,
    ylabel: str | None = None,
    title: str | None = None,
    separator: str | None = None,
    *args,
    **kwargs,
) -> list[Line2D]:
    """Plot third octave bands from `data` levels and `thirds` bands.

    Args:
      data: levels in an 1-D NumPy array.
      thirds: thirds in an 1-D NumPy array. Note that you can use
        [`acoustic_toolbox.bands.third`][acoustic_toolbox.bands.third] for this
        or manually enter all bands.
      axes: a `matplotlib.axes` object.
      kHz: if `True` it shows "1k" or "2.5k" instead of "1000" or "2500" as
        tick labels.
      xlabel: a `str` containing label for x axis (optional).
      ylabel: a `str` containing label for y axis (optional).
      title: a `str` containing title (optional).
      separator: a `str` defining the decimal separator. By default takes '.'
        or ',' values according to system settings (when separator is None).
      *args:
      **kwargs:

    Returns:
      A list of [`matplotlib.lines.Line2D`][matplotlib.lines.Line2D] objects.

    See Also:
      [`matplotlib.axes.Axes.plot`][matplotlib.axes.Axes.plot]
    """
    band_type = "third"
    k_ticks = kHz
    return plot_bands(
        data,
        thirds,
        axes,
        band_type,
        k_ticks,
        xlabel,
        ylabel,
        title,
        separator,
        *args,
        **kwargs,
    )

plot_bands

plot_bands(
    data: ndarray,
    bands: ndarray,
    axes: Axes,
    band_type: Literal["octave", "third"],
    k_ticks: bool = False,
    xlabel: str | None = None,
    ylabel: str | None = None,
    title: str | None = None,
    separator: str | None = None,
    *args,
    **kwargs,
) -> list[Line2D]

Plot bands from data levels and bands.

Only use if you want to plot from arbitrary octave or third octave data.

PARAMETER	DESCRIPTION
data	levels in an 1-D NumPy array. TYPE: ndarray
bands	bands in an 1-D NumPy array. TYPE: ndarray
axes	matplotlib.axes object. TYPE: Axes
band_type	'octave' or 'third' are accepted values. TYPE: Literal['octave', 'third']
k_ticks	if True it shows "1k" or "2.5k" instead of "1000" or "2500" as tick labels. TYPE: bool DEFAULT: False
xlabel	label for x axis. TYPE: str | None DEFAULT: None
ylabel	label for y axis. TYPE: str | None DEFAULT: None
title	title. TYPE: str | None DEFAULT: None
separator	decimal separator. By default takes '.' or ',' values according to system settings (when separator is None). TYPE: str | None DEFAULT: None
*args	additional arguments for matplotlib.axes.plot. DEFAULT: ()
**kwargs	additional arguments for matplotlib.axes.plot. DEFAULT: {}

RETURNS	DESCRIPTION
list[Line2D]	A list of matplotlib.lines.Line2D objects.

See Also

matplotlib.axes.Axes.plot

Source code in acoustic_toolbox/imaging.py

def plot_bands(
    data: np.ndarray,
    bands: np.ndarray,
    axes: Axes,
    band_type: Literal["octave", "third"],
    k_ticks: bool = False,
    xlabel: str | None = None,
    ylabel: str | None = None,
    title: str | None = None,
    separator: str | None = None,
    *args,
    **kwargs,
) -> list[Line2D]:
    """Plot bands from `data` levels and `bands`.

    Only use if you want to plot from arbitrary octave or third octave data.

    Args:
      data: levels in an 1-D NumPy array.
      bands: bands in an 1-D NumPy array.
      axes: `matplotlib.axes` object.
      band_type: `'octave'` or `'third'` are accepted values.
      k_ticks: if `True` it shows "1k" or "2.5k" instead of "1000" or "2500" as
        tick labels.
      xlabel: label for x axis.
      ylabel: label for y axis.
      title: title.
      separator: decimal separator. By default takes '.' or ',' values
        according to system settings (when separator is None).
      *args: additional arguments for `matplotlib.axes.plot`.
      **kwargs: additional arguments for `matplotlib.axes.plot`.

    Returns:
      A list of [`matplotlib.lines.Line2D`][matplotlib.lines.Line2D] objects.

    See Also:
      [`matplotlib.axes.Axes.plot`][matplotlib.axes.Axes.plot]
    """
    if axes is None:
        axes = plt.gca()
    factor = 0.1
    min_auto = bands[0] * (1 - factor)
    max_auto = bands[-1] * (1 + factor)
    axes.set_xlim([min_auto, max_auto])
    axes.set_xscale(band_type)

    # Set tick labels.
    ticklabels = _get_ticklabels(band_type, k_ticks, separator)
    if band_type == "third":
        third_ticks = True
    elif band_type == "octave":
        third_ticks = False
    axes.set_xticklabels(ticklabels, minor=third_ticks)

    # Set x and y labels and title.
    if xlabel is not None:
        axes.set_xlabel(xlabel)
    if ylabel is not None:
        axes.set_ylabel(ylabel)
    if title is not None:
        axes.set_title(title)
    return axes.plot(bands, data, *args, **kwargs)

:::