Plotting Functions

Plotting functions for visualizing circumplex data.

FUNCTION	DESCRIPTION
allocate_subplot_axes	Allocate the subplot axes based on the number of data subsets.
create_circumplex_subplots	Create a figure with subplots containing circumplex plots.
create_iso_subplots	Create a set of subplots displaying data visualizations for soundscape analysis.
density	Plot a density plot of ISOCoordinates.
density_plot	Wrapper for the density function to maintain backwards compatibility.
iso_annotation	Add text annotations to circumplex plot based on coordinate values.
iso_plot	Plot a soundscape visualization based on the specified metrics using different
jointplot	Create a jointplot with a central distribution and marginal plots.
scatter	Plot ISOcoordinates as scatter points on a soundscape circumplex grid.
scatter_plot	Wrapper for the scatter function to maintain backwards compatibility.

allocate_subplot_axes

allocate_subplot_axes(nrows, ncols, n_subplots)

Allocate the subplot axes based on the number of data subsets.

PARAMETER	DESCRIPTION
nrows	Number of rows for subplots. Can be None to auto-determine. TYPE: int | None
ncols	Number of columns for subplots. Can be None to auto-determine. TYPE: int | None
n_subplots	Total number of subplots needed. TYPE: int

RETURNS	DESCRIPTION
tuple[int, int]	The number of rows and columns for the subplot grid.

Notes

Logic for determining subplot layout: - If both nrows and ncols are specified, use those values - If both are None, calculate a grid as close to square as possible - If only one is specified, calculate the other to fit all subplots

Source code in soundscapy/plotting/plot_functions.py

def allocate_subplot_axes(
    nrows: int | None, ncols: int | None, n_subplots: int
) -> tuple[int, int, int]:
    """
    Allocate the subplot axes based on the number of data subsets.

    Parameters
    ----------
    nrows : int | None
        Number of rows for subplots. Can be None to auto-determine.
    ncols : int | None
        Number of columns for subplots. Can be None to auto-determine.
    n_subplots : int
        Total number of subplots needed.

    Returns
    -------
    tuple[int, int]
        The number of rows and columns for the subplot grid.

    Notes
    -----
    Logic for determining subplot layout:
    - If both nrows and ncols are specified, use those values
    - If both are None, calculate a grid as close to square as possible
    - If only one is specified, calculate the other to fit all subplots

    """
    # If both dimensions are specified, return them as is
    if nrows is not None and ncols is not None:
        return nrows, ncols, n_subplots

    # If both dimensions are None, create a grid as close to square as possible
    if nrows is None and ncols is None:
        ncols = int(np.ceil(np.sqrt(n_subplots)))
        nrows = int(np.ceil(n_subplots / ncols))
    # If only one dimension is specified, calculate the other
    elif nrows is not None and ncols is None:
        ncols = int(np.ceil(n_subplots / nrows))
    elif nrows is None and ncols is not None:
        nrows = int(np.ceil(n_subplots / ncols))
    else:
        msg = (
            "We should never reach this point - both nrows and ncols are None, "
            "but were missed in earlier check."
        )
        raise ValueError(msg)

    n_subplots = nrows * ncols

    return nrows, ncols, n_subplots

create_circumplex_subplots

create_circumplex_subplots(data_list, plot_type='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.

.. deprecated:: 0.8.0 Use :func:create_iso_subplots instead.

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

Example

>>> import pandas as pd
>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> 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="scatter", nrows=1, ncols=2
... )
>>> plt.show() # xdoctest: +SKIP
>>> isinstance(fig, plt.Figure)
True
>>> plt.close('all')

Source code in soundscapy/plotting/plot_functions.py

def create_circumplex_subplots(
    data_list: list[pd.DataFrame],
    plot_type: Literal["density", "scatter", "simple_density"] = "density",
    incl_scatter: bool = True,  # noqa: FBT001, FBT002
    subtitles: list[str] | None = None,
    title: str = "Circumplex Subplots",
    nrows: int | None = None,
    ncols: int | None = None,
    figsize: tuple[int, int] = (10, 10),
    **kwargs: Any,
) -> Figure:
    """
    Create a figure with subplots containing circumplex plots.

    .. deprecated:: 0.8.0
       Use :func:`create_iso_subplots` instead.

    Parameters
    ----------
        data_list : List of DataFrames to plot.
        plot_type : Type of plot to create.
        incl_scatter : Whether to include scatter points on density plots.
        subtitles : List of subtitles for each subplot.
        title : Title for the entire figure.
        nrows : Number of rows in the subplot grid.
        ncols : Number of columns in the subplot grid.
        figsize : 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
        >>> import matplotlib.pyplot as plt
        >>> 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="scatter", nrows=1, ncols=2
        ... )
        >>> plt.show() # xdoctest: +SKIP
        >>> isinstance(fig, plt.Figure)
        True
        >>> plt.close('all')

    """
    warnings.warn(
        "The `create_circumplex_subplots` function is deprecated and will be removed "
        "in a future version. Use `create_iso_subplots` instead.",
        DeprecationWarning,
        stacklevel=2,
    )

    # Map plot_type to plot_layers
    if plot_type == "scatter":
        plot_layers = ["scatter"]
    elif plot_type == "density":
        plot_layers = ["density"]
        if incl_scatter:
            plot_layers.insert(0, "scatter")
    elif plot_type == "simple_density":
        plot_layers = ["simple_density"]
        if incl_scatter:
            plot_layers.insert(0, "scatter")
    else:
        warnings.warn(
            "Can't recognize plot type. Using default 'density' plot type with scatter.",
            UserWarning,
            stacklevel=2,
        )
        plot_layers = ["scatter", "density"]

    # Map subtitles to subplot_titles
    subplot_titles = subtitles

    # Call create_iso_subplots with translated parameters
    fig, _ = create_iso_subplots(
        data=data_list,
        subplot_titles=subplot_titles,
        title=title,
        nrows=nrows,
        ncols=ncols,
        figsize=figsize,
        plot_layers=plot_layers,  # type: ignore[arg-type]
        **kwargs,
    )

    return fig

create_iso_subplots

create_iso_subplots(data, x='ISOPleasant', y='ISOEventful', subplot_by=None, title='Soundscapy Plot', plot_layers=('scatter', 'density'), *, subplot_size=(4, 4), subplot_titles='by_group', subplot_title_prefix='Plot', nrows=None, ncols=None, **kwargs)

Create a set of subplots displaying data visualizations for soundscape analysis.

This function generates a collection of subplots, where each subplot corresponds to a subset of the input data. The subplots can display scatter plots, density plots, or simplified density plots, and can be organized by specific grouping criteria. Users can specify titles, overall size, row and column layout, and layering of plot types.

PARAMETER	DESCRIPTION
data	Input data to be visualized. Can be a single data frame or a list of data frames for use in multiple subplots. TYPE: pandas.DataFrame or list of pandas.DataFrame
x	The name of the column in the data to be used for the x-axis. Default is "ISOPleasant". TYPE: str DEFAULT: 'ISOPleasant'
y	The name of the column in the data to be used for the y-axis. Default is "ISOEventful". TYPE: str DEFAULT: 'ISOEventful'
subplot_by	The column name by which to group data into subplots. If None, data is not grouped and plotted in a single set of axes. Default is None. TYPE: str or None DEFAULT: None
title	The overarching title of the figure. If None, no overall title is added. Default is "Soundscapy Plot". TYPE: str or None DEFAULT: 'Soundscapy Plot'
plot_layers	such Literals, optional Type(s) of plot layers to include in each subplot. Can be a single type or a sequence of types. Default is ("scatter", "density"). TYPE: Literal["scatter", "density", "simple_density"] or Sequence of DEFAULT: ('scatter', 'density')
subplot_size	Size of each subplot in inches as (width, height). Default is (4, 4). TYPE: tuple of int DEFAULT: (4, 4)
subplot_titles	optional Determines how subplot titles are assigned. Options are "by_group" (titles derived from group names), "numbered" (titles as indices), or a list of custom titles. If None, no titles are added. Default is "by_group". TYPE: Literal["by_group", "numbered"], list of str, or None, DEFAULT: 'by_group'
subplot_title_prefix	Prefix for subplot titles if "numbered" is selected as subplot_titles. Default is "Plot". TYPE: str DEFAULT: 'Plot'
nrows	Number of rows for the subplot grid. If None, automatically calculated based on the number of subplots. Default is None. TYPE: int or None DEFAULT: None
ncols	Number of columns for the subplot grid. If None, automatically calculated based on the number of subplots. Default is None. TYPE: int or None DEFAULT: None
**kwargs	Additional keyword arguments to pass to matplotlib's plt.subplots or for customizing the figure and subplots. DEFAULT: {}

RETURNS	DESCRIPTION
tuple	A tuple containing: - fig : matplotlib.figure.Figure The created matplotlib figure object containing the subplots. - np.ndarray An array of matplotlib.axes.Axes objects corresponding to the subplots.

Examples:

Basic subplots with default settings:

