Visualization Module / 可視化モジュール

The wandas.visualization module provides functionality for visually representing audio data. wandas.visualization モジュールは、オーディオデータを視覚的に表現するための機能を提供します。

Plotting / プロッティング

Provides plotting functions for visualizing audio data. オーディオデータを視覚化するためのプロッティング関数を提供します。

wandas.visualization.plotting

Attributes

logger = logging.getLogger(__name__) module-attribute

TFrame = TypeVar('TFrame', bound='BaseFrame[Any]') module-attribute

PlotLabel = str | Sequence[str] | None module-attribute

Classes

PlotStrategy

Bases: ABC, Generic[TFrame]

Base class for plotting strategies

Source code in wandas/visualization/plotting.py

class PlotStrategy(abc.ABC, Generic[TFrame]):
    """Base class for plotting strategies"""

    name: ClassVar[str]

    @abc.abstractmethod
    def channel_plot(
        self,
        x: Any,
        y: Any,
        ax: Axes,
        label: PlotLabel = None,
        alpha: float = 1.0,
    ) -> None:
        """Implementation of channel plotting"""

    @abc.abstractmethod
    def plot(
        self,
        bf: TFrame,
        ax: Axes | None = None,
        title: str | None = None,
        overlay: bool = False,
        **kwargs: Any,
    ) -> Axes | Iterator[Axes]:
        """Implementation of plotting"""

Attributes

name class-attribute

Functions

channel_plot(x, y, ax, label=None, alpha=1.0) abstractmethod

Implementation of channel plotting

Source code in wandas/visualization/plotting.py

@abc.abstractmethod
def channel_plot(
    self,
    x: Any,
    y: Any,
    ax: Axes,
    label: PlotLabel = None,
    alpha: float = 1.0,
) -> None:
    """Implementation of channel plotting"""

plot(bf, ax=None, title=None, overlay=False, **kwargs) abstractmethod

Implementation of plotting

Source code in wandas/visualization/plotting.py

@abc.abstractmethod
def plot(
    self,
    bf: TFrame,
    ax: Axes | None = None,
    title: str | None = None,
    overlay: bool = False,
    **kwargs: Any,
) -> Axes | Iterator[Axes]:
    """Implementation of plotting"""

WaveformPlotStrategy

Bases: PlotStrategy['ChannelFrame']

Strategy for waveform plotting

Source code in wandas/visualization/plotting.py

class WaveformPlotStrategy(PlotStrategy["ChannelFrame"]):
    """Strategy for waveform plotting"""

    name = "waveform"

    def channel_plot(
        self,
        x: Any,
        y: Any,
        ax: Axes,
        label: PlotLabel = None,
        alpha: float = 1.0,
        **kwargs: Any,
    ) -> None:
        """Implementation of channel plotting"""
        if label is not None:
            kwargs["label"] = label
        if alpha is not None:
            kwargs["alpha"] = alpha
        ax.plot(x, y, **kwargs)
        ax.set_ylabel("Amplitude")
        ax.grid(True)
        if label is not None:
            ax.legend()

    def plot(
        self,
        bf: ChannelFrame,
        ax: Axes | None = None,
        title: str | None = None,
        overlay: bool = False,
        **kwargs: Any,
    ) -> Axes | Iterator[Axes]:
        """Waveform plotting"""
        kwargs = kwargs or {}
        axes_cls = _matplotlib_axes_type("waveform plot")
        line2d_cls = _matplotlib_line2d_type("waveform plot")
        explicit_ylabel = "ylabel" in kwargs
        ylabel = kwargs.pop("ylabel", "Amplitude")
        xlabel = kwargs.pop("xlabel", "Time [s]")
        alpha = kwargs.pop("alpha", 1)
        label = kwargs.pop("label", None)
        plot_kwargs = filter_kwargs(line2d_cls, kwargs, strict_mode=True)
        ax_set = filter_kwargs(axes_cls.set, kwargs, strict_mode=True)
        data = _reshape_to_2d(bf.data)

        def _waveform_ylabel(ylabel: str, ch_meta: Any) -> str:
            unit_suffix = f" [{ch_meta.unit}]" if ch_meta.unit else ""
            return f"{ylabel}{unit_suffix}"

        if (overlay or ax is not None) and not explicit_ylabel:
            channel_units = [ch_meta.unit for ch_meta in bf.channels]
            if channel_units and all(unit and unit == channel_units[0] for unit in channel_units):
                ylabel = f"{ylabel} [{channel_units[0]}]"

        return _plot_line_layout(
            self,
            bf,
            bf.time,
            data,
            ax=ax,
            title=title,
            overlay=overlay,
            ylabel=ylabel,
            xlabel=xlabel,
            default_title=bf.label or "Channel Data",
            alpha=alpha,
            label=label,
            plot_kwargs=plot_kwargs,
            ax_set=ax_set,
            per_channel_ylabel_fn=_waveform_ylabel,
        )

Attributes

name = 'waveform' class-attribute instance-attribute

Functions

channel_plot(x, y, ax, label=None, alpha=1.0, **kwargs)

Implementation of channel plotting

Source code in wandas/visualization/plotting.py

def channel_plot(
    self,
    x: Any,
    y: Any,
    ax: Axes,
    label: PlotLabel = None,
    alpha: float = 1.0,
    **kwargs: Any,
) -> None:
    """Implementation of channel plotting"""
    if label is not None:
        kwargs["label"] = label
    if alpha is not None:
        kwargs["alpha"] = alpha
    ax.plot(x, y, **kwargs)
    ax.set_ylabel("Amplitude")
    ax.grid(True)
    if label is not None:
        ax.legend()

