aind_ephys_utils.plots.raster module

Raster plot helpers for ragged spike times.

aind_ephys_utils.plots.raster.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