>>> import soundscapy as sspy
>>> import matplotlib.pyplot as plt
>>> import pandas as pd
>>> data = sspy.isd.load()
>>> data = sspy.add_iso_coords(data)
>>> four_locs = sspy.isd.select_location_ids(data,
...     ['CamdenTown', 'PancrasLock', 'RegentsParkJapan', 'RegentsParkFields']
... )
>>> fig, axes = sspy.create_iso_subplots(four_locs, subplot_by="LocationID")
>>> plt.show() # xdoctest: +SKIP

Create subplots by specifying a list of data

>>> 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, axes = create_iso_subplots(
...     [data1, data2], plot_layers="scatter", nrows=1, ncols=2
... )
>>> plt.show() # xdoctest: +SKIP
>>> assert len(axes) == 2
>>> plt.close('all')

Source code in soundscapy/plotting/plot_functions.py

def create_iso_subplots(
    data: pd.DataFrame | list[pd.DataFrame],
    x: str = "ISOPleasant",
    y: str = "ISOEventful",
    subplot_by: str | None = None,
    title: str | None = "Soundscapy Plot",
    plot_layers: Literal["scatter", "density", "simple_density"]
    | Sequence[Literal["scatter", "simple_density", "density"]] = (
        "scatter",
        "density",
    ),
    *,
    subplot_size: tuple[int, int] = (4, 4),
    subplot_titles: Literal["by_group", "numbered"] | list[str] | None = "by_group",
    subplot_title_prefix: str = "Plot",  # Only used if subplot_titles = 'numbered'
    nrows: int | None = None,
    ncols: int | None = None,
    **kwargs,
) -> tuple[Figure, np.ndarray]:
    """
    Create a set of subplots displaying data visualizations for soundscape analysis.

    This function generates a collection of subplots, where each subplot corresponds
    to a subset of the input data. The subplots can display scatter plots, density
    plots, or simplified density plots, and can be organized by specific grouping
    criteria. Users can specify titles, overall size, row and column layout, and
    layering of plot types.

    Parameters
    ----------
    data : pandas.DataFrame or list of pandas.DataFrame
        Input data to be visualized. Can be a single data frame or a list of data
        frames for use in multiple subplots.
    x : str, optional
        The name of the column in the data to be used for the x-axis. Default is
        "ISOPleasant".
    y : str, optional
        The name of the column in the data to be used for the y-axis. Default is
        "ISOEventful".
    subplot_by : str or None, optional
        The column name by which to group data into subplots. If None, data is not
        grouped and plotted in a single set of axes. Default is None.
    title : str or None, optional
        The overarching title of the figure. If None, no overall title is added.
        Default is "Soundscapy Plot".
    plot_layers : Literal["scatter", "density", "simple_density"] or Sequence of
        such Literals, optional
        Type(s) of plot layers to include in each subplot. Can be a single type
        or a sequence of types. Default is ("scatter", "density").
    subplot_size : tuple of int, optional
        Size of each subplot in inches as (width, height). Default is (4, 4).
    subplot_titles : Literal["by_group", "numbered"], list of str, or None,
        optional
        Determines how subplot titles are assigned. Options are "by_group" (titles
        derived from group names), "numbered" (titles as indices), or a list of
        custom titles. If None, no titles are added. Default is "by_group".
    subplot_title_prefix : str, optional
        Prefix for subplot titles if "numbered" is selected as `subplot_titles`.
        Default is "Plot".
    nrows : int or None, optional
        Number of rows for the subplot grid. If None, automatically calculated
        based on the number of subplots. Default is None.
    ncols : int or None, optional
        Number of columns for the subplot grid. If None, automatically calculated
        based on the number of subplots. Default is None.
    **kwargs
        Additional keyword arguments to pass to matplotlib's `plt.subplots` or for
        customizing the figure and subplots.

    Returns
    -------
    tuple
        A tuple containing:
        - fig : matplotlib.figure.Figure
            The created matplotlib figure object containing the subplots.
        - np.ndarray
            An array of matplotlib.axes.Axes objects corresponding to the subplots.

    Examples
    --------
    Basic subplots with default settings:
    >>> import soundscapy as sspy
    >>> import matplotlib.pyplot as plt
    >>> import pandas as pd
    >>> data = sspy.isd.load()
    >>> data = sspy.add_iso_coords(data)
    >>> four_locs = sspy.isd.select_location_ids(data,
    ...     ['CamdenTown', 'PancrasLock', 'RegentsParkJapan', 'RegentsParkFields']
    ... )
    >>> fig, axes = sspy.create_iso_subplots(four_locs, subplot_by="LocationID")
    >>> plt.show() # xdoctest: +SKIP

    Create subplots by specifying a list of data
    >>> 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, axes = create_iso_subplots(
    ...     [data1, data2], plot_layers="scatter", nrows=1, ncols=2
    ... )
    >>> plt.show() # xdoctest: +SKIP
    >>> assert len(axes) == 2
    >>> plt.close('all')

    """
    # Process input data and prepare for subplot creation
    data_list, subplot_titles_list, n_subplots = _prepare_subplot_data(
        data=data, x=y, y=y, subplot_by=subplot_by, subplot_titles=subplot_titles
    )

    # Calculate subplot layout
    nrows, ncols, n_subplots = allocate_subplot_axes(nrows, ncols, n_subplots)

    # Set up figure and subplots
    if title:
        vert_adjust = 1.2
    else:
        vert_adjust = 1.0
    figsize = kwargs.pop(
        "figsize", (ncols * subplot_size[0], nrows * (vert_adjust * subplot_size[1]))
    )

    subplots_params = SubplotsParams()
    subplots_params.update(
        nrows=nrows,
        ncols=ncols,
        figsize=figsize,
        subplot_by=subplot_by,
        extra="ignore",
        **kwargs,
    )

    fig, axes = plt.subplots(**subplots_params.as_plt_subplots_args())

    # Create each subplot
    _create_subplots(
        data_list,
        axes,
        n_subplots,
        subplot_titles_list,
        x,
        y,
        plot_layers,
        subplot_title_prefix,
        **kwargs,
    )

    # Add overall title and adjust layout
    if title:
        fig.suptitle(title, fontsize=DEFAULT_STYLE_PARAMS["title_fontsize"])

    fig.tight_layout()

    return fig, axes

density

density(data, title='Soundscape Density Plot', ax=None, *, x='ISOPleasant', y='ISOEventful', hue=None, incl_scatter=True, density_type='full', palette='colorblind', scatter_kws=None, legend='auto', prim_labels=None, **kwargs)

Plot a density plot of ISOCoordinates.

Creates a kernel density estimate visualization of data distribution on a circumplex grid with the custom Soundscapy styling for soundscape circumplex visualisations. Can optionally include a scatter plot of the underlying data points.

PARAMETER	DESCRIPTION
data	Input data structure containing coordinate data, typically with ISOPleasant and ISOEventful columns. TYPE: DataFrame
title	Title to add to circumplex plot, by default "Soundscape Density Plot" TYPE: str | None DEFAULT: 'Soundscape Density Plot'
ax	Pre-existing axes object to use for the plot, by default None If None call matplotlib.pyplot.subplots with figsize internally. TYPE: Axes DEFAULT: None
x	Column name for x variable, by default "ISOPleasant" TYPE: str DEFAULT: 'ISOPleasant'
y	Column name for y variable, by default "ISOEventful" TYPE: str DEFAULT: 'ISOEventful'
hue	Grouping variable that will produce density contours with different colors. Can be either categorical or numeric, although color mapping will behave differently in latter case, by default None TYPE: str | ndarray | Series | None DEFAULT: None
incl_scatter	Whether to include a scatter plot of the data points, by default True TYPE: bool DEFAULT: True
density_type	Type of density plot to draw. "full" uses default parameters, "simple" uses a lower number of levels (2), higher threshold (0.5), and lower alpha (0.5) for a cleaner visualization, by default "full" TYPE: (full, simple) DEFAULT: "full"
palette	Method for choosing the colors to use when mapping the hue semantic. String values are passed to seaborn.color_palette(). List or dict values imply categorical mapping, while a colormap object implies numeric mapping, by default "colorblind" TYPE: SeabornPaletteType | None DEFAULT: 'colorblind'
scatter_kws	Keyword arguments to pass to seaborn.scatterplot if incl_scatter is True, by default {"s": 25, "linewidth": 0} TYPE: dict | None DEFAULT: None
incl_outline	Whether to include an outline for the density contours, by default False TYPE: bool
legend	How to draw the legend. If "brief", numeric hue variables will be represented with a sample of evenly spaced values. If "full", every group will get an entry in the legend. If "auto", choose between brief or full representation based on number of levels. If False, no legend data is added and no legend is drawn, by default "auto" TYPE: (auto, brief, full, False) DEFAULT: "auto"
prim_labels	Deprecated. Use xlabel and ylabel parameters instead. TYPE: bool | None DEFAULT: None
**kwargs	Additional styling parameters: alpha : float, optional Proportional opacity of the density fill, by default 0.8 fill : bool, optional If True, fill in the area between bivariate contours, by default True levels : int | Iterable[float], optional Number of contour levels or values to draw contours at, by default 10 thresh : float, optional Lowest iso-proportional level at which to draw a contour line, by default 0.05 bw_adjust : float, optional Factor that multiplicatively scales the bandwidth, by default 1.2 xlabel, ylabel : str | Literal[False], optional Custom axis labels. By default, "\(P_{ISO}\)" and "\(E_{ISO}\)" with math rendering. If None is passed, the column names (x and y) will be used as labels. If a string is provided, it will be used as the label. If False is passed, axis labels will be hidden. xlim, ylim : tuple[float, float], optional Limits for x and y axes, by default (-1, 1) for both legend_loc : MplLegendLocType, optional Location of legend, by default "best" diagonal_lines : bool, optional Whether to include diagonal dimension labels (e.g. calm, etc.), by default False figsize : tuple[int, int], optional Size of the figure to return if ax is None, by default (5, 5) prim_ax_fontdict : dict, optional Font dictionary for axis labels with these defaults: { "family": "sans-serif", "fontstyle": "normal", "fontsize": "large", "fontweight": "medium", "parse_math": True, "c": "black", "alpha": 1, } - fontsize, fontweight, fontstyle, family, c, alpha, parse_math: Direct parameters for font styling in axis labels Also accepts additional keyword arguments for matplotlib's contour and contourf functions. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
Axes object containing the plot.