plot(bf, ax=None, title=None, overlay=False, **kwargs)

Waveform plotting

Source code in wandas/visualization/plotting.py

def plot(
    self,
    bf: ChannelFrame,
    ax: Axes | None = None,
    title: str | None = None,
    overlay: bool = False,
    **kwargs: Any,
) -> Axes | Iterator[Axes]:
    """Waveform plotting"""
    kwargs = kwargs or {}
    axes_cls = _matplotlib_axes_type("waveform plot")
    line2d_cls = _matplotlib_line2d_type("waveform plot")
    explicit_ylabel = "ylabel" in kwargs
    ylabel = kwargs.pop("ylabel", "Amplitude")
    xlabel = kwargs.pop("xlabel", "Time [s]")
    alpha = kwargs.pop("alpha", 1)
    label = kwargs.pop("label", None)
    plot_kwargs = filter_kwargs(line2d_cls, kwargs, strict_mode=True)
    ax_set = filter_kwargs(axes_cls.set, kwargs, strict_mode=True)
    data = _reshape_to_2d(bf.data)

    def _waveform_ylabel(ylabel: str, ch_meta: Any) -> str:
        unit_suffix = f" [{ch_meta.unit}]" if ch_meta.unit else ""
        return f"{ylabel}{unit_suffix}"

    if (overlay or ax is not None) and not explicit_ylabel:
        channel_units = [ch_meta.unit for ch_meta in bf.channels]
        if channel_units and all(unit and unit == channel_units[0] for unit in channel_units):
            ylabel = f"{ylabel} [{channel_units[0]}]"

    return _plot_line_layout(
        self,
        bf,
        bf.time,
        data,
        ax=ax,
        title=title,
        overlay=overlay,
        ylabel=ylabel,
        xlabel=xlabel,
        default_title=bf.label or "Channel Data",
        alpha=alpha,
        label=label,
        plot_kwargs=plot_kwargs,
        ax_set=ax_set,
        per_channel_ylabel_fn=_waveform_ylabel,
    )

FrequencyPlotStrategy

Bases: PlotStrategy['SpectralFrame']

Strategy for frequency domain plotting

Source code in wandas/visualization/plotting.py

class FrequencyPlotStrategy(PlotStrategy["SpectralFrame"]):
    """Strategy for frequency domain plotting"""

    name = "frequency"

    def channel_plot(
        self,
        x: Any,
        y: Any,
        ax: Axes,
        label: PlotLabel = None,
        alpha: float = 1.0,
        **kwargs: Any,
    ) -> None:
        """Implementation of channel plotting"""
        if label is not None:
            kwargs["label"] = label
        if alpha is not None and alpha != 1.0:
            kwargs["alpha"] = alpha
        ax.plot(x, y, **kwargs)
        ax.grid(True)
        if label is not None:
            ax.legend()

    def plot(
        self,
        bf: SpectralFrame,
        ax: Axes | None = None,
        title: str | None = None,
        overlay: bool = False,
        **kwargs: Any,
    ) -> Axes | Iterator[Axes]:
        """Frequency domain plotting"""
        kwargs = kwargs or {}
        axes_cls = _matplotlib_axes_type("frequency plot")
        line2d_cls = _matplotlib_line2d_type("frequency plot")
        is_aw = kwargs.pop("Aw", False)
        if len(bf.operation_history) > 0 and bf.operation_history[-1]["operation"] == "coherence":
            data = bf.magnitude
            ylabel = kwargs.pop("ylabel", "coherence")
        else:
            if is_aw:
                unit = "dBA"
                data = bf.dBA
            else:
                unit = "dB"
                data = bf.dB
            ylabel = kwargs.pop("ylabel", f"Spectrum level [{unit}]")
        data = _reshape_to_2d(data)
        xlabel = kwargs.pop("xlabel", "Frequency [Hz]")
        alpha = kwargs.pop("alpha", 1)
        label = kwargs.pop("label", None)
        plot_kwargs = filter_kwargs(line2d_cls, kwargs, strict_mode=True)
        ax_set = filter_kwargs(axes_cls.set, kwargs, strict_mode=True)

        return _plot_line_layout(
            self,
            bf,
            bf.freqs,
            data,
            ax=ax,
            title=title,
            overlay=overlay,
            ylabel=ylabel,
            xlabel=xlabel,
            default_title=bf.label or "Channel Data",
            alpha=alpha,
            label=label,
            plot_kwargs=plot_kwargs,
            ax_set=ax_set,
        )

Attributes

name = 'frequency' class-attribute instance-attribute

Functions

channel_plot(x, y, ax, label=None, alpha=1.0, **kwargs)

Implementation of channel plotting

Source code in wandas/visualization/plotting.py

def channel_plot(
    self,
    x: Any,
    y: Any,
    ax: Axes,
    label: PlotLabel = None,
    alpha: float = 1.0,
    **kwargs: Any,
) -> None:
    """Implementation of channel plotting"""
    if label is not None:
        kwargs["label"] = label
    if alpha is not None and alpha != 1.0:
        kwargs["alpha"] = alpha
    ax.plot(x, y, **kwargs)
    ax.grid(True)
    if label is not None:
        ax.legend()

plot(bf, ax=None, title=None, overlay=False, **kwargs)

Frequency domain plotting

Source code in wandas/visualization/plotting.py

