API Reference#

class driftplots.DriftPlotter(path_or_analyzer, verbose=True)[source]#

Load Kilosort or SpikeInterface output and plot drift maps.

On construction, spike data is loaded from a Kilosort output directory or a SpikeInterface SortingAnalyzer and stored as read-only arrays.

Parameters:

path_or_analyzer (str | Path) – Path to a Kilosort sorter output directory, or a SpikeInterface SortingAnalyzer object. When a path is given it must contain exactly one kilosort*.log file, which is used to detect the Kilosort version.

drift_map_plot_interactive(decimate='estimate', good_units_only=False, amplitude_cmap_scaling='linear', n_color_bins=20, point_size=5.0, filter_amplitude_mode=None, filter_amplitude_values=(), title=None, verbose=True)[source]#

Create an interactive pyqtgraph-based drift map widget.

Parameters:

  • decimate (int | bool | None | Literal['estimate']) – Thin the spike dataset before plotting. Pass "estimate" to automatically reduce spikes to a reasonable count (≈ 100 000). Pass False, None, or 0 to disable decimation. Pass an integer n to keep every n-th spike.

  • good_units_only (bool | str) – If True, only spikes belonging to “good” units are displayed. For Kilosort, this is taken from the cluster_groups.csv / cluster_group.tsv file that reflects labels set in Phy. For a SortingAnalyzer, a string must be passed. The labels are taken from the sorting property with the passed name (e.g. “KSLabel”).

  • amplitude_cmap_scaling (str | tuple[float, float]) – Controls how spike amplitudes are mapped to the greyscale colormap. Pass "linear" or "log2" or "log10" for automatic scaling, or a (min, max) tuple to set explicit bounds. When explicit bounds are set, the scaling is linear.

  • n_color_bins (int) – Number of discrete greyscale bins used to colour spikes by amplitude.

  • point_size (float) – Diameter of each scatter point in pixels.

  • filter_amplitude_mode (str | None) – Controls how spikes are filtered based on amplitude before plotting. "percentile" treats the bounds as percentile ranks; "absolute" treats them as raw amplitude values. None disables amplitude filtering.

  • filter_amplitude_values (tuple[float, ...]) – (low, high) bounds for amplitude filtering, used as set by filter_amplitude_mode. Ignored when filter_amplitude_mode is None.

  • title (bool | str | None) – Plot title. Pass a string to set a custom title, True to use a default title, or None / False to suppress the title entirely.

  • verbose (bool) – If True, messages are printed.

Returns:

The pyqtgraph widget. The widget is already populated but not yet shown; call app.exec() to display it.

Return type:

DriftmapPlotWidget

drift_map_plot_matplotlib(decimate='estimate', good_units_only=False, amplitude_cmap_scaling='linear', n_color_bins=20, point_size=5.0, filter_amplitude_mode=None, filter_amplitude_values=(), add_histogram_plot=False, weight_histogram_by_amplitude=False, title=None, ax=None, verbose=True)[source]#

Create a static Matplotlib drift map figure.

Parameters:

  • decimate (int | bool | None | Literal['estimate']) – Thin the spike dataset before plotting. Pass "estimate" to automatically reduce spikes to a reasonable count (≈ 100 000). Pass False, None, or 0 to disable decimation. Pass an integer n to keep every n-th spike.

  • good_units_only (bool | str) – If True, only spikes belonging to “good” units are displayed. For Kilosort, this is taken from the cluster_groups.csv / cluster_group.tsv file that reflects labels set in Phy. For a SortingAnalyzer, a string must be passed. The labels are taken from the sorting property with the passed name (e.g. “KSLabel”).

  • amplitude_cmap_scaling (str | tuple[float, float]) – Controls how spike amplitudes are mapped to the greyscale colormap. Pass "linear" or "log2" or "log10" for automatic scaling, or a (min, max) tuple to set explicit bounds. When explicit bounds are set, the scaling is linear.

  • n_color_bins (int) – Number of discrete greyscale bins used to colour spikes by amplitude.

  • point_size (float) – Diameter of each scatter point in pixels.

  • filter_amplitude_mode (str | None) – Controls how spikes are filtered based on amplitude before plotting. "percentile" treats the bounds as percentile ranks; "absolute" treats them as raw amplitude values. None disables amplitude filtering.

  • filter_amplitude_values (tuple[float, ...]) – (low, high) bounds for amplitude filtering, used as set by filter_amplitude_mode. Ignored when filter_amplitude_mode is None.

  • add_histogram_plot (bool) – If True, add a side panel showing a depth histogram of spike activity.

  • weight_histogram_by_amplitude (bool) – If True, weight the depth histogram by spike amplitude rather than counting spikes uniformly. Only used when add_histogram_plot is True.

  • title (bool | str | None) – Plot title. Pass a string to set a custom title, True to use a default title, or None / False to suppress the title entirely.

  • ax (Axes | None) – Existing Matplotlib axis to draw the drift map on. When add_histogram_plot is True, a histogram axis is added beside this axis.

  • verbose (bool) – If True, messages are printed.

Returns:

The populated Matplotlib figure.

Return type:

Figure

class driftplots.MultiSessionDriftmapWidget(panels, grid=None, width=700, height=820)[source]#

A grid container that displays multiple DriftmapPlotWidget panels.

Panels are laid out on an auto-computed (or user-specified) grid and their scatter-plot y-axes are linked so scrolling / zooming in one panel keeps all panels in sync.

Parameters:

  • panels (list[DriftmapPlotWidget]) – Drift-map widgets to arrange in the grid.

  • grid (tuple[int, int] | None) – Explicit (n_rows, n_cols) layout. If None, a roughly square layout is computed automatically.

  • width (int) – Width allocated per panel column (pixels).

  • height (int) – Height allocated per panel row (pixels).

plot()[source]#

Display the widget and start the Qt event loop.

This is a blocking call: it shows the window and runs app.exec() until the window is closed.

driftplots.get_amplitudes(list_of_path_or_analyzer, good_units_only=False, concatenate=False, verbose=True)[source]#

Return spike amplitudes from one or more sorter outputs.

Parameters:

  • list_of_path_or_analyzer (list[Path | SortingAnalyzer]) – Kilosort output directory paths or SpikeInterface SortingAnalyzer objects to load amplitudes from. Can be a mix of both.

  • good_units_only (bool | str) – If True, only spikes belonging to “good” units are displayed. For Kilosort, this is taken from the cluster_groups.csv / cluster_group.tsv file that reflects labels set in Phy. For a SortingAnalyzer, a string must be passed. The labels are taken from the sorting property with the passed name (e.g. “KSLabel”).

  • concatenate (bool) – If True, concatenate all per-session amplitude arrays into a single 1-D array. If False (default), return a list with one array per session.

  • verbose (bool) – If True, messages are printed.

Returns:

When concatenate=True, a single 1-D array of all spike amplitudes. When concatenate=False, a list of 1-D arrays, one per entry in list_of_path_or_analyzer.

Return type:

ndarray | list[ndarray]