Plotting

Utility functions for creating various types of circumplex plots.

create_circumplex_subplots

create_circumplex_subplots(data_list, plot_type=PlotType.DENSITY, incl_scatter=True, subtitles=None, title='Circumplex Subplots', nrows=None, ncols=None, figsize=(10, 10), **kwargs)

Create a figure with subplots containing circumplex plots.

RETURNS	DESCRIPTION
`matplotlib.figure.Figure: A figure containing the subplots.`

Example

>>> import pandas as pd
>>> import numpy as np
>>> np.random.seed(42)
>>> data1 = pd.DataFrame({'ISOPleasant': np.random.uniform(-1, 1, 50),
...                       'ISOEventful': np.random.uniform(-1, 1, 50)})
>>> data2 = pd.DataFrame({'ISOPleasant': np.random.uniform(-1, 1, 50),
...                       'ISOEventful': np.random.uniform(-1, 1, 50)})
>>> fig = create_circumplex_subplots([data1, data2], plot_type=PlotType.SCATTER, nrows=1, ncols=2)
>>> isinstance(fig, plt.Figure)
True

Source code in soundscapy/plotting/plot_functions.py

def create_circumplex_subplots(
    data_list: List[pd.DataFrame],
    plot_type: PlotType | str = PlotType.DENSITY,
    incl_scatter: bool = True,
    subtitles: Optional[List[str]] = None,
    title: str = "Circumplex Subplots",
    nrows: int = None,
    ncols: int = None,
    figsize: Tuple[int, int] = (10, 10),
    **kwargs: Any,
) -> plt.Figure:
    """
    Create a figure with subplots containing circumplex plots.

    Parameters
    ----------
        data_list (List[pd.DataFrame]): List of DataFrames to plot.
        plot_type (PlotType): Type of plot to create.
        incl_scatter (bool): Whether to include scatter points on density plots.
        nrows (int): Number of rows in the subplot grid.
        ncols (int): Number of columns in the subplot grid.
        figsize (tuple): Figure size (width, height) in inches.
        **kwargs: Additional keyword arguments to pass to scatter_plot or density_plot.

    Returns
    -------
        matplotlib.figure.Figure: A figure containing the subplots.

    Example
    -------
        >>> import pandas as pd
        >>> import numpy as np
        >>> np.random.seed(42)
        >>> data1 = pd.DataFrame({'ISOPleasant': np.random.uniform(-1, 1, 50),
        ...                       'ISOEventful': np.random.uniform(-1, 1, 50)})
        >>> data2 = pd.DataFrame({'ISOPleasant': np.random.uniform(-1, 1, 50),
        ...                       'ISOEventful': np.random.uniform(-1, 1, 50)})
        >>> fig = create_circumplex_subplots([data1, data2], plot_type=PlotType.SCATTER, nrows=1, ncols=2)
        >>> isinstance(fig, plt.Figure)
        True
    """
    if isinstance(plot_type, str):
        plot_type = PlotType[plot_type.upper()]

    if nrows is None and ncols is None:
        nrows = 2
        ncols = len(data_list) // nrows
    elif nrows is None:
        nrows = len(data_list) // ncols
    elif ncols is None:
        ncols = len(data_list) // nrows

    if subtitles is None:
        subtitles = [f"({i + 1})" for i in range(len(data_list))]
    elif len(subtitles) != len(data_list):
        raise ValueError("Number of subtitles must match number of dataframes")

    fig, axes = plt.subplots(nrows, ncols, figsize=figsize)
    axes = axes.flatten() if isinstance(axes, np.ndarray) else [axes]

    color = kwargs.get("color", sns.color_palette("colorblind", 1)[0])

    for data, ax, subtitle in zip(data_list, axes, subtitles):
        if plot_type == PlotType.SCATTER or incl_scatter:
            scatter_plot(data, title=subtitle, ax=ax, color=color, **kwargs)
        if plot_type == PlotType.DENSITY:
            density_plot(data, title=subtitle, ax=ax, color=color, **kwargs)
        elif plot_type == PlotType.SIMPLE_DENSITY:
            density_plot(
                data, title=subtitle, simple_density=True, ax=ax, color=color, **kwargs
            )

    plt.suptitle(title)

    plt.tight_layout()
    return fig

density_plot