def plot(
    self,
    bf: SpectralFrame,
    ax: Axes | None = None,
    title: str | None = None,
    overlay: bool = False,
    **kwargs: Any,
) -> Axes | Iterator[Axes]:
    """Frequency domain plotting"""
    kwargs = kwargs or {}
    axes_cls = _matplotlib_axes_type("frequency plot")
    line2d_cls = _matplotlib_line2d_type("frequency plot")
    is_aw = kwargs.pop("Aw", False)
    if len(bf.operation_history) > 0 and bf.operation_history[-1]["operation"] == "coherence":
        data = bf.magnitude
        ylabel = kwargs.pop("ylabel", "coherence")
    else:
        if is_aw:
            unit = "dBA"
            data = bf.dBA
        else:
            unit = "dB"
            data = bf.dB
        ylabel = kwargs.pop("ylabel", f"Spectrum level [{unit}]")
    data = _reshape_to_2d(data)
    xlabel = kwargs.pop("xlabel", "Frequency [Hz]")
    alpha = kwargs.pop("alpha", 1)
    label = kwargs.pop("label", None)
    plot_kwargs = filter_kwargs(line2d_cls, kwargs, strict_mode=True)
    ax_set = filter_kwargs(axes_cls.set, kwargs, strict_mode=True)

    return _plot_line_layout(
        self,
        bf,
        bf.freqs,
        data,
        ax=ax,
        title=title,
        overlay=overlay,
        ylabel=ylabel,
        xlabel=xlabel,
        default_title=bf.label or "Channel Data",
        alpha=alpha,
        label=label,
        plot_kwargs=plot_kwargs,
        ax_set=ax_set,
    )

NOctPlotStrategy

Bases: PlotStrategy['NOctFrame']

Strategy for N-octave band analysis plotting

Source code in wandas/visualization/plotting.py

class NOctPlotStrategy(PlotStrategy["NOctFrame"]):
    """Strategy for N-octave band analysis plotting"""

    name = "noct"

    def channel_plot(
        self,
        x: Any,
        y: Any,
        ax: Axes,
        label: PlotLabel = None,
        alpha: float = 1.0,
        **kwargs: Any,
    ) -> None:
        """Implementation of channel plotting"""
        if label is not None:
            kwargs["label"] = label
        if alpha is not None and alpha != 1.0:
            kwargs["alpha"] = alpha
        ax.step(x, y, **kwargs)
        ax.grid(True)
        if label is not None:
            ax.legend()

    def plot(
        self,
        bf: NOctFrame,
        ax: Axes | None = None,
        title: str | None = None,
        overlay: bool = False,
        **kwargs: Any,
    ) -> Axes | Iterator[Axes]:
        """N-octave band analysis plotting"""
        kwargs = kwargs or {}
        axes_cls = _matplotlib_axes_type("noct plot")
        line2d_cls = _matplotlib_line2d_type("noct plot")
        is_aw = kwargs.pop("Aw", False)

        if is_aw:
            unit = "dBrA"
            data = bf.dBA
        else:
            unit = "dBr"
            data = bf.dB
        data = _reshape_to_2d(data)
        ylabel = kwargs.pop("ylabel", f"Spectrum level [{unit}]")
        xlabel = kwargs.pop("xlabel", "Center frequency [Hz]")
        alpha = kwargs.pop("alpha", 1)
        label = kwargs.pop("label", None)
        plot_kwargs = filter_kwargs(line2d_cls, kwargs, strict_mode=True)
        ax_set = filter_kwargs(axes_cls.set, kwargs, strict_mode=True)

        default_title = bf.label or f"1/{bf.n!s}-Octave Spectrum"
        return _plot_line_layout(
            self,
            bf,
            bf.freqs,
            data,
            ax=ax,
            title=title,
            overlay=overlay,
            ylabel=ylabel,
            xlabel=xlabel,
            default_title=default_title,
            alpha=alpha,
            label=label,
            plot_kwargs=plot_kwargs,
            ax_set=ax_set,
        )

Attributes

name = 'noct' class-attribute instance-attribute

Functions

channel_plot(x, y, ax, label=None, alpha=1.0, **kwargs)

Implementation of channel plotting

Source code in wandas/visualization/plotting.py

def channel_plot(
    self,
    x: Any,
    y: Any,
    ax: Axes,
    label: PlotLabel = None,
    alpha: float = 1.0,
    **kwargs: Any,
) -> None:
    """Implementation of channel plotting"""
    if label is not None:
        kwargs["label"] = label
    if alpha is not None and alpha != 1.0:
        kwargs["alpha"] = alpha
    ax.step(x, y, **kwargs)
    ax.grid(True)
    if label is not None:
        ax.legend()

plot(bf, ax=None, title=None, overlay=False, **kwargs)

N-octave band analysis plotting

Source code in wandas/visualization/plotting.py

def plot(
    self,
    bf: NOctFrame,
    ax: Axes | None = None,
    title: str | None = None,
    overlay: bool = False,
    **kwargs: Any,
) -> Axes | Iterator[Axes]:
    """N-octave band analysis plotting"""
    kwargs = kwargs or {}
    axes_cls = _matplotlib_axes_type("noct plot")
    line2d_cls = _matplotlib_line2d_type("noct plot")
    is_aw = kwargs.pop("Aw", False)

    if is_aw:
        unit = "dBrA"
        data = bf.dBA
    else:
        unit = "dBr"
        data = bf.dB
    data = _reshape_to_2d(data)
    ylabel = kwargs.pop("ylabel", f"Spectrum level [{unit}]")
    xlabel = kwargs.pop("xlabel", "Center frequency [Hz]")
    alpha = kwargs.pop("alpha", 1)
    label = kwargs.pop("label", None)
    plot_kwargs = filter_kwargs(line2d_cls, kwargs, strict_mode=True)
    ax_set = filter_kwargs(axes_cls.set, kwargs, strict_mode=True)

    default_title = bf.label or f"1/{bf.n!s}-Octave Spectrum"
    return _plot_line_layout(
        self,
        bf,
        bf.freqs,
        data,
        ax=ax,
        title=title,
        overlay=overlay,
        ylabel=ylabel,
        xlabel=xlabel,
        default_title=default_title,
        alpha=alpha,
        label=label,
        plot_kwargs=plot_kwargs,
        ax_set=ax_set,
    )