Notes

This function will raise a warning if the dataset has fewer than RECOMMENDED_MIN_SAMPLES (30) data points, as density plots are not reliable with small sample sizes.

Examples:

Basic density plot with default settings:

>>> import soundscapy as sspy
>>> import matplotlib.pyplot as plt
>>> data = sspy.isd.load()
>>> data = sspy.add_iso_coords(data)
>>> ax = sspy.density(data)
>>> plt.show() # xdoctest: +SKIP

Simple density plot with fewer contour levels:

>>> ax = sspy.density(data, density_type="simple")
>>> plt.show() # xdoctest: +SKIP

Density plot with custom styling:

>>> sub_data = sspy.isd.select_location_ids(
...    data, ['CamdenTown', 'PancrasLock', 'RegentsParkJapan', 'RegentsParkFields'])
>>> ax = sspy.density(
...     sub_data,
...     hue="SessionID",
...     incl_scatter=True,
...     legend_loc="upper right",
...     fill = False,
...     density_type = "simple",
... )
>>> plt.show() # xdoctest: +SKIP

Add density to existing plots:

>>> fig, axes = plt.subplots(1, 2, figsize=(12, 6))
>>> axes[0] = sspy.density(
...     sspy.isd.select_location_ids(data, ['CamdenTown', 'PancrasLock']),
...     ax=axes[0], title="CamdenTown and PancrasLock", hue="LocationID",
...     density_type="simple"
... )
>>> axes[1] = sspy.density(
...     sspy.isd.select_location_ids(data, ['RegentsParkJapan']),
...     ax=axes[1], title="RegentsParkJapan"
... )
>>> plt.tight_layout()
>>> plt.show() # xdoctest: +SKIP
>>> plt.close('all')

Source code in soundscapy/plotting/plot_functions.py

def density(
    data: pd.DataFrame,
    title: str | None = "Soundscape Density Plot",
    ax: Axes | None = None,
    *,
    x: str | None = "ISOPleasant",
    y: str | None = "ISOEventful",
    hue: str | None = None,
    incl_scatter: bool = True,
    density_type: str = "full",
    palette: SeabornPaletteType | None = "colorblind",
    scatter_kws: dict | None = None,
    legend: Literal["auto", "brief", "full", False] = "auto",
    prim_labels: bool | None = None,  # Alias for primary_labels, deprecated
    **kwargs,
) -> Axes:
    """
    Plot a density plot of ISOCoordinates.

    Creates a kernel density estimate visualization of data distribution on a
    circumplex grid with the custom Soundscapy styling for soundscape circumplex
    visualisations. Can optionally include a scatter plot of the underlying data points.

    Parameters
    ----------
    data : pd.DataFrame
        Input data structure containing coordinate data, typically with ISOPleasant
        and ISOEventful columns.
    title : str | None, optional
        Title to add to circumplex plot, by default "Soundscape Density Plot"
    ax : matplotlib.axes.Axes, optional
        Pre-existing axes object to use for the plot, by default None
        If `None` call `matplotlib.pyplot.subplots` with `figsize` internally.
    x : str, optional
        Column name for x variable, by default "ISOPleasant"
    y : str, optional
        Column name for y variable, by default "ISOEventful"
    hue : str | np.ndarray | pd.Series | None, optional
        Grouping variable that will produce density contours with different colors.
        Can be either categorical or numeric, although color mapping will behave
        differently in latter case, by default None
    incl_scatter : bool, optional
        Whether to include a scatter plot of the data points, by default True
    density_type : {"full", "simple"}, optional
        Type of density plot to draw. "full" uses default parameters, "simple"
        uses a lower number of levels (2), higher threshold (0.5), and lower alpha (0.5)
        for a cleaner visualization, by default "full"
    palette : SeabornPaletteType | None, optional
        Method for choosing the colors to use when mapping the hue semantic.
        String values are passed to seaborn.color_palette().
        List or dict values imply categorical mapping, while a colormap object
        implies numeric mapping, by default "colorblind"
    scatter_kws : dict | None, optional
        Keyword arguments to pass to `seaborn.scatterplot` if incl_scatter is True,
        by default {"s": 25, "linewidth": 0}
    incl_outline : bool, optional
        Whether to include an outline for the density contours, by default False
    legend : {"auto", "brief", "full", False}, optional
        How to draw the legend. If "brief", numeric hue variables will be
        represented with a sample of evenly spaced values. If "full", every group will
        get an entry in the legend. If "auto", choose between brief or full
        representation based on number of levels.
        If False, no legend data is added and no legend is drawn, by default "auto"
    prim_labels : bool | None, optional
        Deprecated. Use xlabel and ylabel parameters instead.

    **kwargs : dict, optional
        Additional styling parameters:

        - alpha : float, optional
            Proportional opacity of the density fill, by default 0.8
        - fill : bool, optional
            If True, fill in the area between bivariate contours, by default True
        - levels : int | Iterable[float], optional
            Number of contour levels or values to draw contours at, by default 10
        - thresh : float, optional
            Lowest iso-proportional level at which to draw a contour line,
            by default 0.05
        - bw_adjust : float, optional
            Factor that multiplicatively scales the bandwidth, by default 1.2
        - xlabel, ylabel : str | Literal[False], optional
            Custom axis labels. By default, "$P_{ISO}$" and "$E_{ISO}$" with math
            rendering.
            If None is passed, the column names (x and y) will be used as labels.
            If a string is provided, it will be used as the label.
            If False is passed, axis labels will be hidden.
        - xlim, ylim : tuple[float, float], optional
            Limits for x and y axes, by default (-1, 1) for both
        - legend_loc : MplLegendLocType, optional
            Location of legend, by default "best"
        - diagonal_lines : bool, optional
            Whether to include diagonal dimension labels (e.g. calm, etc.),
            by default False
        - figsize : tuple[int, int], optional
            Size of the figure to return if `ax` is None, by default (5, 5)
        - prim_ax_fontdict : dict, optional
            Font dictionary for axis labels with these defaults:

            {
                "family": "sans-serif",
                "fontstyle": "normal",
                "fontsize": "large",
                "fontweight": "medium",
                "parse_math": True,
                "c": "black",
                "alpha": 1,
            }
        - fontsize, fontweight, fontstyle, family, c, alpha, parse_math:
            Direct parameters for font styling in axis labels

        Also accepts additional keyword arguments for matplotlib's contour and contourf
        functions.

    Returns
    -------
        Axes object containing the plot.

    Notes
    -----
    This function will raise a warning if the dataset has fewer than
    RECOMMENDED_MIN_SAMPLES (30) data points, as density plots are not reliable
    with small sample sizes.

    Examples
    --------
    Basic density plot with default settings:

    >>> import soundscapy as sspy
    >>> import matplotlib.pyplot as plt
    >>> data = sspy.isd.load()
    >>> data = sspy.add_iso_coords(data)
    >>> ax = sspy.density(data)
    >>> plt.show() # xdoctest: +SKIP

    Simple density plot with fewer contour levels:

    >>> ax = sspy.density(data, density_type="simple")
    >>> plt.show() # xdoctest: +SKIP

    Density plot with custom styling:

    >>> sub_data = sspy.isd.select_location_ids(
    ...    data, ['CamdenTown', 'PancrasLock', 'RegentsParkJapan', 'RegentsParkFields'])
    >>> ax = sspy.density(
    ...     sub_data,
    ...     hue="SessionID",
    ...     incl_scatter=True,
    ...     legend_loc="upper right",
    ...     fill = False,
    ...     density_type = "simple",
    ... )
    >>> plt.show() # xdoctest: +SKIP

    Add density to existing plots:

    >>> fig, axes = plt.subplots(1, 2, figsize=(12, 6))
    >>> axes[0] = sspy.density(
    ...     sspy.isd.select_location_ids(data, ['CamdenTown', 'PancrasLock']),
    ...     ax=axes[0], title="CamdenTown and PancrasLock", hue="LocationID",
    ...     density_type="simple"
    ... )
    >>> axes[1] = sspy.density(
    ...     sspy.isd.select_location_ids(data, ['RegentsParkJapan']),
    ...     ax=axes[1], title="RegentsParkJapan"
    ... )
    >>> plt.tight_layout()
    >>> plt.show() # xdoctest: +SKIP
    >>> plt.close('all')

    """
    style_args, subplots_args, kwargs = _setup_style_and_subplots_args_from_kwargs(
        x=x, y=y, prim_labels=prim_labels, kwargs=kwargs
    )

    # Set up density parameters
    density_args = _setup_density_params(
        data=data,
        x=x,
        y=y,
        hue=hue,
        density_type=density_type,
        palette=palette,
        legend=legend,
        **kwargs,
    )

    # Check if dataset is large enough for density plots
    _valid_density(data)

    if ax is None:
        _, ax = plt.subplots(1, 1, figsize=subplots_args.get("figsize"))

    # Removes the palette if no hue is specified
    if density_args.get("hue") is None:
        density_args.update(palette=None)

    # Set up scatter parameters if needed
    scatter_args = ScatterParams()
    scatter_args.update(
        data=data,
        x=x,
        y=y,
        palette=palette,
        hue=density_args.get("hue"),
        color=density_args.get("color"),
        **(scatter_kws or {}),
    )

    scatter_args.crosscheck_palette_hue()
    density_args.crosscheck_palette_hue()

    if incl_scatter:
        d = sns.scatterplot(ax=ax, **scatter_args.as_seaborn_kwargs())

    if density_type == "simple":
        d = sns.kdeplot(ax=ax, **density_args.as_seaborn_kwargs())
        d = sns.kdeplot(ax=ax, **density_args.to_outline().as_seaborn_kwargs())

    elif density_type == "full":
        d = sns.kdeplot(ax=ax, **density_args.as_seaborn_kwargs())
    else:
        raise ValueError

    _set_style()
    _circumplex_grid(
        ax=ax,
        xlim=style_args.get("xlim"),
        ylim=style_args.get("ylim"),
        xlabel=style_args.get("xlabel"),
        ylabel=style_args.get("ylabel"),
        diagonal_lines=style_args.get("diagonal_lines"),
        prim_ax_fontdict=style_args.get("prim_ax_fontdict"),
    )
    if title is not None:
        _set_circum_title(
            ax=ax,
            title=title,
            xlabel=style_args.get("xlabel"),
            ylabel=style_args.get("ylabel"),
        )
    if legend is not None and hue is not None:
        _move_legend(ax=ax, new_loc=style_args.get("legend_loc"))

    return d