density_plot(data, x='ISOPleasant', y='ISOEventful', hue=None, title='Soundscape Density Plot', xlim=DEFAULT_XLIM, ylim=DEFAULT_YLIM, palette='colorblind', fill=True, incl_outline=False, incl_scatter=True, diagonal_lines=False, show_labels=True, legend=True, legend_location='best', backend=Backend.SEABORN, apply_styling=True, figsize=DEFAULT_FIGSIZE, simple_density=False, simple_density_thresh=0.5, simple_density_levels=2, simple_density_alpha=0.5, ax=None, extra_params={}, **kwargs)

Create a density plot using the CircumplexPlot class.

RETURNS	DESCRIPTION
`plt.Axes \| go.Figure: The resulting plot object.`

Source code in soundscapy/plotting/plot_functions.py

def density_plot(
    data: pd.DataFrame,
    x: str = "ISOPleasant",
    y: str = "ISOEventful",
    hue: Optional[str] = None,
    title: str = "Soundscape Density Plot",
    xlim: Tuple[float, float] = DEFAULT_XLIM,
    ylim: Tuple[float, float] = DEFAULT_YLIM,
    palette: str = "colorblind",
    fill: bool = True,
    incl_outline: bool = False,
    incl_scatter: bool = True,
    diagonal_lines: bool = False,
    show_labels: bool = True,
    legend=True,
    legend_location: str = "best",
    backend: Backend = Backend.SEABORN,
    apply_styling: bool = True,
    figsize: Tuple[int, int] = DEFAULT_FIGSIZE,
    simple_density: bool = False,
    simple_density_thresh: float = 0.5,
    simple_density_levels: int = 2,
    simple_density_alpha: float = 0.5,
    ax: Optional[plt.Axes] = None,
    extra_params: ExtraParams = {},
    **kwargs: Any,
) -> plt.Axes | go.Figure:
    """
    Create a density plot using the CircumplexPlot class.

    Parameters
    ----------
        data (pd.DataFrame): The data to plot.
        x (str): Column name for x-axis data.
        y (str): Column name for y-axis data.
        hue (Optional[str]): Column name for color-coding data points.
        title (str): Title of the plot.
        xlim (Tuple[float, float]): x-axis limits.
        ylim (Tuple[float, float]): y-axis limits.
        palette (str): Color palette to use.
        fill (bool): Whether to fill the density contours.
        incl_outline (bool): Whether to include an outline for the density contours.
        diagonal_lines (bool): Whether to draw diagonal lines.
        show_labels (bool): Whether to show axis labels.
        legend (bool): Whether to show the legend.
        legend_location (str): Location of the legend.
        backend (Backend): The plotting backend to use.
        apply_styling (bool): Whether to apply circumplex-specific styling.
        figsize (Tuple[int, int]): Size of the figure.
        simple_density (bool): Whether to use simple density plot (Seaborn only).
        simple_density_thresh (float): Threshold for simple density plot.
        simple_density_levels (int): Number of levels for simple density plot.
        simple_density_alpha (float): Alpha value for simple density plot.
        ax (Optional[plt.Axes]): A matplotlib Axes object to plot on.
        extra_params (ExtraParams): Additional parameters for backend-specific functions.
        **kwargs: Additional keyword arguments to pass to the backend.

    Returns
    -------
        plt.Axes | go.Figure: The resulting plot object.

    """
    params = CircumplexPlotParams(
        x=x,
        y=y,
        hue=hue,
        title=title,
        xlim=xlim,
        ylim=ylim,
        palette=palette if hue else None,
        fill=fill,
        incl_outline=incl_outline,
        diagonal_lines=diagonal_lines,
        show_labels=show_labels,
        legend=legend,
        legend_location=legend_location,
        extra_params={**extra_params, **kwargs},
    )

    style_options = StyleOptions(
        figsize=figsize,
        simple_density=dict(
            thresh=simple_density_thresh,
            levels=simple_density_levels,
            alpha=simple_density_alpha,
        )
        if simple_density
        else None,
    )

    plot = CircumplexPlot(data, params, backend, style_options)

    if incl_scatter and backend == Backend.SEABORN:
        plot.scatter(apply_styling=True, ax=ax)
        ax = plot.get_axes()
    elif incl_scatter and backend == Backend.PLOTLY:
        # TODO: Implement overlaying scatter on density plot for Plotly backend
        raise NotImplementedError(
            "Overlaying a scatter on a density plot is not yet supported for Plotly backend. "
            "Please change to Seaborn backend or use `incl_scatter=False`."
        )

    if simple_density:
        plot.simple_density(apply_styling=apply_styling, ax=ax)
    else:
        plot.density(apply_styling=apply_styling, ax=ax)

    if isinstance(plot._backend, SeabornBackend):
        return plot.get_axes()
    else:
        return plot.get_figure()