SpectrogramPlotStrategy

Bases: PlotStrategy['SpectrogramFrame']

Strategy for spectrogram plotting

Source code in wandas/visualization/plotting.py

class SpectrogramPlotStrategy(PlotStrategy["SpectrogramFrame"]):
    """Strategy for spectrogram plotting"""

    name = "spectrogram"

    def channel_plot(
        self,
        x: Any,
        y: Any,
        ax: Axes,
        label: PlotLabel = None,
        alpha: float = 1.0,
        **kwargs: Any,
    ) -> None:
        """Implementation of channel plotting"""

    def plot(
        self,
        bf: SpectrogramFrame,
        ax: Axes | None = None,
        title: str | None = None,
        overlay: bool = False,
        **kwargs: Any,
    ) -> Axes | Iterator[Axes]:
        """Spectrogram plotting"""
        # Explicit overlay mode is not supported for spectrograms
        if overlay:
            raise ValueError("Overlay is not supported for SpectrogramPlotStrategy.")

        # If an Axes is provided, allow drawing into it only for single-channel frames
        if ax is not None and bf.n_channels > 1:
            raise ValueError("ax must be None when n_channels > 1.")

        kwargs = kwargs or {}
        plt = _matplotlib_pyplot("spectrogram plot")
        axes_cls = _matplotlib_axes_type("spectrogram plot")
        figure_cls = _matplotlib_figure_type("spectrogram plot")

        is_aw = kwargs.pop("Aw", False)
        if is_aw:
            unit = "dBA"
            data = bf.dBA
        else:
            unit = "dB"
            data = bf.dB
        data = _reshape_spectrogram_data(data)

        cmap = kwargs.pop("cmap", "jet")
        vmin = kwargs.pop("vmin", None)
        vmax = kwargs.pop("vmax", None)
        fmin = kwargs.pop("fmin", 0)
        fmax = kwargs.pop("fmax", None)
        xlim = kwargs.pop("xlim", None)
        ylim = kwargs.pop("ylim", None)
        shading = kwargs.pop("shading", "auto")
        ax_set_kwargs = filter_kwargs(axes_cls.set, kwargs, strict_mode=True)

        def draw_spectrogram(target_ax: Axes, channel_data: np.ndarray, plot_title: str | None) -> Any:
            times, freqs = _spectrogram_axis_values(bf, channel_data)
            image_kwargs = filter_kwargs(target_ax.pcolormesh, kwargs, strict_mode=True)
            img = target_ax.pcolormesh(
                times,
                freqs,
                channel_data,
                shading=shading,
                cmap=cmap,
                vmin=vmin,
                vmax=vmax,
                **image_kwargs,
            )
            spectrogram_ylim = ylim if ylim is not None else (fmin, fmax) if fmin != 0 or fmax is not None else None
            target_ax.set(
                title=plot_title,
                ylabel="Frequency [Hz]",
                xlabel="Time [s]",
                xlim=xlim,
                ylim=spectrogram_ylim,
                **ax_set_kwargs,
            )
            return img

        if ax is not None:
            img = draw_spectrogram(ax, data[0], title or bf.label or "Spectrogram")

            fig = ax.figure
            if fig is not None:
                try:
                    cbar = fig.colorbar(img, ax=ax)
                    cbar.set_label(f"Spectrum level [{unit}]")
                except (ValueError, AttributeError) as e:
                    logger.warning(f"Failed to create colorbar for spectrogram: {type(e).__name__}: {e}")
            return ax

        # Create a new figure if ax is None
        num_channels = bf.n_channels
        fig, axs = plt.subplots(num_channels, 1, figsize=(10, 5 * num_channels), sharex=True)
        if not isinstance(fig, figure_cls):
            raise ValueError("fig must be a matplotlib Figure object.")
        # Convert axs to array if it is a single Axes object
        if not isinstance(axs, np.ndarray):
            axs = np.array([axs])

        for ax_i, channel_data, ch_meta in zip(axs.flatten(), data, bf.channels, strict=True):
            img = draw_spectrogram(ax_i, channel_data, ch_meta.label)
            try:
                cbar = ax_i.figure.colorbar(img, ax=ax_i)
                cbar.set_label(f"Spectrum level [{unit}]")
            except (ValueError, AttributeError) as e:
                logger.warning(f"Failed to create colorbar for spectrogram: {type(e).__name__}: {e}")
            fig.suptitle(title or "Spectrogram Data")
        plt.tight_layout()
        plt.show()

        return _return_axes_iterator(fig.axes)

Attributes

name = 'spectrogram' class-attribute instance-attribute

Functions

channel_plot(x, y, ax, label=None, alpha=1.0, **kwargs)

Implementation of channel plotting

Source code in wandas/visualization/plotting.py

def channel_plot(
    self,
    x: Any,
    y: Any,
    ax: Axes,
    label: PlotLabel = None,
    alpha: float = 1.0,
    **kwargs: Any,
) -> None:
    """Implementation of channel plotting"""

plot(bf, ax=None, title=None, overlay=False, **kwargs)

Spectrogram plotting

Source code in wandas/visualization/plotting.py