density_plot

density_plot(*args, **kwargs)

Wrapper for the density function to maintain backwards compatibility.

PARAMETER	DESCRIPTION
*args	Positional arguments to pass to the density function. TYPE: tuple DEFAULT: ()
**kwargs	Keyword arguments to pass to the density function. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
Axes	The Axes object containing the plot.

Source code in soundscapy/plotting/plot_functions.py

def density_plot(*args, **kwargs) -> Axes | np.ndarray | ISOPlot:  # noqa: ANN002
    """
    Wrapper for the density function to maintain backwards compatibility.

    Parameters
    ----------
    *args : tuple
        Positional arguments to pass to the density function.
    **kwargs : dict
        Keyword arguments to pass to the density function.

    Returns
    -------
    Axes
        The Axes object containing the plot.

    """  # noqa: D401
    warnings.warn(
        "The `density_plot` function is deprecated and will be removed in a "
        "future version. Use `density` instead."
        "\nAs of v0.8, `density_plot` is an alias for `density` and does not maintain "
        "full backwards compatibility with v0.7. It may work, or some arguments may "
        "fail.",
        DeprecationWarning,
        stacklevel=2,
    )
    if kwargs.pop("backend", None) is not None:
        warnings.warn(
            "`Backend` is no longer supported in the density_plot function (v0.8+).",
            DeprecationWarning,
            stacklevel=2,
        )
    filtered_args = [a for a in args if not isinstance(a, Backend)]

    kwargs = {
        k: v
        for k, v in kwargs.items()
        if k
        not in (
            "backend",
            "show_labels",
            "apply_styling",
            "simple_density",
            "simple_density_thresh",
            "simple_density_levels",
            "simple_density_alpha",
        )
    }

    # Convert simple_density parameters to the new API if they exist
    if "density_type" not in kwargs and kwargs.pop("simple_density", False):
        kwargs["density_type"] = "simple"

    return density(*filtered_args, **kwargs)

iso_annotation

iso_annotation(ax, data, location, *, x_adj=0, y_adj=0, x_key=DEFAULT_XCOL, y_key=DEFAULT_YCOL, ha='center', va='center', fontsize='small', arrowprops=None, **text_kwargs)

Add text annotations to circumplex plot based on coordinate values.

Directly uses plt.annotate

PARAMETER	DESCRIPTION
ax	existing plt axes to add to TYPE: Axes
data	dataframe of coordinate points TYPE: Dataframe
location	name of the coordinate to plot TYPE: str
x_adj	value to adjust x location by, by default 0 TYPE: int DEFAULT: 0
y_adj	value to adjust y location by, by default 0 TYPE: int DEFAULT: 0
x_key	name of x column, by default "ISOPleasant" TYPE: str DEFAULT: DEFAULT_XCOL
y_key	name of y column, by default "ISOEventful" TYPE: str DEFAULT: DEFAULT_YCOL
ha	horizontal alignment, by default "center" TYPE: str DEFAULT: 'center'
va	vertical alignment, by default "center" TYPE: str DEFAULT: 'center'
fontsize	by default "small" TYPE: str DEFAULT: 'small'
arrowprops	dict of properties to send to plt.annotate, by default dict(arrowstyle="-", ec="black") TYPE: dict DEFAULT: None

Source code in soundscapy/plotting/plot_functions.py

def iso_annotation(
    ax: Axes,
    data: pd.DataFrame,
    location: str,
    *,
    x_adj: int = 0,
    y_adj: int = 0,
    x_key: str = DEFAULT_XCOL,
    y_key: str = DEFAULT_YCOL,
    ha: str = "center",
    va: str = "center",
    fontsize: str = "small",
    arrowprops: dict | None = None,
    **text_kwargs,
) -> None:
    """
    Add text annotations to circumplex plot based on coordinate values.

    Directly uses plt.annotate

    Parameters
    ----------
    ax : matplotlib.pyplot.Axes
        existing plt axes to add to
    data : pd.Dataframe
        dataframe of coordinate points
    location : str
        name of the coordinate to plot
    x_adj : int, optional
        value to adjust x location by, by default 0
    y_adj : int, optional
        value to adjust y location by, by default 0
    x_key : str, optional
        name of x column, by default "ISOPleasant"
    y_key : str, optional
        name of y column, by default "ISOEventful"
    ha : str, optional
        horizontal alignment, by default "center"
    va : str, optional
        vertical alignment, by default "center"
    fontsize : str, optional
        by default "small"
    arrowprops : dict, optional
        dict of properties to send to plt.annotate,
        by default dict(arrowstyle="-", ec="black")

    """
    if arrowprops is None:
        arrowprops = {"arrowstyle": "-", "ec": "black"}

    # noinspection PyTypeChecker
    ax.annotate(
        text=data["LocationID"][location],
        xy=(
            data[x_key][location],
            data[y_key][location],
        ),
        xytext=(
            data[x_key][location] + x_adj,
            data[y_key][location] + y_adj,
        ),
        ha=ha,
        va=va,
        arrowprops=arrowprops,
        annotation_clip=True,
        fontsize=fontsize,
        **text_kwargs,
    )

iso_plot

iso_plot(data, x='ISOPleasant', y='ISOEventful', title='Soundscapy Plot', plot_layers=('scatter', 'density'), **kwargs)

Plot a soundscape visualization based on the specified metrics using different combinations of layers such as scatter, density, or simple density plots.

The function generates a 2D plot (via Matplotlib Axes object) based on the x and y metrics provided. Users can choose between individual layers or specify a combination of the supported plot layers. It supports automatic handling for specific layer combinations, such as "scatter + density". The core plotting functionality is delegated to other helper functions (scatter and density).

PARAMETER	DESCRIPTION
data	The dataset containing the metrics to be plotted. Must include the columns specified for x and y. TYPE: DataFrame
x	The column name within data to be used for the x-axis. Defaults to "ISOPleasant". TYPE: str DEFAULT: 'ISOPleasant'
y	The column name within data to be used for the y-axis. Defaults to "ISOEventful". TYPE: str DEFAULT: 'ISOEventful'
title	The title of the plot. If not specified, defaults to "Soundscapy Plot". TYPE: str or None DEFAULT: 'Soundscapy Plot'
plot_layers	or Sequence[{"scatter", "density", "simple_density"}], optional Specifies the type or combination of plot layers to generate. Valid options include: - "scatter": A scatter plot - "density": A density plot (without scatter points, unless combined) - "simple_density": A simplified density plot (without scatter points, unless combined). Can be passed as a string (single layer) or as a sequence of strings (combination of layers). Defaults to ("scatter", "density"). TYPE: (scatter, density, simple_density) DEFAULT: "scatter"
**kwargs	Additional keyword arguments to be passed to the underlying plotting functions (scatter or density). These allow for customization such as marker styles, colors, etc. TYPE: any DEFAULT: {}

