Plotting¶

plot ¶

Plotting helpers for :class:Spectrogram and :class:RSF outputs.

Thin wrappers around :mod:matplotlib that handle the per-axis formatting (log-spaced frequency/rate/scale ticks, the upward/downward rate split, etc.) so notebook code can stay short.

plt_spectrogram ¶

plt_spectrogram(spectrogram: Spectrogram | ndarray, title: str = 'Auditory Spectrogram', figsize: tuple = (12, 6), cmap: str = 'viridis', frmlen_ms: float = 16.0, ax: Optional[Axes] = None, show_colorbar: bool = True, title_fontsize: int = 12, label_fontsize: int = 10, tick_fontsize: int = 9, interpolation: str = 'bilinear') -> Axes

Plot a single auditory spectrogram.

PARAMETER	DESCRIPTION
`spectrogram`	Spectrogram dataclass or a raw `(n_freq, n_time)` array. TYPE: `Spectrogram or ndarray`
`title`	Plot title. TYPE: `str` DEFAULT: `"Auditory Spectrogram"`
`figsize`	Figure size. Only used when `ax` is None. TYPE: `tuple` DEFAULT: `(12, 6)`
`cmap`	Matplotlib colormap. TYPE: `str` DEFAULT: `"viridis"`
`frmlen_ms`	Frame length in ms, used to compute the time axis when a raw array is passed. TYPE: `float` DEFAULT: `16.0`
`ax`	Axes to draw on. If None, a new figure is created and shown. TYPE: `Axes` DEFAULT: `None`
`show_colorbar`	Add a colorbar (only when `ax` is None). TYPE: `bool` DEFAULT: `True`
`title_fontsize`	Title font size. TYPE: `int` DEFAULT: `12`
`label_fontsize`	Axis label font size. TYPE: `int` DEFAULT: `10`
`tick_fontsize`	Tick label font size. TYPE: `int` DEFAULT: `9`
`interpolation`	Interpolation passed to :func:`matplotlib.axes.Axes.imshow`. TYPE: `str` DEFAULT: `"bilinear"`

RETURNS	DESCRIPTION
`Axes`	The axes the spectrogram was drawn on.

plt_spectrogram_grid ¶

plt_spectrogram_grid(data: List[Dict], n_cols: int = 4, figsize: tuple | None = None, cmap: str = 'viridis', frmlen_ms: float = 16.0, suptitle: str | None = None, save_path: Optional[str] = None) -> None

Plot multiple spectrograms in a grid.

PARAMETER	DESCRIPTION
`data`	Each entry must have a `"spectrogram"` key (a :class:`Spectrogram` or raw array) and may have a `"title"` key. TYPE: `list of dict`
`n_cols`	Number of columns in the grid. TYPE: `int` DEFAULT: `4`
`figsize`	Figure size. Auto-calculated from `n_cols` and the number of rows if not given. TYPE: `tuple` DEFAULT: `None`
`cmap`	Matplotlib colormap. TYPE: `str` DEFAULT: `"viridis"`
`frmlen_ms`	Frame length in ms, used when raw arrays are passed. TYPE: `float` DEFAULT: `16.0`
`suptitle`	Overall figure title. TYPE: `str` DEFAULT: `None`
`save_path`	If given, save the figure to this path at 200 DPI before showing. TYPE: `str` DEFAULT: `None`

plt_rsf ¶

plt_rsf(rsf: RSF | ndarray, rates: ndarray | None = None, scales: ndarray | None = None, fold: bool = False, title: str = 'Rate-Scale Representation', figsize: tuple = (10, 8), cmap: str = 'viridis', ax: Optional[Axes] = None, show_colorbar: bool = True, title_fontsize: int = 12, label_fontsize: int = 10, tick_fontsize: int = 9, square: bool = False) -> Axes

Plot a single RSF representation as a 2D scale-by-rate heatmap.

PARAMETER	DESCRIPTION
`rsf`	RSF dataclass, or a raw 4D array of shape `(n_frames, n_rates, n_scales, n_freq)` (in which case `rates` and `scales` must be supplied). TYPE: `RSF or ndarray`
`rates`	Rate axis values for tick labels. Defaults to `rsf.rates` when `rsf` is an :class:`RSF`. TYPE: `ndarray` DEFAULT: `None`
`scales`	Scale axis values for tick labels. Defaults to `rsf.scales` when `rsf` is an :class:`RSF`. TYPE: `ndarray` DEFAULT: `None`
`fold`	If True, average the upward and downward halves and mirror the result back out to produce a symmetric plot. TYPE: `bool` DEFAULT: `False`
`title`	Plot title. TYPE: `str` DEFAULT: `"Rate-Scale Representation"`
`figsize`	Figure size. Only used when `ax` is None. TYPE: `tuple` DEFAULT: `(10, 8)`
`cmap`	Matplotlib colormap. TYPE: `str` DEFAULT: `"viridis"`
`ax`	Axes to draw on. If None, a new figure is created and shown. TYPE: `Axes` DEFAULT: `None`
`show_colorbar`	Add a colorbar (only when `ax` is None). TYPE: `bool` DEFAULT: `True`
`title_fontsize`	Title font size. TYPE: `int` DEFAULT: `12`
`label_fontsize`	Axis label font size. TYPE: `int` DEFAULT: `10`
`tick_fontsize`	Tick label font size. TYPE: `int` DEFAULT: `9`
`square`	Force a square aspect ratio on the axes. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Axes`	The axes the RSF was drawn on.

RAISES	DESCRIPTION
`ValueError`	If `rsf` is a raw array but `rates` or `scales` is None.

plt_rsf_grid ¶

plt_rsf_grid(data: List[Dict], rates: ndarray | None = None, scales: ndarray | None = None, fold: bool = False, n_cols: int = 6, figsize: tuple | None = None, cmap: str = 'viridis', suptitle: str | None = None, save_path: Optional[str] = None) -> None

Plot multiple RSF representations in a grid.

PARAMETER	DESCRIPTION
`data`	Each entry must have an `"rsf"` key (an :class:`RSF` or raw 4D array) and may have a `"title"` key. TYPE: `list of dict`
`rates`	Rate axis values. Defaults to `rates` from the first :class:`RSF` in `data`. TYPE: `ndarray` DEFAULT: `None`
`scales`	Scale axis values. Defaults to `scales` from the first :class:`RSF` in `data`. TYPE: `ndarray` DEFAULT: `None`
`fold`	Forwarded to :func:`plt_rsf` for each subplot. TYPE: `bool` DEFAULT: `False`
`n_cols`	Number of columns in the grid. TYPE: `int` DEFAULT: `6`
`figsize`	Figure size. Auto-calculated if not given. TYPE: `tuple` DEFAULT: `None`
`cmap`	Matplotlib colormap. TYPE: `str` DEFAULT: `"viridis"`
`suptitle`	Overall figure title. TYPE: `str` DEFAULT: `None`
`save_path`	If given, save the figure to this path at 200 DPI before showing. TYPE: `str` DEFAULT: `None`

RAISES	DESCRIPTION
`ValueError`	If raw RSF arrays are passed but `rates` or `scales` is None.