def plot(
    self,
    bf: SpectrogramFrame,
    ax: Axes | None = None,
    title: str | None = None,
    overlay: bool = False,
    **kwargs: Any,
) -> Axes | Iterator[Axes]:
    """Spectrogram plotting"""
    # Explicit overlay mode is not supported for spectrograms
    if overlay:
        raise ValueError("Overlay is not supported for SpectrogramPlotStrategy.")

    # If an Axes is provided, allow drawing into it only for single-channel frames
    if ax is not None and bf.n_channels > 1:
        raise ValueError("ax must be None when n_channels > 1.")

    kwargs = kwargs or {}
    plt = _matplotlib_pyplot("spectrogram plot")
    axes_cls = _matplotlib_axes_type("spectrogram plot")
    figure_cls = _matplotlib_figure_type("spectrogram plot")

    is_aw = kwargs.pop("Aw", False)
    if is_aw:
        unit = "dBA"
        data = bf.dBA
    else:
        unit = "dB"
        data = bf.dB
    data = _reshape_spectrogram_data(data)

    cmap = kwargs.pop("cmap", "jet")
    vmin = kwargs.pop("vmin", None)
    vmax = kwargs.pop("vmax", None)
    fmin = kwargs.pop("fmin", 0)
    fmax = kwargs.pop("fmax", None)
    xlim = kwargs.pop("xlim", None)
    ylim = kwargs.pop("ylim", None)
    shading = kwargs.pop("shading", "auto")
    ax_set_kwargs = filter_kwargs(axes_cls.set, kwargs, strict_mode=True)

    def draw_spectrogram(target_ax: Axes, channel_data: np.ndarray, plot_title: str | None) -> Any:
        times, freqs = _spectrogram_axis_values(bf, channel_data)
        image_kwargs = filter_kwargs(target_ax.pcolormesh, kwargs, strict_mode=True)
        img = target_ax.pcolormesh(
            times,
            freqs,
            channel_data,
            shading=shading,
            cmap=cmap,
            vmin=vmin,
            vmax=vmax,
            **image_kwargs,
        )
        spectrogram_ylim = ylim if ylim is not None else (fmin, fmax) if fmin != 0 or fmax is not None else None
        target_ax.set(
            title=plot_title,
            ylabel="Frequency [Hz]",
            xlabel="Time [s]",
            xlim=xlim,
            ylim=spectrogram_ylim,
            **ax_set_kwargs,
        )
        return img

    if ax is not None:
        img = draw_spectrogram(ax, data[0], title or bf.label or "Spectrogram")

        fig = ax.figure
        if fig is not None:
            try:
                cbar = fig.colorbar(img, ax=ax)
                cbar.set_label(f"Spectrum level [{unit}]")
            except (ValueError, AttributeError) as e:
                logger.warning(f"Failed to create colorbar for spectrogram: {type(e).__name__}: {e}")
        return ax

    # Create a new figure if ax is None
    num_channels = bf.n_channels
    fig, axs = plt.subplots(num_channels, 1, figsize=(10, 5 * num_channels), sharex=True)
    if not isinstance(fig, figure_cls):
        raise ValueError("fig must be a matplotlib Figure object.")
    # Convert axs to array if it is a single Axes object
    if not isinstance(axs, np.ndarray):
        axs = np.array([axs])

    for ax_i, channel_data, ch_meta in zip(axs.flatten(), data, bf.channels, strict=True):
        img = draw_spectrogram(ax_i, channel_data, ch_meta.label)
        try:
            cbar = ax_i.figure.colorbar(img, ax=ax_i)
            cbar.set_label(f"Spectrum level [{unit}]")
        except (ValueError, AttributeError) as e:
            logger.warning(f"Failed to create colorbar for spectrogram: {type(e).__name__}: {e}")
        fig.suptitle(title or "Spectrogram Data")
    plt.tight_layout()
    plt.show()

    return _return_axes_iterator(fig.axes)

DescribePlotStrategy

Bases: PlotStrategy['ChannelFrame']

Strategy for visualizing ChannelFrame data with describe plot

Source code in wandas/visualization/plotting.py