RETURNS	DESCRIPTION
Axes	A Matplotlib Axes object corresponding to the generated plot. TYPE: Axes

Notes

This function supports only specific combinations of layers. If an unsupported combination is specified, an exception will be raised. Layer compatibility rules: - Single layers: "scatter", "density", or "simple_density". - Dual layers: - "scatter" + "density" - "scatter" + "simple_density"

RAISES	DESCRIPTION
TypeError	If the plot_layers argument is not a string or a sequence of strings.
ValueError	If the plot_layers argument specifies an unsupported plot type or combination of plot layers.

Examples:

Basic density and scatter plot with default settings:

>>> import soundscapy as sspy
>>> import matplotlib.pyplot as plt
>>> data = sspy.isd.load()
>>> data = sspy.add_iso_coords(data)
>>> ax = sspy.iso_plot(data)
>>> plt.show()  # xdoctest: +SKIP

Basic scatter plot:

>>> ax = sspy.iso_plot(data, plot_layers="scatter")
>>> plt.show()  # xdoctest: +SKIP

Simple density plot with fewer contour levels:

>>> ax = sspy.iso_plot(data, plot_layers="simple_density")
>>> plt.show() # xdoctest: +SKIP

Simple density with scatter points

>>> ax = sspy.iso_plot(data, plot_layers=["scatter", "simple_density"])
>>> plt.show() # xdoctest: +SKIP

Density plot with custom styling:

>>> sub_data = sspy.isd.select_location_ids(
...    data, ['CamdenTown', 'PancrasLock', 'RegentsParkJapan', 'RegentsParkFields'])
>>> ax = sspy.iso_plot(
...     sub_data,
...     hue="SessionID",
...     plot_layers = ["scatter", "simple_density"],
...     legend_loc="upper right",
...     fill = False,
... )
>>> plt.show() # xdoctest: +SKIP

Add density to existing plots:

>>> fig, axes = plt.subplots(1, 2, figsize=(12, 6))
>>> axes[0] = sspy.iso_plot(
...     sspy.isd.select_location_ids(data, ['CamdenTown', 'PancrasLock']),
...     ax=axes.flatten()[0], title="CamdenTown and PancrasLock", hue="LocationID",
... )
>>> axes[1] = sspy.iso_plot(
...     sspy.isd.select_location_ids(data, ['RegentsParkJapan']),
...     ax=axes.flatten()[1], title="RegentsParkJapan"
... )
>>> plt.tight_layout()
>>> plt.show() # xdoctest: +SKIP
>>> plt.close('all')

Source code in soundscapy/plotting/plot_functions.py

def iso_plot(
    data: pd.DataFrame,
    x: str = "ISOPleasant",
    y: str = "ISOEventful",
    title: str | None = "Soundscapy Plot",
    plot_layers: Literal["scatter", "density", "simple_density"]
    | Sequence[Literal["scatter", "density", "simple_density"]] = (
        "scatter",
        "density",
    ),
    **kwargs,
) -> Axes:
    """
    Plot a soundscape visualization based on the specified metrics using different
    combinations of layers such as scatter, density, or simple density plots.

    The function generates a 2D plot (via Matplotlib Axes object) based on the `x` and
    `y` metrics provided. Users can choose between individual layers or specify a
    combination of the supported plot layers. It supports automatic handling for
    specific layer combinations, such as "scatter + density". The core plotting
    functionality is delegated to other helper functions (`scatter` and `density`).

    Parameters
    ----------
    data : pandas.DataFrame
        The dataset containing the metrics to be plotted. Must include the columns
        specified for `x` and `y`.
    x : str, optional
        The column name within `data` to be used for the x-axis. Defaults to
        "ISOPleasant".
    y : str, optional
        The column name within `data` to be used for the y-axis. Defaults to
        "ISOEventful".
    title : str or None, optional
        The title of the plot. If not specified, defaults to "Soundscapy Plot".
    plot_layers : {"scatter", "density", "simple_density"}
        or Sequence[{"scatter", "density", "simple_density"}], optional

        Specifies the type or combination of plot layers to generate. Valid options
        include:
         - "scatter": A scatter plot
         - "density": A density plot (without scatter points, unless combined)
         - "simple_density": A simplified density plot (without scatter points,
           unless combined).

        Can be passed as a string (single layer) or as a sequence of strings
        (combination of layers). Defaults to ("scatter", "density").
    **kwargs : any
        Additional keyword arguments to be passed to the underlying plotting
        functions (`scatter` or `density`). These allow for customization such as
        marker styles, colors, etc.

    Returns
    -------
    Axes : matplotlib.axes._axes.Axes
        A Matplotlib Axes object corresponding to the generated plot.

    Notes
    -----
    This function supports only specific combinations of layers. If an unsupported
    combination is specified, an exception will be raised. Layer compatibility
    rules:
      - Single layers: "scatter", "density", or "simple_density".
      - Dual layers:
        - "scatter" + "density"
        - "scatter" + "simple_density"

    Raises
    ------
    TypeError
        If the `plot_layers` argument is not a string or a sequence of strings.
    ValueError
        If the `plot_layers` argument specifies an unsupported plot type or
        combination of plot layers.

    Examples
    --------
    Basic density and scatter plot with default settings:

    >>> import soundscapy as sspy
    >>> import matplotlib.pyplot as plt
    >>> data = sspy.isd.load()
    >>> data = sspy.add_iso_coords(data)
    >>> ax = sspy.iso_plot(data)
    >>> plt.show()  # xdoctest: +SKIP

    Basic scatter plot:

    >>> ax = sspy.iso_plot(data, plot_layers="scatter")
    >>> plt.show()  # xdoctest: +SKIP

    Simple density plot with fewer contour levels:

    >>> ax = sspy.iso_plot(data, plot_layers="simple_density")
    >>> plt.show() # xdoctest: +SKIP

    Simple density with scatter points

    >>> ax = sspy.iso_plot(data, plot_layers=["scatter", "simple_density"])
    >>> plt.show() # xdoctest: +SKIP

    Density plot with custom styling:

    >>> sub_data = sspy.isd.select_location_ids(
    ...    data, ['CamdenTown', 'PancrasLock', 'RegentsParkJapan', 'RegentsParkFields'])
    >>> ax = sspy.iso_plot(
    ...     sub_data,
    ...     hue="SessionID",
    ...     plot_layers = ["scatter", "simple_density"],
    ...     legend_loc="upper right",
    ...     fill = False,
    ... )
    >>> plt.show() # xdoctest: +SKIP

    Add density to existing plots:

    >>> fig, axes = plt.subplots(1, 2, figsize=(12, 6))
    >>> axes[0] = sspy.iso_plot(
    ...     sspy.isd.select_location_ids(data, ['CamdenTown', 'PancrasLock']),
    ...     ax=axes.flatten()[0], title="CamdenTown and PancrasLock", hue="LocationID",
    ... )
    >>> axes[1] = sspy.iso_plot(
    ...     sspy.isd.select_location_ids(data, ['RegentsParkJapan']),
    ...     ax=axes.flatten()[1], title="RegentsParkJapan"
    ... )
    >>> plt.tight_layout()
    >>> plt.show() # xdoctest: +SKIP
    >>> plt.close('all')

    """  # noqa: D205
    if isinstance(plot_layers, str):
        plot_layers = [plot_layers]

    if not isinstance(plot_layers, Sequence):
        raise TypeError(PLOT_LAYER_TYPE_ERROR.format(type=type(plot_layers)))

    # Handle single layer case
    if len(plot_layers) == 1:
        layer_type = plot_layers[0]
        if layer_type == "scatter":
            return scatter(data, x=x, y=y, title=title, **kwargs)
        if layer_type == "simple_density":
            return density(
                data,
                x=x,
                y=y,
                title=title,
                density_type="simple",
                incl_scatter=False,
                **kwargs,
            )
        if layer_type == "density":
            return density(data, x=x, y=y, title=title, incl_scatter=False, **kwargs)

        raise ValueError(PLOT_LAYER_VALUE_ERROR.format(layers=plot_layers))

    # Handle two layer case
    if len(plot_layers) == 2:
        layers_set = set(plot_layers)

        if "scatter" in layers_set and "density" in layers_set:
            return density(data, x=x, y=y, title=title, incl_scatter=True, **kwargs)

        if "scatter" in layers_set and "simple_density" in layers_set:
            return density(
                data,
                x=x,
                y=y,
                title=title,
                density_type="simple",
                incl_scatter=True,
                **kwargs,
            )

        # Default case for unrecognized but valid length combinations
        return density(data, x=x, y=y, title=title, incl_scatter=True, **kwargs)

    # More than 2 layers is not supported
    raise ValueError(PLOT_LAYER_VALUE_ERROR.format(layers=plot_layers))

jointplot

jointplot(data, *, x=DEFAULT_XCOL, y=DEFAULT_YCOL, title='Soundscape Joint Plot', hue=None, incl_scatter=True, density_type='full', palette='colorblind', color=DEFAULT_COLOR, figsize=DEFAULT_FIGSIZE, scatter_kws=None, incl_outline=False, alpha=DEFAULT_SEABORN_PARAMS['alpha'], fill=True, levels=10, thresh=0.05, bw_adjust=DEFAULT_BW_ADJUST, legend='auto', prim_labels=None, joint_kws=None, marginal_kws=None, marginal_kind='kde', **kwargs)

