dspk.synapse.io

Probes (site geometry: presets, probe files, channel maps) and sortings (Phy / Kilosort folders, .sorting.zarr, NWB /units).

A Probe follows a recording’s channels: remap applies a channel map (see ops.layout), depth_order gives the map that sorts channels by depth. A Sorting holds units with their spike trains, templates and quality metrics.

probe_of	The probe a recording file carries, if any (SpikeGLX metadata).
read_probe_file	Reads a probe file and the channel map that puts a recording in its contact order.
Probe	A probe’s geometry.
Sorting	A spike sorting.

Functions

probe_of

probe_of(
    path: str | PathLike,
    source: str | None = None,
) -> Probe | None

The probe a recording file carries, if any (SpikeGLX metadata).

Parameters

• path : str or os.PathLike
  The recording.
• source : str, default None
  One of the file’s sources.

Returns

• Probe or None

read_probe_file

read_probe_file(path: str | PathLike) -> tuple[Probe, dict]

Reads a probe file and the channel map that puts a recording in its contact order.

Parameters

• path : str or os.PathLike
  A .json probe: probeinterface or Kilosort 4. .mat files are refused.

Returns

• Probe — The probe, in contact order.
• dict — The channel map that reads a recording in that order.

Raises

• OSError: When the file cannot be read.
• ValueError: When it is not a probe file dspk reads.

Classes

Probe

A probe’s geometry: the position of the site under every recording channel.

Positions are in µm, y is depth. Make one with preset, grid, from_positions, read_probe_file or probe_of.

Examples

>>> import dspk
>>> probe = dspk.synapse.io.Probe.preset("tetrode")
>>> len(probe)
4

Properties

Name	Type	Description
name	str	The probe’s name.
channels	list[int]	The recording channel of every site, in site order.
positions	np.ndarray	Site positions (sites, 3) in µm: x, y (depth), z.
shanks	list[int]	The shank of every site.

Probe.preset

preset(
    name: str,
    *,
    pitch_um: float = DEFAULT_HDEMG_PITCH_UM,
) -> Probe

A nominal layout by name.

Parameters

• name : {"neuropixels1", "neuropixels2", "tetrode", "utah", "hdemg4x8", "hdemg8x8"}
  One of PRESETS.
• pitch_um : float, default DEFAULT_HDEMG_PITCH_UM
  Electrode spacing of the HD-EMG grids, in µm; the other presets ignore it.

Returns

• Probe

Raises

• ValueError: For an unknown name.

Probe.grid

grid(rows: int, cols: int, pitch_um: float) -> Probe

A rows x cols grid; channel row * cols + col sits at (col, row) * pitch_um.

Parameters

• rows : int
  Grid rows.
• cols : int
  Grid columns.
• pitch_um : float
  Electrode spacing, in µm.

Returns

• Probe

Probe.from_positions

from_positions(
    positions,
    *,
    shanks: Sequence[int] | None = None,
    name: str = 'probe',
) -> Probe

Sites at given positions, channel i at row i.

Parameters

• positions : array_like
(channels, 2) or (channels, 3) in µm.
• shanks : sequence of int, default None
  The shank of each site; by default all on one.
• name : str, default 'probe'
  A name for the probe.

Returns

• Probe

Probe.from_json

from_json(text: str) -> Probe

A probe from the JSON to_json writes.

Parameters

• text : str
  The JSON.

Returns

• Probe

Raises

• ValueError: When the JSON is not a probe.

Probe.remap

remap(map) -> Probe

The geometry after a channel map, so it follows a remapped recording.

Parameters

• map : dict, list of dict, str or os.PathLike
  Any form ops.layout.as_map takes.

Returns

• Probe

Raises

• ValueError: When the map is invalid for this probe.

Probe.depth_order

depth_order() -> dict

A channel map that sorts the channels by shank, then depth, then x.

Returns

• dict — {"base", "pairs"}, for ops.layout.remap and remap.