class DescribePlotStrategy(PlotStrategy["ChannelFrame"]):
    """Strategy for visualizing ChannelFrame data with describe plot"""

    name = "describe"

    def channel_plot(
        self,
        x: Any,
        y: Any,
        ax: Axes,
        label: PlotLabel = None,
        alpha: float = 1.0,
        **kwargs: Any,
    ) -> None:
        """Implementation of channel plotting"""
        # This method is not used for describe plot

    def plot(
        self,
        bf: ChannelFrame,
        ax: Axes | None = None,
        title: str | None = None,
        overlay: bool = False,
        **kwargs: Any,
    ) -> Axes | Iterator[Axes]:
        """Implementation of describe method for visualizing ChannelFrame data"""

        plt = _matplotlib_pyplot("describe plot")
        gridspec = _matplotlib_gridspec("describe plot")

        fmin = kwargs.pop("fmin", 0)
        fmax = kwargs.pop("fmax", None)
        cmap = kwargs.pop("cmap", "jet")
        vmin = kwargs.pop("vmin", None)
        vmax = kwargs.pop("vmax", None)
        xlim = kwargs.pop("xlim", None)
        ylim = kwargs.pop("ylim", None)
        is_aw = kwargs.pop("Aw", False)
        waveform = kwargs.pop("waveform", {})
        spectral = kwargs.pop("spectral", {"xlim": (vmin, vmax)})

        gs = gridspec.GridSpec(2, 3, height_ratios=[1, 3], width_ratios=[3, 1, 0.1])
        gs.update(wspace=0.2)

        fig = plt.figure(figsize=(12, 6))
        fig.subplots_adjust(wspace=0.0001)

        # First subplot (Time Plot)
        ax_1 = fig.add_subplot(gs[0])
        bf.plot(plot_type="waveform", ax=ax_1, overlay=True)
        ax_1.set(**waveform)
        ax_1.legend().set_visible(False)
        ax_1.set(xlabel="", title="")

        # Second subplot (STFT Plot)
        ax_2 = fig.add_subplot(gs[3], sharex=ax_1)
        stft_ch = bf.stft()
        if is_aw:
            unit = "dBA"
            channel_data = stft_ch.dBA
        else:
            unit = "dB"
            channel_data = stft_ch.dB
        if channel_data.ndim == 3:
            channel_data = channel_data[0]
        # Get the maximum value of the data and round it to a convenient value
        if vmax is None:
            data_max = np.nanmax(channel_data)
            # Round to a convenient number with increments of 10, 5, or 2
            for step in [10, 5, 2]:
                rounded_max = np.ceil(data_max / step) * step
                if rounded_max >= data_max:
                    vmax = rounded_max
                    vmin = vmax - 180
                    break
        times, freqs = _spectrogram_axis_values(stft_ch, channel_data)
        img = ax_2.pcolormesh(times, freqs, channel_data, shading="auto", cmap=cmap, vmin=vmin, vmax=vmax)
        spectrogram_ylim = ylim if ylim is not None else (fmin, fmax) if fmin != 0 or fmax is not None else None
        ax_2.set(xlabel="Time [s]", ylabel="Frequency [Hz]", xlim=xlim, ylim=spectrogram_ylim)

        # Third subplot
        ax_3 = fig.add_subplot(gs[1])
        ax_3.axis("off")

        # Fourth subplot (Welch Plot)
        ax_4 = fig.add_subplot(gs[4], sharey=ax_2)
        welch_ch = bf.welch()
        if is_aw:
            unit = "dBA"
            data_db = welch_ch.dBA
        else:
            unit = "dB"
            data_db = welch_ch.dB
        ax_4.plot(data_db.T, welch_ch.freqs.T)
        ax_4.grid(True)
        ax_4.set(xlabel=f"Spectrum level [{unit}]", **spectral)

        cbar = fig.colorbar(img, ax=ax_4, format="%+2.0f")
        cbar.set_label(unit)
        fig.suptitle(title or bf.label or "Channel Data")

        return _return_axes_iterator(fig.axes)

Attributes

name = 'describe' class-attribute instance-attribute

Functions

channel_plot(x, y, ax, label=None, alpha=1.0, **kwargs)

Implementation of channel plotting

Source code in wandas/visualization/plotting.py

def channel_plot(
    self,
    x: Any,
    y: Any,
    ax: Axes,
    label: PlotLabel = None,
    alpha: float = 1.0,
    **kwargs: Any,
) -> None:
    """Implementation of channel plotting"""

plot(bf, ax=None, title=None, overlay=False, **kwargs)

Implementation of describe method for visualizing ChannelFrame data

Source code in wandas/visualization/plotting.py

def plot(
    self,
    bf: ChannelFrame,
    ax: Axes | None = None,
    title: str | None = None,
    overlay: bool = False,
    **kwargs: Any,
) -> Axes | Iterator[Axes]:
    """Implementation of describe method for visualizing ChannelFrame data"""

    plt = _matplotlib_pyplot("describe plot")
    gridspec = _matplotlib_gridspec("describe plot")

    fmin = kwargs.pop("fmin", 0)
    fmax = kwargs.pop("fmax", None)
    cmap = kwargs.pop("cmap", "jet")
    vmin = kwargs.pop("vmin", None)
    vmax = kwargs.pop("vmax", None)
    xlim = kwargs.pop("xlim", None)
    ylim = kwargs.pop("ylim", None)
    is_aw = kwargs.pop("Aw", False)
    waveform = kwargs.pop("waveform", {})
    spectral = kwargs.pop("spectral", {"xlim": (vmin, vmax)})

    gs = gridspec.GridSpec(2, 3, height_ratios=[1, 3], width_ratios=[3, 1, 0.1])
    gs.update(wspace=0.2)

    fig = plt.figure(figsize=(12, 6))
    fig.subplots_adjust(wspace=0.0001)

    # First subplot (Time Plot)
    ax_1 = fig.add_subplot(gs[0])
    bf.plot(plot_type="waveform", ax=ax_1, overlay=True)
    ax_1.set(**waveform)
    ax_1.legend().set_visible(False)
    ax_1.set(xlabel="", title="")

    # Second subplot (STFT Plot)
    ax_2 = fig.add_subplot(gs[3], sharex=ax_1)
    stft_ch = bf.stft()
    if is_aw:
        unit = "dBA"
        channel_data = stft_ch.dBA
    else:
        unit = "dB"
        channel_data = stft_ch.dB
    if channel_data.ndim == 3:
        channel_data = channel_data[0]
    # Get the maximum value of the data and round it to a convenient value
    if vmax is None:
        data_max = np.nanmax(channel_data)
        # Round to a convenient number with increments of 10, 5, or 2
        for step in [10, 5, 2]:
            rounded_max = np.ceil(data_max / step) * step
            if rounded_max >= data_max:
                vmax = rounded_max
                vmin = vmax - 180
                break
    times, freqs = _spectrogram_axis_values(stft_ch, channel_data)
    img = ax_2.pcolormesh(times, freqs, channel_data, shading="auto", cmap=cmap, vmin=vmin, vmax=vmax)
    spectrogram_ylim = ylim if ylim is not None else (fmin, fmax) if fmin != 0 or fmax is not None else None
    ax_2.set(xlabel="Time [s]", ylabel="Frequency [Hz]", xlim=xlim, ylim=spectrogram_ylim)

    # Third subplot
    ax_3 = fig.add_subplot(gs[1])
    ax_3.axis("off")

    # Fourth subplot (Welch Plot)
    ax_4 = fig.add_subplot(gs[4], sharey=ax_2)
    welch_ch = bf.welch()
    if is_aw:
        unit = "dBA"
        data_db = welch_ch.dBA
    else:
        unit = "dB"
        data_db = welch_ch.dB
    ax_4.plot(data_db.T, welch_ch.freqs.T)
    ax_4.grid(True)
    ax_4.set(xlabel=f"Spectrum level [{unit}]", **spectral)

    cbar = fig.colorbar(img, ax=ax_4, format="%+2.0f")
    cbar.set_label(unit)
    fig.suptitle(title or bf.label or "Channel Data")

    return _return_axes_iterator(fig.axes)