Create a jointplot with a central distribution and marginal plots.

Creates a visualization with a main plot (density or scatter) in the center and marginal distribution plots along the x and y axes. The main plot uses the custom Soundscapy styling for soundscape circumplex visualisations, and the marginals show the individual distributions of each variable.

PARAMETER	DESCRIPTION
data	Input data structure containing coordinate data, typically with ISOPleasant and ISOEventful columns. TYPE: DataFrame
x	Column name for x variable, by default "ISOPleasant" TYPE: str DEFAULT: DEFAULT_XCOL
y	Column name for y variable, by default "ISOEventful" TYPE: str DEFAULT: DEFAULT_YCOL
title	Title to add to the jointplot, by default "Soundscape Joint Plot" TYPE: str | None DEFAULT: 'Soundscape Joint Plot'
hue	Grouping variable that will produce plots with different colors. Can be either categorical or numeric, although color mapping will behave differently in latter case, by default None TYPE: str | ndarray | Series | None DEFAULT: None
incl_scatter	Whether to include a scatter plot of the data points in the joint plot, by default True TYPE: bool DEFAULT: True
density_type	Type of density plot to draw. "full" uses default parameters, "simple" uses a lower number of levels (2), higher threshold (0.5), and lower alpha (0.5) for a cleaner visualization, by default "full" TYPE: (full, simple) DEFAULT: "full"
palette	Method for choosing the colors to use when mapping the hue semantic. String values are passed to seaborn.color_palette(). List or dict values imply categorical mapping, while a colormap object implies numeric mapping, by default "colorblind" TYPE: SeabornPaletteType | None DEFAULT: 'colorblind'
color	Color to use for the plot elements when not using hue mapping, by default "#0173B2" (first color from colorblind palette) TYPE: ColorType | None DEFAULT: DEFAULT_COLOR
figsize	Size of the figure to create (determines height, width is proportional), by default (5, 5) TYPE: tuple[int, int] DEFAULT: DEFAULT_FIGSIZE
scatter_kws	Additional keyword arguments to pass to scatter plot if incl_scatter is True, by default None TYPE: dict[str, Any] | None DEFAULT: None
incl_outline	Whether to include an outline for the density contours, by default False TYPE: bool DEFAULT: False
alpha	Opacity level for the density fill, by default 0.8 TYPE: float DEFAULT: DEFAULT_SEABORN_PARAMS['alpha']
fill	Whether to fill the density contours, by default True TYPE: bool DEFAULT: True
levels	Number of contour levels or specific levels to draw. A vector argument must have increasing values in [0, 1], by default 10 TYPE: int | Iterable[float] DEFAULT: 10
thresh	Lowest iso-proportion level at which to draw contours, by default 0.05 TYPE: float DEFAULT: 0.05
bw_adjust	Factor that multiplicatively scales the bandwidth. Increasing will make the density estimate smoother, by default 1.2 TYPE: float DEFAULT: DEFAULT_BW_ADJUST
legend	How to draw the legend for hue mapping, by default "auto" TYPE: (auto, brief, full, False) DEFAULT: "auto"
prim_labels	Deprecated. Use xlabel and ylabel parameters instead. TYPE: bool | None DEFAULT: None
joint_kws	Additional keyword arguments to pass to the joint plot, by default None TYPE: dict[str, Any] | None DEFAULT: None
marginal_kws	Additional keyword arguments to pass to the marginal plots, by default {"fill": True, "common_norm": False} TYPE: dict[str, Any] | None DEFAULT: None
marginal_kind	Type of plot to draw in the marginal axes, either "kde" for kernel density estimation or "hist" for histogram, by default "kde" TYPE: (kde, hist) DEFAULT: "kde"
**kwargs	Additional styling parameters: xlabel, ylabel : str | Literal[False], optional Custom axis labels. By default "\(P_{ISO}\)" and "\(E_{ISO}\)" with math rendering. If None is passed, the column names (x and y) will be used as labels. If a string is provided, it will be used as the label. If False is passed, axis labels will be hidden. - xlim, ylim : tuple[float, float], optional Limits for x and y axes, by default (-1, 1) for both - legend_loc : MplLegendLocType, optional Location of legend, by default "best" - diagonal_lines : bool, optional Whether to include diagonal dimension labels (e.g. calm, etc.), by default False - prim_ax_fontdict : dict, optional Font dictionary for axis labels with these defaults: { "family": "sans-serif", "fontstyle": "normal", "fontsize": "large", "fontweight": "medium", "parse_math": True, "c": "black", "alpha": 1, } TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
JointGrid	The seaborn JointGrid object containing the plot

Notes

This function will raise a warning if the dataset has fewer than RECOMMENDED_MIN_SAMPLES (30) data points, as density plots are not reliable with small sample sizes.

Examples:

Basic jointplot with default settings:

>>> import soundscapy as sspy
>>> import matplotlib.pyplot as plt
>>> data = sspy.isd.load()
>>> data = sspy.add_iso_coords(data)
>>> g = sspy.jointplot(data)
>>> plt.show() # xdoctest: +SKIP

Jointplot with histogram marginals:

>>> g = sspy.jointplot(data, marginal_kind="hist")
>>> plt.show() # xdoctest: +SKIP

Jointplot with custom styling and grouping:

>>> g = sspy.jointplot(
...     data,
...     hue="LocationID",
...     incl_scatter=True,
...     density_type="simple",
...     diagonal_lines=True,
...     figsize=(6, 6),
...     title="Grouped Soundscape Analysis"
... )
>>> plt.show() # xdoctest: +SKIP
>>> plt.close('all')

Source code in soundscapy/plotting/plot_functions.py

