API¶

spikeinterface.core¶

spikeinterface.core.load_extractor(file_or_folder_or_dict, base_folder=None) → BaseExtractor¶

Instantiate extractor from:

a dict
a json file
a pickle file
folder (after save)
a zarr folder (after save)

Parameters

file_or_folder_or_dictdictionary or folder or file (json, pickle): The file path, folder path, or dictionary to load the extractor from
base_folderstr | Path | bool (optional): The base folder to make relative paths absolute. If True and file_or_folder_or_dict is a file, the parent folder of the file is used.

Returns

extractor: Recording or Sorting: The loaded extractor object

class spikeinterface.core.BaseRecording(sampling_frequency: float, channel_ids: list, dtype)¶

Abstract class representing several a multichannel timeseries (or block of raw ephys traces). Internally handle list of RecordingSegment

add_recording_segment(recording_segment)¶

Adds a recording segment.

Parameters

recording_segmentBaseRecordingSegment: The recording segment to add

binary_compatible_with(dtype=None, time_axis=None, file_paths_lenght=None, file_offset=None, file_suffix=None)¶

Check is the recording is binary compatible with some constrain on

dtype

tim_axis

len(file_paths)

file_offset

file_suffix

get_binary_description()¶: When rec.is_binary_compatible() is True this returns a dictionary describing the binary format.

get_duration(segment_index=None) → float¶

Returns the duration in seconds.

Parameters

segment_indexint or None, default: None: The sample index to retrieve the duration for. For multi-segment objects, it is required, default: None With single segment recording returns the duration of the single segment

Returns

float: The duration in seconds

get_memory_size(segment_index=None) → int¶

Returns the memory size of segment_index in bytes.

Parameters

segment_indexint or None, default: None: The index of the segment for which the memory size should be calculated. For multi-segment objects, it is required, default: None With single segment recording returns the memory size of the single segment

Returns

int: The memory size of the specified segment in bytes.

get_num_frames(segment_index=None) → int¶

Returns the number of samples for a segment.

Parameters

segment_indexint or None, default: None: The segment index to retrieve the number of samples for. For multi-segment objects, it is required, default: None With single segment recording returns the number of samples in the segment

Returns

int: The number of samples

get_num_samples(segment_index=None) → int¶

Returns the number of samples for a segment.

Parameters

segment_indexint or None, default: None: The segment index to retrieve the number of samples for. For multi-segment objects, it is required, default: None With single segment recording returns the number of samples in the segment

Returns

int: The number of samples

get_num_segments() → int¶

Returns the number of segments.

Returns

int: Number of segments in the recording

get_time_info(segment_index=None) → dict¶

Retrieves the timing attributes for a given segment index. As with other recorders this method only needs a segment index in the case of multi-segment recordings.

Returns

dict

A dictionary containing the following key-value pairs:

“sampling_frequency”: The sampling frequency of the RecordingSegment.
“t_start”: The start time of the RecordingSegment.
“time_vector”: The time vector of the RecordingSegment.

Notes

The keys are always present, but the values may be None.

get_times(segment_index=None)¶

Get time vector for a recording segment.

If the segment has a time_vector, then it is returned. Otherwise a time_vector is constructed on the fly with sampling frequency. If t_start is defined and the time vector is constructed on the fly, the first time will be t_start. Otherwise it will start from 0.

Parameters

segment_indexint or None, default: None: The segment index (required for multi-segment)

Returns

np.array: The 1d times array

get_total_duration() → float¶

Returns the total duration in seconds

Returns

float: The duration in seconds

get_total_memory_size() → int¶

Returns the sum in bytes of all the memory sizes of the segments.

Returns

int: The total memory size in bytes for all segments.

get_total_samples() → int¶

Returns the sum of the number of samples in each segment.

Returns

int: The total number of samples

Returns traces from recording.

Parameters

segment_indexint | None, default: None: The segment index to get traces from. If recording is multi-segment, it is required, default: None
start_frameint | None, default: None: The start frame. If None, 0 is used, default: None
end_frameint | None, default: None: The end frame. If None, the number of samples in the segment is used, default: None
channel_idslist | np.array | tuple | None, default: None: The channel ids. If None, all channels are used, default: None
order“C” | “F” | None, default: None: The order of the traces (“C” | “F”). If None, traces are returned as they are
return_scaledbool, default: False: If True and the recording has scaling (gain_to_uV and offset_to_uV properties), traces are scaled to uV
cast_unsignedbool, default: False: If True and the traces are unsigned, they are cast to integer and centered (an offset of (2**nbits) is subtracted)

Returns

np.array: The traces (num_samples, num_channels)

Raises

ValueError: If return_scaled is True, but recording does not have scaled traces

has_scaled_traces() → bool¶

Checks if the recording has scaled traces

Returns

bool: True if the recording has scaled traces, False otherwise

has_time_vector(segment_index=None)¶

Check if the segment of the recording has a time vector.

Parameters

segment_indexint or None, default: None: The segment index (required for multi-segment)

Returns

bool: True if the recording has time vectors, False otherwise

is_binary_compatible() → bool¶

Checks if the recording is “binary” compatible. To be used before calling rec.get_binary_description()

Returns

bool: True if the underlying recording is binary

rename_channels(new_channel_ids: list | np.array | tuple)¶

Returns a new recording object with renamed channel ids.

Parameters

new_channel_idslist or np.array or tuple: The new channel ids. They are mapped positionally to the old channel ids.

sample_index_to_time(sample_ind, segment_index=None)¶: Transform sample index into time in seconds

set_times(times, segment_index=None, with_warning=True)¶

Set times for a recording segment.

Parameters

times1d np.array: The time vector
segment_indexint or None, default: None: The segment index (required for multi-segment)
with_warningbool, default: True: If True, a warning is printed

class spikeinterface.core.BaseSorting(sampling_frequency: float, unit_ids: List)¶

Abstract class representing several segment several units and relative spiketrains.

count_num_spikes_per_unit(outputs='dict')¶

For each unit : get number of spikes across segments.

Parameters

outputs: “dict” | “array”, default: “dict”: Control the type of the returned object: a dict (keys are unit_ids) or an numpy array.

Returns

dict or numpy.array: Dict : Dictionary with unit_ids as key and number of spikes as values Numpy array : array of size len(unit_ids) in the same order as unit_ids.

count_total_num_spikes() → int¶

Get total number of spikes in the sorting.

This is the sum of all spikes in all segments across all units.

Returns

total_num_spikes: int: The total number of spike

get_all_spike_trains(outputs='unit_id')¶: Return all spike trains concatenated. This is deprecated and will be removed in spikeinterface 0.102 use sorting.to_spike_vector() instead

get_num_samples(segment_index=None) → int¶

Returns the number of samples of the associated recording for a segment.

Parameters

segment_indexint or None, default: None: The segment index to retrieve the number of samples for. For multi-segment objects, it is required

Returns

int: The number of samples

get_times(segment_index=None)¶

Get time vector for a registered recording segment.

If a recording is registered:

if the segment has a time_vector, then it is returned
if not, a time_vector is constructed on the fly with sampling frequency

If there is no registered recording it returns None

get_total_duration()¶

Returns the total duration in s of the associated recording.

Returns

float: The duration in seconds

get_total_samples() → int¶

Returns the total number of samples of the associated recording.

Returns

int: The total number of samples

has_time_vector(segment_index=None)¶: Check if the segment of the registered recording has a time vector.

precompute_spike_trains(from_spike_vector=None)¶

Pre-computes and caches all spike trains for this sorting

Parameters

from_spike_vector: None | bool, default: None: If None, then it is automatic depending on whether the spike vector is cached. If True, will compute it from the spike vector. If False, will call get_unit_spike_train for each segment for each unit.

register_recording(recording, check_spike_frames=True)¶

Register a recording to the sorting.

Parameters

recordingBaseRecording: Recording with the same number of segments as current sorting. Assigned to self._recording.
check_spike_framesbool, default: True: If True, assert for each segment that all spikes are within the recording’s range.

remove_empty_units()¶

Returns a new sorting object which contains only units with at least one spike. For multi-segments, a unit is considered empty if it contains no spikes in all segments.

Returns

BaseSorting: Sorting object with non-empty units

remove_units(remove_unit_ids) → BaseSorting¶

Returns a new sorting object with contains only a selected subset of units.

Parameters

remove_unit_idsnumpy.array or list: List of unit ids to remove

Returns

BaseSorting: Sorting without the removed units

rename_units(new_unit_ids: numpy.ndarray | list) → BaseSorting¶

Returns a new sorting object with renamed units.

Parameters

new_unit_idsnumpy.array or list: List of new names for unit ids. They should map positionally to the existing unit ids.

Returns

BaseSorting: Sorting object with renamed units

select_units(unit_ids, renamed_unit_ids=None) → BaseSorting¶

Returns a new sorting object which contains only a selected subset of units.

Parameters

unit_idsnumpy.array or list: List of unit ids to keep
renamed_unit_idsnumpy.array or list, default: None: If given, the kept unit ids are renamed

Returns

BaseSorting: Sorting object with selected units

to_multiprocessing(n_jobs)¶

When necessary turn sorting object into: * NumpySorting when n_jobs=1 * SharedMemorySorting when n_jobs>1

If the sorting is already NumpySorting, SharedMemorySorting or NumpyFolderSorting then this return the sortign itself, no transformation so.

Parameters

n_jobs: int: The number of jobs.
Returns
——-
sharable_sorting:: A sorting that can be used for multiprocessing.

to_numpy_sorting(propagate_cache=True)¶

Turn any sorting in a NumpySorting. useful to have it in memory with a unique vector representation.

Parameters

propagate_cachebool: Propagate the cache of indivudual spike trains.

to_shared_memory_sorting()¶: Turn any sorting in a SharedMemorySorting. Usefull to have it in memory with a unique vector representation and sharable across processes.

to_spike_vector(concatenated=True, extremum_channel_inds=None, use_cache=True) → numpy.ndarray | list[numpy.ndarray]¶

Construct a unique structured numpy vector concatenating all spikes with several fields: sample_index, unit_index, segment_index.

Parameters

concatenated: bool, default: True: With concatenated=True the output is one numpy “spike vector” with spikes from all segments. With concatenated=False the output is a list “spike vector” by segment.
extremum_channel_inds: None or dict, default: None: If a dictionnary of unit_id to channel_ind is given then an extra field “channel_index”. This can be convinient for computing spikes postion after sorter. This dict can be computed with get_template_extremum_channel(we, outputs=”index”)
use_cache: bool, default: True: When True the spikes vector is cached as an attribute of the object (_cached_spike_vector). This caching only occurs when extremum_channel_inds=None.

Returns

spikes: np.array: Structured numpy array (“sample_index”, “unit_index”, “segment_index”) with all spikes Or (“sample_index”, “unit_index”, “segment_index”, “channel_index”) if extremum_channel_inds is given

class spikeinterface.core.BaseSnippets(sampling_frequency: float, nbefore: Optional[int], snippet_len: int, channel_ids: list, dtype)¶: Abstract class representing several multichannel snippets.

class spikeinterface.core.BaseEvent(channel_ids, structured_dtype)¶

Abstract class representing events.

Parameters

channel_idslist or np.array: The channel ids
structured_dtypedtype or dict: The dtype of the events. If dict, each key is the channel_id and values must be the dtype of the channel (also structured). If dtype, each channel is assigned the same dtype. In case of structured dtypes, the “time” or “timestamp” field name must be present.

get_event_times(channel_id: Optional[Union[int, str]] = None, segment_index: Optional[int] = None, start_time: Optional[float] = None, end_time: Optional[float] = None)¶

Return events timestamps of a channel in seconds.

Parameters

channel_idint | str | None, default: None: The event channel id
segment_indexint | None, default: None: The segment index, required for multi-segment objects
start_timefloat | None, default: None: The start time in seconds
end_timefloat | None, default: None: The end time in seconds

Returns

np.array: 1d array of timestamps for the event channel

get_events(channel_id: Optional[Union[int, str]] = None, segment_index: Optional[int] = None, start_time: Optional[float] = None, end_time: Optional[float] = None)¶

Return events of a channel in its native structured type.

Parameters

channel_idint | str | None, default: None: The event channel id
segment_indexint | None, default: None: The segment index, required for multi-segment objects
start_timefloat | None, default: None: The start time in seconds
end_timefloat | None, default: None: The end time in seconds

Returns

np.array: Structured np.array of dtype get_dtype(channel_id)

class spikeinterface.core.WaveformExtractor(recording: Optional[BaseRecording], sorting: BaseSorting, folder=None, rec_attributes=None, allow_unfiltered: bool = False, sparsity=None)¶

Class to extract waveform on paired Recording-Sorting objects. Waveforms are persistent on disk and cached in memory.

Parameters

recording: Recording | None: The recording object
sorting: Sorting: The sorting object
folder: Path: The folder where waveforms are cached
rec_attributes: None or dict: When recording is None then a minimal dict with some attributes is needed.
allow_unfiltered: bool, default: False: If true, will accept unfiltered recording.
Returns
——-
we: WaveformExtractor: The WaveformExtractor object

Examples

>>> # Instantiate
>>> we = WaveformExtractor.create(recording, sorting, folder)

>>> # Compute
>>> we = we.set_params(...)
>>> we = we.run_extract_waveforms(...)

>>> # Retrieve
>>> waveforms = we.get_waveforms(unit_id)
>>> template = we.get_template(unit_id, mode="median")

>>> # Load  from folder (in another session)
>>> we = WaveformExtractor.load(folder)

delete_extension(extension_name) → None¶

Deletes an existing extension.

Parameters

extension_name: str: The extension name.

delete_waveforms() → None¶: Deletes waveforms folder.

get_all_templates(unit_ids: list | np.array | tuple | None = None, mode='average', percentile: float | None = None)¶

Return templates (average waveforms) for multiple units.

Parameters

unit_ids: list or None: Unit ids to retrieve waveforms for
mode: “average” | “median” | “std” | “percentile”, default: “average”: The mode to compute the templates
percentile: float, default: None: Percentile to use for mode=”percentile”

Returns

templates: np.array: The returned templates (num_units, num_samples, num_channels)

get_available_extension_names()¶

Return a list of loaded or available extension names either in memory or in persistent extension folders. Then instances can be loaded with we.load_extension(extension_name)

Importante note: extension modules need to be loaded (and so registered) before this call, otherwise extensions will be ignored even if the folder exists.

Returns

extension_names_in_folder: list: A list of names of computed extension in this folder

get_extension_class(extension_name: str)¶

Get extension class from name and check if registered.

Parameters

extension_name: str: The extension name.

Returns

ext_class:: The class of the extension.

get_sampled_indices(unit_id)¶

Return sampled spike indices of extracted waveforms

Parameters

unit_id: int or str: Unit id to retrieve indices for

Returns

sampled_indices: np.array: The sampled indices

get_template(unit_id, mode='average', sparsity=None, force_dense: bool = False, percentile: Optional[float] = None)¶

Return template (average waveform).

Parameters

unit_id: int or str: Unit id to retrieve waveforms for
mode: “average” | “median” | “std” | “percentile”, default: “average”: The mode to compute the template
sparsity: ChannelSparsity, default: None: Sparsity to apply to the waveforms (if WaveformExtractor is not sparse)
force_dense: bool, default: False: Return a dense template even if the waveform extractor is sparse
percentile: float, default: None: Percentile to use for mode=”percentile”. Values must be between 0 and 100 inclusive

Returns

template: np.array: The returned template (num_samples, num_channels)

get_template_segment(unit_id, segment_index, mode='average', sparsity=None)¶

Return template for the specified unit id computed from waveforms of a specific segment.

Parameters

unit_id: int or str: Unit id to retrieve waveforms for
segment_index: int: The segment index to retrieve template from
mode: “average” | “median” | “std”, default: “average”: The mode to compute the template
sparsity: ChannelSparsity, default: None: Sparsity to apply to the waveforms (if WaveformExtractor is not sparse).

Returns

template: np.array: The returned template (num_samples, num_channels)

get_waveforms(unit_id, with_index: bool = False, cache: bool = False, lazy: bool = True, sparsity=None, force_dense: bool = False)¶

Return waveforms for the specified unit id.

Parameters

unit_id: int or str: Unit id to retrieve waveforms for
with_index: bool, default: False: If True, spike indices of extracted waveforms are returned
cache: bool, default: False: If True, waveforms are cached to the self._waveforms dictionary
lazy: bool, default: True: If True, waveforms are loaded as memmap objects (when format=”binary”) or Zarr datasets (when format=”zarr”). If False, waveforms are loaded as np.array objects
sparsity: ChannelSparsity, default: None: Sparsity to apply to the waveforms (if WaveformExtractor is not sparse)
force_dense: bool, default: False: Return dense waveforms even if the waveform extractor is sparse

Returns

wfs: np.array: The returned waveform (num_spikes, num_samples, num_channels)
indices: np.array: If “with_index” is True, the spike indices corresponding to the waveforms extracted

get_waveforms_segment(segment_index: int, unit_id, sparsity)¶

Return waveforms from a specified segment and unit_id.

Parameters

segment_index: int: The segment index to retrieve waveforms from
unit_id: int or str: Unit id to retrieve waveforms for
sparsity: ChannelSparsity, default: None: Sparsity to apply to the waveforms (if WaveformExtractor is not sparse)

Returns

wfs: np.array: The returned waveform (num_spikes, num_samples, num_channels)

has_extension(extension_name: str) → bool¶

Check if the extension exists in memory or in the folder.

Parameters

extension_name: str: The extension name.

Returns

exists: bool: Whether the extension exists or not

load_extension(extension_name: str)¶

Load an extension from its name. The module of the extension must be loaded and registered.

Parameters

extension_name: str: The extension name.

Returns

ext_instanace:: The loaded instance of the extension

precompute_templates(modes=('average', 'std', 'median', 'percentile'), percentile=None) → None¶

Precompute all templates for different “modes”:

average
std
median
percentile

Parameters

modes: list: The modes to compute the templates
percentile: float, default: None: Percentile to use for mode=”percentile”
The results is cached in memory as a 3d ndarray (nunits, nsamples, nchans)
and also saved as an npy file in the folder to avoid recomputation each time.

classmethod register_extension(extension_class) → None¶

This maintains a list of possible extensions that are available. It depends on the imported submodules (e.g. for postprocessing module).

For instance: import spikeinterface as si si.WaveformExtractor.extensions == []

from spikeinterface.postprocessing import WaveformPrincipalComponent si.WaveformExtractor.extensions == [WaveformPrincipalComponent, …]

save(folder, format='binary', use_relative_path: bool = False, overwrite: bool = False, sparsity=None, **kwargs) → WaveformExtractor¶

Save WaveformExtractor object to disk.

Parameters

folderstr or Path: The output waveform folder
format“binary” | “zarr”, default: “binary”: The backend to use for saving the waveforms
overwritebool: If True and folder exists, it is deleted, default: False
use_relative_pathbool, default: False: If True, the recording and sorting paths are relative to the waveforms folder. This allows portability of the waveform folder provided that the relative paths are the same, but forces all the data files to be in the same drive
sparsityChannelSparsity, default: None: If given and WaveformExtractor is not sparse, it makes the returned WaveformExtractor sparse

select_units(unit_ids, new_folder=None, use_relative_path: bool = False) → WaveformExtractor¶

Filters units by creating a new waveform extractor object in a new folder.

Extensions are also updated to filter the selected unit ids.

Parameters

unit_idslist or array: The unit ids to keep in the new WaveformExtractor object
new_folderPath or None: The new folder where selected waveforms are copied

Returns

weWaveformExtractor: The newly create waveform extractor with the selected units

set_params(ms_before: float = 1.0, ms_after: float = 2.0, max_spikes_per_unit: int = 500, return_scaled: bool = False, dtype=None) → None¶

Set parameters for waveform extraction

Parameters

ms_before: float: Cut out in ms before spike time
ms_after: float: Cut out in ms after spike time
max_spikes_per_unit: int: Maximum number of spikes to extract per unit
return_scaled: bool: If True and recording has gain_to_uV/offset_to_uV properties, waveforms are converted to uV.
dtype: np.dtype: The dtype of the computed waveforms

set_recording(recording: Optional[BaseRecording], rec_attributes: Optional[dict] = None, allow_unfiltered: bool = False) → None¶

Sets the recording object and attributes for the WaveformExtractor.

Parameters

recording: Recording | None: The recording object
rec_attributes: None or dict: When recording is None then a minimal dict with some attributes is needed.
allow_unfiltered: bool, default: False: If true, will accept unfiltered recording.

spikeinterface.core.extract_waveforms(recording, sorting, folder=None, mode='folder', precompute_template=('average',), ms_before=1.0, ms_after=2.0, max_spikes_per_unit=500, overwrite=False, return_scaled=True, dtype=None, sparse=True, sparsity=None, sparsity_temp_folder=None, num_spikes_for_sparsity=100, unit_batch_size=200, allow_unfiltered=False, use_relative_path=False, seed=None, load_if_exists=None, **kwargs)¶

Extracts waveform on paired Recording-Sorting objects. Waveforms can be persistent on disk (mode`=”folder”) or in-memory (`mode`=”memory”). By default, waveforms are extracted on a subset of the spikes (`max_spikes_per_unit) and on all channels (dense). If the sparse parameter is set to True, a sparsity is estimated using a small number of spikes (num_spikes_for_sparsity) and waveforms are extracted and saved in sparse mode.

Parameters

recording: Recording

The recording object

sorting: Sorting

The sorting object

folder: str or Path or None, default: None

The folder where waveforms are cached

mode: “folder” | “memory, default: “folder”

The mode to store waveforms. If “folder”, waveforms are stored on disk in the specified folder. The “folder” argument must be specified in case of mode “folder”. If “memory” is used, the waveforms are stored in RAM. Use this option carefully!

precompute_template: None or list, default: [“average”]

Precompute average/std/median for template. If None, no templates are precomputed

ms_before: float, default: 1.0

Time in ms to cut before spike peak

ms_after: float, default: 2.0

Time in ms to cut after spike peak

max_spikes_per_unit: int or None, default: 500

Number of spikes per unit to extract waveforms from Use None to extract waveforms for all spikes

overwrite: bool, default: False

If True and “folder” exists, the folder is removed and waveforms are recomputed Otherwise an error is raised.

return_scaled: bool, default: True

If True and recording has gain_to_uV/offset_to_uV properties, waveforms are converted to uV

dtype: dtype or None, default: None

Dtype of the output waveforms. If None, the recording dtype is maintained

sparse: bool, default: True

If True, before extracting all waveforms the precompute_sparsity() function is run using a few spikes to get an estimate of dense templates to create a ChannelSparsity object. Then, the waveforms will be sparse at extraction time, which saves a lot of memory. When True, you must some provide kwargs handle precompute_sparsity() to control the kind of sparsity you want to apply (by radius, by best channels, …).

sparsity: ChannelSparsity or None, default: None

The sparsity used to compute waveforms. If this is given, sparse is ignored. Default None.

sparsity_temp_folder: str or Path or None, default: None