MatrixPlotStrategy

Bases: PlotStrategy['SpectralFrame']

Strategy for displaying relationships between channels in matrix format

Source code in wandas/visualization/plotting.py

class MatrixPlotStrategy(PlotStrategy["SpectralFrame"]):
    """Strategy for displaying relationships between channels in matrix format"""

    name = "matrix"

    def channel_plot(
        self,
        x: Any,
        y: Any,
        ax: Axes,
        label: PlotLabel = None,
        alpha: float = 1.0,
        **kwargs: Any,
    ) -> None:
        # Work on a local copy to avoid mutating caller-provided kwargs
        plot_kwargs = dict(kwargs)

        # Extract axes settings from kwargs copy
        title = plot_kwargs.pop("title", None)
        ylabel = plot_kwargs.pop("ylabel", None)
        xlabel = plot_kwargs.pop("xlabel", "Frequency [Hz]")

        if label is not None:
            plot_kwargs["label"] = label
        if alpha is not None and alpha != 1.0:
            plot_kwargs["alpha"] = alpha
        ax.plot(x, y, **plot_kwargs)
        ax.grid(True)
        if title is not None:
            ax.set_title(title)
        if ylabel is not None:
            ax.set_ylabel(ylabel)
        ax.set_xlabel(xlabel)
        if label is not None:
            ax.legend()

    def plot(
        self,
        bf: SpectralFrame,
        ax: Axes | None = None,
        title: str | None = None,
        overlay: bool = False,
        **kwargs: Any,
    ) -> Axes | Iterator[Axes]:
        kwargs = kwargs or {}
        plt = _matplotlib_pyplot("matrix plot")
        axes_cls = _matplotlib_axes_type("matrix plot")
        line2d_cls = _matplotlib_line2d_type("matrix plot")
        is_aw = kwargs.pop("Aw", False)
        if len(bf.operation_history) > 0 and bf.operation_history[-1]["operation"] == "coherence":
            unit = ""
            data = bf.magnitude
            ylabel = kwargs.pop("ylabel", "coherence")
        else:
            if is_aw:
                unit = "dBA"
                data = bf.dBA
            else:
                unit = "dB"
                data = bf.dB
            ylabel = kwargs.pop("ylabel", f"Spectrum level [{unit}]")

        data = _reshape_to_2d(data)

        xlabel = kwargs.pop("xlabel", "Frequency [Hz]")
        alpha = kwargs.pop("alpha", 1)
        plot_kwargs = filter_kwargs(line2d_cls, kwargs, strict_mode=True)
        ax_set = filter_kwargs(axes_cls.set, kwargs, strict_mode=True)
        num_channels = bf.n_channels
        # If an Axes is provided, prefer drawing into it (treat as overlay)
        if ax is not None:
            overlay = True
        if overlay:
            if ax is None:
                fig, ax = plt.subplots(1, 1, figsize=(6, 6))
            else:
                fig = ax.figure
            self.channel_plot(
                bf.freqs,
                data.T,
                ax,  # Always Axes type here
                title=title or bf.label or "Spectral Data",
                ylabel=ylabel,
                xlabel=xlabel,
                alpha=alpha,
                **plot_kwargs,
            )
            ax.set(**ax_set)
            if fig is not None:
                fig.suptitle(title or bf.label or "Spectral Data")
            if ax.figure != fig:  # Only show if we created the figure
                plt.tight_layout()
                plt.show()
            return ax
        num_rows = int(np.ceil(np.sqrt(num_channels)))
        fig, axs = plt.subplots(
            num_rows,
            num_rows,
            figsize=(3 * num_rows, 3 * num_rows),
            sharex=True,
            sharey=True,
        )
        if isinstance(axs, np.ndarray):
            axes_list = axs.flatten().tolist()
        elif isinstance(axs, list):
            import itertools

            axes_list = list(itertools.chain.from_iterable(axs))
        else:
            axes_list = [axs]
        for ax_i, channel_data, ch_meta in zip(axes_list, data, bf.channels, strict=False):
            self.channel_plot(
                bf.freqs,
                channel_data,
                ax_i,
                title=ch_meta.label,
                ylabel=ylabel,
                xlabel=xlabel,
                alpha=alpha,
                **plot_kwargs,
            )
            ax_i.set(**ax_set)
        fig.suptitle(title or bf.label or "Spectral Data")
        plt.tight_layout()
        plt.show()
        return _return_axes_iterator(fig.axes)

Attributes

name = 'matrix' class-attribute instance-attribute

Functions

channel_plot(x, y, ax, label=None, alpha=1.0, **kwargs)

Source code in wandas/visualization/plotting.py