def jointplot(
    data: pd.DataFrame,
    *,
    x: str = DEFAULT_XCOL,
    y: str = DEFAULT_YCOL,
    title: str | None = "Soundscape Joint Plot",
    hue: str | None = None,
    incl_scatter: bool = True,
    density_type: str = "full",
    palette: SeabornPaletteType | None = "colorblind",
    color: ColorType | None = DEFAULT_COLOR,
    figsize: tuple[int, int] = DEFAULT_FIGSIZE,
    scatter_kws: dict[str, Any] | None = None,
    incl_outline: bool = False,
    alpha: float = DEFAULT_SEABORN_PARAMS["alpha"],
    fill: bool = True,
    levels: int | tuple[float, ...] = 10,
    thresh: float = 0.05,
    bw_adjust: float = DEFAULT_BW_ADJUST,
    legend: Literal["auto", "brief", "full", False] = "auto",
    prim_labels: bool | None = None,  # Alias for primary_labels, deprecated
    joint_kws: dict[str, Any] | None = None,
    marginal_kws: dict[str, Any] | None = None,
    marginal_kind: str = "kde",
    **kwargs,
) -> sns.JointGrid:
    """
    Create a jointplot with a central distribution and marginal plots.

    Creates a visualization with a main plot (density or scatter) in the center and
    marginal distribution plots along the x and y axes. The main plot uses the custom
    Soundscapy styling for soundscape circumplex visualisations, and the marginals show
    the individual distributions of each variable.

    Parameters
    ----------
    data : pd.DataFrame
        Input data structure containing coordinate data, typically with ISOPleasant
        and ISOEventful columns.
    x : str, optional
        Column name for x variable, by default "ISOPleasant"
    y : str, optional
        Column name for y variable, by default "ISOEventful"
    title : str | None, optional
        Title to add to the jointplot, by default "Soundscape Joint Plot"
    hue : str | np.ndarray | pd.Series | None, optional
        Grouping variable that will produce plots with different colors.
        Can be either categorical or numeric, although color mapping will behave
        differently in latter case, by default None
    incl_scatter : bool, optional
        Whether to include a scatter plot of the data points in the joint plot,
        by default True
    density_type : {"full", "simple"}, optional
        Type of density plot to draw. "full" uses default parameters, "simple"
        uses a lower number of levels (2), higher threshold (0.5), and lower alpha (0.5)
        for a cleaner visualization, by default "full"
    palette : SeabornPaletteType | None, optional
        Method for choosing the colors to use when mapping the hue semantic.
        String values are passed to seaborn.color_palette().
        List or dict values imply categorical mapping, while a colormap object
        implies numeric mapping, by default "colorblind"
    color : ColorType | None, optional
        Color to use for the plot elements when not using hue mapping,
        by default "#0173B2" (first color from colorblind palette)
    figsize : tuple[int, int], optional
        Size of the figure to create (determines height, width is proportional),
        by default (5, 5)
    scatter_kws : dict[str, Any] | None, optional
        Additional keyword arguments to pass to scatter plot if incl_scatter is True,
        by default None
    incl_outline : bool, optional
        Whether to include an outline for the density contours, by default False
    alpha : float, optional
        Opacity level for the density fill, by default 0.8
    fill : bool, optional
        Whether to fill the density contours, by default True
    levels : int | Iterable[float], optional
        Number of contour levels or specific levels to draw. A vector argument
        must have increasing values in [0, 1], by default 10
    thresh : float, optional
        Lowest iso-proportion level at which to draw contours, by default 0.05
    bw_adjust : float, optional
        Factor that multiplicatively scales the bandwidth. Increasing will make
        the density estimate smoother, by default 1.2
    legend : {"auto", "brief", "full", False}, optional
        How to draw the legend for hue mapping, by default "auto"
    prim_labels : bool | None, optional
        Deprecated. Use xlabel and ylabel parameters instead.
    joint_kws : dict[str, Any] | None, optional
        Additional keyword arguments to pass to the joint plot, by default None
    marginal_kws : dict[str, Any] | None, optional
        Additional keyword arguments to pass to the marginal plots,
        by default {"fill": True, "common_norm": False}
    marginal_kind : {"kde", "hist"}, optional
        Type of plot to draw in the marginal axes, either "kde" for kernel
        density estimation or "hist" for histogram, by default "kde"

    **kwargs : dict, optional
        Additional styling parameters:

        - xlabel, ylabel : str | Literal[False], optional
            Custom axis labels. By default "$P_{ISO}$" and "$E_{ISO}$" with
            math rendering.

            If None is passed, the column names (x and y) will be used as labels.

            If a string is provided, it will be used as the label.

            If False is passed, axis labels will be hidden.
        - xlim, ylim : tuple[float, float], optional
            Limits for x and y axes, by default (-1, 1) for both
        - legend_loc : MplLegendLocType, optional
            Location of legend, by default "best"
        - diagonal_lines : bool, optional
            Whether to include diagonal dimension labels (e.g. calm, etc.),
            by default False
        - prim_ax_fontdict : dict, optional
            Font dictionary for axis labels with these defaults:

            {
                "family": "sans-serif",
                "fontstyle": "normal",
                "fontsize": "large",
                "fontweight": "medium",
                "parse_math": True,
                "c": "black",
                "alpha": 1,
            }

    Returns
    -------
    sns.JointGrid
        The seaborn JointGrid object containing the plot

    Notes
    -----
    This function will raise a warning if the dataset has fewer than
    RECOMMENDED_MIN_SAMPLES (30) data points, as density plots are not reliable
    with small sample sizes.

    Examples
    --------
    Basic jointplot with default settings:

    >>> import soundscapy as sspy
    >>> import matplotlib.pyplot as plt
    >>> data = sspy.isd.load()
    >>> data = sspy.add_iso_coords(data)
    >>> g = sspy.jointplot(data)
    >>> plt.show() # xdoctest: +SKIP

    Jointplot with histogram marginals:

    >>> g = sspy.jointplot(data, marginal_kind="hist")
    >>> plt.show() # xdoctest: +SKIP

    Jointplot with custom styling and grouping:

    >>> g = sspy.jointplot(
    ...     data,
    ...     hue="LocationID",
    ...     incl_scatter=True,
    ...     density_type="simple",
    ...     diagonal_lines=True,
    ...     figsize=(6, 6),
    ...     title="Grouped Soundscape Analysis"
    ... )
    >>> plt.show() # xdoctest: +SKIP
    >>> plt.close('all')

    """
    # Check if dataset is large enough for density plots
    _valid_density(data)

    style_args, subplots_args, kwargs = _setup_style_and_subplots_args_from_kwargs(
        x=x, y=y, prim_labels=prim_labels, kwargs=kwargs
    )

    # Initialize default dicts if None
    scatter_args = ScatterParams()
    scatter_args.update(**scatter_kws) if scatter_kws is not None else None

    joint_kws = {} if joint_kws is None else joint_kws
    marginal_kws = (
        {"fill": True, "common_norm": False} if marginal_kws is None else marginal_kws
    )

    if density_type == "simple":
        thresh = DEFAULT_SIMPLE_DENSITY_PARAMS["thresh"]
        levels = DEFAULT_SIMPLE_DENSITY_PARAMS["levels"]
        alpha = DEFAULT_SIMPLE_DENSITY_PARAMS["alpha"]
        incl_outline = True

    # Handle hue and color
    if hue is None:
        # Removes the palette if no hue is specified
        palette = None
        color = sns.color_palette("colorblind", 1)[0] if color is None else color

    # Create the joint grid
    g = sns.JointGrid(
        data=data,
        x=x,
        y=y,
        hue=hue,
        palette=palette,
        # height=figsize[0],  # Use figsize for height
        xlim=style_args.xlim,
        ylim=style_args.ylim,
    )

    # Add the density plot to the joint plot area
    density(
        data,
        x=x,
        y=y,
        incl_scatter=incl_scatter,
        density_type=density_type,
        title=None,  # We'll set the title separately
        ax=g.ax_joint,
        hue=hue,
        palette=palette,
        color=color,
        scatter_kws=scatter_kws,
        incl_outline=incl_outline,
        legend_loc=style_args.legend_loc,
        alpha=alpha,
        legend=legend,
        fill=fill,
        levels=levels,
        thresh=thresh,
        bw_adjust=bw_adjust,
        diagonal_lines=style_args.diagonal_lines,
        xlim=style_args.xlim,
        ylim=style_args.ylim,
        **joint_kws,
    )

    # Add the marginal plots
    if marginal_kind == "hist":
        sns.histplot(
            data=data,
            x=x,
            hue=hue,
            palette=palette,
            ax=g.ax_marg_x,
            binrange=style_args.xlim,
            legend=False,
            **marginal_kws,
        )
        sns.histplot(
            data=data,
            y=y,
            hue=hue,
            palette=palette,
            ax=g.ax_marg_y,
            binrange=style_args.ylim,
            legend=False,
            **marginal_kws,
        )
    elif marginal_kind == "kde":
        sns.kdeplot(
            data=data,
            x=x,
            hue=hue,
            palette=palette,
            ax=g.ax_marg_x,
            bw_adjust=bw_adjust,
            legend=False,
            **marginal_kws,
        )
        sns.kdeplot(
            data=data,
            y=y,
            hue=hue,
            palette=palette,
            ax=g.ax_marg_y,
            bw_adjust=bw_adjust,
            legend=False,
            **marginal_kws,
        )

    # Set title
    if title is not None:
        g.ax_marg_x.set_title(title, pad=6.0)

    _set_style()
    _circumplex_grid(
        ax=g.ax_joint,
        xlim=style_args.get("xlim"),
        ylim=style_args.get("ylim"),
        xlabel=style_args.get("xlabel"),
        ylabel=style_args.get("ylabel"),
        diagonal_lines=style_args.get("diagonal_lines"),
        prim_ax_fontdict=style_args.get("prim_ax_fontdict"),
    )

    if legend is not None and hue is not None:
        _move_legend(ax=g.ax_joint, new_loc=style_args.get("legend_loc"))

    return g

scatter

scatter(data, title='Soundscape Scatter Plot', ax=None, *, x='ISOPleasant', y='ISOEventful', hue=None, palette='colorblind', legend='auto', prim_labels=None, **kwargs)

Plot ISOcoordinates as scatter points on a soundscape circumplex grid.

Creates a scatter plot of data on a standardized circumplex grid with the custom Soundscapy styling for soundscape circumplex visualisations.

PARAMETER	DESCRIPTION
data	Input data structure containing coordinate data, typically with ISOPleasant and ISOEventful columns. TYPE: DataFrame
x	Column name for x variable, by default "ISOPleasant" TYPE: str DEFAULT: 'ISOPleasant'
y	Column name for y variable, by default "ISOEventful" TYPE: str DEFAULT: 'ISOEventful'
title	Title to add to circumplex plot, by default "Soundscape Scatter Plot" TYPE: str | None DEFAULT: 'Soundscape Scatter Plot'
ax	Pre-existing matplotlib axes for the plot, by default None If None call matplotlib.pyplot.subplots with figsize internally. TYPE: Axes DEFAULT: None
hue	Grouping variable that will produce points with different colors. Can be either categorical or numeric, although color mapping will behave differently in latter case, by default None TYPE: str | ndarray | Series | None DEFAULT: None
palette	Method for choosing the colors to use when mapping the hue semantic. String values are passed to seaborn.color_palette(). List or dict values imply categorical mapping, while a colormap object implies numeric mapping, by default "colorblind" TYPE: SeabornPaletteType DEFAULT: 'colorblind'
color	Color to use for the plot elements when not using hue mapping, by default "#0173B2" (first color from colorblind palette) TYPE: ColorType | None
figsize	Size of the figure to return if ax is None, by default (5, 5) TYPE: tuple[int, int]
s	Size of scatter points, by default 20 TYPE: float
legend	How to draw the legend. If "brief", numeric hue and size variables will be represented with a sample of evenly spaced values. If "full", every group will get an entry in the legend. If "auto", choose between brief or full representation based on number of levels. If False, no legend data is added and no legend is drawn, by default "auto" TYPE: (auto, brief, full, False) DEFAULT: "auto"
prim_labels	Deprecated. Use xlabel and ylabel parameters instead. TYPE: bool | None DEFAULT: None