If sparse is True, this is the temporary folder where the dense waveforms are temporarily saved. If None, dense waveforms are extracted in memory in batches (which can be controlled by the unit_batch_size parameter. With a large number of units (e.g., > 400), it is advisable to use a temporary folder.

num_spikes_for_sparsity: int, default: 100

The number of spikes to use to estimate sparsity (if sparse=True).

unit_batch_size: int, default: 200

The number of units to process at once when extracting dense waveforms (if sparse=True and sparsity_temp_folder is None).

allow_unfiltered: bool

If true, will accept an allow_unfiltered recording.

use_relative_path: bool, default: False

If True, the recording and sorting paths are relative to the waveforms folder. This allows portability of the waveform folder provided that the relative paths are the same, but forces all the data files to be in the same drive.

seed: int or None, default: None

Random seed for spike selection

sparsity kwargs:

method: str

“best_channels”: N best channels with the largest amplitude. Use the “num_channels” argument to specify the
number of channels.
“radius”: radius around the best channel. Use the “radius_um” argument to specify the radius in um
“snr”: threshold based on template signal-to-noise ratio. Use the “threshold” argument
to specify the SNR threshold (in units of noise levels)
“ptp”: threshold based on the peak-to-peak values on every channels. Use the “threshold” argument
to specify the ptp threshold (in units of noise levels)
“energy”: threshold based on the expected energy that should be present on the channels,
given their noise levels. Use the “threshold” argument to specify the SNR threshold (in units of noise levels)
“by_property”: sparsity is given by a property of the recording and sorting(e.g. “group”).
Use the “by_property” argument to specify the property name.

peak_sign: str

Sign of the template to compute best channels (“neg”, “pos”, “both”)

num_channels: int

Number of channels for “best_channels” method

radius_um: float

Radius in um for “radius” method

threshold: float

Threshold in SNR “threshold” method

by_property: object

Property name for “by_property” method

job kwargs:

**job_kwargs: keyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
  Number of samples per chunk
- chunk_memory: str
  Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
  Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
  Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
progress_bar: bool
If True, a progress bar is printed
mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems

Returns

we: WaveformExtractor: The WaveformExtractor object

Examples

>>> import spikeinterface as si

>>> # Extract dense waveforms and save to disk
>>> we = si.extract_waveforms(recording, sorting, folder="waveforms")

>>> # Extract dense waveforms with parallel processing and save to disk
>>> job_kwargs = dict(n_jobs=8, chunk_duration="1s", progress_bar=True)
>>> we = si.extract_waveforms(recording, sorting, folder="waveforms", **job_kwargs)

>>> # Extract dense waveforms on all spikes
>>> we = si.extract_waveforms(recording, sorting, folder="waveforms-all", max_spikes_per_unit=None)

>>> # Extract dense waveforms in memory
>>> we = si.extract_waveforms(recording, sorting, folder=None, mode="memory")

>>> # Extract sparse waveforms (with radius-based sparsity of 50um) and save to disk
>>> we = si.extract_waveforms(recording, sorting, folder="waveforms-sparse", mode="folder",
>>>                           sparse=True, num_spikes_for_sparsity=100, method="radius", radius_um=50)

spikeinterface.core.load_waveforms(folder, with_recording: bool = True, sorting: Optional[BaseSorting] = None) → WaveformExtractor¶

Load a waveform extractor object from disk.

Parameters

folderstr or Path: The folder / zarr folder where the waveform extractor is stored
with_recordingbool, default: True: If True, the recording is loaded. If False, the WaveformExtractor object in recordingless mode.
sortingBaseSorting, default: None: If passed, the sorting object associated to the waveform extractor

Returns

we: WaveformExtractor: The loaded waveform extractor

spikeinterface.core.compute_sparsity(templates_or_waveform_extractor, method='radius', peak_sign='neg', num_channels=5, radius_um=100.0, threshold=5, by_property=None)¶

Get channel sparsity (subset of channels) for each template with several methods.

Parameters

templates_or_waveform_extractor: Templates | WaveformExtractor

A Templates or a WaveformExtractor object. Some methods accept both objects (e.g. “best_channels”, “radius”, ) Other methods need WaveformExtractor because internally the recording is needed.

method: str

“best_channels”: N best channels with the largest amplitude. Use the “num_channels” argument to specify the
number of channels.
“radius”: radius around the best channel. Use the “radius_um” argument to specify the radius in um
“snr”: threshold based on template signal-to-noise ratio. Use the “threshold” argument
to specify the SNR threshold (in units of noise levels)
“ptp”: threshold based on the peak-to-peak values on every channels. Use the “threshold” argument
to specify the ptp threshold (in units of noise levels)
“energy”: threshold based on the expected energy that should be present on the channels,
given their noise levels. Use the “threshold” argument to specify the SNR threshold (in units of noise levels)
“by_property”: sparsity is given by a property of the recording and sorting(e.g. “group”).
Use the “by_property” argument to specify the property name.

peak_sign: str

Sign of the template to compute best channels (“neg”, “pos”, “both”)

num_channels: int

Number of channels for “best_channels” method

radius_um: float

Radius in um for “radius” method

threshold: float

Threshold in SNR “threshold” method

by_property: object

Property name for “by_property” method

Returns

sparsity: ChannelSparsity: The estimated sparsity

class spikeinterface.core.ChannelSparsity(mask, unit_ids, channel_ids)¶

Handle channel sparsity for a set of units. That is, for every unit, it indicates which channels are used to represent the waveform and the rest of the non-represented channels are assumed to be zero.

Internally, sparsity is stored as a boolean mask.

The ChannelSparsity object can also provide other sparsity representations:

ChannelSparsity.unit_id_to_channel_ids : unit_id to channel_ids

ChannelSparsity.unit_id_to_channel_indices : unit_id channel_inds

By default it is constructed with a boolean array:

>>> sparsity = ChannelSparsity(mask, unit_ids, channel_ids)

But can be also constructed from a dictionary:

>>> sparsity = ChannelSparsity.from_unit_id_to_channel_ids(unit_id_to_channel_ids, unit_ids, channel_ids)

Parameters

mask: np.array of bool: The sparsity mask (num_units, num_channels)
unit_ids: list or array: Unit ids vector or list
channel_ids: list or array: Channel ids vector or list

Examples

The class can also be used to construct/estimate the sparsity from a Waveformextractor with several methods:

Using the N best channels (largest template amplitude):

>>> sparsity = ChannelSparsity.from_best_channels(we, num_channels, peak_sign="neg")

Using a neighborhood by radius:

>>> sparsity = ChannelSparsity.from_radius(we, radius_um, peak_sign="neg")

Using a SNR threshold: >>> sparsity = ChannelSparsity.from_snr(we, threshold, peak_sign=”neg”)

Using a template energy threshold: >>> sparsity = ChannelSparsity.from_energy(we, threshold)

Using a recording/sorting property (e.g. “group”):

>>> sparsity = ChannelSparsity.from_property(we, by_property="group")

classmethod create_dense(we)¶: Create a sparsity object with all selected channel for all units.

densify_waveforms(waveforms: ndarray, unit_id: str | int) → ndarray¶

Densify sparse waveforms that were sparisified according to a unit’s channel sparsity.

Given a unit_id its sparsified waveform, this method places the waveform back into its original form within a dense array.

Parameters

waveformsnp.array: The sparsified waveforms array of shape (num_waveforms, num_samples, num_active_channels) or a single sparse waveform (template) with shape (num_samples, num_active_channels).
unit_idstr: The unit_id that was used to sparsify the waveform.

Returns

densified_waveformsnp.array: The densified waveforms array of shape (num_waveforms, num_samples, num_channels) or a single dense waveform (template) with shape (num_samples, num_channels).

classmethod from_best_channels(templates_or_we, num_channels, peak_sign='neg')¶: Construct sparsity from N best channels with the largest amplitude. Use the “num_channels” argument to specify the number of channels.

classmethod from_energy(we, threshold)¶: Construct sparsity from a threshold based on per channel energy ratio. Use the “threshold” argument to specify the SNR threshold.

classmethod from_property(we, by_property)¶: Construct sparsity witha property of the recording and sorting(e.g. “group”). Use the “by_property” argument to specify the property name.

classmethod from_ptp(we, threshold)¶: Construct sparsity from a thresholds based on template peak-to-peak values. Use the “threshold” argument to specify the SNR threshold.

classmethod from_radius(templates_or_we, radius_um, peak_sign='neg')¶: Construct sparsity from a radius around the best channel. Use the “radius_um” argument to specify the radius in um

classmethod from_snr(we, threshold, peak_sign='neg')¶: Construct sparsity from a thresholds based on template signal-to-noise ratio. Use the “threshold” argument to specify the SNR threshold.

classmethod from_unit_id_to_channel_ids(unit_id_to_channel_ids, unit_ids, channel_ids)¶: Create a sparsity object from dict unit_id to channel_ids.

sparsify_waveforms(waveforms: ndarray, unit_id: str | int) → ndarray¶

Sparsify the waveforms according to a unit_id corresponding sparsity.

Given a unit_id, this method selects only the active channels for that unit and removes the rest.

Parameters

waveformsnp.array: Dense waveforms with shape (num_waveforms, num_samples, num_channels) or a single dense waveform (template) with shape (num_samples, num_channels).
unit_idstr: The unit_id for which to sparsify the waveform.

Returns

sparsified_waveformsnp.array: Sparse waveforms with shape (num_waveforms, num_samples, num_active_channels) or a single sparsified waveform (template) with shape (num_samples, num_active_channels).

to_dict()¶: Return a serializable dict.

class spikeinterface.core.BinaryRecordingExtractor(file_paths, sampling_frequency, dtype, num_channels=None, t_starts=None, channel_ids=None, time_axis=0, file_offset=0, gain_to_uV=None, offset_to_uV=None, is_filtered=None, num_chan=None)¶

RecordingExtractor for a binary format

Parameters

file_paths: str or Path or list: Path to the binary file
sampling_frequency: float: The sampling frequency
num_channels: int: Number of channels
num_chan: int [deprecated, use num_channels instead, will be removed as early as v0.100.0]: Number of channels
dtype: str or dtype: The dtype of the binary file
time_axis: int, default: 0: The axis of the time dimension
t_starts: None or list of float, default: None: Times in seconds of the first sample for each segment
channel_ids: list, default: None: A list of channel ids
file_offset: int, default: 0: Number of bytes in the file to offset by during memmap instantiation.
gain_to_uV: float or array-like, default: None: The gain to apply to the traces
offset_to_uV: float or array-like, default: None: The offset to apply to the traces
is_filtered: bool or None, default: None: If True, the recording is assumed to be filtered. If None, is_filtered is not set.

Returns

recording: BinaryRecordingExtractor: The recording Extractor

Notes

When both num_channels and num_chan are provided, num_channels is used and num_chan is ignored.

class spikeinterface.core.ZarrRecordingExtractor(folder_path: pathlib.Path | str, storage_options: Optional[dict] = None)¶

RecordingExtractor for a zarr format

Parameters

folder_path: str or Path: Path to the zarr root folder
storage_options: dict or None: Storage options for zarr store. E.g., if “s3://” or “gcs://” they can provide authentication methods, etc.

Returns

recording: ZarrRecordingExtractor: The recording Extractor

class spikeinterface.core.BinaryFolderRecording(folder_path)¶

BinaryFolderRecording is an internal format used in spikeinterface. It is a BinaryRecordingExtractor + metadata contained in a folder.

It is created with the function: recording.save(format=”binary”, folder=”/myfolder”)

Parameters

folder_path: str or Path

Returns

recording: BinaryFolderRecording: The recording

class spikeinterface.core.NpzFolderSorting(folder_path)¶

NpzFolderSorting is the old internal format used in spikeinterface (<=0.98.0)

This a folder that contains:

“sorting_cached.npz” file in the NpzSortingExtractor format

“npz.json” which the json description of NpzSortingExtractor

a metadata folder for units properties.

It is created with the function: sorting.save(folder=”/myfolder”, format=”npz_folder”)

Parameters

folder_path: str or Path

Returns

sorting: NpzFolderSorting: The sorting

class spikeinterface.core.NpyFolderSnippets(folder_path)¶

NpyFolderSnippets is an internal format used in spikeinterface. It is a NpySnippetsExtractor + metadata contained in a folder.

It is created with the function: snippets.save(format=”npy”, folder=”/myfolder”)

Parameters

folder_path: str or Path: The path to the folder

Returns

snippets: NpyFolderSnippets: The snippets

class spikeinterface.core.NumpyRecording(traces_list, sampling_frequency, t_starts=None, channel_ids=None)¶

In memory recording. Contrary to previous version this class does not handle npy files.

Parameters

traces_list: list of array or array (if mono segment): The traces to instantiate a mono or multisegment Recording
sampling_frequency: float: The sampling frequency in Hz
t_starts: None or list of float: Times in seconds of the first sample for each segment
channel_ids: list: An optional list of channel_ids. If None, linear channels are assumed

class spikeinterface.core.NumpySorting(spikes, sampling_frequency, unit_ids)¶

In memory sorting object. The internal representation is always done with a long “spike vector”.

But we have convenient class methods to instantiate from:

other sorting object: NumpySorting.from_sorting()
from time+labels: NumpySorting.from_times_labels()
from dict of list: NumpySorting.from_unit_dict()
from neo: NumpySorting.from_neo_spiketrain_list()

Parameters

spikes: numpy.array: A numpy vector, the one given by Sorting.to_spike_vector().
sampling_frequency: float: The sampling frequency in Hz
channel_ids: list: A list of unit_ids.

class spikeinterface.core.NumpySnippets(snippets_list, spikesframes_list, sampling_frequency, nbefore=None, channel_ids=None)¶

In memory recording. Contrary to previous version this class does not handle npy files.

Parameters

snippets_list: list of array or array (if mono segment): The snippets to instantiate a mono or multisegment basesnippet
spikesframes_list: list of array or array (if mono segment): Frame of each snippet
sampling_frequency: float: The sampling frequency in Hz
channel_ids: list: An optional list of channel_ids. If None, linear channels are assumed

class spikeinterface.core.AppendSegmentRecording(recording_list, sampling_frequency_max_diff=0)¶

Takes as input a list of parent recordings each with multiple segments and returns a single multi-segment recording that “appends” all segments from all parent recordings.

For instance, given one recording with 2 segments and one recording with 3 segments, this class will give one recording with 5 segments

Parameters

recording_listlist of BaseRecording: A list of recordings
sampling_frequency_max_difffloat, default: 0: Maximum allowed difference of sampling frequencies across recordings

class spikeinterface.core.ConcatenateSegmentRecording(recording_list, ignore_times=True, sampling_frequency_max_diff=0)¶

Return a recording that “concatenates” all segments from all parent recordings into one recording with a single segment. The operation is lazy.

For instance, given one recording with 2 segments and one recording with 3 segments, this class will give one recording with one large segment made by concatenating the 5 segments.

Time information is lost upon concatenation. By default ignore_times is True. If it is False, you get an error unless:

all segments DO NOT have times, AND

all segment have t_start=None

Parameters

recording_listlist of BaseRecording: A list of recordings
ignore_times: bool, default: True: If True, time information (t_start, time_vector) is ignored when concatenating recordings
sampling_frequency_max_difffloat, default: 0: Maximum allowed difference of sampling frequencies across recordings

class spikeinterface.core.SelectSegmentRecording(recording: BaseRecording, segment_indices: int | list[int])¶

Return a new recording with a subset of segments from a multi-segment recording.

Parameters

recordingBaseRecording: The multi-segment recording
segment_indicesint | list[int]: The segment indices to select

class spikeinterface.core.AppendSegmentSorting(sorting_list, sampling_frequency_max_diff=0)¶

Return a sorting that “append” all segments from all sorting into one sorting multi segment.

Parameters

sorting_listlist of BaseSorting: A list of sortings
sampling_frequency_max_difffloat, default: 0: Maximum allowed difference of sampling frequencies across sortings

class spikeinterface.core.SplitSegmentSorting(parent_sorting: BaseSorting, recording_or_recording_list=None)¶

Splits a sorting with a single segment to multiple segments based on the given list of recordings (must be in order)

Parameters

parent_sortingBaseSorting: Sorting with a single segment (e.g. from sorting concatenated recording)
recording_or_recording_listlist of recordings, ConcatenateSegmentRecording, or None, default: None: If list of recordings, uses the lengths of those recordings to split the sorting into smaller segments If ConcatenateSegmentRecording, uses the associated list of recordings to split the sorting into smaller segments If None, looks for the recording associated with the sorting

class spikeinterface.core.SelectSegmentSorting(sorting: BaseSorting, segment_indices: int | list[int])¶

Return a new sorting with a single segment from a multi-segment sorting.

Parameters

sortingBaseSorting: The multi-segment sorting
segment_indicesint | list[int]: The segment indices to select

spikeinterface.core.download_dataset(repo: str = 'https://gin.g-node.org/NeuralEnsemble/ephy_testing_data', remote_path: str = 'mearec/mearec_test_10s.h5', local_folder: Optional[Path] = None, update_if_exists: bool = False, unlock: bool = False) → Path¶

Function to download dataset from a remote repository using datalad.

Parameters

repostr, default: “https://gin.g-node.org/NeuralEnsemble/ephy_testing_data”: The repository to download the dataset from
remote_pathstr, default: “mearec/mearec_test_10s.h5”: A specific subdirectory in the repository to download (e.g. Mearec, SpikeGLX, etc)
local_folderstr, default: None: The destination folder / directory to download the dataset to. defaults to the path “get_global_dataset_folder()” / f{repo_name} (see spikeinterface.core.globals)
update_if_existsbool, default: False: Forces re-download of the dataset if it already exists, default: False
unlockbool, default: False: Use to enable the edition of the downloaded file content, default: False

Returns

Path: The local path to the downloaded dataset

spikeinterface.core.write_binary_recording(recording, file_paths, dtype=None, add_file_extension=True, byte_offset=0, auto_cast_uint=True, **job_kwargs)¶

Save the trace of a recording extractor in several binary .dat format.

Note :: time_axis is always 0 (contrary to previous version. to get time_axis=1 (which is a bad idea) use write_binary_recording_file_handle()

Parameters

recording: RecordingExtractor

The recording extractor object to be saved in .dat format

file_path: str or list[str]

The path to the file.

dtype: dtype or None, default: None

Type of the saved data If True, file the “.raw” file extension is added if the file name is not a “raw”, “bin”, or “dat”

byte_offset: int, default: 0

Offset in bytes for the binary file (e.g. to write a header)

auto_cast_uint: bool, default: True

If True, unsigned integers are automatically cast to int if the specified dtype is signed

**job_kwargs: keyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
  Number of samples per chunk
- chunk_memory: str
  Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
  Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
  Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
progress_bar: bool
If True, a progress bar is printed
mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems

spikeinterface.core.set_global_tmp_folder(folder)¶: Set the global path temporary folder.

spikeinterface.core.set_global_dataset_folder(folder)¶: Set the global dataset folder.

spikeinterface.core.set_global_job_kwargs(**job_kwargs)¶

Set the global job kwargs.

Parameters

**job_kwargs: keyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
  Number of samples per chunk
- chunk_memory: str
  Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
  Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
  Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
progress_bar: bool
If True, a progress bar is printed
mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems

spikeinterface.core.get_random_data_chunks(recording, return_scaled=False, num_chunks_per_segment=20, chunk_size=10000, concatenated=True, seed=0, margin_frames=0)¶

Extract random chunks across segments

This is used for instance in get_noise_levels() to estimate noise on traces.

Parameters

recording: BaseRecording: The recording to get random chunks from
return_scaled: bool, default: False: If True, returned chunks are scaled to uV
num_chunks_per_segment: int, default: 20: Number of chunks per segment
chunk_size: int, default: 10000: Size of a chunk in number of frames
concatenated: bool, default: True: If True chunk are concatenated along time axis
seed: int, default: 0: Random seed
margin_frames: int, default: 0: Margin in number of frames to avoid edge effects

Returns

chunk_list: np.array: Array of concatenate chunks per segment

spikeinterface.core.get_channel_distances(recording)¶: Distance between channel pairs

spikeinterface.core.get_closest_channels(recording, channel_ids=None, num_channels=None)¶

Get closest channels + distances

Parameters

recording: RecordingExtractor: The recording extractor to get closest channels
channel_ids: list: List of channels ids to compute there near neighborhood
num_channels: int, default: None: Maximum number of neighborhood channels to return

Returns

closest_channels_indsarray (2d): Closest channel indices in ascending order for each channel id given in input
dists: array (2d): Distance in ascending order for each channel id given in input

spikeinterface.core.get_noise_levels(recording: BaseRecording, return_scaled: bool = True, method: Literal['mad', 'std'] = 'mad', force_recompute: bool = False, **random_chunk_kwargs)¶

Estimate noise for each channel using MAD methods. You can use standard deviation with method=”std”

Internally it samples some chunk across segment. And then, it use MAD estimator (more robust than STD)

Parameters

recording: BaseRecording: The recording extractor to get noise levels
return_scaled: bool: If True, returned noise levels are scaled to uV
method: “mad” | “std”, default: “mad”: The method to use to estimate noise levels
force_recompute: bool: If True, noise levels are recomputed even if they are already stored in the recording extractor
random_chunk_kwargs: dict: Kwargs for get_random_data_chunks

Returns

noise_levels: array: Noise levels for each channel

spikeinterface.core.get_chunk_with_margin(rec_segment, start_frame, end_frame, channel_indices, margin, add_zeros=False, add_reflect_padding=False, window_on_margin=False, dtype=None)¶

Helper to get chunk with margin

The margin is extracted from the recording when possible. If at the edge of the recording, no margin is used unless one of add_zeros or add_reflect_padding is True. In the first case zero padding is used, in the second case np.pad is called with mod=”reflect”.

spikeinterface.core.order_channels_by_depth(recording, channel_ids=None, dimensions=('x', 'y'), flip=False)¶

Order channels by depth, by first ordering the x-axis, and then the y-axis.

Parameters

recordingBaseRecording: The input recording
channel_idslist/array or None: If given, a subset of channels to order locations for
dimensionsstr, tuple, or list, default: (‘x’, ‘y’): If str, it needs to be ‘x’, ‘y’, ‘z’. If tuple or list, it sorts the locations in two dimensions using lexsort. This approach is recommended since there is less ambiguity
flip: bool, default: False: If flip is False then the order is bottom first (starting from tip of the probe). If flip is True then the order is upper first.

Returns

order_fnp.array: Array with sorted indices
order_rnp.array: Array with indices to revert sorting

spikeinterface.core.get_template_amplitudes(templates_or_waveform_extractor, peak_sign: neg' | 'pos' | 'both = 'neg', mode: extremum' | 'at_index = 'extremum')¶

Get amplitude per channel for each unit.

Parameters

templates_or_waveform_extractor: Templates | WaveformExtractor: A Templates or a WaveformExtractor object
peak_sign: “neg” | “pos” | “both”, default: “neg”: Sign of the template to compute best channels
mode: “extremum” | “at_index”, default: “extremum”: “extremum”: max or min “at_index”: take value at spike index

Returns

peak_values: dict: Dictionary with unit ids as keys and template amplitudes as values

spikeinterface.core.get_template_extremum_channel(templates_or_waveform_extractor, peak_sign: neg' | 'pos' | 'both = 'neg', mode: extremum' | 'at_index = 'extremum', outputs: id' | 'index = 'id')¶

Compute the channel with the extremum peak for each unit.

Parameters

templates_or_waveform_extractor: Templates | WaveformExtractor

A Templates or a WaveformExtractor object

peak_sign: “neg” | “pos” | “both”, default: “neg”

Sign of the template to compute best channels

mode: “extremum” | “at_index”, default: “extremum”

“extremum”: max or min “at_index”: take value at spike index

outputs: “id” | “index”, default: “id”

“id”: channel id
“index”: channel index

Returns

extremum_channels: dict: Dictionary with unit ids as keys and extremum channels (id or index based on “outputs”) as values

spikeinterface.core.get_template_extremum_channel_peak_shift(templates_or_waveform_extractor, peak_sign: neg' | 'pos' | 'both = 'neg')¶

In some situations spike sorters could return a spike index with a small shift related to the waveform peak. This function estimates and return these alignment shifts for the mean template. This function is internally used by compute_spike_amplitudes() to accurately retrieve the spike amplitudes.

Parameters

templates_or_waveform_extractor: Templates | WaveformExtractor: A Templates or a WaveformExtractor object
peak_sign: “neg” | “pos” | “both”, default: “neg”: Sign of the template to compute best channels

Returns

shifts: dict: Dictionary with unit ids as keys and shifts as values

spikeinterface.core.get_template_extremum_amplitude(templates_or_waveform_extractor, peak_sign: neg' | 'pos' | 'both = 'neg', mode: extremum' | 'at_index = 'at_index')¶

Computes amplitudes on the best channel.

Parameters

templates_or_waveform_extractor: Templates | WaveformExtractor: A Templates or a WaveformExtractor object
peak_sign: “neg” | “pos” | “both”: Sign of the template to compute best channels
mode: “extremum” | “at_index”, default: “at_index”: Where the amplitude is computed “extremum”: max or min “at_index”: take value at spike index

Returns

amplitudes: dict: Dictionary with unit ids as keys and amplitudes as values

spikeinterface.core.append_recordings(recording_list, sampling_frequency_max_diff=0)¶

Takes as input a list of parent recordings each with multiple segments and returns a single multi-segment recording that “appends” all segments from all parent recordings.

For instance, given one recording with 2 segments and one recording with 3 segments, this class will give one recording with 5 segments

Parameters

recording_listlist of BaseRecording: A list of recordings
sampling_frequency_max_difffloat, default: 0: Maximum allowed difference of sampling frequencies across recordings

spikeinterface.core.concatenate_recordings(recording_list, ignore_times=True, sampling_frequency_max_diff=0)¶

Return a recording that “concatenates” all segments from all parent recordings into one recording with a single segment. The operation is lazy.

For instance, given one recording with 2 segments and one recording with 3 segments, this class will give one recording with one large segment made by concatenating the 5 segments.

Time information is lost upon concatenation. By default ignore_times is True. If it is False, you get an error unless:

all segments DO NOT have times, AND

all segment have t_start=None

Parameters

recording_listlist of BaseRecording: A list of recordings
ignore_times: bool, default: True: If True, time information (t_start, time_vector) is ignored when concatenating recordings
sampling_frequency_max_difffloat, default: 0: Maximum allowed difference of sampling frequencies across recordings

spikeinterface.core.split_recording(recording: BaseRecording)¶

Return a list of mono-segment recordings from a multi-segment recording.

Parameters

recordingBaseRecording: The multi-segment recording

Returns

recording_list: A list of mono-segment recordings

spikeinterface.core.select_segment_recording(recording: BaseRecording, segment_indices: int | list[int])¶

Return a new recording with a subset of segments from a multi-segment recording.

Parameters

recordingBaseRecording: The multi-segment recording
segment_indicesint | list[int]: The segment indices to select

spikeinterface.core.append_sortings(sorting_list, sampling_frequency_max_diff=0)¶

Return a sorting that “append” all segments from all sorting into one sorting multi segment.

Parameters

sorting_listlist of BaseSorting: A list of sortings
sampling_frequency_max_difffloat, default: 0: Maximum allowed difference of sampling frequencies across sortings

spikeinterface.core.split_sorting(parent_sorting: BaseSorting, recording_or_recording_list=None)¶

Splits a sorting with a single segment to multiple segments based on the given list of recordings (must be in order)

Parameters

parent_sortingBaseSorting: Sorting with a single segment (e.g. from sorting concatenated recording)
recording_or_recording_listlist of recordings, ConcatenateSegmentRecording, or None, default: None: If list of recordings, uses the lengths of those recordings to split the sorting into smaller segments If ConcatenateSegmentRecording, uses the associated list of recordings to split the sorting into smaller segments If None, looks for the recording associated with the sorting

spikeinterface.core.select_segment_sorting(sorting: BaseSorting, segment_indices: int | list[int])¶

Return a new sorting with a single segment from a multi-segment sorting.

Parameters

sortingBaseSorting: The multi-segment sorting
segment_indicesint | list[int]: The segment indices to select

spikeinterface.core.read_binary(file_paths, sampling_frequency, dtype, num_channels=None, t_starts=None, channel_ids=None, time_axis=0, file_offset=0, gain_to_uV=None, offset_to_uV=None, is_filtered=None, num_chan=None)¶

RecordingExtractor for a binary format

Parameters

file_paths: str or Path or list: Path to the binary file
sampling_frequency: float: The sampling frequency
num_channels: int: Number of channels
num_chan: int [deprecated, use num_channels instead, will be removed as early as v0.100.0]: Number of channels
dtype: str or dtype: The dtype of the binary file
time_axis: int, default: 0: The axis of the time dimension
t_starts: None or list of float, default: None: Times in seconds of the first sample for each segment
channel_ids: list, default: None: A list of channel ids
file_offset: int, default: 0: Number of bytes in the file to offset by during memmap instantiation.
gain_to_uV: float or array-like, default: None: The gain to apply to the traces
offset_to_uV: float or array-like, default: None: The offset to apply to the traces
is_filtered: bool or None, default: None: If True, the recording is assumed to be filtered. If None, is_filtered is not set.

Returns

recording: BinaryRecordingExtractor: The recording Extractor

Notes

When both num_channels and num_chan are provided, num_channels is used and num_chan is ignored.

spikeinterface.core.read_zarr(folder_path: str | pathlib.Path, storage_options: Optional[dict] = None) → spikeinterface.core.zarrextractors.ZarrRecordingExtractor | spikeinterface.core.zarrextractors.ZarrSortingExtractor¶

Read recording or sorting from a zarr format

Parameters

folder_path: str or Path: Path to the zarr root file
storage_options: dict or None: Storage options for zarr store. E.g., if “s3://” or “gcs://” they can provide authentication methods, etc.

Returns

extractor: ZarrExtractor: The loaded extractor

Low-level¶

class spikeinterface.core.BaseWaveformExtractorExtension(waveform_extractor)¶

This the base class to extend the waveform extractor. It handles persistency to disk any computations related to a waveform extractor.

For instance:

principal components
spike amplitudes
quality metrics

The design is done via a WaveformExtractor.register_extension(my_extension_class), so that only imported modules can be used as extension.

It also enables any custum computation on top on waveform extractor to be implemented by the user.

An extension needs to inherit from this class and implement some abstract methods:

_reset
_set_params
_run

The subclass must also save to the self.extension_folder any file that needs to be reloaded when calling _load_extension_data

The subclass must also set an extension_name attribute which is not None by default.

class spikeinterface.core.ChunkRecordingExecutor(recording, func, init_func, init_args, verbose=False, progress_bar=False, handle_returns=False, gather_func=None, n_jobs=1, total_memory=None, chunk_size=None, chunk_memory=None, chunk_duration=None, mp_context=None, job_name='', max_threads_per_process=1)¶

Core class for parallel processing to run a “function” over chunks on a recording.

It supports running a function:

in loop with chunk processing (low RAM usage)
at once if chunk_size is None (high RAM usage)
in parallel with ProcessPoolExecutor (higher speed)

The initializer (“init_func”) allows to set a global context to avoid heavy serialization (for examples, see implementation in core.WaveformExtractor).

Parameters

recording: RecordingExtractor: The recording to be processed
func: function: Function that runs on each chunk
init_func: function: Initializer function to set the global context (accessible by “func”)
init_args: tuple: Arguments for init_func
verbose: bool: If True, output is verbose
job_name: str, default: “”: Job name
handle_returns: bool, default: False: If True, the function can return values
gather_func: None or callable, default: None: Optional function that is called in the main thread and retrieves the results of each worker. This function can be used instead of handle_returns to implement custom storage on-the-fly.
n_jobs: int, default: 1: Number of jobs to be used. Use -1 to use as many jobs as number of cores
total_memory: str, default: None: Total memory (RAM) to use (e.g. “1G”, “500M”)
chunk_memory: str, default: None: Memory per chunk (RAM) to use (e.g. “1G”, “500M”)
chunk_size: int or None, default: None: Size of each chunk in number of samples. If “total_memory” or “chunk_memory” are used, it is ignored.
chunk_durationstr or float or None: Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
mp_context“fork” | “spawn” | None, default: None: “fork” or “spawn”. If None, the context is taken by the recording.get_preferred_mp_context(). “fork” is only safely available on LINUX systems.
max_threads_per_process: int or None, default: None: Limit the number of thread per process using threadpoolctl modules. This used only when n_jobs>1 If None, no limits.
progress_bar: bool, default: False: If True, a progress bar is printed to monitor the progress of the process

Returns

res: list: If “handle_returns” is True, the results for each chunk process

spikeinterface.extractors¶

NEO-based¶

spikeinterface.extractors.read_alphaomega(folder_path, lsx_files=None, stream_id='RAW', stream_name=None, all_annotations=False)¶

Class for reading from AlphaRS and AlphaLab SnR boards.

Based on neo.rawio.AlphaOmegaRawIO

Parameters

folder_path: str or Path-like: The folder path to the AlphaOmega recordings.
lsx_files: list of strings or None, default: None: A list of listings files that refers to mpx files to load.
stream_id: {“RAW”, “LFP”, “SPK”, “ACC”, “AI”, “UD”}, default: “RAW”: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_alphaomega_event(folder_path)¶: Class for reading events from AlphaOmega MPX file format

spikeinterface.extractors.read_axona(file_path, all_annotations=False)¶

Class for reading Axona RAW format.

Based on neo.rawio.AxonaRawIO

Parameters

file_path: str: The file path to load the recordings from.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_biocam(file_path, mea_pitch=None, electrode_width=None, stream_id=None, stream_name=None, block_index=None, all_annotations=False)¶

Class for reading data from a Biocam file from 3Brain.

Based on neo.rawio.BiocamRawIO

Parameters

file_path: str: The file path to load the recordings from.
mea_pitch: float, default: None: The inter-electrode distance (pitch) between electrodes.
electrode_width: float, default: None: Width of the electrodes in um.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_binary(file_paths, sampling_frequency, dtype, num_channels=None, t_starts=None, channel_ids=None, time_axis=0, file_offset=0, gain_to_uV=None, offset_to_uV=None, is_filtered=None, num_chan=None)¶

RecordingExtractor for a binary format

Parameters

file_paths: str or Path or list: Path to the binary file
sampling_frequency: float: The sampling frequency
num_channels: int: Number of channels
num_chan: int [deprecated, use num_channels instead, will be removed as early as v0.100.0]: Number of channels
dtype: str or dtype: The dtype of the binary file
time_axis: int, default: 0: The axis of the time dimension
t_starts: None or list of float, default: None: Times in seconds of the first sample for each segment
channel_ids: list, default: None: A list of channel ids
file_offset: int, default: 0: Number of bytes in the file to offset by during memmap instantiation.
gain_to_uV: float or array-like, default: None: The gain to apply to the traces
offset_to_uV: float or array-like, default: None: The offset to apply to the traces
is_filtered: bool or None, default: None: If True, the recording is assumed to be filtered. If None, is_filtered is not set.

Returns

recording: BinaryRecordingExtractor: The recording Extractor

Notes

When both num_channels and num_chan are provided, num_channels is used and num_chan is ignored.

spikeinterface.extractors.read_blackrock(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False, use_names_as_ids=False)¶

Class for reading BlackRock data.

Based on neo.rawio.BlackrockRawIO

Parameters

file_path: str: The file path to load the recordings from.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_ced(file_path, stream_id=None, stream_name=None, all_annotations=False)¶

Class for reading smr/smrw CED file.

Based on neo.rawio.CedRawIO / sonpy

Alternative to read_spike2 which does not handle smrx

Parameters

file_path: str: The file path to the smr or smrx file.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
block_index: int, default: None: If there are several blocks, specify the block index you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_intan(file_path, stream_id=None, stream_name=None, all_annotations=False, use_names_as_ids=False)¶

Class for reading data from a intan board. Supports rhd and rhs format.

Based on neo.rawio.IntanRawIO

Parameters

file_path: str: The file path to load the recordings from.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_maxwell(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False, rec_name=None, install_maxwell_plugin=False)¶

Class for reading data from Maxwell device. It handles MaxOne (old and new format) and MaxTwo.

Based on neo.rawio.MaxwellRawIO

Parameters

file_path: str: The file path to the maxwell h5 file.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load. For MaxTwo when there are several wells at the same time you need to specify stream_id=’well000’ or ‘well0001’, etc.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.
rec_name: str, default: None: When the file contains several recordings you need to specify the one you want to extract. (rec_name=’rec0000’).
install_maxwell_plugin: bool, default: False: If True, install the maxwell plugin for neo.

spikeinterface.extractors.read_mearec(file_path)¶

Read a MEArec file.

Parameters

file_path: str or Path: Path to MEArec h5 file

Returns

recording: MEArecRecordingExtractor: The recording extractor object
sorting: MEArecSortingExtractor: The sorting extractor object

spikeinterface.extractors.read_mcsraw(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False)¶

Class for reading data from “Raw” Multi Channel System (MCS) format. This format is NOT the native MCS format (.mcd). This format is a raw format with an internal binary header exported by the “MC_DataTool binary conversion” with the option header selected.

Based on neo.rawio.RawMCSRawIO

Parameters

file_path: str: The file path to load the recordings from.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
block_index: int, default: None: If there are several blocks, specify the block index you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_neuralynx(folder_path, stream_id=None, stream_name=None, all_annotations=False, exclude_filename=None)¶

Class for reading neuralynx folder

Based on neo.rawio.NeuralynxRawIO

Parameters

folder_path: str: The file path to load the recordings from.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.
exlude_filename: list[str], default: None: List of filename to exclude from the loading. For example, use exclude_filename=[“events.nev”] to skip loading the event file.

spikeinterface.extractors.read_neuralynx_sorting(folder_path: str, sampling_frequency: Optional[float] = None, stream_id: Optional[str] = None, stream_name: Optional[str] = None)¶

Class for reading spike data from a folder with neuralynx spiking data (i.e .nse and .ntt formats).

Based on neo.rawio.NeuralynxRawIO

Parameters

folder_path: str: The file path to load the recordings from.
sampling_frequency: float: The sampling frequency for the spiking channels. When the signal data is available (.ncs) those files will be used to extract the frequency. Otherwise, the sampling frequency needs to be specified for this extractor.
stream_id: str, default: None: Used to extract information about the sampling frequency and t_start from the analog signal if provided.
stream_name: str, default: None: Used to extract information about the sampling frequency and t_start from the analog signal if provided.

spikeinterface.extractors.read_neuroexplorer(file_path, stream_id=None, stream_name=None, all_annotations=False)¶

Class for reading NEX (NeuroExplorer data format) files.

Based on neo.rawio.NeuroExplorerRawIO

Importantly, at the moment, this recorder only extracts one channel of the recording. This is because the NeuroExplorerRawIO class does not support multi-channel recordings as in the NeuroExplorer format they might have different sampling rates.

Consider extracting all the channels and then concatenating them with the aggregate_channels function.

>>> from spikeinterface.extractors.neoextractors.neuroexplorer import NeuroExplorerRecordingExtractor
>>> from spikeinterface.core import aggregate_channels
>>>
>>> file_path="/the/path/to/your/nex/file.nex"
>>>
>>> streams = NeuroExplorerRecordingExtractor.get_streams(file_path=file_path)
>>> stream_names = streams[0]
>>>
>>> your_signal_stream_names = "Here goes the logic to filter from stream names the ones that you know have the same sampling rate and you want to aggregate"
>>>
>>> recording_list = [NeuroExplorerRecordingExtractor(file_path=file_path, stream_name=stream_name) for stream_name in your_signal_stream_names]
>>> recording = aggregate_channels(recording_list)

Parameters

file_path: str: The file path to load the recordings from.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load. For this neo reader streams are defined by their sampling frequency.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_neuroscope(file_path, stream_id=None, keep_mua_units=False, exclude_shanks=None, load_recording=True, load_sorting=False)¶

Read neuroscope recording and sorting. This function assumses that all .res and .clu files are in the same folder as the .xml file.

Parameters

file_path: str: The xml file.
stream_id: str or None: The stream id to load. If None, the first stream is loaded
keep_mua_units: bool, default: False: Optional. Whether or not to return sorted spikes from multi-unit activity
exclude_shanks: list: Optional. List of indices to ignore. The set of all possible indices is chosen by default, extracted as the final integer of all the .res. % i and .clu. % i pairs.
load_recording: bool, default: True: If True, the recording is loaded
load_sorting: bool, default: False: If True, the sorting is loaded

spikeinterface.extractors.read_nix(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False)¶

Class for reading Nix file

Based on neo.rawio.NIXRawIO

Parameters

file_path: str: The file path to load the recordings from.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
block_index: int, default: None: If there are several blocks, specify the block index you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_openephys(folder_path, **kwargs)¶

Read “legacy” or “binary” Open Ephys formats

Parameters

folder_path: str or Path: Path to openephys folder
stream_id: str, default: None: If there are several streams, specify the stream id you want to load
stream_name: str, default: None: If there are several streams, specify the stream name you want to load
block_index: int, default: None: If there are several blocks (experiments), specify the block index you want to load
all_annotations: bool, default: False: Load exhaustively all annotation from neo
load_sync_channelbool, default: False: If False (default) and a SYNC channel is present (e.g. Neuropixels), this is not loaded. If True, the SYNC channel is loaded and can be accessed in the analog signals. For open ephsy binary format only
load_sync_timestampsbool, default: False: If True, the synchronized_timestamps are loaded and set as times to the recording. If False (default), only the t_start and sampling rate are set, and timestamps are assumed to be uniform and linearly increasing. For open ephsy binary format only
experiment_names: str, list, or None, default: None: If multiple experiments are available, this argument allows users to select one or more experiments. If None, all experiements are loaded as blocks. E.g. experiment_names=”experiment2”, experiment_names=[“experiment1”, “experiment2”] For open ephsy binary format only
ignore_timestamps_errors: bool, default: False: Ignore the discontinuous timestamps errors in neo For open ephsy legacy format only

Returns

recording: OpenEphysLegacyRecordingExtractor or OpenEphysBinaryExtractor

spikeinterface.extractors.read_openephys_event(folder_path, block_index=None)¶

Read Open Ephys events from “binary” format.

Parameters

folder_path: str or Path: Path to openephys folder
block_index: int, default: None: If there are several blocks (experiments), specify the block index you want to load.

Returns

event: OpenEphysBinaryEventExtractor

spikeinterface.extractors.read_plexon(file_path, stream_id=None, stream_name=None, all_annotations=False)¶

Class for reading plexon plx files.

Based on neo.rawio.PlexonRawIO

Parameters

file_path: str: The file path to load the recordings from.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_plexon_sorting(file_path)¶

Class for reading plexon spiking data (.plx files).

Based on neo.rawio.PlexonRawIO

Parameters

file_path: str: The file path to load the recordings from.

spikeinterface.extractors.read_plexon2(file_path, stream_id=None, stream_name=None, all_annotations=False)¶

Class for reading plexon pl2 files.

Based on neo.rawio.Plexon2RawIO

Parameters

file_path: str: The file path to load the recordings from.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_plexon2_sorting(file_path, sampling_frequency=None)¶

Class for reading plexon spiking data from .pl2 files.

Based on neo.rawio.Plexon2RawIO

Parameters

file_path: str: The file path to load the recordings from.
sampling_frequency: float, default: None: The sampling frequency of the sorting (required for multiple streams with different sampling frequencies).

spikeinterface.extractors.read_spike2(file_path, stream_id=None, stream_name=None, all_annotations=False)¶

Class for reading spike2 smr files. smrx are not supported with this, prefer CedRecordingExtractor instead.

Based on neo.rawio.Spike2RawIO

Parameters

file_path: str: The file path to load the recordings from.
stream_id: str, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_spikegadgets(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False)¶

Class for reading rec files from spikegadgets.

Based on neo.rawio.SpikeGadgetsRawIO

Parameters

file_path: str: The file path to load the recordings from.
stream_id: str or None, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str or None, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_spikeglx(folder_path, load_sync_channel=False, stream_id=None, stream_name=None, all_annotations=False)¶

Class for reading data saved by SpikeGLX software. See https://billkarsh.github.io/SpikeGLX/

Based on neo.rawio.SpikeGLXRawIO

Contrary to older verions, this reader is folder-based. If the folder contains several streams (e.g., “imec0.ap”, “nidq” ,”imec0.lf”), then the stream has to be specified with “stream_id” or “stream_name”.

Parameters

folder_path: str: The folder path to load the recordings from.
load_sync_channel: bool default: False: Whether or not to load the last channel in the stream, which is typically used for synchronization. If True, then the probe is not loaded.
stream_id: str or None, default: None: If there are several streams, specify the stream id you want to load. For example, “imec0.ap”, “nidq”, or “imec0.lf”.
stream_name: str or None, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_tdt(folder_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False)¶

Class for reading TDT folder.

Based on neo.rawio.TdTRawIO

Parameters

folder_path: str: The folder path to the tdt folder.
stream_id: str or None, default: None: If there are several streams, specify the stream id you want to load.
stream_name: str or None, default: None: If there are several streams, specify the stream name you want to load.
all_annotations: bool, default: False: Load exhaustively all annotations from neo.

spikeinterface.extractors.read_zarr(folder_path: str | pathlib.Path, storage_options: Optional[dict] = None) → spikeinterface.core.zarrextractors.ZarrRecordingExtractor | spikeinterface.core.zarrextractors.ZarrSortingExtractor¶

Read recording or sorting from a zarr format

Parameters

folder_path: str or Path: Path to the zarr root file
storage_options: dict or None: Storage options for zarr store. E.g., if “s3://” or “gcs://” they can provide authentication methods, etc.

Returns

extractor: ZarrExtractor: The loaded extractor

Non-NEO-based¶

spikeinterface.extractors.read_alf_sorting(folder_path, sampling_frequency=30000)¶

Load ALF format data as a sorting extractor.

Parameters

folder_pathstr or Path: Path to the ALF folder.
sampling_frequencyint, default: 30000: The sampling frequency.

Returns

extractorALFSortingExtractor: The loaded data.

spikeinterface.extractors.read_bids(folder_path)¶

Load a BIDS folder of data into extractor objects.

The following files are considered:

_channels.tsv

_contacts.tsv

_ephys.nwb

_probes.tsv

Parameters

folder_pathstr or Path: Path to the BIDS folder.

Returns

extractorslist of extractors: The loaded data, with attached Probes.

spikeinterface.extractors.read_cbin_ibl(folder_path, load_sync_channel=False, stream_name='ap')¶

Load IBL data as an extractor object.

IBL have a custom format - compressed binary with spikeglx meta.

The format is like spikeglx (have a meta file) but contains:

“cbin” file (instead of “bin”)

“ch” file used by mtscomp for compression info

Parameters

folder_path: str or Path: Path to ibl folder.
load_sync_channel: bool, default: False: Load or not the last channel (sync). If not then the probe is loaded.
stream_name: str, default: “ap”.: Whether to load AP or LFP band, one of “ap” or “lp”.

Returns

recordingCompressedBinaryIblExtractor: The loaded data.

spikeinterface.extractors.read_combinato(folder_path, sampling_frequency=None, user='simple', det_sign='both', keep_good_only=True)¶

Load Combinato format data as a sorting extractor.

Parameters

folder_pathstr or Path: Path to the Combinato folder.
sampling_frequencyint, default: 30000: The sampling frequency.
userstr, default: “simple”: The username that ran the sorting
det_sign“both”, “pos”, “neg”, default: “both”: Which sign was used for detection.
keep_good_onlybool, default: True: Whether to only keep good units.

Returns

extractorCombinatoSortingExtractor: The loaded data.

spikeinterface.extractors.read_ibl_streaming_recording(session: str, stream_name: str, load_sync_channel: bool = False, cache_folder: Optional[Union[Path, str]] = None, remove_cached: bool = True)¶

Stream IBL data as an extractor object.

Parameters

sessionstr

The session ID to extract recordings for. In ONE, this is sometimes referred to as the “eid”. When doing a session lookup such as

>>> from one.api import ONE
>>> one = ONE(base_url="https://openalyx.internationalbrainlab.org", password="international", silent=True)
>>> sessions = one.alyx.rest("sessions", "list", tag="2022_Q2_IBL_et_al_RepeatedSite")

each returned value in sessions refers to it as the “id”.

stream_namestr

The name of the stream to load for the session. These can be retrieved from calling StreamingIblExtractor.get_stream_names(session=”<your session ID>”).

load_sync_channelsbool, default: false

Load or not the last channel (sync). If not then the probe is loaded.

cache_folderstr or None, default: None

The location to temporarily store chunks of data during streaming. The default uses the folder designated by ONE.alyx._par.CACHE_DIR / “cache”, which is typically the designated “Downloads” folder on your operating system. As long as remove_cached is set to True, the only files that will persist in this folder are the metadata header files and the chunk of data being actively streamed and used in RAM.

remove_cachedbool, default: True

Whether or not to remove streamed data from the cache immediately after it is read. If you expect to reuse fetched data many times, and have the disk space available, it is recommended to set this to False.

Returns

recordingIblStreamingRecordingExtractor: The recording extractor which allows access to the traces.

spikeinterface.extractors.read_hdsort(file_path, keep_good_only=True)¶

Load HDSort format data as a sorting extractor.

Parameters

file_pathstr or Path: Path to HDSort mat file.
keep_good_onlybool, default: True: Whether to only keep good units.

Returns

extractorHDSortSortingExtractor: The loaded data.

spikeinterface.extractors.read_herdingspikes(file_path, load_unit_info=True)¶

Load HerdingSpikes format data as a sorting extractor.

Parameters

folder_pathstr or Path: Path to the ALF folder.
load_unit_infobool, default: True: Whether to load the unit info from the file.

Returns

extractorHerdingSpikesSortingExtractor: The loaded data.

spikeinterface.extractors.read_kilosort(folder_path: Path | str, keep_good_only: bool = False, remove_empty_units: bool = True)¶

Load Kilosort format data as a sorting extractor.

Parameters

folder_path: str or Path: Path to the output Phy folder (containing the params.py).
keep_good_onlybool, default: True: Whether to only keep good units. If True, only Kilosort-labeled ‘good’ units are returned.
remove_empty_unitsbool, default: True: If True, empty units are removed from the sorting extractor.

Returns

extractorKiloSortSortingExtractor: The loaded Sorting object.

spikeinterface.extractors.read_klusta(file_or_folder_path, exclude_cluster_groups=None)¶

Load Klusta format data as a sorting extractor.

Parameters

file_or_folder_pathstr or Path: Path to the ALF folder.
exclude_cluster_groups: list or str, default: None: Cluster groups to exclude (e.g. “noise” or [“noise”, “mua”]).

Returns

extractorKlustaSortingExtractor: The loaded data.

spikeinterface.extractors.read_mcsh5(file_path, stream_id=0)¶

Load a MCS H5 file as a recording extractor.

Parameters

file_pathstr or Path: The path to the MCS h5 file.
stream_idint, default: 0: The stream ID to load.

Returns

recordingMCSH5RecordingExtractor: The loaded data.

spikeinterface.extractors.read_mda_recording(folder_path, raw_fname='raw.mda', params_fname='params.json', geom_fname='geom.csv')¶

Load MDA format data as a recording extractor.

Parameters

folder_pathstr or Path: Path to the MDA folder.
raw_fname: str, default: “raw.mda”: File name of raw file
params_fname: str, default: “params.json”: File name of params file
geom_fname: str, default: “geom.csv”: File name of geom file

Returns

extractorMdaRecordingExtractor: The loaded data.

spikeinterface.extractors.read_mda_sorting(file_path, sampling_frequency)¶

Load MDA format data as a sorting extractor.

Parameters

file_pathstr or Path: Path to the MDA file.
sampling_frequencyint: The sampling frequency.

Returns

extractorMdaRecordingExtractor: The loaded data.

spikeinterface.extractors.read_nwb(file_path, load_recording=True, load_sorting=False, electrical_series_path=None)¶

Reads NWB file into SpikeInterface extractors.

Parameters

file_path: str or Path: Path to NWB file.
load_recordingbool, default: True: If True, the recording object is loaded.
load_sortingbool, default: False: If True, the recording object is loaded.
electrical_series_path: str or None, default: None: The name of the ElectricalSeries (if multiple ElectricalSeries are present)

Returns

extractors: extractor or tuple: Single RecordingExtractor/SortingExtractor or tuple with both (depending on “load_recording”/”load_sorting”) arguments.

spikeinterface.extractors.read_phy(folder_path: Path | str, exclude_cluster_groups: Optional[list[str] | str] = None, load_all_cluster_properties: bool = True)¶

Load Phy format data as a sorting extractor.

Parameters

folder_path: str or Path: Path to the output Phy folder (containing the params.py).
exclude_cluster_groups: list or str, default: None: Cluster groups to exclude (e.g. “noise” or [“noise”, “mua”]).
load_all_cluster_propertiesbool, default: True: If True, all cluster properties are loaded from the tsv/csv files.

Returns

extractorPhySortingExtractor: The loaded Sorting object.

spikeinterface.extractors.read_shybrid_recording(file_path)¶

Load SHYBRID format data as a recording extractor.

Parameters

file_pathstr or Path: Path to the SHYBRID file.

Returns

extractorSHYBRIDRecordingExtractor: Loaded data.

spikeinterface.extractors.read_shybrid_sorting(file_path, sampling_frequency, delimiter=',')¶

Load SHYBRID format data as a sorting extractor.

Parameters

file_pathstr or Path: Path to the SHYBRID file.
sampling_frequencyint: The sampling frequency.
delimiterstr: The delimiter to use for loading the file.

Returns

extractorSHYBRIDSortingExtractor: Loaded data.

spikeinterface.extractors.read_spykingcircus(folder_path)¶

Load SpykingCircus format data as a recording extractor.

Parameters

folder_pathstr or Path: Path to the SpykingCircus folder.

Returns

extractorSpykingCircusSortingExtractor: Loaded data.

spikeinterface.extractors.toy_example(duration=10, num_channels=4, num_units=10, sampling_frequency=30000.0, num_segments=2, average_peak_amplitude=-100, upsample_factor=None, contact_spacing_um=40.0, num_columns=1, spike_times=None, spike_labels=None, firing_rate=3.0, seed=None)¶

Returns a generated dataset with “toy” units and spikes on top on white noise. This is useful to test api, algos, postprocessing and visualization without any downloading.

This a rewrite (with the lazy approach) of the old spikeinterface.extractor.toy_example() which itself was also a rewrite from the very old spikeextractor.toy_example() (from Jeremy Magland). In this new version, the recording is totally lazy and so it does not use disk space or memory. It internally uses NoiseGeneratorRecording + generate_templates + InjectTemplatesRecording.

For better control, you should use the generate_ground_truth_recording(), but provides better control over the parameters.

Parameters

duration: float or list[float], default: 10: Duration in seconds. If a list is provided, it will be the duration of each segment.
num_channels: int, default: 4: Number of channels
num_units: int, default: 10: Number of units
sampling_frequency: float, default: 30000: Sampling frequency
num_segments: int, default: 2: Number of segments.
spike_times: np.array or list[nparray] or None, default: None: Spike time in the recording
spike_labels: np.array or list[nparray] or None, default: None: Cluster label for each spike time (needs to specified both together).
# score_detection: int (between 0 and 1)
# Generate the sorting based on a subset of spikes compare with the trace generation
firing_rate: float, default: 3.0: The firing rate for the units (in Hz)
seed: int or None, default: None: Seed for random initialization.

Returns

recording: RecordingExtractor: The output recording extractor.
sorting: SortingExtractor: The output sorting extractor.

spikeinterface.extractors.read_tridesclous(folder_path, chan_grp=None)¶

Load Tridesclous format data as a sorting extractor.

Parameters

folder_pathstr or Path: Path to the Tridesclous folder.
chan_grplist or None, default: None: The channel group(s) to load.

Returns

extractorTridesclousSortingExtractor: Loaded data.

spikeinterface.extractors.read_waveclus(file_path, keep_good_only=True)¶

Load WaveClus format data as a sorting extractor.

Parameters

file_pathstr or Path: Path to the WaveClus file.
keep_good_onlybool, default: True: Whether to only keep good units.

Returns

extractorWaveClusSortingExtractor: Loaded data.

spikeinterface.extractors.read_yass(folder_path)¶

Load YASS format data as a sorting extractor.

Parameters

folder_pathstr or Path: Path to the ALF folder.

Returns

extractorYassSortingExtractor: Loaded data.

spikeinterface.preprocessing¶

spikeinterface.preprocessing.astype(recording, dtype=None)¶

The spikeinterface analog of numpy.astype

Converts a recording to another dtype on the fly.

For recording with an unsigned dtype, please use the unsigned_to_signed preprocessing function.

spikeinterface.preprocessing.average_across_direction(parent_recording: BaseRecording, direction: str = 'y', dtype='float32')¶: Abstract class representing several a multichannel timeseries (or block of raw ephys traces). Internally handle list of RecordingSegment

spikeinterface.preprocessing.bandpass_filter(recording, freq_min=300.0, freq_max=6000.0, margin_ms=5.0, dtype=None, **filter_kwargs)¶

Bandpass filter of a recording

Parameters

recording: Recording: The recording extractor to be re-referenced
freq_min: float: The highpass cutoff frequency in Hz
freq_max: float: The lowpass cutoff frequency in Hz
margin_ms: float: Margin in ms on border to avoid border effect
dtype: dtype or None: The dtype of the returned traces. If None, the dtype of the parent recording is used
{}
Returns
——-
filter_recording: BandpassFilterRecording: The bandpass-filtered recording extractor object

spikeinterface.preprocessing.blank_staturation(recording, abs_threshold=None, quantile_threshold=None, direction='upper', fill_value=None, num_chunks_per_segment=50, chunk_size=500, seed=0)¶

Find and remove parts of the signal with extereme values. Some arrays may produce these when amplifiers enter saturation, typically for short periods of time. To remove these artefacts, values below or above a threshold are set to the median signal value. The threshold is either be estimated automatically, using the lower and upper 0.1 signal percentile with the largest deviation from the median, or specificed. Use this function with caution, as it may clip uncontaminated signals. A warning is printed if the data range suggests no artefacts.

Parameters

recording: RecordingExtractor: The recording extractor to be transformed Minimum value. If None, clipping is not performed on lower interval edge.
abs_threshold: float or None, default: None: The absolute value for considering that the signal is saturating
quantile_threshold: float or None, default: None: Tha value in [0, 1] used if abs_threshold is None to automatically set the abs_threshold given the data. Must be provided if abs_threshold is None
direction: “upper” | “lower” | “both”, default: “upper”: Only values higher than the detection threshold are set to fill_value (“higher”), or only values lower than the detection threshold (“lower”), or both (“both”)
fill_value: float or None, default: None: The value to write instead of the saturating signal. If None, then the value is automatically computed as the median signal value
num_chunks_per_segment: int, default: 50: The number of chunks per segments to consider to estimate the threshold/fill_values
chunk_size: int, default: 500: The chunk size to estimate the threshold/fill_values
seed: int, default: 0: The seed to select the random chunks

Returns

rescaled_traces: BlankSaturationRecording: The filtered traces recording extractor object

spikeinterface.preprocessing.center(recording, mode='median', dtype='float32', **random_chunk_kwargs)¶

Centers traces from the given recording extractor by removing the median/mean of each channel.

Parameters

recording: RecordingExtractor: The recording extractor to be centered
mode: “median” | “mean”, default: “median”: The method used to center the traces
dtype: str or np.dtype, default: “float32”: The dtype of the output traces
**random_chunk_kwargs: Keyword arguments for `spikeinterface.core.get_random_data_chunk()` function

Returns

centered_traces: ScaleRecording: The centered traces recording extractor object

spikeinterface.preprocessing.clip(recording, a_min=None, a_max=None)¶

Limit the values of the data between a_min and a_max. Values exceeding the range will be set to the minimum or maximum, respectively.

Parameters

recording: RecordingExtractor: The recording extractor to be transformed
a_min: float or None, default: None: Minimum value. If None, clipping is not performed on lower interval edge.
a_max: float or None, default: None: Maximum value. If None, clipping is not performed on upper interval edge.

Returns

rescaled_traces: ClipTracesRecording: The clipped traces recording extractor object

spikeinterface.preprocessing.common_reference(recording: BaseRecording, reference: Literal['global', 'single', 'local'] = 'global', operator: Literal['median', 'average'] = 'median', groups=None, ref_channel_ids=None, local_radius=(30, 55), dtype=None)¶

Re-references the recording extractor traces. That is, the value of the traces are shifted so the there is a new zero (reference).

The new reference can be estimated either by using a common median reference (CMR) or a common average reference (CAR).

The new reference can be set three ways:

“global”: the median/average of all channels is set as the new reference.
In this case, the ‘global’ median/average is subtracted from all channels.
“single”: In the simplest case, a single channel from the recording is set as the new reference.
This channel is subtracted from all other channels. To use this option, the ref_channel_ids argument is used with a single channel id. Note that this option will zero out the reference channel. A collection of channels can also be used as the new reference. In this case, the median/average of the selected channels is subtracted from all other channels. To use this option, pass the group of channels as a list in ref_channel_ids.
“local”: the median/average within an annulus is set as the new reference.
The parameters of the annulus are specified using the local_radius argument. With this option, both channels which are too close and channels which are too far are excluded from the median/average. Note that setting the local_radius to (0, exclude_radius) will yield a simple circular local region.

Parameters

recording: RecordingExtractor

The recording extractor to be re-referenced

reference: “global” | “single” | “local”, default: “global”

If “global” the reference is the average or median across all the channels. If “single”, the reference is a single channel or a list of channels that need to be set with the ref_channel_ids. If “local”, the reference is the set of channels within an annulus that must be set with the local_radius parameter.

operator: “median” | “average”, default: “median”

If “median”, a common median reference (CMR) is implemented (the median of: the selected channels is removed for each timestamp).
If “average”, common average reference (CAR) is implemented (the mean of the selected channels is removed: for each timestamp).

groups: list or None, default: None

List of lists containing the channel ids for splitting the reference. The CMR, CAR, or referencing with respect to single channels are applied group-wise. However, this is not applied for the local CAR. It is useful when dealing with different channel groups, e.g. multiple tetrodes.

ref_channel_ids: list or str or int, default: None

If no “groups” are specified, all channels are referenced to “ref_channel_ids”. If “groups” is provided, then a list of channels to be applied to each group is expected. If “single” reference, a list of one channel or an int is expected.

local_radius: tuple(int, int), default: (30, 55)

Use in the local CAR implementation as the selecting annulus with the following format:

(exclude radius, include radius)

Where the exlude radius is the inner radius of the annulus and the include radius is the outer radius of the annulus. The exclude radius is used to exclude channels that are too close to the reference channel and the include radius delineates the outer boundary of the annulus whose role is to exclude channels that are too far away.

dtype: None or dtype, default: None

If None the parent dtype is kept.

Returns

referenced_recording: CommonReferenceRecording: The re-referenced recording extractor object

spikeinterface.preprocessing.correct_lsb(recording, num_chunks_per_segment=20, chunk_size=10000, seed=None, verbose=False)¶

Estimates the LSB of the recording and divide traces by LSB to ensure LSB = 1. Medians are also subtracted to avoid rounding errors.

Parameters

recordingRecordingExtractor: The recording extractor to be LSB-corrected.
num_chunks_per_segment: int, default: 20: Number of chunks per segment for random chunk
chunk_sizeint, default: 10000: Size of a chunk in number for random chunk
seedint or None, default: None: Random seed for random chunk
verbosebool, default: False: If True, estimate LSB value is printed

Returns

correct_lsb_recording: ScaleRecording: The recording extractor with corrected LSB

spikeinterface.preprocessing.correct_motion(recording, preset='nonrigid_accurate', folder=None, output_motion_info=False, detect_kwargs={}, select_kwargs={}, localize_peaks_kwargs={}, estimate_motion_kwargs={}, interpolate_motion_kwargs={}, **job_kwargs)¶

High-level function that estimates the motion and interpolates the recording.

This function has some intermediate steps that can be controlled one by one with parameters:

detect peaks
(optional) sub-sample peaks to speed up the localization
localize peaks
estimate the motion
create and return a InterpolateMotionRecording recording object

Even if this function is convinient, we recommend to run all step separately for fine tuning.

Optionally, this function can create a folder with files and figures ready to check.

This function depends on several modular components of spikeinterface.sortingcomponents.

If select_kwargs is None then all peak are used for localized.

The recording must be preprocessed (filter and denoised at least), and we recommend to not use whithening before motion estimation.

Parameters for each step are handled as separate dictionaries. For more information please check the documentation of the following functions:

detect_peaks()

select_peaks()

localize_peaks()

estimate_motion()

interpolate_motion()

Possible presets:

nonrigid_accurate: method by Paninski lab (monopolar_triangulation + decentralized)
nonrigid_fast_and_accurate: mixed methods by KS & Paninski lab (grid_convolution + decentralized)
rigid_fast: Rigid and not super accurate but fast. Use center of mass.
kilosort_like: Mimic the drift correction of kilosort (grid_convolution + iterative_template)

Parameters

recording: RecordingExtractor

The recording extractor to be transformed

preset: str, default: “nonrigid_accurate”

The preset name

folder: Path str or None, default: None

If not None then intermediate motion info are saved into a folder

output_motion_info: bool, default: False

If True, then the function returns a motion_info dictionary that contains variables to check intermediate steps (motion_histogram, non_rigid_windows, pairwise_displacement) This dictionary is the same when reloaded from the folder

detect_kwargs: dict

Optional parameters to overwrite the ones in the preset for “detect” step.

select_kwargs: dict

If not None, optional parameters to overwrite the ones in the preset for “select” step. If None, the “select” step is skipped.

localize_peaks_kwargs: dict

Optional parameters to overwrite the ones in the preset for “localize” step.

estimate_motion_kwargs: dict

Optional parameters to overwrite the ones in the preset for “estimate_motion” step.

interpolate_motion_kwargs: dict

Optional parameters to overwrite the ones in the preset for “detect” step.

**job_kwargs: keyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
  Number of samples per chunk
- chunk_memory: str
  Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
  Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
  Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
progress_bar: bool
If True, a progress bar is printed
mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems

Returns

recording_corrected: Recording: The motion corrected recording
motion_info: dict: Optional output if output_motion_info=True

spikeinterface.preprocessing.depth_order(parent_recording, channel_ids=None, dimensions=('x', 'y'), flip=False)¶

Re-orders the recording (channel IDs, channel locations, and traces)

Sorts channels lexicographically according to the dimensions in dimensions. See the documentation for order_channels_by_depth.

Parameters

recordingBaseRecording: The recording to re-order.
channel_idslist/array or None: If given, a subset of channels to order locations for
dimensionsstr or tuple, list, default: (“x”, “y”): If str, it needs to be “x”, “y”, “z”. If tuple or list, it sorts the locations in two dimensions using lexsort. This approach is recommended since there is less ambiguity
flip: bool, default: False: If flip is False then the order is bottom first (starting from tip of the probe). If flip is True then the order is upper first.

spikeinterface.preprocessing.detect_bad_channels(recording: BaseRecording, method: str = 'coherence+psd', std_mad_threshold: float = 5, psd_hf_threshold: float = 0.02, dead_channel_threshold: float = -0.5, noisy_channel_threshold: float = 1.0, outside_channel_threshold: float = -0.75, outside_channels_location: Literal['top', 'bottom', 'both'] = 'top', n_neighbors: int = 11, nyquist_threshold: float = 0.8, direction: Literal['x', 'y', 'z'] = 'y', chunk_duration_s: float = 0.3, num_random_chunks: int = 100, welch_window_ms: float = 10.0, highpass_filter_cutoff: float = 300, neighborhood_r2_threshold: float = 0.9, neighborhood_r2_radius_um: float = 30.0, seed: Optional[int] = None)¶

Perform bad channel detection. The recording is assumed to be filtered. If not, a highpass filter is applied on the fly.

Different methods are implemented:

stdthrehshold on channel standard deviations
If the standard deviation of a channel is greater than std_mad_threshold times the median of all channels standard deviations, the channel is flagged as noisy
mad : same as std, but using median absolute deviations instead
coeherence+psdmethod developed by the International Brain Laboratory that detects bad channels of three types:
- Dead channels are those with low similarity to the surrounding channels (n=`n_neighbors` median)
- Noise channels are those with power at >80% Nyquist above the psd_hf_threshold (default 0.02 uV^2 / Hz) and a high coherence with “far away” channels”
- Out of brain channels are contigious regions of channels dissimilar to the median of all channels at the top end of the probe (i.e. large channel number)
neighborhood_r2
A method tuned for LFP use-cases, where channels should be highly correlated with their spatial neighbors. This method estimates the correlation of each channel with the median of its spatial neighbors, and considers channels bad when this correlation is too small.

Parameters

recordingBaseRecording: The recording for which bad channels are detected
method“coeherence+psd” | “std” | “mad” | “neighborhood_r2”, default: “coeherence+psd”: The method to be used for bad channel detection
std_mad_thresholdfloat, default: 5: The standard deviation/mad multiplier threshold
psd_hf_threshold (coeherence+psd)float, default: 0.02: An absolute threshold (uV^2/Hz) used as a cutoff for noise channels. Channels with average power at >80% Nyquist larger than this threshold will be labeled as noise
dead_channel_threshold (coeherence+psd)float, default: -0.5: Threshold for channel coherence below which channels are labeled as dead
noisy_channel_threshold (coeherence+psd)float, default: 1: Threshold for channel coherence above which channels are labeled as noisy (together with psd condition)
outside_channel_threshold (coeherence+psd)float, default: -0.75: Threshold for channel coherence above which channels at the edge of the recording are marked as outside of the brain
outside_channels_location (coeherence+psd)“top” | “bottom” | “both”, default: “top”: Location of the outside channels. If “top”, only the channels at the top of the probe can be marked as outside channels. If “bottom”, only the channels at the bottom of the probe can be marked as outside channels. If “both”, both the channels at the top and bottom of the probe can be marked as outside channels
n_neighbors (coeherence+psd)int, default: 11: Number of channel neighbors to compute median filter (needs to be odd)
nyquist_threshold (coeherence+psd)float, default: 0.8: Frequency with respect to Nyquist (Fn=1) above which the mean of the PSD is calculated and compared with psd_hf_threshold
direction (coeherence+psd): “x” | “y” | “z”, default: “y”: The depth dimension
highpass_filter_cutofffloat, default: 300: If the recording is not filtered, the cutoff frequency of the highpass filter
chunk_duration_sfloat, default: 0.5: Duration of each chunk
num_random_chunksint, default: 100: Number of random chunks Having many chunks is important for reproducibility.
welch_window_msfloat, default: 10: Window size for the scipy.signal.welch that will be converted to nperseg
neighborhood_r2_thresholdfloat, default: 0.95: R^2 threshold for the neighborhood_r2 method.
neighborhood_r2_radius_umfloat, default: 30: Spatial radius below which two channels are considered neighbors in the neighborhood_r2 method.
seedint or None, default: None: The random seed to extract chunks

Returns

bad_channel_idsnp.array

The identified bad channel ids

channel_labelsnp.array of str

Channels labels depending on the method:

(coeherence+psd) good/dead/noise/out
(std, mad) good/noise

Notes

For details refer to: International Brain Laboratory et al. (2022). Spike sorting pipeline for the International Brain Laboratory. https://www.internationalbrainlab.com/repro-ephys

Examples

>>> import spikeinterface.preprocessing as spre
>>> bad_channel_ids, channel_labels = spre.detect_bad_channels(recording, method="coherence+psd")
>>> # remove bad channels
>>> recording_clean = recording.remove_channels(bad_channel_ids)

spikeinterface.preprocessing.directional_derivative(recording: BaseRecording, direction: str = 'y', order: int = 1, edge_order: int = 1, dtype='float32')¶: Abstract class representing several a multichannel timeseries (or block of raw ephys traces). Internally handle list of RecordingSegment

spikeinterface.preprocessing.filter(recording, band=[300.0, 6000.0], btype='bandpass', filter_order=5, ftype='butter', filter_mode='sos', margin_ms=5.0, add_reflect_padding=False, coeff=None, dtype=None)¶

Generic filter class based on:

scipy.signal.iirfilter

scipy.signal.filtfilt or scipy.signal.sosfilt

BandpassFilterRecording is built on top of it.

Parameters

recording: Recording: The recording extractor to be re-referenced
band: float or list, default: [300.0, 6000.0]: If float, cutoff frequency in Hz for “highpass” filter type If list. band (low, high) in Hz for “bandpass” filter type
btype: “bandpass” | “highpass”, default: “bandpass”: Type of the filter
margin_ms: float, default: 5.0: Margin in ms on border to avoid border effect
filter_mode: “sos” | “ba”, default: “sos”: Filter form of the filter coefficients: - second-order sections (“sos”) - numerator/denominator: (“ba”)
coef: array or None, default: None: Filter coefficients in the filter_mode form.
dtype: dtype or None, default: None: The dtype of the returned traces. If None, the dtype of the parent recording is used
{}

Returns

filter_recording: FilterRecording: The filtered recording extractor object

spikeinterface.preprocessing.gaussian_filter(recording: BaseRecording, freq_min: float = 300.0, freq_max: float = 5000.0, margin_sd: float = 5.0)¶

Class for performing a gaussian filtering/smoothing on a recording.

This is done by a convolution with a Gaussian kernel, which acts as a lowpass-filter. A highpass-filter can be computed by subtracting the result of the convolution to the original signal. A bandpass-filter is obtained by substracting the signal smoothed with a narrow gaussian to the signal smoothed with a wider gaussian.

Here, convolution is performed in the Fourier domain to accelerate the computation.

Parameters

recording: BaseRecording: The recording extractor to be filtered.
freq_min: float or None: The lower frequency cutoff for the bandpass filter. If None, the resulting object is a lowpass filter.
freq_max: float or None: The higher frequency cutoff for the bandpass filter. If None, the resulting object is a highpass filter.
margin_sd: float, default: 5.0: The number of standard deviation to take for margins.

Returns

gaussian_filtered_recording: GaussianFilterRecording: The filtered recording extractor object.

spikeinterface.preprocessing.highpass_filter(recording, freq_min=300.0, margin_ms=5.0, dtype=None, **filter_kwargs)¶

Highpass filter of a recording

Parameters

recording: Recording: The recording extractor to be re-referenced
freq_min: float: The highpass cutoff frequency in Hz
margin_ms: float: Margin in ms on border to avoid border effect
dtype: dtype or None: The dtype of the returned traces. If None, the dtype of the parent recording is used
{}
Returns
——-
filter_recording: HighpassFilterRecording: The highpass-filtered recording extractor object

spikeinterface.preprocessing.highpass_spatial_filter(recording, n_channel_pad=60, n_channel_taper=0, direction='y', apply_agc=True, agc_window_length_s=0.1, highpass_butter_order=3, highpass_butter_wn=0.01)¶

Perform destriping with high-pass spatial filtering. Uses the kfilt() function of the International Brain Laboratory.

Median average filtering, by removing the median of signal across channels, assumes noise is constant across all channels. However, noise have exhibit low-frequency changes across nearby channels.

Alternative to median filtering across channels, in which the cut-band is extended from 0 to the 0.01 Nyquist corner frequency using butterworth filter. This allows removal of contaminating stripes that are not constant across channels.

Performs filtering on the 0 axis (across channels), with optional padding (mirrored) and tapering (cosine taper) prior to filtering. Applies a butterworth filter on the 0-axis with tapering / padding.

Parameters

recordingBaseRecording: The parent recording
n_channel_padint, default: 60: Number of channels to pad prior to filtering. Channels are padded with mirroring. If None, no padding is applied
n_channel_taperint, default: 0: Number of channels to perform cosine tapering on prior to filtering. If None and n_channel_pad is set, n_channel_taper will be set to the number of padded channels. Otherwise, the passed value will be used
direction“x” | “y” | “z”, default: “y”: The direction in which the spatial filter is applied
apply_agcbool, default: True: It True, Automatic Gain Control is applied
agc_window_length_sfloat, default: 0.1: Window in seconds to compute Hanning window for AGC
highpass_butter_orderint, default: 3: Order of spatial butterworth filter
highpass_butter_wnfloat, default: 0.01: Critical frequency (with respect to Nyquist) of spatial butterworth filter

Returns

highpass_recordingHighpassSpatialFilterRecording: The recording with highpass spatial filtered traces

References

Details of the high-pass spatial filter function (written by Olivier Winter) used in the IBL pipeline can be found at: International Brain Laboratory et al. (2022). Spike sorting pipeline for the International Brain Laboratory. https://www.internationalbrainlab.com/repro-ephys

spikeinterface.preprocessing.interpolate_bad_channels(recording, bad_channel_ids, sigma_um=None, p=1.3, weights=None)¶

Interpolate the channel labeled as bad channels using linear interpolation. This is based on the distance (Gaussian kernel) from the bad channel, as determined from x,y channel coordinates.

Details of the interpolation function (written by Olivier Winter) used in the IBL pipeline can be found at:

International Brain Laboratory et al. (2022). Spike sorting pipeline for the International Brain Laboratory. https://www.internationalbrainlab.com/repro-ephys

Parameters

recording: BaseRecording: The parent recording
bad_channel_idslist or 1d np.array: Channel ids of the bad channels to interpolate.
sigma_umfloat or None, default: None: Distance between sequential channels in um. If None, will use the most common distance between y-axis channels
pfloat, default: 1.3: Exponent of the Gaussian kernel. Determines rate of decay for distance weightings
weightsnp.array or None, default: None: The weights to give to bad_channel_ids at interpolation. If None, weights are automatically computed

Returns

interpolated_recording: InterpolateBadChannelsRecording: The recording object with interpolated bad channels

spikeinterface.preprocessing.normalize_by_quantile(recording, scale=1.0, median=0.0, q1=0.01, q2=0.99, mode='by_channel', dtype='float32', **random_chunk_kwargs)¶

Rescale the traces from the given recording extractor with a scalar and offset. First, the median and quantiles of the distribution are estimated. Then the distribution is rescaled and offset so that the scale is given by the distance between the quantiles (1st and 99th by default) is set to scale, and the median is set to the given median.

Parameters

recording: RecordingExtractor: The recording extractor to be transformed
scale: float, default: 1.0: Scale for the output distribution
median: float, default: 0.0: Median for the output distribution
q1: float, default: 0.01: Lower quantile used for measuring the scale
q1: float, default: 0.99: Upper quantile used for measuring the
mode: “by_channel” | “pool_channel”, default: “by_channel”: If “by_channel” each channel is rescaled independently.
dtype: str or np.dtype, default: “float32”: The dtype of the output traces
**random_chunk_kwargs: Keyword arguments for `spikeinterface.core.get_random_data_chunk()` function

Returns

rescaled_traces: NormalizeByQuantileRecording: The rescaled traces recording extractor object

spikeinterface.preprocessing.notch_filter(recording, freq=3000, q=30, margin_ms=5.0, dtype=None)¶

Parameters

recording: RecordingExtractor: The recording extractor to be notch-filtered
freq: int or float: The target frequency in Hz of the notch filter
q: int: The quality factor of the notch filter
{}
Returns
——-
filter_recording: NotchFilterRecording: The notch-filtered recording extractor object

spikeinterface.preprocessing.phase_shift(recording, margin_ms=40.0, inter_sample_shift=None, dtype=None)¶

This apply a phase shift to a recording to cancel the small sampling delay across for some recording system.

This is particularly relevant for neuropixel recording.

This code is inspired from from IBL lib. https://github.com/int-brain-lab/ibllib/blob/master/ibllib/dsp/fourier.py and also the one from spikeglx https://billkarsh.github.io/SpikeGLX/help/dmx_vs_gbl/dmx_vs_gbl/

Parameters

recording: Recording: The recording. It need to have “inter_sample_shift” in properties.
margin_ms: float, default: 40.0: Margin in ms for computation. 40ms ensure a very small error when doing chunk processing
inter_sample_shift: None or numpy array, default: None: If “inter_sample_shift” is not in recording properties, we can externally provide one.

Returns

filter_recording: PhaseShiftRecording: The phase shifted recording object

spikeinterface.preprocessing.rectify(recording)¶: Abstract class representing several a multichannel timeseries (or block of raw ephys traces). Internally handle list of RecordingSegment

spikeinterface.preprocessing.remove_artifacts(recording, list_triggers, ms_before=0.5, ms_after=3.0, mode='zeros', fit_sample_spacing=1.0, list_labels=None, artifacts=None, sparsity=None, scale_amplitude=False, time_jitter=0, waveforms_kwargs={'allow_unfiltered': True, 'mode': 'memory'})¶

Removes stimulation artifacts from recording extractor traces. By default, artifact periods are zeroed-out (mode = “zeros”). This is only recommended for traces that are centered around zero (e.g. through a prior highpass filter); if this is not the case, linear and cubic interpolation modes are also available, controlled by the “mode” input argument. Note that several artifacts can be removed at once (potentially with distinct duration each), if labels are specified

Parameters

recording: RecordingExtractor

The recording extractor to remove artifacts from

list_triggers: list of lists/arrays

One list per segment of int with the stimulation trigger frames

ms_before: float or None, default: 0.5

Time interval in ms to remove before the trigger events. If None, then also ms_after must be None and a single sample is removed

ms_after: float or None, default: 3.0

Time interval in ms to remove after the trigger events. If None, then also ms_before must be None and a single sample is removed

list_labels: list of lists/arrays or None

One list per segment of labels with the stimulation labels for the given artefacs. labels should be strings, for JSON serialization. Required for “median” and “average” modes.

mode: “zeros”, “linear”, “cubic”, “average”, “median”, default: “zeros”

Determines what artifacts are replaced by. Can be one of the following:

“zeros”: Artifacts are replaced by zeros.
“median”: The median over all artifacts is computed and subtracted for
each occurence of an artifact
“average”: The mean over all artifacts is computed and subtracted for each
occurence of an artifact
“linear”: Replacement are obtained through Linear interpolation between
the trace before and after the artifact. If the trace starts or ends with an artifact period, the gap is filled with the closest available value before or after the artifact.
“cubic”: Cubic spline interpolation between the trace before and after
the artifact, referenced to evenly spaced fit points before and after the artifact. This is an option thatcan be helpful if there are significant LFP effects around the time of the artifact, but visual inspection of fit behaviour with your chosen settings is recommended. The spacing of fit points is controlled by “fit_sample_spacing”, with greater spacing between points leading to a fit that is less sensitive to high frequency fluctuations but at the cost of a less smooth continuation of the trace. If the trace starts or ends with an artifact, the gap is filled with the closest available value before or after the artifact.

fit_sample_spacing: float, default: 1.0

Determines the spacing (in ms) of reference points for the cubic spline fit if mode = “cubic”. Note: The actual fit samples are the median of the 5 data points around the time of each sample point to avoid excessive influence from hyper-local fluctuations.

artifacts: dict or None, default: None

If provided (when mode is “median” or “average”) then it must be a dict with keys that are the labels of the artifacts, and values the artifacts themselves, on all channels (and thus bypassing ms_before and ms_after)

sparsity: dict or None, default: None

If provided (when mode is “median” or “average”) then it must be a dict with keys that are the labels of the artifacts, and values that are boolean mask of the channels where the artifacts should be considered (for subtraction/scaling)

scale_amplitude: False, default: False

If true, then for mode “median” or “average” the amplitude of the template will be scaled in amplitude at each time occurence to minimize residuals

time_jitter: float, default: 0

If non 0, then for mode “median” or “average”, a time jitter in ms can be allowed to minimize the residuals

waveforms_kwargs: dict or None, default: None

The arguments passed to the WaveformExtractor object when extracting the artifacts, for mode “median” or “average”. By default, the global job kwargs are used, in addition to {“allow_unfiltered” : True, “mode”:”memory”}. To estimate sparse artifact

Returns

removed_recording: RemoveArtifactsRecording: The recording extractor after artifact removal

spikeinterface.preprocessing.resample(recording, resample_rate, margin_ms=100.0, dtype=None, skip_checks=False)¶

Resample the recording extractor traces.

If the original sampling rate is multiple of the resample_rate, it will use the signal.decimate method from scipy. In other cases, it uses signal.resample. In the later case, the resulting signal can have issues on the edges, mainly on the rightmost.

Parameters

recordingRecording: The recording extractor to be re-referenced
resample_rateint: The resampling frequency
marginfloat, default: 100.0: Margin in ms for computations, will be used to decrease edge effects.
dtypedtype or None, default: None: The dtype of the returned traces. If None, the dtype of the parent recording is used.
skip_checksbool, default: False: If True, checks on sampling frequencies and cutoff filter frequencies are skipped

Returns

resample_recording: ResampleRecording: The resampled recording extractor object.

spikeinterface.preprocessing.scale(recording, gain=1.0, offset=0.0, dtype='float32')¶

Scale traces from the given recording extractor with a scalar and offset. New traces = traces*scalar + offset.

Parameters

recording: RecordingExtractor: The recording extractor to be transformed
gain: float or array: Scalar for the traces of the recording extractor or array with scalars for each channel
offset: float or array: Offset for the traces of the recording extractor or array with offsets for each channel
dtype: str or np.dtype, default: “float32”: The dtype of the output traces

Returns

transform_traces: ScaleRecording: The transformed traces recording extractor object

spikeinterface.preprocessing.silence_periods(recording, list_periods, mode='zeros', noise_levels=None, **random_chunk_kwargs)¶

Silence user-defined periods from recording extractor traces. By default, periods are zeroed-out (mode = “zeros”). You can also fill the periods with noise. Note that both methods assume that traces that are centered around zero. If this is not the case, make sure you apply a filter or center function prior to silencing periods.

Parameters

recording: RecordingExtractor

The recording extractor to silance periods

list_periods: list of lists/arrays

One list per segment of tuples (start_frame, end_frame) to silence

noise_levels: array

Noise levels if already computed

mode: “zeros” | “noise, default: “zeros”

Determines what periods are replaced by. Can be one of the following:

“zeros”: Artifacts are replaced by zeros.
“noise”: The periods are filled with a gaussion noise that has the
same variance that the one in the recordings, on a per channel basis

**random_chunk_kwargs: Keyword arguments for `spikeinterface.core.get_random_data_chunk()` function

Returns

silence_recording: SilencedPeriodsRecording: The recording extractor after silencing some periods

spikeinterface.preprocessing.unsigned_to_signed(recording, bit_depth=None)¶

Converts a recording with unsigned traces to a signed one.

Parameters

recording: Recording: The recording to be signed.
bit_depth: int or None, default: None: In case the bit depth of the ADC does not match that of the data type, it specifies the bit depth of the ADC to estimate the offset. For example, a bit_depth of 12 will correct for an offset of 2**11

spikeinterface.preprocessing.whiten(recording, dtype=None, apply_mean=False, mode='global', radius_um=100.0, int_scale=None, eps=None, W=None, M=None, **random_chunk_kwargs)¶

Whitens the recording extractor traces.

Parameters

recording: RecordingExtractor: The recording extractor to be whitened.
dtype: None or dtype, default: None: If None the the parent dtype is kept. For integer dtype a int_scale must be also given.
mode: “global” | “local”, default: “global”: “global” use the entire covariance matrix to compute the W matrix “local” use local covariance (by radius) to compute the W matrix
radius_um: None or float, default: None: Used for mode = “local” to get the neighborhood
apply_mean: bool, default: False: Substract or not the mean matrix M before the dot product with W.
int_scaleNone or float, default: None: Apply a scaling factor to fit the integer range. This is used when the dtype is an integer, so that the output is scaled. For example, a value of int_scale=200 will scale the traces value to a standard deviation of 200.
epsfloat or None, default: None: Small epsilon to regularize SVD. If None, eps is defaulted to 1e-8. If the data is float type and scaled down to very small values, then the eps is automatically set to a small fraction (1e-3) of the median of the squared data.
W2d np.array or None, default: None: Pre-computed whitening matrix
M1d np.array or None, default: None: Pre-computed means. M can be None when previously computed with apply_mean=False
**random_chunk_kwargsKeyword arguments for spikeinterface.core.get_random_data_chunk() function

Returns

whitened_recording: WhitenRecording: The whitened recording extractor

spikeinterface.preprocessing.zero_channel_pad(parent_recording: BaseRecording, num_channels: int, channel_mapping: Union[list, None] = None)¶: Abstract class representing several a multichannel timeseries (or block of raw ephys traces). Internally handle list of RecordingSegment

spikeinterface.preprocessing.zscore(recording, mode='median+mad', gain=None, offset=None, int_scale=None, dtype='float32', **random_chunk_kwargs)¶

Centers traces from the given recording extractor by removing the median of each channel and dividing by the MAD.

Parameters

recording: RecordingExtractor: The recording extractor to be centered
mode: “median+mad” | “mean+std”, default: “median+mad”: The mode to compute the zscore
dtype: None or dtype: If None the the parent dtype is kept. For integer dtype a int_scale must be also given.
gainNone or np.array: Pre-computed gain.
offsetNone or np.array: Pre-computed offset
int_scaleNone or float: Apply a scaling factor to fit the integer range. This is used when the dtype is an integer, so that the output is scaled. For example, a value of int_scale=200 will scale the zscore value to a standard deviation of 200.
**random_chunk_kwargs: Keyword arguments for `spikeinterface.core.get_random_data_chunk()` function

Returns

centered_traces: ScaleRecording: The centered traces recording extractor object

spikeinterface.postprocessing¶

spikeinterface.postprocessing.compute_noise_levels(waveform_extractor, load_if_exists=False, **params)¶

Computes the noise level associated to each recording channel.

This function will wraps the get_noise_levels(recording) to make the noise levels persistent on disk (folder or zarr) as a WaveformExtension. The noise levels do not depend on the unit list, only the recording, but it is a convenient way to retrieve the noise levels directly ine the WaveformExtractor.

Note that the noise levels can be scaled or not, depending on the return_scaled parameter of the WaveformExtractor.

Parameters

waveform_extractor: WaveformExtractor: A waveform extractor object
load_if_exists: bool, default: False: If True, the noise levels are loaded if they already exist
**params: dict with additional parameters

Returns

noise_levels: np.array: noise level vector.

spikeinterface.postprocessing.compute_template_metrics(waveform_extractor, load_if_exists: bool = False, metric_names: Optional[list[str]] = None, peak_sign: Optional[str] = 'neg', upsampling_factor: int = 10, sparsity: Optional[ChannelSparsity] = None, include_multi_channel_metrics: bool = False, metrics_kwargs: Optional[dict] = None)¶

Compute template metrics including:

peak_to_valley
peak_trough_ratio
halfwidth
repolarization_slope
recovery_slope
num_positive_peaks
num_negative_peaks

Optionally, the following multi-channel metrics can be computed (when include_multi_channel_metrics=True):

velocity_above
velocity_below
exp_decay
spread

Parameters

waveform_extractorWaveformExtractor

The waveform extractor used to compute template metrics

load_if_existsbool, default: False

Whether to load precomputed template metrics, if they already exist.

metric_nameslist or None, default: None

List of metrics to compute (see si.postprocessing.get_template_metric_names())

peak_sign{“neg”, “pos”}, default: “neg”

Whether to use the positive (“pos”) or negative (“neg”) peaks to estimate extremum channels.

upsampling_factorint, default: 10

The upsampling factor to upsample the templates

sparsity: ChannelSparsity or None, default: None

If None, template metrics are computed on the extremum channel only. If sparsity is given, template metrics are computed on all sparse channels of each unit. For more on generating a ChannelSparsity, see the ~spikeinterface.compute_sparsity() function.

include_multi_channel_metrics: bool, default: False

Whether to compute multi-channel metrics

metrics_kwargs: dict

Additional arguments to pass to the metric functions. Including:

recovery_window_ms: the window in ms after the peak to compute the recovery_slope, default: 0.7
peak_relative_threshold: the relative threshold to detect positive and negative peaks, default: 0.2
peak_width_ms: the width in samples to detect peaks, default: 0.2
depth_direction: the direction to compute velocity above and below, default: “y” (see notes)
min_channels_for_velocity: the minimum number of channels above or below to compute velocity, default: 5
min_r2_velocity: the minimum r2 to accept the velocity fit, default: 0.7
exp_peak_function: the function to use to compute the peak amplitude for the exp decay, default: “ptp”
min_r2_exp_decay: the minimum r2 to accept the exp decay fit, default: 0.5
spread_threshold: the threshold to compute the spread, default: 0.2
spread_smooth_um: the smoothing in um to compute the spread, default: 20
column_range: the range in um in the horizontal direction to consider channels for velocity, default: None
- If None, all channels all channels are considered
- If 0 or 1, only the “column” that includes the max channel is considered
- If > 1, only channels within range (+/-) um from the max channel horizontal position are used

Returns

template_metricspd.DataFrame: Dataframe with the computed template metrics. If “sparsity” is None, the index is the unit_id. If “sparsity” is given, the index is a multi-index (unit_id, channel_id)

Notes

If any multi-channel metric is in the metric_names or include_multi_channel_metrics is True, sparsity must be None, so that one metric value will be computed per unit. For multi-channel metrics, 3D channel locations are not supported. By default, the depth direction is “y”.

spikeinterface.postprocessing.compute_principal_components(waveform_extractor, load_if_exists=False, n_components=5, mode='by_channel_local', sparsity=None, whiten=True, dtype='float32', tmp_folder=None, **job_kwargs)¶

Compute PC scores from waveform extractor. The PCA projections are pre-computed only on the sampled waveforms available from the WaveformExtractor.

Parameters

waveform_extractor: WaveformExtractor

The waveform extractor

load_if_exists: bool, default: False

If True and pc scores are already in the waveform extractor folders, pc scores are loaded and not recomputed.

n_components: int, default: 5

Number of components fo PCA

mode: “by_channel_local” | “by_channel_global” | “concatenated”, default: “by_channel_local”

The PCA mode:

“by_channel_local”: a local PCA is fitted for each channel (projection by channel)
“by_channel_global”: a global PCA is fitted for all channels (projection by channel)
“concatenated”: channels are concatenated and a global PCA is fitted

sparsity: ChannelSparsity or None, default: None

The sparsity to apply to waveforms. If waveform_extractor is already sparse, the default sparsity will be used

whiten: bool, default: True

If True, waveforms are pre-whitened

dtype: dtype, default: “float32”

Dtype of the pc scores

tmp_folder: str or Path or None, default: None

The temporary folder to use for parallel computation. If you run several compute_principal_components functions in parallel with mode “by_channel_local”, you need to specify a different tmp_folder for each call, to avoid overwriting to the same folder

n_jobs: int, default: 1

Number of jobs used to fit the PCA model (if mode is “by_channel_local”)

progress_bar: bool, default: False

If True, a progress bar is shown

Returns

pc: WaveformPrincipalComponent: The waveform principal component object

Examples

>>> we = si.extract_waveforms(recording, sorting, folder='waveforms')
>>> pc = si.compute_principal_components(we, n_components=3, mode='by_channel_local')
>>> # get pre-computed projections for unit_id=1
>>> projections = pc.get_projections(unit_id=1)
>>> # get all pre-computed projections and labels
>>> all_projections, all_labels = pc.get_all_projections()
>>> # retrieve fitted pca model(s)
>>> pca_model = pc.get_pca_model()
>>> # compute projections on new waveforms
>>> proj_new = pc.project_new(new_waveforms)
>>> # run for all spikes in the SortingExtractor
>>> pc.run_for_all_spikes(file_path="all_pca_projections.npy")

spikeinterface.postprocessing.compute_spike_amplitudes(waveform_extractor, load_if_exists=False, peak_sign='neg', return_scaled=True, outputs='concatenated', **job_kwargs)¶

Computes the spike amplitudes from a WaveformExtractor.

The waveform extractor is used to determine the max channel per unit.
Then a “peak_shift” is estimated because for some sorters the spike index is not always at the peak.
Amplitudes are extracted in chunks (parallel or not)

Parameters

waveform_extractor: WaveformExtractor: The waveform extractor object
load_if_existsbool, default: False: Whether to load precomputed spike amplitudes, if they already exist.
peak_sign: “neg” | “pos” | “both”, default: “neg: The sign to compute maximum channel
return_scaled: bool, deafult: True: If True and recording has gain_to_uV/offset_to_uV properties, amplitudes are converted to uV.
outputs: “concatenated” | “by_unit”, default: “concatenated”: How the output should be returned
{}

Returns

amplitudes: np.array or list of dict

The spike amplitudes.

If “concatenated” all amplitudes for all spikes and all units are concatenated
If “by_unit”, amplitudes are returned as a list (for segments) of dictionaries (for units)

spikeinterface.postprocessing.compute_unit_locations(waveform_extractor, load_if_exists=False, method='monopolar_triangulation', outputs='numpy', **method_kwargs)¶

Localize units in 2D or 3D with several methods given the template.

Parameters

waveform_extractor: WaveformExtractor: A waveform extractor object
load_if_existsbool, default: False: Whether to load precomputed unit locations, if they already exist
method: “center_of_mass” | “monopolar_triangulation” | “grid_convolution”, default: “center_of_mass”: The method to use for localization
outputs: “numpy” | “by_unit”, default: “numpy”: The output format
method_kwargs:: Other kwargs depending on the method

Returns

unit_locations: np.array: unit location with shape (num_unit, 2) or (num_unit, 3) or (num_unit, 3) (with alpha)

spikeinterface.postprocessing.compute_spike_locations(waveform_extractor, load_if_exists=False, ms_before=0.5, ms_after=0.5, spike_retriver_kwargs={'channel_from_template': True, 'peak_sign': 'neg', 'radius_um': 50}, method='center_of_mass', method_kwargs={}, outputs='concatenated', **job_kwargs)¶

Localize spikes in 2D or 3D with several methods given the template.

Parameters

waveform_extractorWaveformExtractor

A waveform extractor object

load_if_existsbool, default: False

Whether to load precomputed spike locations, if they already exist

ms_beforefloat, default: 0.5

The left window, before a peak, in milliseconds

ms_afterfloat, default: 0.5

The right window, after a peak, in milliseconds

spike_retriver_kwargs: dict

A dictionary to control the behavior for getting the maximum channel for each spike This dictionary contains:

channel_from_template: bool, default: True
For each spike is the maximum channel computed from template or re estimated at every spikes channel_from_template = True is old behavior but less acurate channel_from_template = False is slower but more accurate

radius_um: float, default: 50
In case channel_from_template=False, this is the radius to get the true peak

peak_sign, default: “neg”
In case channel_from_template=False, this is the peak sign.

method“center_of_mass” | “monopolar_triangulation” | “grid_convolution”, default: “center_of_mass”

The localization method to use

method_kwargsdict, default: dict()

Other kwargs depending on the method.

outputs“concatenated” | “by_unit”, default: “concatenated”

The output format

{}

Returns

spike_locations: np.array or list of dict

The spike locations.

If “concatenated” all locations for all spikes and all units are concatenated
If “by_unit”, locations are returned as a list (for segments) of dictionaries (for units)

spikeinterface.postprocessing.compute_template_similarity(waveform_extractor, load_if_exists=False, method='cosine_similarity', waveform_extractor_other=None)¶

Compute similarity between templates with several methods.

Parameters

waveform_extractor: WaveformExtractor: A waveform extractor object
load_if_existsbool, default: False: Whether to load precomputed similarity, if is already exists.
method: str, default: “cosine_similarity”: The method to compute the similarity
waveform_extractor_other: WaveformExtractor, default: None: A second waveform extractor object

Returns

similarity: np.array: The similarity matrix

spikeinterface.postprocessing.compute_correlograms(waveform_or_sorting_extractor, load_if_exists=False, window_ms: float = 50.0, bin_ms: float = 1.0, method: auto' | 'numpy' | 'numba = 'auto')¶

Compute auto and cross correlograms.

Parameters

waveform_or_sorting_extractorWaveformExtractor or BaseSorting: If WaveformExtractor, the correlograms are saved as WaveformExtensions
load_if_existsbool, default: False: Whether to load precomputed crosscorrelograms, if they already exist
window_msfloat, default: 100.0: The window in ms
bin_msfloat, default: 5: The bin size in ms
method“auto” | “numpy” | “numba”, default: “auto”: If “auto” and numba is installed, numba is used, otherwise numpy is used

Returns

ccgsnp.array: Correlograms with shape (num_units, num_units, num_bins) The diagonal of ccgs is the auto correlogram. ccgs[A, B, :] is the symmetry of ccgs[B, A, :] ccgs[A, B, :] have to be read as the histogram of spiketimesA - spiketimesB
binsnp.array: The bin edges in ms

spikeinterface.postprocessing.compute_isi_histograms(waveform_or_sorting_extractor, load_if_exists=False, window_ms: float = 50.0, bin_ms: float = 1.0, method: str = 'auto')¶

Compute ISI histograms.

Parameters

waveform_or_sorting_extractorWaveformExtractor or BaseSorting: If WaveformExtractor, the ISI histograms are saved as WaveformExtensions
load_if_existsbool, default: False: Whether to load precomputed crosscorrelograms, if they already exist
window_msfloat, default: 50: The window in ms
bin_msfloat, default: 1: The bin size in ms
method“auto” | “numpy” | “numba”, default: “auto”: . If “auto” and numba is installed, numba is used, otherwise numpy is used

Returns

isi_histogramsnp.array: IDI_histograms with shape (num_units, num_bins)
binsnp.array: The bin edges in ms

spikeinterface.postprocessing.get_template_metric_names()¶

spikeinterface.postprocessing.align_sorting(sorting, unit_peak_shifts)¶

Class to shift a unit (generally to align the template on the peak) given the shifts for each unit.

Parameters

sorting: BaseSorting: The sorting to align.
unit_peak_shifts: dict: Dictionary mapping the unit_id to the unit’s shift (in number of samples). A positive shift means the spike train is shifted back in time, while a negative shift means the spike train is shifted forward.

Returns

aligned_sorting: AlignSortingExtractor: The aligned sorting.

spikeinterface.qualitymetrics¶

spikeinterface.qualitymetrics.compute_quality_metrics(waveform_extractor, load_if_exists=False, metric_names=None, qm_params=None, peak_sign=None, seed=None, sparsity=None, skip_pc_metrics=False, verbose=False, **job_kwargs)¶

Compute quality metrics on waveform extractor.

Parameters

waveform_extractor: WaveformExtractor: The waveform extractor to compute metrics on.
load_if_existsbool, default: False: Whether to load precomputed quality metrics, if they already exist.
metric_nameslist or None: List of quality metrics to compute.
qm_paramsdict or None: Dictionary with parameters for quality metrics calculation. Default parameters can be obtained with: si.qualitymetrics.get_default_qm_params()
sparsitydict or None, default: None: If given, the sparse channel_ids for each unit in PCA metrics computation. This is used also to identify neighbor units and speed up computations. If None all channels and all units are used for each unit.
skip_pc_metricsbool: If True, PC metrics computation is skipped.
n_jobsint: Number of jobs (used for PCA metrics)
verbosebool: If True, output is verbose.
progress_barbool: If True, progress bar is shown.

Returns

metrics: pandas.DataFrame: Data frame with the computed metrics

spikeinterface.qualitymetrics.get_quality_metric_list()¶: Get a list of the available quality metrics.

spikeinterface.qualitymetrics.get_quality_pca_metric_list()¶: Get a list of the available PCA-based quality metrics.

spikeinterface.qualitymetrics.get_default_qm_params()¶

Return default dictionary of quality metrics parameters.

Returns

dict: Default qm parameters with metric name as key and parameter dictionary as values.

spikeinterface.sorters¶

spikeinterface.sorters.available_sorters()¶: Lists available sorters.

spikeinterface.sorters.installed_sorters()¶: Lists installed sorters.

spikeinterface.sorters.get_default_sorter_params(sorter_name_or_class)¶

Returns default parameters for the specified sorter.

Parameters

sorter_name_or_class: str or SorterClass: The sorter to retrieve default parameters from.

Returns

default_params: dict: Dictionary with default params for the specified sorter.

spikeinterface.sorters.get_sorter_params_description(sorter_name_or_class)¶

Returns a description of the parameters for the specified sorter.

Parameters

sorter_name_or_class: str or SorterClass: The sorter to retrieve parameters description from.

Returns

params_description: dict: Dictionary with parameter description

spikeinterface.sorters.print_sorter_versions()¶: “Prints the versions of the installed sorters.

spikeinterface.sorters.get_sorter_description(sorter_name_or_class)¶

Returns a brief description for the specified sorter.

Parameters

sorter_name_or_class: str or SorterClass: The sorter to retrieve description from.

Returns

params_description: dict: Dictionary with parameter description.

spikeinterface.sorters.run_sorter(sorter_name: str, recording: BaseRecording, output_folder: Optional[str] = None, remove_existing_folder: bool = False, delete_output_folder: bool = False, verbose: bool = False, raise_error: bool = True, docker_image: Optional[Union[bool, str]] = False, singularity_image: Optional[Union[bool, str]] = False, delete_container_files: bool = True, with_output: bool = True, **sorter_params)¶

Generic function to run a sorter via function approach.

Parameters

sorter_name: str

The sorter name

recording: RecordingExtractor

The recording extractor to be spike sorted

output_folder: str or Path

Path to output folder

remove_existing_folder: bool

If True and output_folder exists yet then delete.

delete_output_folder: bool, default: False

If True, output folder is deleted

verbose: bool, default: False

If True, output is verbose

raise_error: bool, default: True

If True, an error is raised if spike sorting fails If False, the process continues and the error is logged in the log file.

docker_image: bool or str, default: False

If True, pull the default docker container for the sorter and run the sorter in that container using docker. Use a str to specify a non-default container. If that container is not local it will be pulled from docker hub. If False, the sorter is run locally

singularity_image: bool or str, default: False

If True, pull the default docker container for the sorter and run the sorter in that container using singularity. Use a str to specify a non-default container. If that container is not local it will be pulled from Docker Hub. If False, the sorter is run locally

with_output: bool, default: True

If True, the output Sorting is returned as a Sorting

delete_container_files: bool, default: True

If True, the container temporary files are deleted after the sorting is done

extra_requirements: list, default: None

List of extra requirements to install in the container

How spikeinterface is installed in the container:

“auto”: if host installation is a pip release then use “github” with tag
if host installation is DEV_MODE=True then use “dev”
“pypi”: use pypi with pip install spikeinterface
“github”: use github with pip install git+https
“folder”: mount a folder in container and install from this one.
So the version in the container is a different spikeinterface version from host, useful for cross checks
“dev”: same as “folder”, but the folder is the spikeinterface.__file__ to ensure same version as host
“no-install”: do not install spikeinterface in the container because it is already installed

spikeinterface_version: str, default: None

The spikeinterface version to install in the container. If None, the current version is used

spikeinterface_folder_source: Path or None, default: None

In case of installation_mode=”folder”, the spikeinterface folder source to use to install in the container

**sorter_params: keyword args

Spike sorter specific arguments (they can be retrieved with get_default_sorter_params(sorter_name_or_class))

Returns

BaseSorting | None: The spike sorted data (it with_output is True) or None (if with_output is False)

Examples

>>> sorting = run_sorter("tridesclous", recording)

spikeinterface.sorters.run_sorter_jobs(job_list, engine='loop', engine_kwargs={}, return_output=False)¶

Run several run_sorter() sequentially or in parallel given a list of jobs.

For engine=”loop” this is equivalent to:

..code:

for job in job_list:
    run_sorter(**job)

The following engines block the I/O:

“loop”
“joblib”
“multiprocessing”
“dask”

The following engines are asynchronous:

“slurm”

Where blocking means that this function is blocking until the results are returned. This is in opposition to asynchronous, where the function returns None almost immediately (aka non-blocking), but the results must be retrieved by hand when jobs are finished. No mechanisim is provided here to be know when jobs are finish. In this asynchronous case, the read_sorter_folder() helps to retrieve individual results.

Parameters

job_list: list of dict: A list a dict that are propagated to run_sorter(…)
engine: str “loop”, “joblib”, “dask”, “slurm”: The engine to run the list. * “loop”: a simple loop. This engine is
engine_kwargs: dict
return_output: bool, dfault False: Return a sortings or None. This also overwrite kwargs in in run_sorter(with_sorting=True/False)

Returns

sortings: None or list of sorting: With engine=”loop” or “joblib” you can optional get directly the list of sorting result if return_output=True.

spikeinterface.sorters.run_sorter_by_property(sorter_name, recording, grouping_property, working_folder, mode_if_folder_exists=None, engine='loop', engine_kwargs={}, verbose=False, docker_image=None, singularity_image=None, **sorter_params)¶

Generic function to run a sorter on a recording after splitting by a “grouping_property” (e.g. “group”).

Internally, the function works as follows:

the recording is split based on the provided “grouping_property” (using the “split_by” function)
the “run_sorters” function is run on the split recordings
sorting outputs are aggregated using the “aggregate_units” function
the “grouping_property” is added as a property to the SortingExtractor

Parameters

sorter_name: str

The sorter name

recording: BaseRecording

The recording to be sorted

grouping_property: object

Property to split by before sorting

working_folder: str

The working directory.

mode_if_folder_exists: bool or None, default: None

Must be None. This is deprecated. If not None then a warning is raise. Will be removed in next release.

engine: “loop” | “joblib” | “dask”, default: “loop”

Which engine to use to run sorter.

engine_kwargs: dict

This contains kwargs specific to the launcher engine:

“loop” : no kwargs
“joblib” : {“n_jobs” : } number of processes
“dask” : {“client”:} the dask client for submitting task

verbose: bool, default: False

Controls sorter verboseness

docker_image: None or str, default: None

If str run the sorter inside a container (docker) using the docker package

**sorter_params: keyword args

Spike sorter specific arguments (they can be retrieved with get_default_sorter_params(sorter_name_or_class))

Returns

sortingUnitsAggregationSorting: The aggregated SortingExtractor.

Examples

This example shows how to run spike sorting split by group using the “joblib” backend with 4 jobs for parallel processing.

>>> sorting = si.run_sorter_by_property("tridesclous", recording, grouping_property="group",
                                        working_folder="sort_by_group", engine="joblib",
                                        engine_kwargs={"n_jobs": 4})

spikeinterface.sorters.read_sorter_folder(output_folder, register_recording=True, sorting_info=True, raise_error=True)¶

Load a sorting object from a spike sorting output folder. The ‘output_folder’ must contain a valid ‘spikeinterface_log.json’ file

Parameters

output_folder: Pth or str: The sorter folder
register_recording: bool, default: True: Attach recording (when json or pickle) to the sorting
sorting_info: bool, default: True: Attach sorting info to the sorting.

Low level¶

class spikeinterface.sorters.BaseSorter(recording=None, output_folder=None, verbose=False, remove_existing_folder=False, delete_output_folder=False)¶: Base Sorter object.

spikeinterface.comparison¶

spikeinterface.comparison.compare_two_sorters(sorting1, sorting2, sorting1_name=None, sorting2_name=None, delta_time=0.4, match_score=0.5, chance_score=0.1, n_jobs=-1, verbose=False)¶

Compares two spike sorter outputs.

Spike trains are matched based on their agreement scores
Individual spikes are labelled as true positives (TP), false negatives (FN), false positives 1 (FP from spike train 1), false positives 2 (FP from spike train 2), misclassifications (CL)

It also allows to get confusion matrix and agreement fraction, false positive fraction and false negative fraction.

Parameters

sorting1: SortingExtractor: The first sorting for the comparison
sorting2: SortingExtractor: The second sorting for the comparison
sorting1_name: str, default: None: The name of sorter 1
sorting2_name:str, default: None: The name of sorter 2
delta_time: float, default: 0.4: Number of ms to consider coincident spikes
match_score: float, default: 0.5: Minimum agreement score to match units
chance_score: float, default: 0.1: Minimum agreement score to for a possible match
n_jobs: int, default: -1: Number of cores to use in parallel. Uses all available if -1
verbose: bool, default: False: If True, output is verbose

Returns

sorting_comparison: SortingComparison: The SortingComparison object

spikeinterface.comparison.compare_multiple_sorters(sorting_list, name_list=None, delta_time=0.4, match_score=0.5, chance_score=0.1, n_jobs=-1, spiketrain_mode='union', verbose=False, do_matching=True)¶

Compares multiple spike sorting outputs based on spike trains.

Pair-wise comparisons are made
An agreement graph is built based on the agreement score

It allows to return a consensus-based sorting extractor with the get_agreement_sorting() method.

Parameters

sorting_list: list

List of sorting extractor objects to be compared

name_list: list, default: None

List of spike sorter names. If not given, sorters are named as “sorter0”, “sorter1”, “sorter2”, etc.

delta_time: float, default: 0.4

Number of ms to consider coincident spikes

match_score: float, default: 0.5

Minimum agreement score to match units

chance_score: float, default: 0.1

Minimum agreement score to for a possible match

n_jobs: int, default: -1

Number of cores to use in parallel. Uses all available if -1

spiketrain_mode: “union” | “intersection”, default: “union”

Mode to extract agreement spike trains:

“union”: spike trains are the union between the spike trains of the best matching two sorters
“intersection”: spike trains are the intersection between the spike trains of the
best matching two sorters

verbose: bool, default: False

if True, output is verbose

Returns

multi_sorting_comparison: MultiSortingComparison: MultiSortingComparison object with the multiple sorter comparison

spikeinterface.comparison.compare_sorter_to_ground_truth(gt_sorting, tested_sorting, gt_name=None, tested_name=None, delta_time=0.4, sampling_frequency=None, match_score=0.5, well_detected_score=0.8, redundant_score=0.2, overmerged_score=0.2, chance_score=0.1, exhaustive_gt=False, n_jobs=-1, match_mode='hungarian', compute_labels=False, compute_misclassifications=False, verbose=False)¶

Compares a sorter to a ground truth.

This class can:

compute a “match between gt_sorting and tested_sorting
compute optionally the score label (TP, FN, CL, FP) for each spike
count by unit of GT the total of each (TP, FN, CL, FP) into a Dataframe GroundTruthComparison.count
compute the confusion matrix .get_confusion_matrix()
compute some performance metric with several strategy based on the count score by unit
count well detected units
count false positive detected units
count redundant units
count overmerged units
summary all this

Parameters

gt_sorting: SortingExtractor: The first sorting for the comparison
tested_sorting: SortingExtractor: The second sorting for the comparison
gt_name: str, default: None: The name of sorter 1
tested_name:str, default: None: The name of sorter 2
delta_time: float, default: 0.4: Number of ms to consider coincident spikes
match_score: float, default: 0.5: Minimum agreement score to match units
chance_score: float, default: 0.1: Minimum agreement score to for a possible match
redundant_score: float, default: 0.2: Agreement score above which units are redundant
overmerged_score: float, default: 0.2: Agreement score above which units can be overmerged
well_detected_score: float, default: 0.8: Agreement score above which units are well detected
exhaustive_gt: bool, default: False: Tell if the ground true is “exhaustive” or not. In other world if the GT have all possible units. It allows more performance measurement. For instance, MEArec simulated dataset have exhaustive_gt=True
match_mode: “hungarian” | “best”, default: “hungarian”: The method to match units
n_jobs: int, default: -1: Number of cores to use in parallel. Uses all available if -1
compute_labels: bool, default: False: If True, labels are computed at instantiation
compute_misclassifications: bool, default: False: If True, misclassifications are computed at instantiation
verbose: bool, default: False: If True, output is verbose

Returns

sorting_comparison: SortingComparison: The SortingComparison object

spikeinterface.comparison.compare_templates(we1, we2, we1_name=None, we2_name=None, unit_ids1=None, unit_ids2=None, match_score=0.7, chance_score=0.3, similarity_method='cosine_similarity', sparsity_dict=None, verbose=False)¶

Compares units from different sessions based on template similarity

Parameters

we1WaveformExtractor: The first waveform extractor to get templates to compare
we2WaveformExtractor: The second waveform extractor to get templates to compare
unit_ids1list, default: None: List of units from we1 to compare
unit_ids2list, default: None: List of units from we2 to compare
similarity_methodstr, default: “cosine_similarity”: Method for the similaroty matrix
sparsity_dictdict, default: None: Dictionary for sparsity
verbosebool, default: False: If True, output is verbose

Returns

comparisonTemplateComparison: The output TemplateComparison object

spikeinterface.comparison.compare_multiple_templates(waveform_list, name_list=None, match_score=0.8, chance_score=0.3, verbose=False, similarity_method='cosine_similarity', sparsity_dict=None, do_matching=True)¶

Compares multiple waveform extractors using template similarity.

Pair-wise comparisons are made
An agreement graph is built based on the agreement score

Parameters

waveform_list: list: List of waveform extractor objects to be compared
name_list: list, default: None: List of session names. If not given, sorters are named as “sess0”, “sess1”, “sess2”, etc.
match_score: float, default: 0.8: Minimum agreement score to match units
chance_score: float, default: 0.3: Minimum agreement score to for a possible match
verbose: bool, default: False: if True, output is verbose

Returns

multi_template_comparison: MultiTemplateComparison: MultiTemplateComparison object with the multiple template comparisons

spikeinterface.comparison.create_hybrid_units_recording(parent_recording: BaseRecording, templates: np.ndarray, injected_sorting: Union[BaseSorting, None] = None, nbefore: Union[List[int], int, None] = None, firing_rate: float = 10, amplitude_factor: Union[np.ndarray, None] = None, amplitude_std: float = 0.0, refractory_period_ms: float = 2.0, injected_sorting_folder: Union[str, Path, None] = None, seed=None)¶

Class for creating a hybrid recording where additional units are added to an existing recording.

Parameters

parent_recording: BaseRecording: Existing recording to add on top of.
templates: np.ndarray[n_units, n_samples, n_channels]: Array containing the templates to inject for all the units.
injected_sorting: BaseSorting | None:: The sorting for the injected units. If None, will be generated using the following parameters.
nbefore: list[int] | int | None: Where is the center of the template for each unit? If None, will default to the highest peak.
firing_rate: float: The firing rate of the injected units (in Hz).
amplitude_factor: np.ndarray | None:: The amplitude factor for each spike. If None, will be generated as a gaussian centered at 1.0 and with an std of amplitude_std.
amplitude_std: float: The standard deviation of the amplitude (centered at 1.0).
refractory_period_ms: float: The refractory period of the injected spike train (in ms).
injected_sorting_folder: str | Path | None: If given, the injected sorting is saved to this folder. It must be specified if injected_sorting is None or not serialisable to file.

Returns

hybrid_units_recording: HybridUnitsRecording: The recording containing real and hybrid units.

spikeinterface.comparison.create_hybrid_spikes_recording(wvf_extractor: Union[WaveformExtractor, Path], injected_sorting: Union[BaseSorting, None] = None, unit_ids: Union[List[int], None] = None, max_injected_per_unit: int = 1000, injected_rate: float = 0.05, refractory_period_ms: float = 1.5, injected_sorting_folder: Union[str, Path, None] = None) → None¶

Class for creating a hybrid recording where additional spikes are added to already existing units.

Parameters

wvf_extractor: WaveformExtractor: The waveform extractor object of the existing recording.
injected_sorting: BaseSorting | None: Additional spikes to inject. If None, will generate it.
max_injected_per_unit: int: If injected_sorting=None, the max number of spikes per unit that is allowed to be injected.
unit_ids: list[int] | None: unit_ids to take in the wvf_extractor for spikes injection.
injected_rate: float: If injected_sorting=None, the max fraction of spikes per unit that is allowed to be injected.
refractory_period_ms: float: If injected_sorting=None, the injected spikes need to respect this refractory period.
injected_sorting_folder: str | Path | None: If given, the injected sorting is saved to this folder. It must be specified if injected_sorting is None or not serializable to file.

Returns

hybrid_spikes_recording: HybridSpikesRecording:: The recording containing units with real and hybrid spikes.

class spikeinterface.comparison.GroundTruthComparison(gt_sorting, tested_sorting, gt_name=None, tested_name=None, delta_time=0.4, sampling_frequency=None, match_score=0.5, well_detected_score=0.8, redundant_score=0.2, overmerged_score=0.2, chance_score=0.1, exhaustive_gt=False, n_jobs=-1, match_mode='hungarian', compute_labels=False, compute_misclassifications=False, verbose=False)¶

Compares a sorter to a ground truth.

This class can:

compute a “match between gt_sorting and tested_sorting
compute optionally the score label (TP, FN, CL, FP) for each spike
count by unit of GT the total of each (TP, FN, CL, FP) into a Dataframe GroundTruthComparison.count
compute the confusion matrix .get_confusion_matrix()
compute some performance metric with several strategy based on the count score by unit
count well detected units
count false positive detected units
count redundant units
count overmerged units
summary all this

Parameters

gt_sorting: SortingExtractor: The first sorting for the comparison
tested_sorting: SortingExtractor: The second sorting for the comparison
gt_name: str, default: None: The name of sorter 1
tested_name:str, default: None: The name of sorter 2
delta_time: float, default: 0.4: Number of ms to consider coincident spikes
match_score: float, default: 0.5: Minimum agreement score to match units
chance_score: float, default: 0.1: Minimum agreement score to for a possible match
redundant_score: float, default: 0.2: Agreement score above which units are redundant
overmerged_score: float, default: 0.2: Agreement score above which units can be overmerged
well_detected_score: float, default: 0.8: Agreement score above which units are well detected
exhaustive_gt: bool, default: False: Tell if the ground true is “exhaustive” or not. In other world if the GT have all possible units. It allows more performance measurement. For instance, MEArec simulated dataset have exhaustive_gt=True
match_mode: “hungarian” | “best”, default: “hungarian”: The method to match units
n_jobs: int, default: -1: Number of cores to use in parallel. Uses all available if -1
compute_labels: bool, default: False: If True, labels are computed at instantiation
compute_misclassifications: bool, default: False: If True, misclassifications are computed at instantiation
verbose: bool, default: False: If True, output is verbose

Returns

sorting_comparison: SortingComparison: The SortingComparison object

count_bad_units()¶: See get_bad_units

count_false_positive_units(redundant_score=None)¶: See get_false_positive_units().

count_overmerged_units(overmerged_score=None)¶: See get_overmerged_units().

count_redundant_units(redundant_score=None)¶: See get_redundant_units().

count_well_detected_units(well_detected_score)¶: Count how many well detected units. kwargs are the same as get_well_detected_units.

get_bad_units()¶

Return units list of “bad units”.

“bad units” are defined as units in tested that are not in the best match list of GT units.

So it is the union of “false positive units” + “redundant units”.

Need exhaustive_gt=True

get_confusion_matrix()¶

Computes the confusion matrix.

Returns

confusion_matrix: pandas.DataFrame: The confusion matrix

get_false_positive_units(redundant_score=None)¶

Return units list of “false positive units” from tested_sorting.

“false positive units” are defined as units in tested that are not matched at all in GT units.

Need exhaustive_gt=True

Parameters

redundant_score: float, default: None: The agreement score below which tested units are counted as “false positive”” (and not “redundant”).

get_overmerged_units(overmerged_score=None)¶

Return “overmerged units”

“overmerged units” are defined as units in tested that match more than one GT unit with an agreement score larger than overmerged_score.

Parameters

overmerged_score: float, default: None: Tested units with 2 or more agreement scores above “overmerged_score” are counted as “overmerged”.

get_performance(method='by_unit', output='pandas')¶

Get performance rate with several method:

“raw_count” : just render the raw count table
“by_unit” : render perf as rate unit by unit of the GT
“pooled_with_average” : compute rate unit by unit and average

Parameters

method: “by_unit” | “pooled_with_average”, default: “by_unit”: The method to compute performance
output: “pandas” | “dict”, default: “pandas”: The output format

Returns

perf: pandas dataframe/series (or dict): dataframe/series (based on “output”) with performance entries

get_redundant_units(redundant_score=None)¶

Return “redundant units”

“redundant units” are defined as units in tested that match a GT units with a big agreement score but it is not the best match. In other world units in GT that detected twice or more.

Parameters

redundant_score=None: float, default: None: The agreement score above which tested units are counted as “redundant” (and not “false positive” ).

get_well_detected_units(well_detected_score=None)¶

Return units list of “well detected units” from tested_sorting.

“well detected units” are defined as units in tested that are well matched to GT units.

Parameters

well_detected_score: float, default: None: The agreement score above which tested units are counted as “well detected”.

print_performance(method='pooled_with_average')¶: Print performance with the selected method

print_summary(well_detected_score=None, redundant_score=None, overmerged_score=None)¶

Print a global performance summary that depend on the context:

exhaustive= True/False
how many gt units (one or several)

This summary mix several performance metrics.

class spikeinterface.comparison.SymmetricSortingComparison(sorting1, sorting2, sorting1_name=None, sorting2_name=None, delta_time=0.4, match_score=0.5, chance_score=0.1, n_jobs=-1, verbose=False)¶

Compares two spike sorter outputs.

Spike trains are matched based on their agreement scores
Individual spikes are labelled as true positives (TP), false negatives (FN), false positives 1 (FP from spike train 1), false positives 2 (FP from spike train 2), misclassifications (CL)

It also allows to get confusion matrix and agreement fraction, false positive fraction and false negative fraction.

Parameters

sorting1: SortingExtractor: The first sorting for the comparison
sorting2: SortingExtractor: The second sorting for the comparison
sorting1_name: str, default: None: The name of sorter 1
sorting2_name:str, default: None: The name of sorter 2
delta_time: float, default: 0.4: Number of ms to consider coincident spikes
match_score: float, default: 0.5: Minimum agreement score to match units
chance_score: float, default: 0.1: Minimum agreement score to for a possible match
n_jobs: int, default: -1: Number of cores to use in parallel. Uses all available if -1
verbose: bool, default: False: If True, output is verbose

Returns

sorting_comparison: SortingComparison: The SortingComparison object

get_agreement_fraction(unit1=None, unit2=None)¶

get_best_unit_match1(unit1)¶

get_best_unit_match2(unit2)¶

get_matching()¶

get_matching_event_count(unit1, unit2)¶

get_matching_unit_list1(unit1)¶

get_matching_unit_list2(unit2)¶

class spikeinterface.comparison.GroundTruthStudy(study_folder)¶

This class is an helper function to run any comparison on several “cases” for many ground-truth dataset.

“cases” refer to:

several sorters for comparisons
same sorter with differents parameters
any combination of these (and more)

For increased flexibility, cases keys can be a tuple so that we can vary complexity along several “levels” or “axis” (paremeters or sorters). In this case, the result dataframes will have MultiIndex to handle the different levels.

A ground-truth dataset is made of a Recording and a Sorting object. For example, it can be a simulated dataset with MEArec or internally generated (see generate_ground_truth_recording()).

This GroundTruthStudy have been refactor in version 0.100 to be more flexible than previous versions. Note that the underlying folder structure is not backward compatible!

compute_metrics(case_keys=None, metric_names=['snr', 'firing_rate'], force=False)¶

copy_sortings(case_keys=None, force=True)¶

classmethod create(study_folder, datasets={}, cases={}, levels=None)¶

extract_waveforms_gt(case_keys=None, **extract_kwargs)¶

get_count_units(case_keys=None, well_detected_score=None, redundant_score=None, overmerged_score=None)¶

get_metrics(key)¶

get_performance_by_unit(case_keys=None)¶

get_run_times(case_keys=None)¶

get_templates(key, mode='average')¶

get_units_snr(key)¶

get_waveform_extractor(case_key=None, dataset_key=None)¶

key_to_str(key)¶

remove_sorting(key)¶

run_comparisons(case_keys=None, comparison_class=<class 'spikeinterface.comparison.paircomparisons.GroundTruthComparison'>, **kwargs)¶

run_sorters(case_keys=None, engine='loop', engine_kwargs={}, keep=True, verbose=False)¶

scan_folder()¶

class spikeinterface.comparison.MultiSortingComparison(sorting_list, name_list=None, delta_time=0.4, match_score=0.5, chance_score=0.1, n_jobs=-1, spiketrain_mode='union', verbose=False, do_matching=True)¶

Compares multiple spike sorting outputs based on spike trains.

Pair-wise comparisons are made
An agreement graph is built based on the agreement score

It allows to return a consensus-based sorting extractor with the get_agreement_sorting() method.

Parameters

sorting_list: list

List of sorting extractor objects to be compared

name_list: list, default: None

List of spike sorter names. If not given, sorters are named as “sorter0”, “sorter1”, “sorter2”, etc.

delta_time: float, default: 0.4

Number of ms to consider coincident spikes

match_score: float, default: 0.5

Minimum agreement score to match units

chance_score: float, default: 0.1

Minimum agreement score to for a possible match

n_jobs: int, default: -1

Number of cores to use in parallel. Uses all available if -1

spiketrain_mode: “union” | “intersection”, default: “union”

Mode to extract agreement spike trains:

“union”: spike trains are the union between the spike trains of the best matching two sorters
“intersection”: spike trains are the intersection between the spike trains of the
best matching two sorters

verbose: bool, default: False

if True, output is verbose

Returns

multi_sorting_comparison: MultiSortingComparison: MultiSortingComparison object with the multiple sorter comparison

get_agreement_sorting(minimum_agreement_count=1, minimum_agreement_count_only=False)¶

Returns AgreementSortingExtractor with units with a “minimum_matching” agreement.

Parameters

minimum_agreement_count: int: Minimum number of matches among sorters to include a unit.
minimum_agreement_count_only: bool: If True, only units with agreement == “minimum_matching” are included. If False, units with an agreement >= “minimum_matching” are included

Returns

agreement_sorting: AgreementSortingExtractor: The output AgreementSortingExtractor

class spikeinterface.comparison.CollisionGTComparison(gt_sorting, tested_sorting, collision_lag=2.0, nbins=11, **kwargs)¶

This class is an extension of GroundTruthComparison by focusing to benchmark spike in collision.

This class needs maintenance and need a bit of refactoring.

collision_lag: float: Collision lag in ms.

class spikeinterface.comparison.CorrelogramGTComparison(gt_sorting, tested_sorting, window_ms=100.0, bin_ms=1.0, well_detected_score=0.8, **kwargs)¶

This class is an extension of GroundTruthComparison by focusing to benchmark correlation reconstruction.

This class needs maintenance and need a bit of refactoring.

class spikeinterface.comparison.CollisionGTStudy(study_folder)¶

class spikeinterface.comparison.CorrelogramGTStudy(study_folder)¶

spikeinterface.widgets¶

spikeinterface.widgets.set_default_plotter_backend(backend)¶

spikeinterface.widgets.get_default_plotter_backend()¶: Return the default backend for spikeinterface widgets. The default backend is “matplotlib” at init. It can be be globally set with set_default_plotter_backend(backend)

spikeinterface.widgets.plot_agreement_matrix(sorting_comparison, ordered=True, count_text=True, unit_ticks=True, backend=None, **backend_kwargs)¶

Plots sorting comparison agreement matrix.

Parameters

sorting_comparison: GroundTruthComparison or SymmetricSortingComparison

The sorting comparison object. Can optionally be symmetric if given a SymmetricSortingComparison

ordered: bool, default: True

Order units with best agreement scores. If True, agreement scores can be seen along a diagonal

count_text: bool, default: True

If True counts are displayed as text

unit_ticks: bool, default: True

If True unit tick labels are displayed

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_all_amplitudes_distributions(waveform_extractor: WaveformExtractor, unit_ids=None, unit_colors=None, backend=None, **backend_kwargs)¶

Plots distributions of amplitudes as violin plot for all or some units.

Parameters

waveform_extractor: WaveformExtractor

The input waveform extractor

unit_ids: list

List of unit ids, default None

unit_colors: None or dict

Dict of colors with key: unit, value: color, default None

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_amplitudes(waveform_extractor: WaveformExtractor, unit_ids=None, unit_colors=None, segment_index=None, max_spikes_per_unit=None, hide_unit_selector=False, plot_histograms=False, bins=None, plot_legend=True, backend=None, **backend_kwargs)¶

Plots spike amplitudes

Parameters

waveform_extractorWaveformExtractor

The input waveform extractor

unit_idslist or None, default: None

List of unit ids

segment_indexint or None, default: None

The segment index (or None if mono-segment)

max_spikes_per_unitint or None, default: None

Number of max spikes per unit to display. Use None for all spikes

hide_unit_selectorbool, default: False

If True the unit selector is not displayed (sortingview backend)

plot_histogrambool, default: False

If True, an histogram of the amplitudes is plotted on the right axis (matplotlib backend)

binsint or None, default: None

If plot_histogram is True, the number of bins for the amplitude histogram. If None this is automatically adjusted

plot_legendbool, default: True

True includes legend in plot

backend: str

[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

ipywidgets:

width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_autocorrelograms(*args, **kargs)¶

Plots unit cross correlograms.

Parameters

waveform_or_sorting_extractorWaveformExtractor or BaseSorting

The object to compute/get crosscorrelograms from

unit_ids list or None, default: None

List of unit ids

min_similarity_for_correlogramsfloat, default: 0.2

For sortingview backend. Threshold for computing pair-wise cross-correlograms. If template similarity between two units is below this threshold, the cross-correlogram is not displayed

window_msfloat, default: 100.0

Window for CCGs in ms. If correlograms are already computed (e.g. with WaveformExtractor), this argument is ignored

bin_msfloat, default: 1.0

Bin size in ms. If correlograms are already computed (e.g. with WaveformExtractor), this argument is ignored

hide_unit_selectorbool, default: False

For sortingview backend, if True the unit selector is not displayed

unit_colors: dict or None, default: None

If given, a dictionary with unit ids as keys and colors as values

backend: str

[‘matplotlib’, ‘sortingview’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_confusion_matrix(gt_comparison, count_text=True, unit_ticks=True, backend=None, **backend_kwargs)¶

Plots sorting comparison confusion matrix.

Parameters

gt_comparison: GroundTruthComparison

The ground truth sorting comparison object

count_text: bool

If True counts are displayed as text

unit_ticks: bool

If True unit tick labels are displayed

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_comparison_collision_by_similarity(comp, templates, unit_ids=None, metric='cosine_similarity', figure=None, ax=None, mode='heatmap', similarity_bins=array([-4.00000000e-01, -2.00000000e-01, -5.55111512e-17, 2.00000000e-01, 4.00000000e-01, 6.00000000e-01, 8.00000000e-01, 1.00000000e+00]), cmap='winter', good_only=False, min_accuracy=0.9, show_legend=False, ylim=(0, 1), backend=None, **backend_kwargs)¶

Plots CollisionGTComparison pair by pair orderer by cosine_similarity

Parameters

comp: CollisionGTComparison

The collision ground truth comparison object

templates: array

template of units

mode: “heatmap” or “lines”

to see collision curves for every pairs (“heatmap”) or as lines averaged over pairs.

similarity_bins: array

if mode is “lines”, the bins used to average the pairs

cmap: string

colormap used to show averages if mode is “lines”

metric: “cosine_similarity”

metric for ordering

good_only: True

keep only the pairs with a non zero accuracy (found templates)

min_accuracy: float

If good only, the minimum accuracy every cell should have, individually, to be considered in a putative pair

unit_ids: list

List of considered units

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_crosscorrelograms(waveform_or_sorting_extractor: Union[WaveformExtractor, BaseSorting], unit_ids=None, min_similarity_for_correlograms=0.2, window_ms=100.0, bin_ms=1.0, hide_unit_selector=False, unit_colors=None, backend=None, **backend_kwargs)¶

Plots unit cross correlograms.

Parameters

waveform_or_sorting_extractorWaveformExtractor or BaseSorting

The object to compute/get crosscorrelograms from

unit_ids list or None, default: None

List of unit ids

min_similarity_for_correlogramsfloat, default: 0.2

For sortingview backend. Threshold for computing pair-wise cross-correlograms. If template similarity between two units is below this threshold, the cross-correlogram is not displayed

window_msfloat, default: 100.0

Window for CCGs in ms. If correlograms are already computed (e.g. with WaveformExtractor), this argument is ignored

bin_msfloat, default: 1.0

Bin size in ms. If correlograms are already computed (e.g. with WaveformExtractor), this argument is ignored

hide_unit_selectorbool, default: False

For sortingview backend, if True the unit selector is not displayed

unit_colors: dict or None, default: None

If given, a dictionary with unit ids as keys and colors as values

backend: str

[‘matplotlib’, ‘sortingview’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_isi_distribution(sorting, unit_ids=None, window_ms=100.0, bin_ms=1.0, backend=None, **backend_kwargs)¶

Plots spike train ISI distribution.

Parameters

sorting: SortingExtractor

The sorting extractor object

unit_ids: list

List of unit ids

bins_ms: int

Bin size in ms

window_ms: float

Window size in ms

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_motion(motion_info, recording=None, depth_lim=None, motion_lim=None, color_amplitude=False, scatter_decimate=None, amplitude_cmap='inferno', amplitude_clim=None, amplitude_alpha=1, backend=None, **backend_kwargs)¶

Plot unit depths

Parameters

motion_info: dict

The motion info return by correct_motion() or load back with load_motion_info()

recordingRecordingExtractor, default: None

The recording extractor object (only used to get “real” times)

sampling_frequencyfloat, default: None

The sampling frequency (needed if recording is None)

depth_limtuple or None, default: None

The min and max depth to display, if None (min and max of the recording)

motion_limtuple or None, default: None

The min and max motion to display, if None (min and max of the motion)

color_amplitudebool, default: False

If True, the color of the scatter points is the amplitude of the peaks

scatter_decimateint, default: None

If > 1, the scatter points are decimated

amplitude_cmapstr, default: “inferno”

The colormap to use for the amplitude

amplitude_climtuple or None, default: None

The min and max amplitude to display, if None (min and max of the amplitudes)

amplitude_alphafloat, default: 1

The alpha of the scatter points

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_multicomparison_agreement(multi_comparison, plot_type='pie', cmap='YlOrRd', fontsize=9, show_legend=True, backend=None, **backend_kwargs)¶

Plots multi comparison agreement as pie or bar plot.

Parameters

multi_comparison: BaseMultiComparison

The multi comparison object

plot_type: “pie” | “bar”, default: “pie”

The plot type

cmap: matplotlib colormap, default: “YlOrRd”

The colormap to be used for the nodes

fontsize: int, default: 9

The text fontsize

show_legend: bool, default: True

If True a legend is shown

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_multicomparison_agreement_by_sorter(multi_comparison, plot_type='pie', cmap='YlOrRd', fontsize=9, show_legend=True, backend=None, **backend_kwargs)¶

Plots multi comparison agreement as pie or bar plot.

Parameters

multi_comparison: BaseMultiComparison

The multi comparison object

plot_type: “pie” | “bar”, default: “pie

The plot type

cmap: matplotlib colormap, default: “Reds”

The colormap to be used for the nodes

fontsize: int, default: 9

The text fontsize

show_legend: bool

Show the legend in the last axes

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_multicomparison_graph(multi_comparison, draw_labels=False, node_cmap='viridis', edge_cmap='hot', alpha_edges=0.5, colorbar=False, backend=None, **backend_kwargs)¶

Plots multi comparison graph.

Parameters

multi_comparison: BaseMultiComparison

The multi comparison object

draw_labels: bool, default: False

If True unit labels are shown

node_cmap: matplotlib colormap, default: “viridis”

The colormap to be used for the nodes

edge_cmap: matplotlib colormap, default: “hot”

The colormap to be used for the edges

alpha_edges: float, default: 0.5

Alpha value for edges

colorbar: bool, default: False

If True a colorbar for the edges is plotted

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_peak_activity(recording, peaks, bin_duration_s=None, with_contact_color=True, with_interpolated_map=True, with_channel_ids=False, with_color_bar=True, backend=None, **backend_kwargs)¶

Plots spike rate (estimated with detect_peaks()) as 2D activity map.

Can be static (bin_duration_s=None) or animated (bin_duration_s=60.)

Parameters

recording: RecordingExtractor

The recording extractor object.

peaks: None or numpy array

Optionally can give already detected peaks to avoid multiple computation.

detect_peaks_kwargs: None or dict, default: None

If peaks is None here the kwargs for detect_peak function.

bin_duration_s: None or float, default: None

If None then static image If not None then it is an animation per bin.

with_contact_color: bool, default: True

Plot rates with contact colors

with_interpolated_map: bool, default: True

Plot rates with interpolated map

with_channel_ids: bool, default: False

Add channel ids text on the probe

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_probe_map(recording, channel_ids=None, with_channel_ids=False, backend=None, **backend_or_plot_probe_kwargs)¶

Plot the probe of a recording.

Parameters

recording: RecordingExtractor

The recording extractor object

channel_ids: list

The channel ids to display

with_channel_ids: bool False default

Add channel ids text on the probe

**plot_probe_kwargs: keyword arguments for probeinterface.plotting.plot_probe_group() function

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_quality_metrics(waveform_extractor: WaveformExtractor, unit_ids=None, include_metrics=None, skip_metrics=None, unit_colors=None, hide_unit_selector=False, backend=None, **backend_kwargs)¶

Plots quality metrics distributions.

Parameters

waveform_extractorWaveformExtractor

The object to compute/get quality metrics from

unit_ids: list or None, default: None

List of unit ids

include_metrics: list or None, default: None

If given, a list of quality metrics to include

skip_metrics: list or None, default: None

If given, a list of quality metrics to skip

unit_colorsdict or None, default: None

If given, a dictionary with unit ids as keys and colors as values

hide_unit_selectorbool, default: False

For sortingview backend, if True the unit selector is not displayed

backend: str

[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

ipywidgets:

width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_rasters(sorting, segment_index=None, unit_ids=None, time_range=None, color='k', backend=None, **backend_kwargs)¶

Plots spike train rasters.

Parameters

sorting: SortingExtractor

The sorting extractor object

segment_index: None or int

The segment index.

unit_ids: list

List of unit ids

time_range: list

List with start time and end time

color: matplotlib color

The color to be used

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_sorting_summary(waveform_extractor: WaveformExtractor, unit_ids=None, sparsity=None, max_amplitudes_per_unit=None, min_similarity_for_correlograms=0.2, curation=False, unit_table_properties=None, label_choices=None, backend=None, **backend_kwargs)¶

Plots spike sorting summary

Parameters

waveform_extractorWaveformExtractor

The waveform extractor object

unit_idslist or None, default: None

List of unit ids

sparsityChannelSparsity or None, default: None

Optional ChannelSparsity to apply If WaveformExtractor is already sparse, the argument is ignored

max_amplitudes_per_unitint or None, default: None

Maximum number of spikes per unit for plotting amplitudes. If None, all spikes are plotted

min_similarity_for_correlogramsfloat, default: 0.2

Threshold for computing pair-wise cross-correlograms. If template similarity between two units is below this threshold, the cross-correlogram is not computed (sortingview backend)

curationbool, default: False

If True, manual curation is enabled (sortingview backend)

label_choiceslist or None, default: None

List of labels to be added to the curation table (sortingview backend)

unit_table_propertieslist or None, default: None

List of properties to be added to the unit table (sortingview backend)

backend: str

[‘sortingview’]

**backend_kwargs: kwargs

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_spike_locations(waveform_extractor: WaveformExtractor, unit_ids=None, segment_index=None, max_spikes_per_unit=500, with_channel_ids=False, unit_colors=None, hide_unit_selector=False, plot_all_units=True, plot_legend=False, hide_axis=False, backend=None, **backend_kwargs)¶

Plots spike locations.

Parameters

waveform_extractorWaveformExtractor

The object to compute/get spike locations from

unit_idslist or None, default: None

List of unit ids

segment_indexint or None, default: None

The segment index (or None if mono-segment)

max_spikes_per_unitint or None, default: 500

Number of max spikes per unit to display. Use None for all spikes.

with_channel_idsbool, default: False

Add channel ids text on the probe

unit_colorsdict or None, default: None

If given, a dictionary with unit ids as keys and colors as values

hide_unit_selectorbool, default: False

For sortingview backend, if True the unit selector is not displayed

plot_all_unitsbool, default: True

If True, all units are plotted. The unselected ones (not in unit_ids), are plotted in grey (matplotlib backend)

plot_legendbool, default: False

If True, the legend is plotted (matplotlib backend)

hide_axisbool, default: False

If True, the axis is set to off (matplotlib backend)

backend: str

[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

ipywidgets:

width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_spikes_on_traces(waveform_extractor: WaveformExtractor, segment_index=None, channel_ids=None, unit_ids=None, order_channel_by_depth=False, time_range=None, unit_colors=None, sparsity=None, mode='auto', return_scaled=False, cmap='RdBu', show_channel_ids=False, color_groups=False, color=None, clim=None, tile_size=512, seconds_per_row=0.2, with_colorbar=True, backend=None, **backend_kwargs)¶

Plots unit spikes/waveforms over traces.

Parameters

waveform_extractorWaveformExtractor

The waveform extractor

channel_idslist or None, default: None

The channel ids to display

unit_idslist or None, default: None

List of unit ids

order_channel_by_depthbool, default: False

If true orders channel by depth

time_range: list or None, default: None

List with start time and end time in seconds

sparsityChannelSparsity or None, default: None

Optional ChannelSparsity to apply If WaveformExtractor is already sparse, the argument is ignored

unit_colorsdict or None, default: None

If given, a dictionary with unit ids as keys and colors as values If None, then the get_unit_colors() is internally used. (matplotlib backend)

mode“line” | “map” | “auto”, default: “auto”

“line”: classical for low channel count
“map”: for high channel count use color heat map
“auto”: auto switch depending on the channel count (“line” if less than 64 channels, “map” otherwise)

return_scaledbool, default: False

If True and the recording has scaled traces, it plots the scaled traces

cmapstr, default: “RdBu”

matplotlib colormap used in mode “map”

show_channel_idsbool, default: False

Set yticks with channel ids

color_groupsbool, default: False

If True groups are plotted with different colors

colorstr or None, default: None

The color used to draw the traces

climNone, tuple or dict, default: None

When mode is “map”, this argument controls color limits. If dict, keys should be the same as recording keys

with_colorbarbool, default: True

When mode is “map”, a colorbar is added

tile_sizeint, default: 512

For sortingview backend, the size of each tile in the rendered image

seconds_per_rowfloat, default: 0.2

For “map” mode and sortingview backend, seconds to render in each row

backend: str

[‘matplotlib’, ‘ipywidgets’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

ipywidgets:

width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_template_metrics(waveform_extractor: WaveformExtractor, unit_ids=None, include_metrics=None, skip_metrics=None, unit_colors=None, hide_unit_selector=False, backend=None, **backend_kwargs)¶

Plots template metrics distributions.

Parameters

waveform_extractorWaveformExtractor

The object to compute/get template metrics from

unit_idslist or None, default: None

List of unit ids

include_metricslist or None, default: None

If given list of quality metrics to include

skip_metricslist or None or None, default: None

If given, a list of quality metrics to skip

unit_colorsdict or None, default: None

If given, a dictionary with unit ids as keys and colors as values

hide_unit_selectorbool, default: False

For sortingview backend, if True the unit selector is not displayed

backend: str

[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

ipywidgets:

width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_template_similarity(waveform_extractor: WaveformExtractor, unit_ids=None, cmap='viridis', display_diagonal_values=False, show_unit_ticks=False, show_colorbar=True, backend=None, **backend_kwargs)¶

Plots unit template similarity.

Parameters

waveform_extractorWaveformExtractor

The object to compute/get template similarity from

unit_idslist or None, default: None

List of unit ids default: None

display_diagonal_valuesbool, default: False

If False, the diagonal is displayed as zeros. If True, the similarity values (all 1s) are displayed

cmapmatplotlib colormap, default: “viridis”

The matplotlib colormap

show_unit_ticksbool, default: False

If True, ticks display unit ids

show_colorbarbool, default: True

If True, color bar is displayed

backend: str

[‘matplotlib’, ‘sortingview’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_traces(recording, segment_index=None, channel_ids=None, order_channel_by_depth=False, time_range=None, mode='auto', return_scaled=False, cmap='RdBu_r', show_channel_ids=False, color_groups=False, color=None, clim=None, tile_size=1500, seconds_per_row=0.2, with_colorbar=True, add_legend=True, backend=None, **backend_kwargs)¶

Plots recording timeseries.

Parameters

recording: RecordingExtractor, dict, or list

The recording extractor object. If dict (or list) then it is a multi-layer display to compare, for example, different processing steps

segment_index: None or int, default: None

The segment index (required for multi-segment recordings)

channel_ids: list or None, default: None

The channel ids to display

order_channel_by_depth: bool, default: False

Reorder channel by depth

time_range: list, tuple or None, default: None

List with start time and end time

mode: “line” | “map” | “auto”, default: “auto”

Three possible modes * “line”: classical for low channel count * “map”: for high channel count use color heat map * “auto”: auto switch depending on the channel count (“line” if less than 64 channels, “map” otherwise)

return_scaled: bool, default: False

If True and the recording has scaled traces, it plots the scaled traces

cmap: matplotlib colormap, default: “RdBu_r”

matplotlib colormap used in mode “map”

show_channel_ids: bool, default: False

Set yticks with channel ids

color_groups: bool, default: False

If True groups are plotted with different colors

color: str or None, default: None

The color used to draw the traces

clim: None, tuple or dict, default: None

When mode is “map”, this argument controls color limits. If dict, keys should be the same as recording keys

with_colorbar: bool, default: True

When mode is “map”, a colorbar is added

tile_size: int, default: 1500

For sortingview backend, the size of each tile in the rendered image

seconds_per_row: float, default: 0.2

For “map” mode and sortingview backend, seconds to render in each row

add_legendbool, default: True

If True adds legend to figures

backend: str

[‘matplotlib’, ‘sortingview’, ‘ipywidgets’, ‘ephyviewer’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

ipywidgets:

width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_unit_depths(waveform_extractor, unit_colors=None, depth_axis=1, peak_sign='neg', backend=None, **backend_kwargs)¶

Plot unit depths

Parameters

waveform_extractorWaveformExtractor

The input waveform extractor

unit_colorsdict or None, default: None

If given, a dictionary with unit ids as keys and colors as values

depth_axisint, default: 1

The dimension of unit_locations that is depth

peak_sign: “neg” | “pos” | “both”, default: “neg”

Sign of peak for amplitudes

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_unit_locations(waveform_extractor: WaveformExtractor, unit_ids=None, with_channel_ids=False, unit_colors=None, hide_unit_selector=False, plot_all_units=True, plot_legend=False, hide_axis=False, backend=None, **backend_kwargs)¶

Plots each unit’s location.

Parameters

waveform_extractorWaveformExtractor

The object to compute/get unit locations from

unit_idslist or None, default: None

List of unit ids

with_channel_idsbool, default: False

Add channel ids text on the probe

unit_colorsdict or None, default: None

If given, a dictionary with unit ids as keys and colors as values

hide_unit_selectorbool, default: False

If True, the unit selector is not displayed (sortingview backend)

plot_all_unitsbool, default: True

If True, all units are plotted. The unselected ones (not in unit_ids), are plotted in grey (matplotlib backend)

plot_legendbool, default: False

If True, the legend is plotted (matplotlib backend)

hide_axisbool, default: False

If True, the axis is set to off (matplotlib backend)

backend: str

[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

ipywidgets:

width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_unit_presence(sorting, segment_index=None, time_range=None, bin_duration_s=0.05, smooth_sigma=4.5, backend=None, **backend_kwargs)¶

Estimates of the probability density function for each unit using Gaussian kernels,

Parameters

sorting: SortingExtractor

The sorting extractor object

segment_index: None or int

The segment index.

time_range: list or None, default: None

List with start time and end time

bin_duration_s: float, default: 0.5

Bin size (in seconds) for the heat map time axis

smooth_sigma: float, default: 4.5

Sigma for the Gaussian kernel (in number of bins)

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_unit_probe_map(waveform_extractor, unit_ids=None, channel_ids=None, animated=None, with_channel_ids=False, colorbar=True, backend=None, **backend_kwargs)¶

Plots unit map. Amplitude is color coded on probe contact.

Can be static (animated=False) or animated (animated=True)

Parameters

waveform_extractor: WaveformExtractor

unit_ids: list

List of unit ids.

channel_ids: list

The channel ids to display

animated: bool, default: False

Animation for amplitude on time

with_channel_ids: bool, default: False

add channel ids text on the probe

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_unit_summary(waveform_extractor, unit_id, unit_colors=None, sparsity=None, radius_um=100, backend=None, **backend_kwargs)¶

Plot a unit summary.

If amplitudes are alreday computed they are displayed.

Parameters

waveform_extractorWaveformExtractor

The waveform extractor object

unit_idint or str

The unit id to plot the summary of

unit_colorsdict or None, default: None

If given, a dictionary with unit ids as keys and colors as values,

sparsityChannelSparsity or None, default: None

Optional ChannelSparsity to apply. If WaveformExtractor is already sparse, the argument is ignored

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_unit_templates(*args, **kargs)¶

Plots unit waveforms.

Parameters

waveform_extractorWaveformExtractor

The input waveform extractor

channel_ids: list or None, default: None

The channel ids to display

unit_idslist or None, default: None

List of unit ids

plot_templatesbool, default: True

If True, templates are plotted over the waveforms

sparsityChannelSparsity or None, default: None

Optional ChannelSparsity to apply If WaveformExtractor is already sparse, the argument is ignored

set_titlebool, default: True

Create a plot title with the unit number if True

plot_channelsbool, default: False

Plot channel locations below traces

unit_selected_waveformsNone or dict, default: None

A dict key is unit_id and value is the subset of waveforms indices that should be be displayed (matplotlib backend)

max_spikes_per_unitint or None, default: 50

If given and unit_selected_waveforms is None, only max_spikes_per_unit random units are displayed per waveform, (matplotlib backend)

scalefloat, default: 1

Scale factor for the waveforms/templates (matplotlib backend)

axis_equalbool, default: False

Equal aspect ratio for x and y axis, to visualize the array geometry to scale

lw_waveformsfloat, default: 1

Line width for the waveforms, (matplotlib backend)

lw_templatesfloat, default: 2

Line width for the templates, (matplotlib backend)

unit_colorsNone or dict, default: None

A dict key is unit_id and value is any color format handled by matplotlib. If None, then the get_unit_colors() is internally used. (matplotlib / ipywidgets backend)

alpha_waveformsfloat, default: 0.5

Alpha value for waveforms (matplotlib backend)

alpha_templatesfloat, default: 1

Alpha value for templates, (matplotlib backend)

shade_templatesbool, default: True

If True, templates are shaded, see templates_percentile_shading argument

templates_percentile_shadingfloat, list of floats, or None, default: [1, 25, 75, 98]

It controls the shading of the templates. If None, the shading is +/- the standard deviation of the templates. If float, it controls the percentile of the template values used to shade the templates. Note that it is one-sided: if 5 is given, the 5th and 95th percentiles are used to shade the templates. If list of floats, it needs to be have an even number of elements which control the lower and upper percentile used to shade the templates. The first half of the elements are used for the lower bounds, and the second half for the upper bounds. Inner elements produce darker shadings. For sortingview backend only 2 or 4 elements are supported.

hide_unit_selectorbool, default: False

For sortingview backend, if True the unit selector is not displayed

same_axisbool, default: False

If True, waveforms and templates are displayed on the same axis (matplotlib backend)

x_offset_unitsbool, default: False

In case same_axis is True, this parameter allow to x-offset the waveforms for different units (recommended for a few units) (matlotlib backend)

plot_legendbool, default: True

Display legend (matplotlib backend)

backend: str

[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

sortingview:

generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None

ipywidgets:

width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_unit_waveforms_density_map(waveform_extractor, channel_ids=None, unit_ids=None, sparsity=None, same_axis=False, use_max_channel=False, peak_sign='neg', unit_colors=None, backend=None, **backend_kwargs)¶

Plots unit waveforms using heat map density.

Parameters

waveform_extractorWaveformExtractor

The waveformextractor for calculating waveforms

channel_idslist or None, default: None

The channel ids to display

unit_idslist or None, default: None

List of unit ids

sparsityChannelSparsity or None, default: None

Optional ChannelSparsity to apply If WaveformExtractor is already sparse, the argument is ignored

use_max_channelbool, default: False

Use only the max channel

peak_sign“neg” | “pos” | “both”, default: “neg”

Used to detect max channel only when use_max_channel=True

unit_colorsNone or dict, default: None

A dict key is unit_id and value is any color format handled by matplotlib. If None, then the get_unit_colors() is internally used

same_axisbool, default: False

If True then all density are plot on the same axis and then channels is the union all channel per units

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_unit_waveforms(waveform_extractor: WaveformExtractor, channel_ids=None, unit_ids=None, plot_waveforms=True, plot_templates=True, plot_channels=False, unit_colors=None, sparsity=None, ncols=5, scale=1, lw_waveforms=1, lw_templates=2, axis_equal=False, unit_selected_waveforms=None, max_spikes_per_unit=50, set_title=True, same_axis=False, shade_templates=True, templates_percentile_shading=[1, 25, 75, 98], x_offset_units=False, alpha_waveforms=0.5, alpha_templates=1, hide_unit_selector=False, plot_legend=True, backend=None, **backend_kwargs)¶

Plots unit waveforms.

Parameters

waveform_extractorWaveformExtractor

The input waveform extractor

channel_ids: list or None, default: None

The channel ids to display

unit_idslist or None, default: None

List of unit ids

plot_templatesbool, default: True

If True, templates are plotted over the waveforms

sparsityChannelSparsity or None, default: None

Optional ChannelSparsity to apply If WaveformExtractor is already sparse, the argument is ignored

set_titlebool, default: True

Create a plot title with the unit number if True

plot_channelsbool, default: False

Plot channel locations below traces

unit_selected_waveformsNone or dict, default: None

A dict key is unit_id and value is the subset of waveforms indices that should be be displayed (matplotlib backend)

max_spikes_per_unitint or None, default: 50

If given and unit_selected_waveforms is None, only max_spikes_per_unit random units are displayed per waveform, (matplotlib backend)

scalefloat, default: 1

Scale factor for the waveforms/templates (matplotlib backend)

axis_equalbool, default: False

Equal aspect ratio for x and y axis, to visualize the array geometry to scale

lw_waveformsfloat, default: 1

Line width for the waveforms, (matplotlib backend)

lw_templatesfloat, default: 2

Line width for the templates, (matplotlib backend)

unit_colorsNone or dict, default: None

A dict key is unit_id and value is any color format handled by matplotlib. If None, then the get_unit_colors() is internally used. (matplotlib / ipywidgets backend)

alpha_waveformsfloat, default: 0.5

Alpha value for waveforms (matplotlib backend)

alpha_templatesfloat, default: 1

Alpha value for templates, (matplotlib backend)

shade_templatesbool, default: True

If True, templates are shaded, see templates_percentile_shading argument

templates_percentile_shadingfloat, list of floats, or None, default: [1, 25, 75, 98]

It controls the shading of the templates. If None, the shading is +/- the standard deviation of the templates. If float, it controls the percentile of the template values used to shade the templates. Note that it is one-sided: if 5 is given, the 5th and 95th percentiles are used to shade the templates. If list of floats, it needs to be have an even number of elements which control the lower and upper percentile used to shade the templates. The first half of the elements are used for the lower bounds, and the second half for the upper bounds. Inner elements produce darker shadings. For sortingview backend only 2 or 4 elements are supported.

hide_unit_selectorbool, default: False

For sortingview backend, if True the unit selector is not displayed

same_axisbool, default: False

If True, waveforms and templates are displayed on the same axis (matplotlib backend)

x_offset_unitsbool, default: False

In case same_axis is True, this parameter allow to x-offset the waveforms for different units (recommended for a few units) (matlotlib backend)

plot_legendbool, default: True

Display legend (matplotlib backend)

backend: str

[‘matplotlib’, ‘ipywidgets’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

ipywidgets:

width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_study_run_times(study, case_keys=None, backend=None, **backend_kwargs)¶

Plot sorter run times for a GroundTruthStudy

Parameters

study: GroundTruthStudy

A study object.

case_keys: list or None

A selection of cases to plot, if None, then all.

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_study_unit_counts(study, case_keys=None, backend=None, **backend_kwargs)¶

Plot unit counts for a study: “num_well_detected”, “num_false_positive”, “num_redundant”, “num_overmerged”

Parameters

study: GroundTruthStudy

A study object.

case_keys: list or None

A selection of cases to plot, if None, then all.

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_study_performances(study, mode='ordered', performance_names=('accuracy', 'precision', 'recall'), case_keys=None, backend=None, **backend_kwargs)¶

Plot performances over case for a study.

Parameters

study: GroundTruthStudy

A study object.

mode: “ordered” | “snr” | “swarm”, default: “ordered”

Which plot mode to use:

“ordered”: plot performance metrics vs unit indices ordered by decreasing accuracy
“snr”: plot performance metrics vs snr
“swarm”: plot performance metrics as a swarm plot (see seaborn.swarmplot for details)

performance_names: list or tuple, default: (“accuracy”, “precision”, “recall”)

Which performances to plot (“accuracy”, “precision”, “recall”)

case_keys: list or None

A selection of cases to plot, if None, then all.

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_study_agreement_matrix(study, ordered=True, case_keys=None, backend=None, **backend_kwargs)¶

Plot agreement matrix.

Parameters

study: GroundTruthStudy

A study object.

case_keys: list or None

A selection of cases to plot, if None, then all.

ordered: bool

Order units with best agreement scores. This enable to see agreement on a diagonal.

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_study_summary(study, case_keys=None, backend=None, **backend_kwargs)¶

Plot a summary of a ground truth study. Internally this plotting function runs:

plot_study_run_times

plot_study_unit_counts

plot_study_performances

plot_study_agreement_matrix

Parameters

study: GroundTruthStudy

A study object.

case_keys: list or None, default: None

A selection of cases to plot, if None, then all.

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.widgets.plot_study_comparison_collision_by_similarity(study, case_keys=None, metric='cosine_similarity', similarity_bins=array([-4.00000000e-01, -2.00000000e-01, -5.55111512e-17, 2.00000000e-01, 4.00000000e-01, 6.00000000e-01, 8.00000000e-01, 1.00000000e+00]), show_legend=False, ylim=(0.5, 1), good_only=False, min_accuracy=0.9, cmap='winter', backend=None, **backend_kwargs)¶

Plots CollisionGTComparison pair by pair orderer by cosine_similarity for all cases in a study.

Parameters

study: CollisionGTStudy

The collision study object.

case_keys: list or None

A selection of cases to plot, if None, then all.

metric: “cosine_similarity”

metric for ordering

similarity_bins: array

if mode is “lines”, the bins used to average the pairs

cmap: string

colormap used to show averages if mode is “lines”

good_only: False

keep only the pairs with a non zero accuracy (found templates)

min_accuracy: float

If good only, the minimum accuracy every cell should have, individually, to be considered in a putative pair

backend: str

[‘matplotlib’]

**backend_kwargs: kwargs

matplotlib:

figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None

Returns

wBaseWidget: The output widget object.

spikeinterface.exporters¶

spikeinterface.exporters.export_to_phy(waveform_extractor: WaveformExtractor, output_folder: str | pathlib.Path, compute_pc_features: bool = True, compute_amplitudes: bool = True, sparsity: Optional[ChannelSparsity] = None, copy_binary: bool = True, remove_if_exists: bool = False, peak_sign: Literal['both', 'neg', 'pos'] = 'neg', template_mode: str = 'median', dtype: Union[dtype[Any], None, type[Any], _SupportsDType[dtype[Any]], str, tuple[Any, int], tuple[Any, Union[SupportsIndex, collections.abc.Sequence[SupportsIndex]]], list[Any], _DTypeDict, tuple[Any, Any]] = None, verbose: bool = True, use_relative_path: bool = False, **job_kwargs)¶

Exports a waveform extractor to the phy template-gui format.

Parameters

waveform_extractor: a WaveformExtractor or None

If WaveformExtractor is provide then the compute is faster otherwise

output_folder: str | Path

The output folder where the phy template-gui files are saved

compute_pc_features: bool, default: True

If True, pc features are computed

compute_amplitudes: bool, default: True

If True, waveforms amplitudes are computed

sparsity: ChannelSparsity or None, default: None

The sparsity object

copy_binary: bool, default: True

If True, the recording is copied and saved in the phy “output_folder”

remove_if_exists: bool, default: False

If True and “output_folder” exists, it is removed and overwritten

peak_sign: “neg” | “pos” | “both”, default: “neg”

Used by compute_spike_amplitudes

template_mode: str, default: “median”

Parameter “mode” to be given to WaveformExtractor.get_template()

dtype: dtype or None, default: None

Dtype to save binary data

verbose: bool, default: True

If True, output is verbose

use_relative_pathbool, default: False

If True and copy_binary=True saves the binary file dat_path in the params.py relative to output_folder (ie dat_path=r”recording.dat”). If copy_binary=False, then uses a path relative to the output_folder If False, uses an absolute path in the params.py (ie dat_path=r”path/to/the/recording.dat”)

**job_kwargs: keyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
  Number of samples per chunk
- chunk_memory: str
  Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
  Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
  Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
progress_bar: bool
If True, a progress bar is printed
mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems

spikeinterface.exporters.export_report(waveform_extractor, output_folder, remove_if_exists=False, format='png', show_figures=False, peak_sign='neg', force_computation=False, **job_kwargs)¶

Exports a SI spike sorting report. The report includes summary figures of the spike sorting output (e.g. amplitude distributions, unit localization and depth VS amplitude) as well as unit-specific reports, that include waveforms, templates, template maps, ISI distributions, and more.

Parameters

waveform_extractor: a WaveformExtractor or None

If WaveformExtractor is provide then the compute is faster otherwise

output_folder: str

The output folder where the report files are saved

remove_if_exists: bool, default: False

If True and the output folder exists, it is removed

format: str, default: “png”

The output figure format (any format handled by matplotlib)

peak_sign: “neg” or “pos”, default: “neg”

used to compute amplitudes and metrics

show_figures: bool, default: False

If True, figures are shown. If False, figures are closed after saving

force_computation: bool, default: False

Force or not some heavy computaion before exporting

**job_kwargs: keyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
  Number of samples per chunk
- chunk_memory: str
  Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
  Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
  Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
progress_bar: bool
If True, a progress bar is printed
mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems

spikeinterface.curation¶

class spikeinterface.curation.CurationSorting(parent_sorting, make_graph=False, properties_policy='keep')¶

Class that handles curation of a Sorting object.

Parameters

parent_sorting: Recording: The recording object
properties_policy: “keep” | “remove”, default: “keep”: Policy used to propagate properties after split and merge operation. If “keep” the properties will be passed to the new units (if the original units have the same value). If “remove” the new units will have an empty value for all the properties
make_graph: bool: True to keep a Networkx graph instance with the curation history
Returns
——-
sorting: Sorting: Sorting object with the selected units merged

class spikeinterface.curation.MergeUnitsSorting(parent_sorting, units_to_merge, new_unit_ids=None, properties_policy='keep', delta_time_ms=0.4)¶

Class that handles several merges of units from a Sorting object based on a list of lists of unit_ids.

Parameters

parent_sorting: Recording

The sorting object

units_to_merge: list/tuple of lists/tuples

A list of lists for every merge group. Each element needs to have at least two elements (two units to merge), but it can also have more (merge multiple units at once).

new_unit_ids: None or list

A new unit_ids for merged units. If given, it needs to have the same length as units_to_merge

properties_policy: “keep” | “remove”, default: “keep”

Policy used to propagate properties. If “keep” the properties will be passed to the new units: (if the units_to_merge have the same value). If “remove” the new units will have an empty value for all the properties of the new unit.

delta_time_ms: float or None

Number of ms to consider for duplicated spikes. None won’t check for duplications

Returns

sorting: Sorting: Sorting object with the selected units merged

class spikeinterface.curation.SplitUnitSorting(parent_sorting, split_unit_id, indices_list, new_unit_ids=None, properties_policy='keep')¶

Class that handles spliting of a unit. It creates a new Sorting object linked to parent_sorting.

Parameters

parent_sorting: Recording

The recording object

parent_unit_id: int

Unit id of the unit to split

indices_list: list

A list of index arrays selecting the spikes to split in each segment. Each array can contain more than 2 indices (e.g. for splitting in 3 or more units) and it should be the same length as the spike train (for each segment)

new_unit_ids: int

Unit ids of the new units to be created.

properties_policy: “keep” | “remove”, default: “keep”

Policy used to propagate properties. If “keep” the properties will be passed to the new units: (if the units_to_merge have the same value). If “remove” the new units will have an empty value for all the properties of the new unit.

Returns

——-

sorting: Sorting

Sorting object with the selected units split

spikeinterface.curation.get_potential_auto_merge(waveform_extractor, minimum_spikes=1000, maximum_distance_um=150.0, peak_sign='neg', bin_ms=0.25, window_ms=100.0, corr_diff_thresh=0.16, template_diff_thresh=0.25, censored_period_ms=0.3, refractory_period_ms=1.0, sigma_smooth_ms=0.6, contamination_threshold=0.2, adaptative_window_threshold=0.5, censor_correlograms_ms: float = 0.15, num_channels=5, num_shift=5, firing_contamination_balance=1.5, extra_outputs=False, steps=None)¶

Algorithm to find and check potential merges between units.

This is taken from lussac version 1 done by Aurelien Wyngaard and Victor Llobet. https://github.com/BarbourLab/lussac/blob/v1.0.0/postprocessing/merge_units.py

The merges are proposed when the following criteria are met:

STEP 1: enough spikes are found in each units for computing the correlogram (minimum_spikes)

STEP 2: each unit is not contaminated (by checking auto-correlogram - contamination_threshold)

STEP 3: estimated unit locations are close enough (maximum_distance_um)

STEP 4: the cross-correlograms of the two units are similar to each auto-corrleogram (corr_diff_thresh)

STEP 5: the templates of the two units are similar (template_diff_thresh)

STEP 6: the unit “quality score” is increased after the merge.

The “quality score” factors in the increase in firing rate (f) due to the merge and a possible increase in contamination (C), wheighted by a factor k (firing_contamination_balance).

\[Q = f(1 - (k + 1)C)\]

Parameters

waveform_extractor: WaveformExtractor: The waveform extractor
minimum_spikes: int, default: 1000: Minimum number of spikes for each unit to consider a potential merge. Enough spikes are needed to estimate the correlogram
maximum_distance_um: float, default: 150: Minimum distance between units for considering a merge
peak_sign: “neg” | “pos” | “both”, default: “neg”: Peak sign used to estimate the maximum channel of a template
bin_ms: float, default: 0.25: Bin size in ms used for computing the correlogram
window_ms: float, default: 100: Window size in ms used for computing the correlogram
corr_diff_thresh: float, default: 0.16: The threshold on the “correlogram distance metric” for considering a merge. It needs to be between 0 and 1
template_diff_thresh: float, default: 0.25: The threshold on the “template distance metric” for considering a merge. It needs to be between 0 and 1
censored_period_ms: float, default: 0.3: Used to compute the refractory period violations aka “contamination”
refractory_period_ms: float, default: 1: Used to compute the refractory period violations aka “contamination”
sigma_smooth_ms: float, default: 0.6: Parameters to smooth the correlogram estimation
contamination_threshold: float, default: 0.2: Threshold for not taking in account a unit when it is too contaminated
adaptative_window_threshold:: float, default: 0.5: Parameter to detect the window size in correlogram estimation
censor_correlograms_ms: float, default: 0.15: The period to censor on the auto and cross-correlograms
num_channels: int, default: 5: Number of channel to use for template similarity computation
num_shift: int, default: 5: Number of shifts in samles to be explored for template similarity computation
firing_contamination_balance: float, default: 1.5: Parameter to control the balance between firing rate and contamination in computing unit “quality score”
extra_outputs: bool, default: False: If True, an additional dictionary (outs) with processed data is returned
steps: None or list of str, default: None: which steps to run (gives flexibility to running just some steps) If None all steps are done. Pontential steps: “min_spikes”, “remove_contaminated”, “unit_positions”, “correlogram”, “template_similarity”, “check_increase_score”. Please check steps explanations above!

Returns

potential_merges:: A list of tuples of 2 elements. List of pairs that could be merged.
outs:: Returned only when extra_outputs=True A dictionary that contains data for debugging and plotting.

spikeinterface.curation.find_redundant_units(sorting, delta_time: float = 0.4, agreement_threshold=0.2, duplicate_threshold=0.8)¶

Finds redundant or duplicate units by comparing the sorting output with itself.

Parameters

sortingBaseSorting: The input sorting object
delta_timefloat, default: 0.4: The time in ms to consider matching spikes
agreement_thresholdfloat, default: 0.2: Threshold on the agreement scores to flag possible redundant/duplicate units
duplicate_thresholdfloat, default: 0.8: Final threshold on the portion of coincident events over the number of spikes above which the unit is flagged as duplicate/redundant

Returns

list: The list of duplicate units
list of 2-element lists: The list of duplicate pairs

spikeinterface.curation.remove_redundant_units(sorting_or_waveform_extractor, align=True, unit_peak_shifts=None, delta_time=0.4, agreement_threshold=0.2, duplicate_threshold=0.8, remove_strategy='minimum_shift', peak_sign='neg', extra_outputs=False)¶

Removes redundant or duplicate units by comparing the sorting output with itself.

When a redundant pair is found, there are several strategies to choose which unit is the best:

“minimum_shift”

“highest_amplitude”

“max_spikes”

Parameters

sorting_or_waveform_extractorBaseSorting or WaveformExtractor

If WaveformExtractor, the spike trains can be optionally realigned using the peak shift in the template to improve the matching procedure. If BaseSorting, the spike trains are not aligned.

alignbool, default: False

If True, spike trains are aligned (if a WaveformExtractor is used)

delta_timefloat, default: 0.4

The time in ms to consider matching spikes

agreement_thresholdfloat, default: 0.2

Threshold on the agreement scores to flag possible redundant/duplicate units

duplicate_thresholdfloat, default: 0.8

Final threshold on the portion of coincident events over the number of spikes above which the unit is removed

remove_strategy: “minimum_shift” | “highest_amplitude” | “max_spikes”, default: “minimum_shift”

Which strategy to remove one of the two duplicated units:

“minimum_shift”: keep the unit with best peak alignment (minimum shift)
If shifts are equal then the “highest_amplitude” is used

“highest_amplitude”: keep the unit with the best amplitude on unshifted max.

“max_spikes”: keep the unit with more spikes

peak_sign: “neg” | “pos” | “both”, default: “neg”

Used when remove_strategy=”highest_amplitude”

extra_outputs: bool, default: False

If True, will return the redundant pairs.

Returns

BaseSorting: Sorting object without redundant units

spikeinterface.curation.remove_duplicated_spikes(sorting: BaseSorting, censored_period_ms: float = 0.3, method: str = 'keep_first') → None¶

Class to remove duplicated spikes from the spike trains. Spikes are considered duplicated if they are less than x ms apart where x is the censored period.

Parameters

sorting: BaseSorting: The parent sorting.
censored_period_ms: float: The censored period to consider 2 spikes to be duplicated (in ms).
method: “keep_first” | “keep_last” | “keep_first_iterative” | “keep_last_iterative” | “random”, default: “keep_first”: Method used to remove the duplicated spikes. If method = “random”, will randomly choose to remove the first or last spike. If method = “keep_first”, for each ISI violation, will remove the second spike. If method = “keep_last”, for each ISI violation, will remove the first spike. If method = “keep_first_iterative”, will iteratively keep the first spike and remove the following violations. If method = “keep_last_iterative”, does the same as “keep_first_iterative” but starting from the end. In the iterative methods, if there is a triplet A, B, C where (A, B) and (B, C) are in the censored period (but not (A, C)), then only B is removed. In the non iterative methods however, only one spike remains.

Returns

sorting_without_duplicated_spikes: Remove_DuplicatedSpikesSorting: The sorting without any duplicated spikes.

spikeinterface.curation.remove_excess_spikes(sorting, recording)¶

Remove excess spikes from the spike trains. Excess spikes are the ones exceeding a recording number of samples, for each segment.

Parameters

sorting: BaseSorting: The parent sorting.
recording: BaseRecording: The recording to use to get the number of samples.

Returns

sorting_without_excess_spikes: Sorting: The sorting without any excess spikes.

spikeinterface.curation.apply_sortingview_curation(sorting, uri_or_json, exclude_labels=None, include_labels=None, skip_merge=False, verbose=False)¶

Apply curation from SortingView manual curation. First, merges (if present) are applied. Then labels are loaded and units are optionally filtered based on exclude_labels and include_labels.

Parameters

sortingBaseSorting: The sorting object to be curated
uri_or_jsonstr or Path: The URI curation link from SortingView or the path to the curation json file
exclude_labelslist, default: None: Optional list of labels to exclude (e.g. [“reject”, “noise”]). Mutually exclusive with include_labels
include_labelslist, default: None: Optional list of labels to include (e.g. [“accept”]). Mutually exclusive with exclude_labels, by default None
skip_mergebool, default: False: If True, merges are not applied (only labels)
verbosebool, default: False: If True, output is verbose

Returns

sorting_curatedBaseSorting: The curated sorting

spikeinterface.generation¶

spikeinterface.generation.make_linear_displacement(start, stop, num_step=10)¶

Generates 2D linear displacements between start and stop positions (included in returned displacements).

Parameters

start: np.array of 2 elements: The start position.
stop: np.array of 2 elements: The stop position.
num_step: int, default: 10: The number of steps between start and stop.

Returns

displacements: np.array: The displacements with shape (num_step, 2)

spikeinterface.generation.move_dense_templates(templates_array, displacements, source_probe, dest_probe=None, interpolation_method='cubic')¶

Move all templates_array given some displacements using spatial interpolation (cubic or linear). Optionally, the displaced templates can be remapped to another probe with a different geometry.

This function operates on dense templates only.

Note: in this function no checks are done to see if templates_array can be interpolatable after displacements. To check if the given displacements are interpolatable use the higher-level function move_templates().

Parameters

templates_array: np.array: A numpy array with dense templates_array. shape = (num_templates, num_samples, num_channels)
displacements: np.array: Displacement vector shape: (num_displacement, 2)
source_probe: Probe: The Probe object on which templates_array are defined
dest_probe: Probe | None, default: None: The destination Probe. Can be different geometry than the original. If None then the same probe is used.
interpolation_method: “cubic” | “linear”, default: “cubic”: The interpolation method.

Returns

new_templates_array: np.array: shape = (num_displacement, num_templates, num_samples, num_channels)

spikeinterface.generation.interpolate_templates(templates_array, source_locations, dest_locations, interpolation_method='cubic')¶

Interpolate templates_array to new positions. Useful to create motion or to remap templates_array form probeA to probeB.

Note that multiple interpolations can be performed by broadcasting when dest_locations have more than one dimension.

Parameters

templates_array: np.array: A numpy array with dense templates_array. shape = (num_templates, num_samples, num_channels)
source_locations: np.array: The channel source location corresponding to templates_array. shape = (num_channels, 2)
dest_locations: np.array: The new channel position, if ndim == 3, then the interpolation is broadcated with last dim. shape = (num_channels, 2) or (num_motions, num_channels, 2)
interpolation_method: str, default “cubic”: The interpolation method.

Returns

new_templates_array: np.array: shape = (num_templates, num_samples, num_channels) or = (num_motions, num_templates, num_samples, num_channel)

class spikeinterface.generation.DriftingTemplates(**kwargs)¶

Templates with drift. This is useful to generate drifting recording.

This class supports 2 different strategies:

move every templates on-the-fly, this lead to one interpolation per spike
precompute some displacements for all templates and use a discreate interpolation, for instance by step of 1um This is the same strategy used by MEArec.

class spikeinterface.generation.InjectDriftingTemplatesRecording(sorting: BaseSorting, drifting_templates: DriftingTemplates, displacement_vectors: list[numpy.ndarray], displacement_sampling_frequency: float, displacement_unit_factor: Optional[ndarray] = None, parent_recording: Optional[BaseRecording] = None, num_samples: Optional[list[int]] = None, amplitude_factor: Optional[Union[list[numpy.ndarray], ndarray, float]] = None, mode='precompute')¶

Class for injecting drifting templates into a recording. This is similar to InjectTemplatesRecording but with drifts.

Parameters

sorting: BaseSorting: Sorting object containing all the units and their spike train
drifting_templates: DriftingTemplates: The drifting template object
displacement_vectors: list of numpy array: The lenght of the list is the number of segment. Per segment, the drift vector is a numpy array with shape (num_times, 2, num_motions) num_motions is generally = 1 but can be > 1 in case of combining several drift vectors
displacement_sampling_frequency: float: The sampling frequency of drift vector
displacement_unit_factor: numpy array or None, default: None: A array containing the factor per unit of the drift. This is used to create non rigid with a factor gradient of depending on units position. shape (num_units, num_motions) If None then all unit have the same factor (1) and the drift is rigid.
parent_recording: BaseRecording or None, default: None: The recording over which to add the templates. If None, will default to traces containing all 0.
num_samples: list[int] or int or None, default: None: The number of samples in the recording per segment. You can use int for mono-segment objects.
amplitude_factor: list of numpy array or numpy array or float or None, default: None: Controls the amplitude scaling for each spike for each unit. If None, no amplitude scaling is applied. If scalar all spikes have the same factor (certainly useless). If vector, it must have the same size as the spike vector.

Returns

injected_recording: InjectDriftingTemplatesRecording: The recording with the templates injected.

spikeinterface.sortingcomponents¶

Peak Localization¶

Sorting components: peak localization.

spikeinterface.sortingcomponents.peak_localization.localize_peaks(recording, peaks, method='center_of_mass', ms_before=0.5, ms_after=0.5, **kwargs)¶

Localize peak (spike) in 2D or 3D depending the method.

When a probe is 2D then:

X is axis 0 of the probe
Y is axis 1 of the probe
Z is orthogonal to the plane of the probe

Parameters

recording: RecordingExtractor

The recording extractor object.

peaks: array

Peaks array, as returned by detect_peaks() in “compact_numpy” way.

method: ‘center_of_mass’, ‘monopolar_triangulation’, ‘grid_convolution’

Method to use.

arguments for method=’center_of_mass’

radius_um: float: Radius in um for channel sparsity.
feature: “ptp” | “mean” | “energy” | “peak_voltage”, default: “ptp”: Feature to consider for computation

arguments for method=’monopolar_triangulation’

radius_um: float: For channel sparsity.
max_distance_um: float, default: 1000: Boundary for distance estimation.
enforce_decreasebool, default: True: Enforce spatial decreasingness for PTP vectors
feature: “ptp”, “energy”, “peak_voltage”, default: “ptp”: The available features to consider for estimating the position via monopolar triangulation are peak-to-peak amplitudes (ptp, default), energy (“energy”, as L2 norm) or voltages at the center of the waveform (peak_voltage)

arguments for method=’grid_convolution’

radius_um: float, default: 40.0: Radius in um for channel sparsity.
upsampling_um: float, default: 5.0: Upsampling resolution for the grid of templates
sigma_ms: float: The temporal decay of the fake templates
margin_um: float, default: 50.0: The margin for the grid of fake templates
peak_sign: “neg” | “pos”, default: “neg”: Sign of the peak if no prototype are provided for the waveforms
prototype: np.array: Fake waveforms for the templates. If None, generated as Gaussian
percentile: float, default: 5.0: The percentage in [0, 100] of the best scalar products kept to estimate the position
weight_method: dict: Parameter that should be provided to the get_convolution_weights() function in order to know how to estimate the positions. One argument is mode that could be either gaussian_2d (KS like) or exponential_3d (default)

**job_kwargs: keyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
  Number of samples per chunk
- chunk_memory: str
  Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
  Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
  Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
progress_bar: bool
If True, a progress bar is printed
mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems

Returns

peak_locations: ndarray: Array with estimated location for each spike. The dtype depends on the method. (“x”, “y”) or (“x”, “y”, “z”, “alpha”).

Peak Detection¶

Sorting components: peak detection.

spikeinterface.sortingcomponents.peak_detection.detect_peaks(recording, method='by_channel', pipeline_nodes=None, gather_mode='memory', folder=None, names=None, **kwargs)¶

Peak detection based on threshold crossing in term of k x MAD.

In “by_channel” : peak are detected in each channel independently In “locally_exclusive” : a single best peak is taken from a set of neighboring channels

Parameters

recording: RecordingExtractor

The recording extractor object.

pipeline_nodes: None or list[PipelineNode]

Optional additional PipelineNode need to computed just after detection time. This avoid reading the recording multiple times.

gather_mode: str

How to gather the results: * “memory”: results are returned as in-memory numpy arrays * “npy”: results are stored to .npy files in folder

folder: str or Path

If gather_mode is “npy”, the folder where the files are created.

names: list

List of strings with file stems associated with returns.

method: ‘by_channel’, ‘locally_exclusive’, ‘locally_exclusive_cl’, ‘by_channel_torch’, ‘locally_exclusive_torch’

Method to use.

arguments for method=’by_channel’

peak_sign: “neg” | “pos” | “both”, default: “neg”: Sign of the peak
detect_threshold: float, default: 5: Threshold, in median absolute deviations (MAD), to use to detect peaks
exclude_sweep_ms: float, default: 0.1: Time, in ms, during which the peak is isolated. Exclusive param with exclude_sweep_size For example, if exclude_sweep_ms is 0.1, a peak is detected if a sample crosses the threshold, and no larger peaks are located during the 0.1ms preceding and following the peak
noise_levels: array or None, default: None: Estimated noise levels to use, if already computed If not provide then it is estimated from a random snippet of the data
random_chunk_kwargs: dict, default: dict(): A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None

arguments for method=’locally_exclusive’

peak_sign: “neg” | “pos” | “both”, default: “neg”: Sign of the peak
detect_threshold: float, default: 5: Threshold, in median absolute deviations (MAD), to use to detect peaks
exclude_sweep_ms: float, default: 0.1: Time, in ms, during which the peak is isolated. Exclusive param with exclude_sweep_size For example, if exclude_sweep_ms is 0.1, a peak is detected if a sample crosses the threshold, and no larger peaks are located during the 0.1ms preceding and following the peak
noise_levels: array or None, default: None: Estimated noise levels to use, if already computed If not provide then it is estimated from a random snippet of the data
random_chunk_kwargs: dict, default: dict(): A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None
radius_um: float: The radius to use to select neighbour channels for locally exclusive detection.

arguments for method=’locally_exclusive_cl’

peak_sign: “neg” | “pos” | “both”, default: “neg”: Sign of the peak
detect_threshold: float, default: 5: Threshold, in median absolute deviations (MAD), to use to detect peaks
exclude_sweep_ms: float, default: 0.1: Time, in ms, during which the peak is isolated. Exclusive param with exclude_sweep_size For example, if exclude_sweep_ms is 0.1, a peak is detected if a sample crosses the threshold, and no larger peaks are located during the 0.1ms preceding and following the peak
noise_levels: array or None, default: None: Estimated noise levels to use, if already computed If not provide then it is estimated from a random snippet of the data
random_chunk_kwargs: dict, default: dict(): A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None
radius_um: float: The radius to use to select neighbour channels for locally exclusive detection.
opencl_context_kwargs: None or dict: kwargs to create the opencl context

arguments for method=’by_channel_torch’

peak_sign: “neg” | “pos” | “both”, default: “neg”: Sign of the peak
detect_threshold: float, default: 5: Threshold, in median absolute deviations (MAD), to use to detect peaks
exclude_sweep_ms: float, default: 0.1: Time, in ms, during which the peak is isolated. Exclusive param with exclude_sweep_size For example, if exclude_sweep_ms is 0.1, a peak is detected if a sample crosses the threshold, and no larger peaks are located during the 0.1ms preceding and following the peak
noise_levels: array or None, default: None: Estimated noise levels to use, if already computed. If not provide then it is estimated from a random snippet of the data
devicestr or None, default: None: “cpu”, “cuda”, or None. If None and cuda is available, “cuda” is selected
return_tensorbool, default: False: If True, the output is returned as a tensor, otherwise as a numpy array
random_chunk_kwargs: dict, default: dict(): A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None.

arguments for method=’locally_exclusive_torch’

peak_sign: “neg” | “pos” | “both”, default: “neg”: Sign of the peak
detect_threshold: float, default: 5: Threshold, in median absolute deviations (MAD), to use to detect peaks
exclude_sweep_ms: float, default: 0.1: Time, in ms, during which the peak is isolated. Exclusive param with exclude_sweep_size For example, if exclude_sweep_ms is 0.1, a peak is detected if a sample crosses the threshold, and no larger peaks are located during the 0.1ms preceding and following the peak
noise_levels: array or None, default: None: Estimated noise levels to use, if already computed If not provide then it is estimated from a random snippet of the data
random_chunk_kwargs: dict, default: dict(): A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None
radius_um: float: The radius to use to select neighbour channels for locally exclusive detection.

**job_kwargs: keyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
  Number of samples per chunk
- chunk_memory: str
  Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
  Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
  Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
progress_bar: bool
If True, a progress bar is printed
mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems

Returns

peaks: array: Detected peaks.

Notes

This peak detection ported from tridesclous into spikeinterface.

Motion Correction¶

class spikeinterface.sortingcomponents.motion_interpolation.InterpolateMotionRecording(recording, motion, temporal_bins, spatial_bins, direction=1, border_mode='remove_channels', spatial_interpolation_method='kriging', sigma_um=20.0, p=1, num_closest=3)¶

Recording that corrects motion on-the-fly given a motion vector estimation (rigid or non-rigid). This internally applies a spatial interpolation on the original traces after reversing the motion. estimate_motion() must be called before this to estimate the motion vector.

Parameters

recording: Recording

The parent recording.

motion: np.array 2D

The motion signal obtained with estimate_motion() motion.shape[0] must correspond to temporal_bins.shape[0] motion.shape[1] is 1 when “rigid” motion and spatial_bins.shape[0] when “non-rigid”

temporal_bins: np.array

Temporal bins in second.

spatial_bins: None or np.array

Bins for non-rigid motion. If None, rigid motion is used

direction: 0 | 1 | 2, default: 1

Dimension along which channel_locations are shifted (0 - x, 1 - y, 2 - z)

spatial_interpolation_method: “kriging” | “idw” | “nearest”, default: “kriging”

The spatial interpolation method used to interpolate the channel locations. See spikeinterface.preprocessing.get_spatial_interpolation_kernel() for more details. Choice of the method:

“kriging” : the same one used in kilosort

“idw” : inverse distance weighted

“nearest” : use neareast channel

sigma_um: float, default: 20.0

Used in the “kriging” formula

p: int, default: 1

Used in the “kriging” formula

num_closest: int, default: 3

Number of closest channels used by “idw” method for interpolation.

border_mode: “remove_channels” | “force_extrapolate” | “force_zeros”, default: “remove_channels”

Control how channels are handled on border:

“remove_channels”: remove channels on the border, the recording has less channels
“force_extrapolate”: keep all channel and force extrapolation (can lead to strange signal)
“force_zeros”: keep all channel but set zeros when outside (force_extrapolate=False)

Returns

corrected_recording: InterpolateMotionRecording: Recording after motion correction

Clustering¶

spikeinterface.sortingcomponents.clustering.find_cluster_from_peaks(recording, peaks, method='stupid', method_kwargs={}, extra_outputs=False, **job_kwargs)¶

Find cluster from peaks.

Parameters

recording: RecordingExtractor

The recording extractor object

peaks: WaveformExtractor

The waveform extractor

method: str

Which method to use (“stupid” | “XXXX”)

method_kwargs: dict, default: dict()

Keyword arguments for the chosen method

extra_outputs: bool, default: False

If True then debug is also return

**job_kwargs: keyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
  Number of samples per chunk
- chunk_memory: str
  Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
  Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
  Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
progress_bar: bool
If True, a progress bar is printed
mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems

Returns

labels: ndarray of int: possible clusters list
peak_labels: array of int: peak_labels.shape[0] == peaks.shape[0]

Template Matching¶

spikeinterface.sortingcomponents.matching.find_spikes_from_templates(recording, method='naive', method_kwargs={}, extra_outputs=False, **job_kwargs)¶

Find spike from a recording from given templates.

Parameters

recording: RecordingExtractor: The recording extractor object
method: “naive” | “tridesclous” | “circus” | “circus-omp” | “wobble”: Which method to use for template matching
method_kwargs: dict, optional: Keyword arguments for the chosen method
extra_outputs: bool: If True then method_kwargs is also returned
job_kwargs: dict: Parameters for ChunkRecordingExecutor

Returns

spikes: ndarray: Spikes found from templates.
method_kwargs:: Optionaly returns for debug purpose.

Notes

For all methods except “wobble”, templates are represented as a WaveformExtractor in method_kwargs so statistics can be extracted. For “wobble” templates are represented as a numpy.ndarray.