def channel_plot(
    self,
    x: Any,
    y: Any,
    ax: Axes,
    label: PlotLabel = None,
    alpha: float = 1.0,
    **kwargs: Any,
) -> None:
    # Work on a local copy to avoid mutating caller-provided kwargs
    plot_kwargs = dict(kwargs)

    # Extract axes settings from kwargs copy
    title = plot_kwargs.pop("title", None)
    ylabel = plot_kwargs.pop("ylabel", None)
    xlabel = plot_kwargs.pop("xlabel", "Frequency [Hz]")

    if label is not None:
        plot_kwargs["label"] = label
    if alpha is not None and alpha != 1.0:
        plot_kwargs["alpha"] = alpha
    ax.plot(x, y, **plot_kwargs)
    ax.grid(True)
    if title is not None:
        ax.set_title(title)
    if ylabel is not None:
        ax.set_ylabel(ylabel)
    ax.set_xlabel(xlabel)
    if label is not None:
        ax.legend()

plot(bf, ax=None, title=None, overlay=False, **kwargs)

Source code in wandas/visualization/plotting.py

def plot(
    self,
    bf: SpectralFrame,
    ax: Axes | None = None,
    title: str | None = None,
    overlay: bool = False,
    **kwargs: Any,
) -> Axes | Iterator[Axes]:
    kwargs = kwargs or {}
    plt = _matplotlib_pyplot("matrix plot")
    axes_cls = _matplotlib_axes_type("matrix plot")
    line2d_cls = _matplotlib_line2d_type("matrix plot")
    is_aw = kwargs.pop("Aw", False)
    if len(bf.operation_history) > 0 and bf.operation_history[-1]["operation"] == "coherence":
        unit = ""
        data = bf.magnitude
        ylabel = kwargs.pop("ylabel", "coherence")
    else:
        if is_aw:
            unit = "dBA"
            data = bf.dBA
        else:
            unit = "dB"
            data = bf.dB
        ylabel = kwargs.pop("ylabel", f"Spectrum level [{unit}]")

    data = _reshape_to_2d(data)

    xlabel = kwargs.pop("xlabel", "Frequency [Hz]")
    alpha = kwargs.pop("alpha", 1)
    plot_kwargs = filter_kwargs(line2d_cls, kwargs, strict_mode=True)
    ax_set = filter_kwargs(axes_cls.set, kwargs, strict_mode=True)
    num_channels = bf.n_channels
    # If an Axes is provided, prefer drawing into it (treat as overlay)
    if ax is not None:
        overlay = True
    if overlay:
        if ax is None:
            fig, ax = plt.subplots(1, 1, figsize=(6, 6))
        else:
            fig = ax.figure
        self.channel_plot(
            bf.freqs,
            data.T,
            ax,  # Always Axes type here
            title=title or bf.label or "Spectral Data",
            ylabel=ylabel,
            xlabel=xlabel,
            alpha=alpha,
            **plot_kwargs,
        )
        ax.set(**ax_set)
        if fig is not None:
            fig.suptitle(title or bf.label or "Spectral Data")
        if ax.figure != fig:  # Only show if we created the figure
            plt.tight_layout()
            plt.show()
        return ax
    num_rows = int(np.ceil(np.sqrt(num_channels)))
    fig, axs = plt.subplots(
        num_rows,
        num_rows,
        figsize=(3 * num_rows, 3 * num_rows),
        sharex=True,
        sharey=True,
    )
    if isinstance(axs, np.ndarray):
        axes_list = axs.flatten().tolist()
    elif isinstance(axs, list):
        import itertools

        axes_list = list(itertools.chain.from_iterable(axs))
    else:
        axes_list = [axs]
    for ax_i, channel_data, ch_meta in zip(axes_list, data, bf.channels, strict=False):
        self.channel_plot(
            bf.freqs,
            channel_data,
            ax_i,
            title=ch_meta.label,
            ylabel=ylabel,
            xlabel=xlabel,
            alpha=alpha,
            **plot_kwargs,
        )
        ax_i.set(**ax_set)
    fig.suptitle(title or bf.label or "Spectral Data")
    plt.tight_layout()
    plt.show()
    return _return_axes_iterator(fig.axes)

Functions

register_plot_strategy(strategy_cls)

Register a new plot strategy from a class

Source code in wandas/visualization/plotting.py

def register_plot_strategy(strategy_cls: type) -> None:
    """Register a new plot strategy from a class"""
    if not issubclass(strategy_cls, PlotStrategy):
        raise TypeError("Strategy class must inherit from PlotStrategy.")
    if inspect.isabstract(strategy_cls):
        raise TypeError("Cannot register abstract PlotStrategy class.")
    _plot_strategies[strategy_cls.name] = strategy_cls

get_plot_strategy(name)

Get plot strategy by name

Source code in wandas/visualization/plotting.py

def get_plot_strategy(name: str) -> type[PlotStrategy[Any]]:
    """Get plot strategy by name"""
    if name not in _plot_strategies:
        raise ValueError(f"Unknown plot type: {name}")
    return _plot_strategies[name]

create_operation(name, **params)

Create operation instance from operation name and parameters

Source code in wandas/visualization/plotting.py

def create_operation(name: str, **params: Any) -> PlotStrategy[Any]:
    """Create operation instance from operation name and parameters"""
    operation_class = get_plot_strategy(name)
    return operation_class(**params)

Describe presentation / Describe 表示

ChannelFrame.describe() is the public entry point. It delegates Figure creation, image saving, and lifecycle handling to wandas.visualization.describe; optional IPython Figure/Audio display is isolated in wandas.visualization.notebook.

ChannelFrame.describe() が公開 entry point です。Figure 作成・画像保存・lifecycle は wandas.visualization.describe、optional IPython Figure/Audio display は wandas.visualization.notebook に分離されています。