aind_ephys_utils.plots package

Submodules

• aind_ephys_utils.plots.annotations module
  • add_scale_bars()
  • annotate_events()
• aind_ephys_utils.plots.colors module
  • get_color_for_region()
• aind_ephys_utils.plots.psth module
  • psth()
• aind_ephys_utils.plots.raster module
  • raster()
• aind_ephys_utils.plots.trajectory module
  • trajectory()

Module contents

Plotting helpers for ephys analysis.

This package provides lightweight matplotlib-based plotting functions for canonical spike representations.

aind_ephys_utils.plots.annotate_events(*, ax: Axes | None = None, events: Sequence[float] | ndarray | DataArray | None = None, intervals: Sequence[Tuple[float, float]] | ndarray | DataArray | None = None, event_labels: Sequence[str] | Dict[float, str] | None = None, interval_labels: Sequence[str] | Dict[Tuple[float, float], str] | None = None, event_style: dict | None = None, interval_style: dict | None = None) → Axes

Overlay events (vertical lines) and intervals (shaded spans).

Parameters:

• ax – Matplotlib Axes to draw on; defaults to plt.gca().

• events – 1D sequence or DataArray of event times.

• intervals – Sequence of (start, end) tuples or DataArray with shape (n, 2).

• event_labels – Optional labels for events (sequence aligned with events or mapping).

• interval_labels – Optional labels for intervals (sequence aligned with intervals or mapping).

• event_style – Optional styling dict passed to ax.axvline.

• interval_style – Optional styling dict passed to ax.axvspan.

aind_ephys_utils.plots.get_color_for_region(region: int | str) → str

Return a hex color string for an Allen region id/name/acronym.

aind_ephys_utils.plots.psth(data: DataArray, *, group_by: str | Sequence[str] | None = None, dim: str = 'trial', method: str = 'mean', compute: bool = True, ax: Axes | None = None, events: Sequence[float] | ndarray | DataArray | None = None, intervals: Sequence[Tuple[float, float]] | ndarray | DataArray | None = None, event_labels: Sequence[str] | Dict[float, str] | None = None, interval_labels: Sequence[str] | Dict[Tuple[float, float], str] | None = None, event_style: dict | None = None, interval_style: dict | None = None, color: str | None = None, alpha: float = 1.0, linewidth: float = 1.5, label: str | None = None, hide_axes: bool = False, x_scale: float | None = None, y_scale: float | None = None, x_scale_text: str | None = None, y_scale_text: str | None = None) → tuple[DataArray, Axes | None]

Plot a PSTH from a binned/continuous DataArray.

Parameters:

• data – Input DataArray. Selection of units/trials should be done upstream. If compute=True and dim is present, ops.psth is used to reduce.

• group_by – Optional trial coord(s) to split and plot conditions.

• dim – Trial dimension to reduce across when compute=True.

• method – Reduction method passed to ops.psth.

• compute – If True, compute the PSTH from data using ops.psth.

• ax – Matplotlib Axes to draw on; created if None.

• events – Optional event times to overlay as vertical lines.

• intervals – Optional intervals to overlay as shaded regions.

• event_labels – Optional labels for events (sequence aligned with events or mapping).

• interval_labels – Optional labels for intervals (sequence aligned with intervals or mapping).

• event_style – Optional styling dict passed to ax.axvline.

• interval_style – Optional styling dict passed to ax.axvspan.

• color – Plot styling options.

• alpha – Plot styling options.

• linewidth – Plot styling options.

• label – Plot styling options.

• hide_axes – If True, hide axes and draw scale bars.

• x_scale – Optional length of x-axis scale bar in data units.

• y_scale – Optional length of y-axis scale bar in data units.

• x_scale_text – Optional label text for the x-axis scale bar.

• y_scale_text – Optional label text for the y-axis scale bar.

Returns:

psth_da is the reduced DataArray; ax is the matplotlib Axes (or None).

Return type:

(psth_da, ax)

aind_ephys_utils.plots.raster(spikes: DataArray, *, group_by: str | Sequence[str] | None = None, color_by: Dict[Any, str] | None = None, sort_by: str | None = None, events: Sequence[float] | ndarray | DataArray | None = None, intervals: Sequence[Tuple[float, float]] | ndarray | DataArray | None = None, event_labels: Sequence[str] | Dict[float, str] | None = None, interval_labels: Sequence[str] | Dict[Tuple[float, float], str] | None = None, event_style: dict | None = None, interval_style: dict | None = None, tlim: tuple[float, float] | None = None, ax: Axes | Sequence[Axes] | None = None, color: str = 'k', linewidth: float = 0.8, markersize: float | None = None, alpha: float | None = 1.0, rasterized: bool = True, show_ylabel: bool = True, unit_gap: int = 3, plot_all_units: bool = False, hide_axes: bool = False, x_scale: float | None = None, y_scale: float | None = None, x_scale_text: str | None = None, y_scale_text: str | None = None) → Axes | ndarray

Raster plot for ragged spike DataArrays.

Parameters:

• spikes – Ragged spike DataArray. Expected dtype=object with a trial dimension. Selection of units/trials should be done upstream.

• group_by – Optional trial coord(s) to split and color trials by condition.

• color_by – Optional mapping from group value or label to colors. Overrides region-based coloring when provided.

• sort_by – Optional trial coord to sort trials by (ascending).

• events – Optional event times to overlay as vertical lines.

• intervals – Optional intervals to overlay as shaded regions.

• event_labels – Optional labels for events (sequence aligned with events or mapping).

• interval_labels – Optional labels for intervals (sequence aligned with intervals or mapping).

• event_style – Optional styling dict passed to ax.axvline.

• interval_style – Optional styling dict passed to ax.axvspan.

• hide_axes – If True, hide axes and draw scale bars.

• x_scale – Optional length of x-axis scale bar in data units.

• y_scale – Optional length of y-axis scale bar in data units.

• x_scale_text – Optional label text for the x-axis scale bar.

• y_scale_text – Optional label text for the y-axis scale bar.

• tlim – Optional (tmin, tmax) for filtering and x-limits.

• ax – Matplotlib Axes to draw on; created if None.

• color – Styling for raster markers.

• linewidth – Styling for raster markers.

• markersize – Styling for raster markers.

• alpha – Styling for raster markers.

• rasterized – If True, rasterize artists for large figures.

• show_ylabel – If True, label y-axis as “trial”.

• unit_gap – Extra blank rows between units when stacking multiple units.

• plot_all_units – If False (default), cap multi-axis plots at 10 units.

Returns:

The matplotlib Axes, or an array of Axes when multiple units are shown.

Return type:

plt.Axes or np.ndarray

aind_ephys_utils.plots.trajectory(data: DataArray, *, group_by: str | Sequence[str] | None = None, component_dim: str = 'component', time_dim: str = 'time', components: Sequence[int] | None = None, ax: Axes | None = None, color: str | None = None, alpha: float = 1.0, linewidth: float = 1.5, label: str | None = None) → Axes

Plot trajectories in low-dimensional space.

Parameters:

• data – Reduced DataArray (e.g., components x time). Selection should be done upstream; this function only plots.

• group_by – Optional trial coord(s) to split and plot conditions.

• component_dim – Name of the component dimension.

• time_dim – Name of the time dimension.

• components – Optional component indices to plot (e.g., [0,1] or [0,1,2]).

• ax – Matplotlib Axes to draw on; created if None.

• color – Plot styling options.

• alpha – Plot styling options.

• linewidth – Plot styling options.

• label – Plot styling options.

Returns:

The matplotlib Axes.

Return type:

plt.Axes