scatter_plot

scatter_plot(data, x='ISOPleasant', y='ISOEventful', hue=None, title='Soundscape Scatter Plot', xlim=DEFAULT_XLIM, ylim=DEFAULT_YLIM, palette='colorblind', diagonal_lines=False, show_labels=True, legend=True, legend_location='best', backend=Backend.SEABORN, apply_styling=True, figsize=DEFAULT_FIGSIZE, ax=None, extra_params={}, **kwargs)

Create a scatter plot using the CircumplexPlot class.

RETURNS	DESCRIPTION
`plt.Axes \| go.Figure: The resulting plot object.`

Source code in soundscapy/plotting/plot_functions.py

def scatter_plot(
    data: pd.DataFrame,
    x: str = "ISOPleasant",
    y: str = "ISOEventful",
    hue: Optional[str] = None,
    title: str = "Soundscape Scatter Plot",
    xlim: Tuple[float, float] = DEFAULT_XLIM,
    ylim: Tuple[float, float] = DEFAULT_YLIM,
    palette: str = "colorblind",
    diagonal_lines: bool = False,
    show_labels: bool = True,
    legend=True,
    legend_location: str = "best",
    backend: Backend = Backend.SEABORN,
    apply_styling: bool = True,
    figsize: Tuple[int, int] = DEFAULT_FIGSIZE,
    ax: Optional[plt.Axes] = None,
    extra_params: ExtraParams = {},
    **kwargs: Any,
) -> plt.Axes | go.Figure:
    """
    Create a scatter plot using the CircumplexPlot class.

    Parameters
    ----------
        data (pd.DataFrame): The data to plot.
        x (str): Column name for x-axis data.
        y (str): Column name for y-axis data.
        hue (Optional[str]): Column name for color-coding data points.
        title (str): Title of the plot.
        xlim (Tuple[float, float]): x-axis limits.
        ylim (Tuple[float, float]): y-axis limits.
        palette (str): Color palette to use.
        diagonal_lines (bool): Whether to draw diagonal lines.
        show_labels (bool): Whether to show axis labels.
        legend (bool): Whether to show the legend.
        legend_location (str): Location of the legend.
        backend (Backend): The plotting backend to use.
        apply_styling (bool): Whether to apply circumplex-specific styling.
        figsize (Tuple[int, int]): Size of the figure.
        ax (Optional[plt.Axes]): A matplotlib Axes object to plot on.
        extra_params (ExtraParams): Additional parameters for backend-specific functions.
        **kwargs: Additional keyword arguments to pass to the backend.

    Returns
    -------
        plt.Axes | go.Figure: The resulting plot object.

    """
    params = CircumplexPlotParams(
        x=x,
        y=y,
        hue=hue,
        title=title,
        xlim=xlim,
        ylim=ylim,
        palette=palette if hue else None,
        diagonal_lines=diagonal_lines,
        show_labels=show_labels,
        legend=legend,
        legend_location=legend_location,
        extra_params={**extra_params, **kwargs},
    )

    style_options = StyleOptions(figsize=figsize)

    plot = CircumplexPlot(data, params, backend, style_options)
    plot.scatter(apply_styling=apply_styling, ax=ax)

    if isinstance(plot._backend, SeabornBackend):
        return plot.get_axes()
    else:
        return plot.get_figure()

Circumplex Plotting

Main module for creating circumplex plots using different backends.

CircumplexPlot

CircumplexPlot(data, params=CircumplexPlotParams(), backend=Backend.SEABORN, style_options=StyleOptions())

A class for creating circumplex plots using different backends.

This class provides methods for creating scatter plots and density plots based on the circumplex model of soundscape perception. It supports multiple backends (currently Seaborn and Plotly) and offers various customization options.

Source code in soundscapy/plotting/circumplex_plot.py

def __init__(
    self,
    data: pd.DataFrame,
    params: CircumplexPlotParams = CircumplexPlotParams(),
    backend: Backend = Backend.SEABORN,
    style_options: StyleOptions = StyleOptions(),
):
    self.data = data
    self.params = params
    self.style_options = style_options
    self._backend = self._create_backend(backend)
    self._plot = None

density

density(apply_styling=True, ax=None)

Create a density plot.

Source code in soundscapy/plotting/circumplex_plot.py