Probe.select

select(channels: Sequence[int]) -> Probe

The sites of some channels, renumbered from 0 in the order given.

Parameters

• channels : sequence of int
  Recording channels to keep.

Returns

• Probe

Probe.neighbours

neighbours(k: int) -> np.ndarray

The k nearest sites of every channel, itself first.

Parameters

• k : int
  Sites per channel.

Returns

• np.ndarray — (channels, k) channel indices.

Probe.to_json

to_json() -> str

The probe as JSON (read back with from_json).

Sorting

A spike sorting: units with their spike trains (sample indices), templates and quality metrics.

Make one with load, from_spikes or synapse.detection.detect_recording.

Examples

>>> import numpy as np
>>> import dspk
>>> s = dspk.synapse.io.Sorting.from_spikes([100, 900, 1500], [0, 1, 0], 30_000.0, 30_000)
>>> s.unit_ids
[0, 1]

Properties

Name	Type	Description
sorter_name	str	Who made the sorting.
sample_rate	float	Sample rate of the recording, in Hz.
total_samples	int	Samples in the recording.
unit_ids	list[int]	The unit ids.
probe	Probe | None	The probe, when the sorting has one.

Sorting.load

load(path: str | PathLike) -> Sorting

Loads a sorting, its format detected from its contents.

Parameters

• path : str or os.PathLike
  A Phy / Kilosort folder, a .sorting.zarr store, or an NWB .nwb.zarr (/units).

Returns

• Sorting

Raises

• OSError: When path does not exist or cannot be read.
• ValueError: When it is not a sorting dspk reads.

Sorting.from_spikes

from_spikes(
    spike_samples,
    spike_units,
    sample_rate: float,
    total_samples: int,
    *,
    sorter_name: str = 'dspk',
    probe: Probe | None = None,
) -> Sorting

A sorting from flat arrays: the sample of every spike and its unit.

Metrics are computed from the spike trains.

Parameters

• spike_samples : array_like
  Sample index of every spike.
• spike_units : array_like
  Unit of every spike.
• sample_rate : float
  Sample rate in Hz.
• total_samples : int
  Samples in the recording (for rates and presence).
• sorter_name : str, default 'dspk'
  Who made it.
• probe : Probe, default None
  The probe the recording was made with.

Returns

• Sorting

Sorting.save

save(path: str | PathLike, format: str | None = None) -> None

Saves the sorting.

Parameters

• path : str or os.PathLike
  Where to write it.
• format : {"phy", "sorting_zarr", "nwb_units"}, default None
  By default from the path’s name: .nwb.zarr → "nwb_units", other .zarr → "sorting_zarr", anything else → "phy" (a folder).

Raises

• OSError: When it cannot be written.

Sorting.spikes

spikes() -> dict[str, np.ndarray]

Every spike, by time.

Returns

• dict of np.ndarray — samples, units, amplitudes (µV) and locations (µm; NaN where not located).

Sorting.spike_train

spike_train(unit_id: int) -> np.ndarray

The spike times of one unit.

Parameters

• unit_id : int
  The unit.

Returns

• np.ndarray — Sample indices, sorted, uint64.

Sorting.template

template(unit_id: int) -> dict | None

The template of one unit, when the sorting has templates.

Parameters

• unit_id : int
  The unit.

Returns

• dict or None — mean, std and se (channels, samples) in µV on channels, count (spikes averaged) and trough_index.

Sorting.units

units() -> dict

One row per unit, as columns.

Returns

• dict of list — unit_id, primary_channel, spikes, firing_rate_hz, snr, isi_violation_ratio, presence_ratio, amplitude_cutoff, composite_score, label.

Constants

Name	Type	Value	Description
DEFAULT_HDEMG_PITCH_UM	float	8000.0
PRESETS		('neuropixels1', 'neuropixels2', 'tetrode', 'utah', 'hdemg4x8', 'hdemg8x8')