PARAMETER	DESCRIPTION
xlabel	Custom axis labels. By default "\(P_{ISO}\)" and "\(E_{ISO}\)" with math rendering. If None is passed, the column names (x and y) will be used as labels. If a string is provided, it will be used as the label. If False is passed, axis labels will be hidden.
ylabel	Custom axis labels. By default "\(P_{ISO}\)" and "\(E_{ISO}\)" with math rendering. If None is passed, the column names (x and y) will be used as labels. If a string is provided, it will be used as the label. If False is passed, axis labels will be hidden.
xlim	Limits for x and y axes, by default (-1, 1) for both TYPE: tuple[float, float]
ylim	Limits for x and y axes, by default (-1, 1) for both TYPE: tuple[float, float]
legend_loc	Location of legend, by default "best" TYPE: MplLegendLocType
diagonal_lines	Whether to include diagonal dimension labels (e.g. calm, etc.), by default False TYPE: bool
prim_ax_fontdict	Font dictionary for axis labels with these defaults: { "family": "sans-serif", "fontstyle": "normal", "fontsize": "large", "fontweight": "medium", "parse_math": True, "c": "black", "alpha": 1, } TYPE: dict
fontsize	Direct parameters for font styling in axis labels
fontweight	Direct parameters for font styling in axis labels
fontstyle	Direct parameters for font styling in axis labels
family	Direct parameters for font styling in axis labels
c	Direct parameters for font styling in axis labels
alpha	Direct parameters for font styling in axis labels
parse_math	Direct parameters for font styling in axis labels

RETURNS	DESCRIPTION
Axes object containing the plot.

Notes

This function applies special styling appropriate for circumplex plots including gridlines, axis labels, and proportional axes.

Examples:

Basic scatter plot with default settings:

>>> import soundscapy as sspy
>>> import matplotlib.pyplot as plt
>>> data = sspy.isd.load()
>>> data = sspy.add_iso_coords(data)
>>> ax = sspy.scatter(data)
>>> plt.show() # xdoctest: +SKIP

Scatter plot with grouping by location:

>>> ax = sspy.scatter(data, hue="LocationID", diagonal_lines=True, legend=False)
>>> plt.show() # xdoctest: +SKIP
>>> plt.close('all')

Source code in soundscapy/plotting/plot_functions.py

def scatter(
    data: pd.DataFrame,
    title: str | None = "Soundscape Scatter Plot",
    ax: Axes | None = None,
    *,
    x: str | None = "ISOPleasant",
    y: str | None = "ISOEventful",
    hue: str | None = None,
    palette: SeabornPaletteType | None = "colorblind",
    legend: Literal["auto", "brief", "full", False] = "auto",
    prim_labels: bool | None = None,  # Alias for primary_labels, deprecated
    **kwargs,
) -> Axes:
    """
    Plot ISOcoordinates as scatter points on a soundscape circumplex grid.

    Creates a scatter plot of data on a standardized circumplex grid with the custom
    Soundscapy styling for soundscape circumplex visualisations.

    Parameters
    ----------
    data
        Input data structure containing coordinate data, typically with ISOPleasant
        and ISOEventful columns.
    x : str, optional
        Column name for x variable, by default "ISOPleasant"
    y : str, optional
        Column name for y variable, by default "ISOEventful"
    title : str | None, optional
        Title to add to circumplex plot, by default "Soundscape Scatter Plot"
    ax : matplotlib.axes.Axes, optional
        Pre-existing matplotlib axes for the plot, by default None
        If `None` call `matplotlib.pyplot.subplots` with `figsize` internally.
    hue : str | np.ndarray | pd.Series | None, optional
        Grouping variable that will produce points with different colors.

        Can be either categorical or numeric,
        although color mapping will behave differently in latter case, by default None
    palette : SeabornPaletteType, optional
        Method for choosing the colors to use when mapping the hue semantic.
        String values are passed to seaborn.color_palette().
        List or dict values imply categorical mapping, while a colormap object
        implies numeric mapping, by default "colorblind"
    color : ColorType | None, optional
        Color to use for the plot elements when not using hue mapping,
        by default "#0173B2" (first color from colorblind palette)
    figsize : tuple[int, int], optional
        Size of the figure to return if `ax` is None, by default (5, 5)
    s : float, optional
        Size of scatter points, by default 20
    legend : {"auto", "brief", "full", False}, optional
        How to draw the legend. If "brief", numeric hue and size variables will be
        represented with a sample of evenly spaced values. If "full", every group will
        get an entry in the legend. If "auto", choose between brief or full
        representation based on number of levels.

        If False, no legend data is added and no legend is drawn, by default "auto"
    prim_labels : bool | None, optional
        Deprecated. Use xlabel and ylabel parameters instead.

    Other Parameters
    ----------------
    xlabel, ylabel
        Custom axis labels. By default "$P_{ISO}$" and "$E_{ISO}$"
        with math rendering.

        If None is passed, the column names (x and y) will be used as labels.

        If a string is provided, it will be used as the label.

        If False is passed, axis labels will be hidden.
    xlim, ylim : tuple[float, float], optional
        Limits for x and y axes, by default (-1, 1) for both
    legend_loc : MplLegendLocType, optional
        Location of legend, by default "best"
    diagonal_lines : bool, optional
        Whether to include diagonal dimension labels (e.g. calm, etc.),
        by default False
    prim_ax_fontdict : dict, optional
        Font dictionary for axis labels with these defaults:

        {
            "family": "sans-serif",
            "fontstyle": "normal",
            "fontsize": "large",
            "fontweight": "medium",
            "parse_math": True,
            "c": "black",
            "alpha": 1,
        }
    fontsize, fontweight, fontstyle, family, c, alpha, parse_math:
        Direct parameters for font styling in axis labels

    Returns
    -------
        Axes object containing the plot.

    Notes
    -----
    This function applies special styling appropriate for circumplex plots including
    gridlines, axis labels, and proportional axes.

    Examples
    --------
    Basic scatter plot with default settings:

    >>> import soundscapy as sspy
    >>> import matplotlib.pyplot as plt
    >>> data = sspy.isd.load()
    >>> data = sspy.add_iso_coords(data)
    >>> ax = sspy.scatter(data)
    >>> plt.show() # xdoctest: +SKIP

    Scatter plot with grouping by location:

    >>> ax = sspy.scatter(data, hue="LocationID", diagonal_lines=True, legend=False)
    >>> plt.show() # xdoctest: +SKIP
    >>> plt.close('all')

    """
    style_args, subplots_args, kwargs = _setup_style_and_subplots_args_from_kwargs(
        x=x, y=y, prim_labels=prim_labels, kwargs=kwargs
    )

    scatter_args = ScatterParams()
    scatter_args.update(
        data=data,
        x=x,
        y=y,
        palette=palette,
        hue=hue,
        legend=legend,
        extra="allow",
        ignore_null=False,
        **kwargs,
    )  # pass all the rest to scatter

    # Removes the palette if no hue is specified
    scatter_args.crosscheck_palette_hue()

    if ax is None:
        _, ax = plt.subplots(1, 1, figsize=subplots_args.figsize)

    p = sns.scatterplot(ax=ax, **scatter_args.as_dict())

    _set_style()
    _circumplex_grid(
        ax=ax,
        **style_args.get_multiple(
            ["xlim", "ylim", "xlabel", "ylabel", "diagonal_lines", "prim_ax_fontdict"]
        ),
    )
    if title is not None:
        _set_circum_title(
            ax=ax,
            title=title,
            xlabel=style_args.get("xlabel"),
            ylabel=style_args.get("ylabel"),
        )
    if legend is not None and hue is not None and style_args.legend_loc is not False:
        _move_legend(ax=ax, new_loc=style_args.get("legend_loc"))
    return p

scatter_plot

scatter_plot(*args, **kwargs)

Wrapper for the scatter function to maintain backwards compatibility.

PARAMETER	DESCRIPTION
*args	Positional arguments to pass to the scatter function. TYPE: tuple DEFAULT: ()
**kwargs	Keyword arguments to pass to the scatter function. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
Axes	The Axes object containing the plot.

Source code in soundscapy/plotting/plot_functions.py

def scatter_plot(*args, **kwargs) -> Axes:  # noqa: ANN002
    """
    Wrapper for the scatter function to maintain backwards compatibility.

    Parameters
    ----------
    *args : tuple
        Positional arguments to pass to the scatter function.
    **kwargs : dict
        Keyword arguments to pass to the scatter function.

    Returns
    -------
    Axes
        The Axes object containing the plot.

    """  # noqa: D401
    warnings.warn(
        "The `scatter_plot` function is deprecated and will be removed in a "
        "future version. Use `scatter` instead."
        "\nAs of v0.8, `scatter_plot` is an alias for `scatter` and does not maintain "
        "full backwards compatibility with v0.7. It may work, or some arguments may "
        "fail.",
        DeprecationWarning,
        stacklevel=2,
    )
    if kwargs.pop("backend", None) is not None:
        warnings.warn(
            "`Backend` is no longer supported in the scatter_plot function (v0.8+).",
            DeprecationWarning,
            stacklevel=2,
        )

    kwargs = {
        k: v
        for k, v in kwargs.items()
        if k not in ("backend", "show_labels", "apply_styling")
    }

    return scatter(*args, **kwargs)

show_submodules: true