def density(
    self, apply_styling: bool = True, ax: Optional[plt.Axes] = None
) -> "CircumplexPlot":
    """Create a density plot."""
    return self._create_plot(PlotType.DENSITY, apply_styling, ax)

get_axes

get_axes()

Get the axes object of the plot (only for Seaborn backend).

Source code in soundscapy/plotting/circumplex_plot.py

def get_axes(self):
    """Get the axes object of the plot (only for Seaborn backend)."""
    if self._plot is None:
        raise ValueError(
            "No plot has been created yet. Call scatter(), density(), or simple_density() first."
        )
    if isinstance(self._backend, SeabornBackend):
        return self._plot[1]  # Return the axes object
    else:
        raise AttributeError("Axes object is not available for Plotly backend")

get_figure

get_figure()

Get the figure object of the plot.

Source code in soundscapy/plotting/circumplex_plot.py

def get_figure(self):
    """Get the figure object of the plot."""
    if self._plot is None:
        raise ValueError(
            "No plot has been created yet. Call scatter(), density(), or simple_density() first."
        )
    return self._plot

get_style_options

get_style_options()

Get the current StyleOptions.

Source code in soundscapy/plotting/circumplex_plot.py

def get_style_options(self) -> StyleOptions:
    """Get the current StyleOptions."""
    return copy.deepcopy(self.style_options)

iso_annotation

iso_annotation(location, x_adj=0, y_adj=0, **kwargs)

Add an annotation to the plot (only for Seaborn backend).

Source code in soundscapy/plotting/circumplex_plot.py

def iso_annotation(self, location, x_adj: float = 0, y_adj: float = 0, **kwargs):
    """Add an annotation to the plot (only for Seaborn backend)."""
    if isinstance(self._backend, SeabornBackend):
        ax = self.get_axes()
        x = self.data[self.params.x].iloc[location]
        y = self.data[self.params.y].iloc[location]
        ax.annotate(
            text=self.data.index[location],
            xy=(x, y),
            xytext=(x + x_adj, y + y_adj),
            ha="center",
            va="center",
            arrowprops=dict(arrowstyle="-", ec="black"),
            **kwargs,
        )
    else:
        raise AttributeError("iso_annotation is not available for Plotly backend")
    return self

scatter

scatter(apply_styling=True, ax=None)

Create a scatter plot.

Source code in soundscapy/plotting/circumplex_plot.py

def scatter(
    self, apply_styling: bool = True, ax: Optional[plt.Axes] = None
) -> "CircumplexPlot":
    """Create a scatter plot."""
    return self._create_plot(PlotType.SCATTER, apply_styling, ax)

show

show()

Display the plot.

Source code in soundscapy/plotting/circumplex_plot.py

def show(self):
    """Display the plot."""
    if self._plot is None:
        raise ValueError(
            "No plot has been created yet. Call scatter(), density(), or simple_density() first."
        )
    self._backend.show(self._plot)

simple_density

simple_density(apply_styling=True, ax=None)

Create a simple density plot.

Source code in soundscapy/plotting/circumplex_plot.py

def simple_density(
    self, apply_styling: bool = True, ax: Optional[plt.Axes] = None
) -> "CircumplexPlot":
    """Create a simple density plot."""
    return self._create_plot(PlotType.SIMPLE_DENSITY, apply_styling, ax)

update_style_options

update_style_options(**kwargs)

Update the StyleOptions with new values.

Source code in soundscapy/plotting/circumplex_plot.py

def update_style_options(self, **kwargs) -> "CircumplexPlot":
    """Update the StyleOptions with new values."""
    new_style_options = copy.deepcopy(self.style_options)
    for key, value in kwargs.items():
        if hasattr(new_style_options, key):
            setattr(new_style_options, key, value)
        else:
            raise ValueError(f"Invalid StyleOptions attribute: {key}")

    self.style_options = new_style_options
    self._backend.style_options = new_style_options
    return self

CircumplexPlotParams `dataclass`

CircumplexPlotParams(x='ISOPleasant', y='ISOEventful', hue=None, title='Soundscape Plot', xlim=DEFAULT_XLIM, ylim=DEFAULT_YLIM, alpha=0.8, fill=True, palette=None, incl_outline=False, diagonal_lines=False, show_labels=True, legend='auto', legend_location='best', extra_params=dict())

Parameters for customizing CircumplexPlot.

Backends

PlotBackend

Bases: ABC

Abstract base class for plot backends.

This class defines the interface for creating scatter and density plots, as well as applying styling to the plots.