API

spikeinterface.core

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

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_length=None, file_offset=None, file_suffix=None, file_paths_lenght=None)

Check is the recording is binary compatible with some constrain on

dtype

tim_axis

len(file_paths)

file_offset

file_suffix

frame_slice(start_frame: int | None, end_frame: int | None) → BaseRecording

Returns a new recording with sliced frames. Note that this operation is not in place.

Parameters:

start_frameint, optional: Start frame index. If None, defaults to the beginning of the recording (frame 0).
end_frameint, optional: End frame index. If None, defaults to the last frame of the recording.

Returns:

BaseRecording: A new recording object with only samples between start_frame and end_frame

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

Get the physical locations of specified channels.

Parameters:

channel_idsarray-like, optional: The IDs of the channels for which to retrieve locations. If None, retrieves locations for all available channels. Default is None.
axes“xy” | “yz” | “xz” | “xyz”, default: “xy”: The spatial axes to return, specified as a string (e.g., “xy”, “xyz”). Default is “xy”.

Returns:

np.ndarray: A 2D or 3D array of shape (n_channels, n_dimensions) containing the locations of the channels. The number of dimensions depends on the axes argument (e.g., 2 for “xy”, 3 for “xyz”).

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_end_time(segment_index=None) → float

Get the stop time of the recording segment.

Parameters:

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

Returns:

float: The stop time 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: int | None = 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: int | None = 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_start_time(segment_index=None) → float

Get the start time of the recording segment.

Parameters:

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

Returns:

float: The start time in seconds

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) → ndarray

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) → BaseRecording

Returns a new recording object with renamed channel ids.

Note that this method does not modify the current recording and instead returns a new recording object.

Parameters:

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

reset_times(): Reset time information in-memory for all segments that have a time vector. If the timestamps come from a file, the files won’t be modified. but only the in-memory attributes of the recording objects are deleted. Also t_start is set to None and the segment’s sampling frequency is set to the recording’s sampling frequency.

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

select_channels(channel_ids: list | np.array | tuple) → BaseRecording

Returns a new recording object with a subset of channels.

Note that this method does not modify the current recording and instead returns a new recording object.

Parameters:

channel_idslist or np.array or tuple: The channel ids to select.

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

shift_times(shift: int | float, segment_index: int | None = None) → None

Shift all times by a scalar value.

Parameters:

shiftint | float: The shift to apply. If positive, times will be increased by shift. e.g. shifting by 1 will be like the recording started 1 second later. If negative, the start time will be decreased i.e. as if the recording started earlier.
segment_indexint | None: The segment on which to shift the times. If None, all segments will be shifted.

time_slice(start_time: float | None, end_time: float | None) → BaseRecording

Returns a new recording object, restricted to the time interval [start_time, end_time].

Parameters:

start_timefloat, optional: Start time in seconds. If None, defaults to the beginning of the recording.
end_timefloat, optional: End time in seconds. If None, defaults to the end of the recording.

Returns:

BaseRecording: A new recording object with only samples between start_time and end_time

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_spikesint: The total number of spike

get_empty_unit_ids() → ndarray

Return the unit IDs that have zero spikes across all segments.

This method returns the complement of get_non_empty_unit_ids with respect to all unit IDs in the sorting.

Returns:

np.ndarray: Array of unit IDs (same dtype as self.unit_ids) for which no spikes exist.

get_non_empty_unit_ids() → ndarray

Return the unit IDs that have at least one spike across all segments.

This method computes the number of spikes for each unit using count_num_spikes_per_unit and filters out units with zero spikes.

Returns:

np.ndarray: Array of unit IDs (same dtype as self.unit_ids) for which at least one spike exists.

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() → float

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) → bool: 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_vectorNone | 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. If the sorting and recording both contain time information, the recording’s time information will be used.

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: 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

time_slice(start_time: float | None, end_time: float | None) → BaseSorting

Returns a new sorting object, restricted to the time interval [start_time, end_time].

Parameters:

start_timefloat | None, default: None: The start time in seconds. If not provided it is set to 0.
end_timefloat | None, default: None: The end time in seconds. If not provided it is set to the total duration.

Returns:

BaseSorting: A new sorting object with only samples between start_time and end_time

time_to_sample_index(time, segment_index=0): Transform time in seconds into sample index

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_jobsint: 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) → ndarray | list[ndarray]

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

Parameters:

concatenatedbool, 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_indsNone 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_cachebool, 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:

spikesnp.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: int | None, snippet_len: int, channel_ids: list, dtype)

Abstract class representing several multichannel snippets.

select_channels(channel_ids: list | np.array | tuple) → BaseSnippets

Returns a new object with sliced channels.

Parameters:

channel_idsnp.array or list: The list of channels to keep

Returns:

BaseRecordingSnippets: The object with sliced channels

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.

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

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.SortingAnalyzer(sorting: BaseSorting, recording: BaseRecording | None = None, rec_attributes: dict | None = None, format: str | None = None, sparsity: ChannelSparsity | None = None, return_scaled: bool = True, backend_options: dict | None = None)

Class to make a pair of Recording-Sorting which will be used used for all post postprocessing, visualization and quality metric computation.

This internally maintains a list of computed ResultExtention (waveform, pca, unit position, spike position, …).

This can live in memory and/or can be be persistent to disk in 2 internal formats (folder/json/npz or zarr). A SortingAnalyzer can be transfer to another format using save_as()

This handle unit sparsity that can be propagated to ResultExtention.

This handle spike sampling that can be propagated to ResultExtention : works on only a subset of spikes.

This internally saves a copy of the Sorting and extracts main recording attributes (without traces) so the SortingAnalyzer object can be reloaded even if references to the original sorting and/or to the original recording are lost.

SortingAnalyzer() should not never be used directly for creating: use instead create_sorting_analyzer(sorting, resording, …) or eventually SortingAnalyzer.create(…)

are_units_mergeable(merge_unit_groups: list[str | int], merging_mode: str = 'soft', sparsity_overlap: float = 0.75, return_masks: bool = False)

Check if soft merges can be performed given sparsity_overlap param.

Parameters:

merge_unit_groupslist/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).
merging_mode“soft” | “hard”, default: “soft”: How merges are performed. In the “soft” mode, merges will be approximated, with no smart merging of the extension data.
sparsity_overlapfloat, default: 0.75: The percentage of overlap that units should share in order to accept merges.
return_masksbool, default: False: If True, return the masks used for the merge.

Returns:

mergeabledict[bool]: Dictionary of of mergeable units. The keys are the merge unit groups (as tuple), and boolean values indicate if the merge is possible.
masksdict[np.array]: Dictionary of masks used for the merge. The keys are the merge unit groups, and the values are the masks used for the merge.

compute(input, save=True, extension_params=None, verbose=False, **kwargs) → AnalyzerExtension | None

Compute one extension or several extensiosn. Internally calls compute_one_extension() or compute_several_extensions() depending on the input type.

Parameters:

inputstr or dict or list: The extensions to compute, which can be passed as: * a string: compute one extension. Additional parameters can be passed as key word arguments. * a dict: compute several extensions. The keys are the extension names and the values are dictionaries with the extension parameters. * a list: compute several extensions. The list contains the extension names. Additional parameters can be passed with the extension_params argument.
savebool, default: True: If True the extension is saved to disk (only if sorting analyzer format is not “memory”)
extension_paramsdict or None, default: None: If input is a list, this parameter can be used to specify parameters for each extension. The extension_params keys must be included in the input list.
**kwargs:: All other kwargs are transmitted to extension.set_params() (if input is a string) or job_kwargs

Returns:

extensionSortingAnalyzerExtension | None: The extension instance if input is a string, None otherwise.

Examples

This function accepts the following possible signatures for flexibility:

Compute one extension, with parameters: >>> analyzer.compute(“waveforms”, ms_before=1.5, ms_after=2.5)

Compute two extensions with a list as input and with default parameters: >>> analyzer.compute([“random_spikes”, “waveforms”])

Compute two extensions with dict as input, one dict per extension >>> analyzer.compute({“random_spikes”:{}, “waveforms”:{“ms_before”:1.5, “ms_after”, “2.5”}})

Compute two extensions with an input list specifying custom parameters for one (the other will use default parameters): >>> analyzer.compute([“random_spikes”, “waveforms”],extension_params={“waveforms”:{“ms_before”:1.5, “ms_after”: “2.5”}})

compute_one_extension(extension_name, save=True, verbose=False, **kwargs) → AnalyzerExtension

Compute one extension.

Important note: when computing again an extension, all extensions that depend on it will be automatically and silently deleted to keep a coherent data.

Parameters:

extension_namestr: The name of the extension. For instance “waveforms”, “templates”, …
savebool, default: True: It the extension can be saved then it is saved. If not then the extension will only live in memory as long as the object is deleted. save=False is convenient to try some parameters without changing an already saved extension.
**kwargs:: All other kwargs are transmitted to extension.set_params() or job_kwargs

Returns:

result_extensionAnalyzerExtension: Return the extension instance

Examples

>>> Note that the return is the instance extension.
>>> extension = sorting_analyzer.compute("waveforms", **some_params)
>>> extension = sorting_analyzer.compute_one_extension("waveforms", **some_params)
>>> wfs = extension.data["waveforms"]
>>> # Note this can be be done in the old way style BUT the return is not the same it return directly data
>>> wfs = compute_waveforms(sorting_analyzer, **some_params)

compute_several_extensions(extensions, save=True, verbose=False, **job_kwargs)

Compute several extensions

Important note: when computing again an extension, all extensions that depend on it will be automatically and silently deleted to keep a coherent data.

Parameters:

extensionsdict: Keys are extension_names and values are params.
savebool, default: True: It the extension can be saved then it is saved. If not then the extension will only live in memory as long as the object is deleted. save=False is convenient to try some parameters without changing an already saved extension.

Returns:

No return

Examples

>>> sorting_analyzer.compute({"waveforms": {"ms_before": 1.2}, "templates" : {"operators": ["average", "std", ]} })
>>> sorting_analyzer.compute_several_extensions({"waveforms": {"ms_before": 1.2}, "templates" : {"operators": ["average", "std"]}})

copy(): Create a a copy of SortingAnalyzer with format “memory”.

delete_extension(extension_name) → None: Delete the extension from the dict and also in the persistent zarr or folder.

get_computable_extensions(): Get all extensions that can be computed by the analyzer.

get_default_extension_params(extension_name: str) → dict

Get the default params for an extension.

Parameters:

extension_namestr: The extension name

Returns:

default_paramsdict: The default parameters for the extension

get_extension(extension_name: str)

Get a AnalyzerExtension. If not loaded then load is automatic.

Return None if the extension is not computed yet (this avoids the use of has_extension() and then get it)

get_loaded_extension_names(): Return the loaded or already computed extensions names.

get_saved_extension_names(): Get extension names saved in folder or zarr that can be loaded. This do not load data, this only explores the directory.

get_sorting_provenance(): Get the original sorting if possible otherwise return None

has_extension(extension_name: str) → bool: Check if the extension exists in memory (dict) or in the folder or in zarr.

classmethod load(folder, recording=None, load_extensions=True, format='auto', backend_options=None): Load folder or zarr. The recording can be given if the recording location has changed. Otherwise the recording is loaded when possible.

load_all_saved_extension(): Load all saved extensions in memory.

load_extension(extension_name: str)

Load an extension from a folder or zarr into the ResultSorting.extensions dict.

Parameters:

extension_namestr: The extension name.

Returns:

ext_instance:: The loaded instance of the extension

merge_units(merge_unit_groups, new_unit_ids=None, censor_ms=None, merging_mode='soft', sparsity_overlap=0.75, new_id_strategy='append', return_new_unit_ids=False, format='memory', folder=None, verbose=False, **job_kwargs) → SortingAnalyzer

This method is equivalent to save_as() but with a list of merges that have to be achieved. Merges units by creating a new SortingAnalyzer object with the appropriate merges

Extensions are also updated to display the merged unit_ids.

Parameters:

merge_unit_groupslist/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_idsNone | list, default: None

A new unit_ids for merged units. If given, it needs to have the same length as merge_unit_groups. If None, merged units will have the first unit_id of every lists of merges

censor_msNone | float, default: None

When merging units, any spikes violating this refractory period will be discarded. If None all units are kept

merging_mode[“soft”, “hard”], default: “soft”

How merges are performed. If the merge_mode is “soft” , merges will be approximated, with no reloading of the waveforms. This will lead to approximations. If merge_mode is “hard”, recomputations are accurately performed, reloading waveforms if needed

sparsity_overlapfloat, default 0.75

The percentage of overlap that units should share in order to accept merges. If this criteria is not achieved, soft merging will not be possible and an error will be raised

new_id_strategy“append” | “take_first”, default: “append”

The strategy that should be used, if new_unit_ids is None, to create new unit_ids.

“append” : new_units_ids will be added at the end of max(sorting.unit_ids)

“take_first” : new_unit_ids will be the first unit_id of every list of merges

return_new_unit_idsbool, default False

Alse return new_unit_ids which are the ids of the new units.

folderPath | None, default: None

The new folder where the analyzer with merged units is copied for format “binary_folder” or “zarr”

format“memory” | “binary_folder” | “zarr”, default: “memory”

The format of SortingAnalyzer

verbosebool, default: False

Whether to display calculations (such as sparsity estimation)

Returns:

analyzerSortingAnalyzer: The newly create SortingAnalyzer with the selected units

remove_units(remove_unit_ids, format='memory', folder=None) → SortingAnalyzer

This method is equivalent to save_as() but with removal of a subset of units. Filters units by creating a new sorting analyzer object in a new folder.

Extensions are also updated to remove the unit ids.

Parameters:

remove_unit_idslist or array: The unit ids to remove in the new SortingAnalyzer object.
format“memory” | “binary_folder” | “zarr” , default: “memory”: The format of the returned SortingAnalyzer.
folderPath or None, default: None: The new folder where the analyzer without removed units is copied if format is “binary_folder” or “zarr”

Returns:

analyzerSortingAnalyzer: The newly create sorting_analyzer with the selected units

save_as(format='memory', folder=None, backend_options=None) → SortingAnalyzer

Save SortingAnalyzer object into another format. Uselful for memory to zarr or memory to binary.

Note that the recording provenance or sorting provenance can be lost.

Mainly propagates the copied sorting and recording properties.

Parameters:

folderstr | Path | None, default: None

The output folder if format is “zarr” or “binary_folder”

format“memory” | “binary_folder” | “zarr”, default: “memory”

The new backend format to use

backend_optionsdict | None, default: None

Keyword arguments for the backend specified by format. It can contain the:

storage_options: dict | None (fsspec storage options)

saving_options: dict | None (additional saving options for creating and saving datasets, e.g. compression/filters for zarr)

select_units(unit_ids, format='memory', folder=None) → SortingAnalyzer

This method is equivalent to save_as() but with a subset of units. Filters units by creating a new sorting analyzer 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 SortingAnalyzer object
format“memory” | “binary_folder” | “zarr” , default: “memory”: The format of the returned SortingAnalyzer.
folderPath | None, deafult: None: The new folder where the analyzer with selected units is copied if format is “binary_folder” or “zarr”

Returns:

analyzerSortingAnalyzer: The newly create sorting_analyzer with the selected units

Set property vector for unit ids.

If the SortingAnalyzer backend is in memory, the property will be only set in memory. If the SortingAnalyzer backend is binary_folder or zarr, the property will also be saved to to the backend.

Parameters:

keystr: The property name
valuesnp.array: Array of values for the property
idslist/np.array, default: None: List of subset of ids to set the values. if None all the ids are set or changed
missing_valueAny, default: None: In case the property is set on a subset of values (“ids” not None), This argument specifies how to fill missing values. The missing_value is required for types int and unsigned int.
savebool, default: True: If True, the property is saved to the backend if possible.

set_temporary_recording(recording: BaseRecording, check_dtype: bool = True)

Sets a temporary recording object. This function can be useful to temporarily set a “cached” recording object that is not saved in the SortingAnalyzer object to speed up computations. Upon reloading, the SortingAnalyzer object will try to reload the recording from the original location in a lazy way.

Parameters:

recordingBaseRecording: The recording object to set as temporary recording.
check_dtypebool, default: True: If True, check that the dtype of the temporary recording is the same as the original recording.

spikeinterface.core.create_sorting_analyzer(sorting, recording, format='memory', folder=None, sparse=True, sparsity=None, return_scaled=True, overwrite=False, backend_options=None, **sparsity_kwargs) → SortingAnalyzer

Create a SortingAnalyzer by pairing a Sorting and the corresponding Recording.

This object will handle a list of AnalyzerExtension for all the post processing steps like: waveforms, templates, unit locations, spike locations, quality metrics …

This object will be also use used for plotting purpose.

Parameters:

sortingSorting

The sorting object

recordingRecording

The recording object

folderstr or Path or None, default: None

The folder where analyzer is cached

format“memory | “binary_folder” | “zarr”, default: “memory”

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

sparsebool, default: True

If True, then a sparsity mask is computed using the estimate_sparsity() function using a few spikes to get an estimate of dense templates to create a ChannelSparsity object. Then, the sparsity will be propagated to all ResultExtention that handle sparsity (like wavforms, pca, …) You can control estimate_sparsity() : all extra arguments are propagated to it (included job_kwargs)

sparsityChannelSparsity or None, default: None

The sparsity used to compute exensions. If this is given, sparse is ignored.

return_scaledbool, default: True

All extensions that play with traces will use this global return_scaled : “waveforms”, “noise_levels”, “templates”. This prevent return_scaled being differents from different extensions and having wrong snr for instance.

overwrite: bool, default: False

If True, overwrite the folder if it already exists.

backend_optionsdict | None, default: None

Keyword arguments for the backend specified by format. It can contain the:

storage_options: dict | None (fsspec storage options)

saving_options: dict | None (additional saving options for creating and saving datasets, e.g. compression/filters for zarr)

sparsity_kwargskeyword arguments

Returns:

sorting_analyzerSortingAnalyzer: The SortingAnalyzer object

Notes

By default creating a SortingAnalyzer can be slow because the sparsity is estimated by default. In some situation, sparsity is not needed, so to make it fast creation, you need to turn sparsity off (or give external sparsity) like this.

Examples

>>> import spikeinterface as si

>>> # Create dense analyzer and save to disk with binary_folder format.
>>> sorting_analyzer = si.create_sorting_analyzer(sorting, recording, format="binary_folder", folder="/path/to_my/result")

>>> # Can be reload
>>> sorting_analyzer = si.load_sorting_analyzer(folder="/path/to_my/result")

>>> # Can run extension
>>> sorting_analyzer = si.compute("unit_locations", ...)

>>> # Can be copy to another format (extensions are propagated)
>>> sorting_analyzer2 = sorting_analyzer.save_as(format="memory")
>>> sorting_analyzer3 = sorting_analyzer.save_as(format="zarr", folder="/path/to_my/result.zarr")

>>> # Can make a copy with a subset of units (extensions are propagated for the unit subset)
>>> sorting_analyzer4 = sorting_analyzer.select_units(unit_ids=sorting.units_ids[:5], format="memory")
>>> sorting_analyzer5 = sorting_analyzer.select_units(unit_ids=sorting.units_ids[:5], format="binary_folder", folder="/result_5units")

spikeinterface.core.load_sorting_analyzer(folder, load_extensions=True, format='auto', backend_options=None) → SortingAnalyzer

Load a SortingAnalyzer object from disk.

Parameters:

folderstr or Path

The folder / zarr folder where the analyzer is stored. If the folder is a remote path stored in the cloud, the backend_options can be used to specify credentials. If the remote path is not accessible, and backend_options is not provided, the function will try to load the object in anonymous mode (anon=True), which enables to load data from open buckets.

load_extensionsbool, default: True

Load all extensions or not.

format“auto” | “binary_folder” | “zarr”

The format of the folder.

backend_optionsdict | None, default: None

The backend options for the backend. The dictionary can contain the following keys:

storage_options: dict | None (fsspec storage options)

saving_options: dict | None (additional saving options for creating and saving datasets)

Returns:

sorting_analyzerSortingAnalyzer: The loaded SortingAnalyzer

Compute channel sparsity from a SortingAnalyzer for each template with several methods.

Parameters:

templates_or_sorting_analyzerTemplates | SortingAnalyzer

A Templates or a SortingAnalyzer object. Some methods accept both objects (“best_channels”, “radius”, ) Other methods require only SortingAnalyzer because internally the recording is needed.

methodstr

“best_channels”N best channels with the largest amplitude. Use the “num_channels” argument to specify the
number of channels.
“closest_channels”N closest channels according to the distance. 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) and the “amplitude_mode” argument to specify the mode to compute the amplitude of the templates.
“amplitude”threshold based on the amplitude values on every channels. Use the “threshold” argument
to specify the ptp threshold (in units of amplitude) and the “amplitude_mode” argument to specify the mode to compute the amplitude of the templates.
“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 energy threshold (in units of noise levels)
“by_property”sparsity is given by a property of the recording and sorting (e.g. “group”).
In this case the sparsity for each unit is given by the channels that have the same property value as the unit. Use the “by_property” argument to specify the property name.
“ptp: : deprecated, use the ‘snr’ method with the ‘peak_to_peak’ amplitude mode instead.

peak_sign“neg” | “pos” | “both”

Sign of the template to compute best channels.

num_channelsint

Number of channels for “best_channels” method.

radius_umfloat

Radius in um for “radius” method.

thresholdfloat

Threshold for “snr”, “energy” (in units of noise levels) and “ptp” methods (in units of amplitude). For the “snr” method, the template amplitude mode is controlled by the “amplitude_mode” argument.

amplitude_mode“extremum” | “at_index” | “peak_to_peak”

Mode to compute the amplitude of the templates for the “snr”, “amplitude”, and “best_channels” methods.

by_propertyobject

Property name for “by_property” method.

Returns:

sparsityChannelSparsity: The estimated sparsity

Estimate the sparsity without needing a SortingAnalyzer or Templates object. In case the sparsity method needs templates, they are computed on-the-fly. For the “snr” method, noise_levels must passed with the noise_levels argument. These can be computed with the get_noise_levels() function.

Contrary to the previous implementation:

all units are computed in one read of recording
it doesn’t require a folder
it doesn’t consume too much memory
it uses internally the estimate_templates_with_accumulator() which is fast and parallel

Note that the “energy” method is not supported because it requires a SortingAnalyzer object.

Parameters:

sortingBaseSorting

The sorting

recordingBaseRecording

The recording

num_spikes_for_sparsityint, default: 100

How many spikes per units to compute the sparsity

ms_beforefloat, default: 1.0

Cut out in ms before spike time

ms_afterfloat, default: 2.5

Cut out in ms after spike time

noise_levelsnp.array | None, default: None

Noise levels required for the “snr” and “energy” methods. You can use the get_noise_levels() function to compute them.

**job_kwargskeyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_sizeint
  Number of samples per chunk
- chunk_memorystr
  Memory usage for each job (e.g. “100M”, “1G”, “500MiB”, “2GiB”)
- total_memorystr
  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_jobsint | float
Number of jobs to use. With -1 the number of jobs is the same as number of cores. Using a float between 0 and 1 will use that fraction of the total cores.
progress_barbool
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:

sparsityChannelSparsity: 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:

masknp.array of bool: The sparsity mask (num_units, num_channels)
unit_idslist or array: Unit ids vector or list
channel_idslist or array: Channel ids vector or list

Examples

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

Using the N best channels (largest template amplitude):

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

Using a neighborhood by radius:

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

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

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

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

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

classmethod create_dense(sorting_analyzer)

Create a sparsity object with all selected channel for all units.

Parameters:

sorting_analyzerSortingAnalyzer: A SortingAnalyzer object.

Returns:

sparsityChannelSparsity: The full sparsity.

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_amplitude(templates_or_sorting_analyzer, threshold, amplitude_mode='extremum', peak_sign='neg')

Construct sparsity from a threshold based on template amplitude. The amplitude is computed with the specified amplitude mode and it is assumed that the amplitude is in uV. The input Templates or SortingAnalyzer object must have scaled templates.

Parameters:

templates_or_sorting_analyzerTemplates | SortingAnalyzer: A Templates or a SortingAnalyzer object.
thresholdfloat: Threshold for “amplitude” method (in uV).
amplitude_mode“extremum” | “at_index” | “peak_to_peak”, default: “extremum”: Mode to compute the amplitude of the templates.

Returns:

sparsityChannelSparsity: The estimated sparsity.

classmethod from_best_channels(templates_or_sorting_analyzer, num_channels, peak_sign='neg', amplitude_mode='extremum')

Construct sparsity from N best channels with the largest amplitude. Use the “num_channels” argument to specify the number of channels.

Parameters:

templates_or_sorting_analyzerTemplates | SortingAnalyzer: A Templates or a SortingAnalyzer object.
num_channelsint: Number of channels for “best_channels” method.
peak_sign“neg” | “pos” | “both”: Sign of the template to compute best channels.
amplitude_mode“extremum” | “at_index” | “peak_to_peak”, default: “extremum”: Mode to compute the amplitude of the templates.

Returns:

sparsityChannelSparsity: The estimated sparsity

classmethod from_closest_channels(templates_or_sorting_analyzer, num_channels)

Construct sparsity from N closest channels Use the “num_channels” argument to specify the number of channels.

Parameters:

templates_or_sorting_analyzerTemplates | SortingAnalyzer: A Templates or a SortingAnalyzer object.
num_channelsint: Number of channels for “best_channels” method.

Returns:

sparsityChannelSparsity: The estimated sparsity

classmethod from_energy(sorting_analyzer, threshold)

Construct sparsity from a threshold based on per channel energy ratio. Use the “threshold” argument to specify the SNR threshold. This method requires the “waveforms” and “noise_levels” extensions to be computed.

Parameters:

sorting_analyzerSortingAnalyzer: A SortingAnalyzer object.
thresholdfloat: Threshold for “energy” method (in units of noise levels).

Returns:

sparsityChannelSparsity: The estimated sparsity.

classmethod from_property(sorting, recording, by_property)

Construct sparsity witha property of the recording and sorting(e.g. “group”). Use the “by_property” argument to specify the property name.

Parameters:

sortingSorting: A Sorting object.
recordingRecording: A Recording object.
by_propertyobject: Property name for “by_property” method. Both the recording and sorting must have this property set.

Returns:

sparsityChannelSparsity: The estimated sparsity.

classmethod from_ptp(templates_or_sorting_analyzer, threshold, noise_levels=None)

Construct sparsity from a thresholds based on template peak-to-peak values. Use the “threshold” argument to specify the peak-to-peak threshold.

Parameters:

templates_or_sorting_analyzerTemplates | SortingAnalyzer: A Templates or a SortingAnalyzer object.
thresholdfloat: Threshold for “ptp” method (in units of amplitude).

Returns:

sparsityChannelSparsity: The estimated sparsity.

classmethod from_radius(templates_or_sorting_analyzer, 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.

Parameters:

templates_or_sorting_analyzerTemplates | SortingAnalyzer: A Templates or a SortingAnalyzer object.
radius_umfloat: Radius in um for “radius” method.
peak_sign“neg” | “pos” | “both”: Sign of the template to compute best channels.

Returns:

sparsityChannelSparsity: The estimated sparsity.

classmethod from_snr(templates_or_sorting_analyzer, threshold, amplitude_mode='extremum', peak_sign='neg', noise_levels=None)

Construct sparsity from a thresholds based on template signal-to-noise ratio. Use the “threshold” argument to specify the SNR threshold.

Parameters:

templates_or_sorting_analyzerTemplates | SortingAnalyzer: A Templates or a SortingAnalyzer object.
thresholdfloat: Threshold for “snr” method (in units of noise levels).
noise_levelsnp.array | None, default: None: Noise levels required for the “snr” method. You can use the get_noise_levels() function to compute them. If the input is a SortingAnalyzer, the noise levels are automatically retrieved if the noise_levels extension is present.
peak_sign“neg” | “pos” | “both”: Sign of the template to compute amplitudes.
amplitude_mode“extremum” | “at_index” | “peak_to_peak”, default: “extremum”: Mode to compute the amplitude of the templates for the “snr” method.

Returns:

sparsityChannelSparsity: The estimated sparsity.

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.Motion(displacement, temporal_bins_s, spatial_bins_um, direction='y', interpolation_method='linear')

Motion of the tissue relative the probe.

Parameters:

displacementnumpy array 2d or list of

Motion estimate in um. List is the number of segment. For each semgent :

shape (temporal bins, spatial bins)

motion.shape[0] = temporal_bins.shape[0]

motion.shape[1] = 1 (rigid) or spatial_bins.shape[1] (non rigid)

temporal_bins_snumpy.array 1d or list of

temporal bins (bin center)

spatial_bins_umnumpy.array 1d

Windows center. spatial_bins_um.shape[0] == displacement.shape[1] If rigid then spatial_bins_um.shape[0] == 1

directionstr, default: ‘y’

Direction of the motion.

interpolation_methodstr

How to determine the displacement between bin centers? See the docs for scipy.interpolate.RegularGridInterpolator for options.

get_displacement_at_time_and_depth(times_s, locations_um, segment_index=None, grid=False)

Evaluate the motion estimate at times and positions

Evaluate the motion estimate, returning the (linearly interpolated) estimated displacement at the given times and locations.

Parameters:

times_s: np.array
locations_um: np.array: Either this is a one-dimensional array (a vector of positions along self.dimension), or else a 2d array with the 2 or 3 spatial dimensions indexed along axis=1.
segment_index: int, default: None: The index of the segment to evaluate. If None, and there is only one segment, then that segment is used.
gridbool, default: False: If grid=False, the default, then times_s and locations_um should have the same one-dimensional shape, and the returned displacement[i] is the displacement at time times_s[i] and location locations_um[i]. If grid=True, times_s and locations_um determine a grid of positions to evaluate the displacement. Then the returned displacement[i,j] is the displacement at depth locations_um[i] and time times_s[j].

Returns:

displacementnp.array: A displacement per input location, of shape times_s.shape if grid=False and (locations_um.size, times_s.size) if grid=True.

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

RecordingExtractor for a binary format

Parameters:

file_pathsstr or Path or list: Path to the binary file
sampling_frequencyfloat: The sampling frequency
num_channelsint: Number of channels
dtypestr or dtype: The dtype of the binary file
time_axisint, default: 0: The axis of the time dimension
t_startsNone or list of float, default: None: Times in seconds of the first sample for each segment
channel_idslist, default: None: A list of channel ids
file_offsetint, default: 0: Number of bytes in the file to offset by during memmap instantiation.
gain_to_uVfloat or array-like, default: None: The gain to apply to the traces
offset_to_uVfloat or array-like, default: None: The offset to apply to the traces
is_filteredbool or None, default: None: If True, the recording is assumed to be filtered. If None, is_filtered is not set.

Returns:

recordingBinaryRecordingExtractor: 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: Path | str, storage_options: dict | None = None)

RecordingExtractor for a zarr format

Parameters:

folder_pathstr or Path: Path to the zarr root folder. This can be a local path or a remote path (s3:// or gcs://). If the path is a remote path, the storage_options can be provided to specify credentials. If the remote path is not accessible and backend_options is not provided, the function will try to load the object in anonymous mode (anon=True), which enables to load data from open buckets.
storage_optionsdict or None: Storage options for zarr store. E.g., if “s3://” or “gcs://” they can provide authentication methods, etc.

Returns:

recordingZarrRecordingExtractor: 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_pathstr or Path

Returns:

recordingBinaryFolderRecording: 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_pathstr or Path

Returns:

sortingNpzFolderSorting: 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_pathstr or Path: The path to the folder

Returns:

snippetsNpyFolderSnippets: 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_listlist of array or array (if mono segment): The traces to instantiate a mono or multisegment Recording
sampling_frequencyfloat: The sampling frequency in Hz
t_startsNone or list of float: Times in seconds of the first sample for each segment
channel_idslist: 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 samples+labels: NumpySorting.from_samples_and_labels()
from times+labels: NumpySorting.from_times_and_labels()
from dict of list: NumpySorting.from_unit_dict()
from neo: NumpySorting.from_neo_spiketrain_list()

Parameters:

spikesnumpy.array: A numpy vector, the one given by Sorting.to_spike_vector().
sampling_frequencyfloat: The sampling frequency in Hz
channel_idslist: 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_listlist of array or array (if mono segment): The snippets to instantiate a mono or multisegment basesnippet
spikesframes_listlist of array or array (if mono segment): Frame of each snippet
sampling_frequencyfloat: The sampling frequency in Hz
channel_idslist: 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: Path | None = None, update_if_exists: bool = False) → Path

Function to download dataset from a remote repository using a combination of datalad and pooch.

Pooch is designed to download single files from a remote repository. Because our datasets in gin sometimes point just to a folder, we still use datalad to download a list of all the files in the folder and then use pooch to download them one by one.

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, optional: The destination folder / directory to download the dataset to. if None, then the path “get_global_dataset_folder()” / f{repo_name} is used (see spikeinterface.core.globals)
update_if_existsbool, default: False: Forces re-download of the dataset if it already exists, default: False

Returns:

Path: The local path to the downloaded dataset

Notes

The reason we use pooch is because have had problems with datalad not being able to download data on windows machines. Especially in the CI.

See https://handbook.datalad.org/en/latest/intro/windows.html

spikeinterface.core.write_binary_recording(recording: BaseRecording, file_paths: list[Path | str] | Path | str, dtype: np.typing.DTypeLike = None, add_file_extension: bool = True, byte_offset: int = 0, auto_cast_uint: bool = True, verbose: bool = False, **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:

recordingRecordingExtractor

The recording extractor object to be saved in .dat format

file_pathstr or list[str]

The path to the file.

dtypedtype or None, default: None

Type of the saved data

add_file_extension, bool, default: True

If True, and the file path does not end in “raw”, “bin”, or “dat” then “raw” is added as an extension.

byte_offsetint, default: 0

Offset in bytes for the binary file (e.g. to write a header). This is useful in case you want to append data to an existing file where you wrote a header or other data before.

auto_cast_uintbool, default: True

If True, unsigned integers are automatically cast to int if the specified dtype is signed .. deprecated:: 0.103, use the unsigned_to_signed function instead.

verbosebool

This is the verbosity of the ChunkRecordingExecutor

**job_kwargskeyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_sizeint
  Number of samples per chunk
- chunk_memorystr
  Memory usage for each job (e.g. “100M”, “1G”, “500MiB”, “2GiB”)
- total_memorystr
  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_jobsint | float
Number of jobs to use. With -1 the number of jobs is the same as number of cores. Using a float between 0 and 1 will use that fraction of the total cores.
progress_barbool
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_kwargskeyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_sizeint
  Number of samples per chunk
- chunk_memorystr
  Memory usage for each job (e.g. “100M”, “1G”, “500MiB”, “2GiB”)
- total_memorystr
  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_jobsint | float
Number of jobs to use. With -1 the number of jobs is the same as number of cores. Using a float between 0 and 1 will use that fraction of the total cores.
progress_barbool
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, concatenated=True, **random_slices_kwargs)

Extract random chunks across segments.

Internally, it uses get_random_recording_slices() and retrieves the traces chunk as a list or a concatenated unique array.

Please read get_random_recording_slices() for more details on parameters.

Parameters:

recordingBaseRecording: The recording to get random chunks from
return_scaledbool, default: False: If True, returned chunks are scaled to uV
num_chunks_per_segmentint, default: 20: Number of chunks per segment
concatenatedbool, default: True: If True chunk are concatenated along time axis
**random_slices_kwargsdict: Options transmited to get_random_recording_slices(), please read documentation from this function for more details.

Returns:

chunk_listnp.array | list of 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:

recordingRecordingExtractor: The recording extractor to get closest channels
channel_idslist: List of channels ids to compute there near neighborhood
num_channelsint, 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
distsarray (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_slices_kwargs: dict = {}, **kwargs) → np.ndarray

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 uses the MAD estimator (more robust than STD) or the STD on each chunk. Finally the average of all MAD/STD values is performed.

The result is cached in a property of the recording, so that the next call on the same recording will use the cached result unless force_recompute=True.

Parameters:

recordingBaseRecording

The recording extractor to get noise levels

return_scaledbool

If True, returned noise levels are scaled to uV

method“mad” | “std”, default: “mad”

The method to use to estimate noise levels

force_recomputebool

If True, noise levels are recomputed even if they are already stored in the recording extractor

random_slices_kwargsdict

Options transmited to get_random_recording_slices(), please read documentation from this function for more details.

**job_kwargskeyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_sizeint
  Number of samples per chunk
- chunk_memorystr
  Memory usage for each job (e.g. “100M”, “1G”, “500MiB”, “2GiB”)
- total_memorystr
  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_jobsint | float
Number of jobs to use. With -1 the number of jobs is the same as number of cores. Using a float between 0 and 1 will use that fraction of the total cores.
progress_barbool
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:

noise_levelsarray: 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
flipbool, 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_sorting_analyzer, peak_sign: neg' | 'pos' | 'both = 'neg', mode: extremum' | 'at_index' | 'peak_to_peak = 'extremum', return_scaled: bool = True, abs_value: bool = True)

Get amplitude per channel for each unit.

Parameters:

templates_or_sorting_analyzerTemplates | SortingAnalyzer: A Templates or a SortingAnalyzer object
peak_sign“neg” | “pos” | “both”: Sign of the template to find extremum channels
mode“extremum” | “at_index” | “peak_to_peak”, default: “at_index”: Where the amplitude is computed * “extremum” : take the peak value (max or min depending on peak_sign) * “at_index” : take value at nbefore index * “peak_to_peak” : take the peak-to-peak amplitude
return_scaledbool, default True: The amplitude is scaled or not.
abs_valuebool = True: Whether the extremum amplitude should be returned as an absolute value or not

Returns:

peak_valuesdict: Dictionary with unit ids as keys and template amplitudes as values

Compute the channel with the extremum peak for each unit.

Parameters:

templates_or_sorting_analyzerTemplates | SortingAnalyzer

A Templates or a SortingAnalyzer object

peak_sign“neg” | “pos” | “both”

Sign of the template to find extremum channels

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

Where the amplitude is computed * “extremum” : take the peak value (max or min depending on peak_sign) * “at_index” : take value at nbefore index * “peak_to_peak” : take the peak-to-peak amplitude

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

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

Returns:

extremum_channelsdict: 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_sorting_analyzer, 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_sorting_analyzerTemplates | SortingAnalyzer: A Templates or a SortingAnalyzer object
peak_sign“neg” | “pos” | “both”: Sign of the template to find extremum channels

Returns:

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

spikeinterface.core.get_template_extremum_amplitude(templates_or_sorting_analyzer, peak_sign: neg' | 'pos' | 'both = 'neg', mode: extremum' | 'at_index' | 'peak_to_peak = 'at_index', abs_value: bool = True)

Computes amplitudes on the best channel.

Parameters:

templates_or_sorting_analyzerTemplates | SortingAnalyzer: A Templates or a SortingAnalyzer object
peak_sign“neg” | “pos” | “both”: Sign of the template to find extremum channels
mode“extremum” | “at_index” | “peak_to_peak”, default: “at_index”: Where the amplitude is computed * “extremum”: take the peak value (max or min depending on peak_sign) * “at_index”: take value at nbefore index * “peak_to_peak”: take the peak-to-peak amplitude
abs_valuebool = True: Whether the extremum amplitude should be returned as an absolute value or not

Returns:

amplitudesdict: 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: int, t_starts=None, channel_ids=None, time_axis=0, file_offset=0, gain_to_uV=None, offset_to_uV=None, is_filtered=None)

RecordingExtractor for a binary format

Parameters:

file_pathsstr or Path or list: Path to the binary file
sampling_frequencyfloat: The sampling frequency
num_channelsint: Number of channels
dtypestr or dtype: The dtype of the binary file
time_axisint, default: 0: The axis of the time dimension
t_startsNone or list of float, default: None: Times in seconds of the first sample for each segment
channel_idslist, default: None: A list of channel ids
file_offsetint, default: 0: Number of bytes in the file to offset by during memmap instantiation.
gain_to_uVfloat or array-like, default: None: The gain to apply to the traces
offset_to_uVfloat or array-like, default: None: The offset to apply to the traces
is_filteredbool or None, default: None: If True, the recording is assumed to be filtered. If None, is_filtered is not set.

Returns:

recordingBinaryRecordingExtractor: 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 | Path, storage_options: dict | None = None) → ZarrRecordingExtractor | ZarrSortingExtractor

Read recording or sorting from a zarr format

Parameters:

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

Returns:

extractorZarrExtractor: The loaded extractor

spikeinterface.core.apply_merges_to_sorting(sorting, merge_unit_groups, new_unit_ids=None, censor_ms=None, return_extra=False, new_id_strategy='append')

Apply a resolved representation of the merges to a sorting object.

This function is not lazy and creates a new NumpySorting with a compact spike_vector as fast as possible.

If censor_ms is not None, duplicated spikes violating the censor_ms refractory period are removed.

Optionally, the boolean mask of kept spikes is returned.

Parameters:

sortingSorting

The Sorting object to apply merges.

merge_unit_groupslist/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_idslist | None, default: None

A new unit_ids for merged units. If given, it needs to have the same length as merge_unit_groups. If None, merged units will have the first unit_id of every lists of merges.

censor_ms: float | None, default: None

When applying the merges, should be discard consecutive spikes violating a given refractory per

return_extrabool, default: False

If True, also return also a boolean mask of kept spikes and new_unit_ids.

new_id_strategy“append” | “take_first”, default: “append”

The strategy that should be used, if new_unit_ids is None, to create new unit_ids.

“append” : new_units_ids will be added at the end of max(sorging.unit_ids)

“take_first” : new_unit_ids will be the first unit_id of every list of merges

Returns:

sortingThe new Sorting object: The newly create sorting with the merged units
keep_masknumpy.array: A boolean mask, if censor_ms is not None, telling which spike from the original spike vector has been kept, given the refractory period violations (None if censor_ms is None)

spikeinterface.core.spike_vector_to_spike_trains(spike_vector: list[array], unit_ids: array) → dict[dict[str, array]]

Computes all spike trains for all units/segments from a spike vector list.

Internally calls numba if numba is installed.

Parameters:

spike_vector: list[np.ndarray]: List of spike vectors optained with sorting.to_spike_vector(concatenated=False)
unit_ids: np.array: Unit ids

Returns:

spike_trains: dict[dict]:: A dict containing, for each segment, the spike trains of all units (as a dict: unit_id –> spike_train).

spikeinterface.core.random_spikes_selection(sorting: BaseSorting, num_samples: int | None = None, method: str = 'uniform', max_spikes_per_unit: int = 500, margin_size: int | None = None, seed: int | None = None)

This replaces select_random_spikes_uniformly(). Random spikes selection of spike across per units. Can optionally avoid spikes on segment borders if margin_size is not None.

Parameters:

sorting: BaseSorting: The sorting object
num_samples: list of int: The number of samples per segment. Can be retrieved from recording with num_samples = [recording.get_num_samples(seg_index) for seg_index in range(recording.get_num_segments())]
method: “uniform” | “all”, default: “uniform”: The method to use. Only “uniform” is implemented for now
max_spikes_per_unit: int, default: 500: The number of spikes per units
margin_size: None | int, default: None: A margin on each border of segments to avoid border spikes
seed: None | int, default: None: A seed for random generator

Returns:

random_spikes_indices: np.array: Selected spike indices coresponding to the sorting spike vector.

Low-level

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

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.waveform_tools).

Parameters:

recordingRecordingExtractor: The recording to be processed
funcfunction: Function that runs on each chunk
init_funcfunction: Initializer function to set the global context (accessible by “func”)
init_argstuple: Arguments for init_func
verbosebool: If True, output is verbose
job_namestr, default: “”: Job name
progress_barbool, default: False: If True, a progress bar is printed to monitor the progress of the process
handle_returnsbool, default: False: If True, the function can return values
gather_funcNone 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.
pool_engine“process” | “thread”, default: “thread”: If n_jobs>1 then use ProcessPoolExecutor or ThreadPoolExecutor
n_jobsint, default: 1: Number of jobs to be used. Use -1 to use as many jobs as number of cores
total_memorystr, default: None: Total memory (RAM) to use (e.g. “1G”, “500M”)
chunk_memorystr, default: None: Memory per chunk (RAM) to use (e.g. “1G”, “500M”)
chunk_sizeint 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_workerint 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.
need_worker_indexbool, default False: If True then each worker will also have a “worker_index” injected in the local worker dict.

Returns:

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

Back-compatibility with `WaveformExtractor` (version < 0.101.0)

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=None, return_scaled=True, dtype=None, sparse=True, sparsity=None, sparsity_temp_folder=None, num_spikes_for_sparsity=100, unit_batch_size=None, allow_unfiltered=None, use_relative_path=None, seed=None, load_if_exists=None, **kwargs)

This mock the extract_waveforms() in version <= 0.100 to not break old codes but using the SortingAnalyzer (version >0.100) internally.

This return a MockWaveformExtractor object that mock the old WaveformExtractor

spikeinterface.core.load_waveforms(folder, with_recording: bool = True, sorting: BaseSorting | None = None, output='MockWaveformExtractor') → MockWaveformExtractor | SortingAnalyzer

This read an old WaveformsExtactor folder (folder or zarr) and convert it into a SortingAnalyzer or MockWaveformExtractor.

It also mimic the old load_waveforms by opening a Sortingresult folder and return a MockWaveformExtractor. This later behavior is usefull to no break old code like this in versio >=0.101

>>> # In this example we is a MockWaveformExtractor that behave the same as before
>>> we = extract_waveforms(..., folder="/my_we")
>>> we = load_waveforms("/my_we")
>>> templates = we.get_all_templates()

Parameters:

folder: str | Path: The folder to the waveform extractor (binary or zarr)
with_recording: bool: For back-compatibility, ignored
sorting: BaseSorting | None, default: None: The sorting object to instantiate with the Waveforms
output: “MockWaveformExtractor” | “SortingAnalyzer”, default: “MockWaveformExtractor”: The output format

Returns:

waveforms_or_analyzer: MockWaveformExtractor | SortingAnalyzer: The returned MockWaveformExtractor or SortingAnalyzer

spikeinterface.core.load_sorting_analyzer_or_waveforms(folder, sorting=None)

Load a SortingAnalyzer from either a newly saved SortingAnalyzer folder or an old WaveformExtractor folder.

Parameters:

folder: str | Path: The folder to the sorting analyzer or waveform extractor
sorting: BaseSorting | None, default: None: The sorting object to instantiate with the SortingAnalyzer (only used for old WaveformExtractor)

Returns:

sorting_analyzer: SortingAnalyzer: The returned SortingAnalyzer.

spikeinterface.extractors

NEO-based

spikeinterface.extractors.read_alphaomega(folder_path, lsx_files=None, stream_id='RAW', stream_name=None, all_annotations: bool = False, use_names_as_ids: bool = False)

Class for reading from AlphaRS and AlphaLab SnR boards.

Based on neo.rawio.AlphaOmegaRawIO

Parameters:

folder_pathstr or Path-like: The folder path to the AlphaOmega recordings.
lsx_fileslist of strings or None, default: None: A list of 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_namestr, default: None: If there are several streams, specify the stream name you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

Examples

>>> from spikeinterface.extractors import read_alphaomega
>>> recording = read_alphaomega(folder_path="alphaomega_folder")

spikeinterface.extractors.read_alphaomega_event(folder_path)

Class for reading events from AlphaOmega MPX file format

Parameters:

folder_pathstr or Path-like: The folder path to the AlphaOmega events.

spikeinterface.extractors.read_axona(file_path: str | Path, all_annotations: bool = False, use_names_as_ids: bool = False)

Class for reading Axona RAW format.

Based on neo.rawio.AxonaRawIO

Parameters:

file_pathstr: The file path to load the recordings from.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

Examples

>>> from spikeinterface.extractors import read_axona
>>> recording = read_axona(file_path=r'my_data.set')

spikeinterface.extractors.read_biocam(file_path, mea_pitch=None, electrode_width=None, fill_gaps_strategy=None, stream_id=None, stream_name=None, all_annotations: bool = False, use_names_as_ids: bool = False)

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

Based on neo.rawio.BiocamRawIO

Parameters:

file_pathstr

The file path to load the recordings from.

mea_pitchfloat, default: None

The inter-electrode distance (pitch) between electrodes.

electrode_widthfloat, default: None

Width of the electrodes in um.

fill_gaps_strategy: “zeros” | “synthetic_noise” | None, default: None

The strategy to fill the gaps in the data when using event-based compression. If None and the file is event-based compressed, you need to specify a fill gaps strategy:

“zeros”: the gaps are filled with unsigned 0s (2048). This value is the “0” of the unsigned 12 bits
representation of the data.
“synthetic_noise”: the gaps are filled with synthetic noise.

stream_idstr, default: None

If there are several streams, specify the stream id you want to load.

stream_namestr, default: None

If there are several streams, specify the stream name you want to load.

all_annotationsbool, default: False

Load exhaustively all annotations from neo.

use_names_as_idsbool, default: False

Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

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

RecordingExtractor for a binary format

Parameters:

file_pathsstr or Path or list: Path to the binary file
sampling_frequencyfloat: The sampling frequency
num_channelsint: Number of channels
dtypestr or dtype: The dtype of the binary file
time_axisint, default: 0: The axis of the time dimension
t_startsNone or list of float, default: None: Times in seconds of the first sample for each segment
channel_idslist, default: None: A list of channel ids
file_offsetint, default: 0: Number of bytes in the file to offset by during memmap instantiation.
gain_to_uVfloat or array-like, default: None: The gain to apply to the traces
offset_to_uVfloat or array-like, default: None: The offset to apply to the traces
is_filteredbool or None, default: None: If True, the recording is assumed to be filtered. If None, is_filtered is not set.

Returns:

recordingBinaryRecordingExtractor: 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, all_annotations: bool = False, use_names_as_ids: bool = False)

Class for reading BlackRock data.

Based on neo.rawio.BlackrockRawIO

Parameters:

file_pathstr: The file path to load the recordings from.
stream_idstr, default: None: If there are several streams, specify the stream id you want to load.
stream_namestr, default: None: If there are several streams, specify the stream name you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

spikeinterface.extractors.read_ced(file_path, stream_id=None, stream_name=None, all_annotations: bool = False, use_names_as_ids: bool = 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_pathstr: The file path to the smr or smrx file.
stream_idstr, default: None: If there are several streams, specify the stream id you want to load.
stream_namestr, default: None: If there are several streams, specify the stream name you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

Examples

>>> from spikeinterface.extractors import read_ced
>>> recording = read_ced(file_path=r'my_data.smr')

spikeinterface.extractors.read_intan(file_path, stream_id=None, stream_name=None, all_annotations=False, use_names_as_ids=False, ignore_integrity_checks: bool = False)

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

Based on neo.rawio.IntanRawIO

Parameters:

file_pathstr

The file path to load the recordings from.

stream_idstr, default: None

If there are several streams, specify the stream id you want to load.

stream_namestr, default: None

If there are several streams, specify the stream name you want to load.

all_annotationsbool, default: False

Load exhaustively all annotations from neo.

ignore_integrity_checksbool, default: False.

If True, data that violates integrity assumptions will be loaded. At the moment the only integrity check we perform is that timestamps are continuous. Setting this to True will ignore this check and set the attribute discontinuous_timestamps to True in the underlying neo object.

use_names_as_idsbool, default: False

Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

In Intan the ids provided by NeoRawIO are the hardware channel ids while the names are custom names given by the user

Examples

>>> from spikeinterface.extractors import read_intan
# intan amplifier data is stored in stream_id = '0'
>>> recording = read_intan(file_path=r'my_data.rhd', stream_id='0')
# intan has multi-file formats as well, but in this case our path should point to the header file 'info.rhd'
>>> recording = read_intan(file_path=r'info.rhd', stream_id='0')

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, use_names_as_ids: bool = False)

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

Based on neo.rawio.MaxwellRawIO

Parameters:

file_pathstr: The file path to the maxwell h5 file.
stream_idstr, 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_namestr, default: None: If there are several streams, specify the stream name you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.
rec_namestr, default: None: When the file contains several recordings you need to specify the one you want to extract. (rec_name=’rec0000’).
install_maxwell_pluginbool, default: False: If True, install the maxwell plugin for neo.
block_indexint, default: None: If there are several blocks (experiments), specify the block index you want to load

spikeinterface.extractors.read_mearec(file_path)

Read a MEArec file.

Parameters:

file_pathstr or Path: Path to MEArec h5 file

Returns:

recordingMEArecRecordingExtractor: The recording extractor object
sortingMEArecSortingExtractor: The sorting extractor object

spikeinterface.extractors.read_mcsraw(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False, use_names_as_ids: bool = 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_pathstr: The file path to load the recordings from.
stream_idstr, default: None: If there are several streams, specify the stream id you want to load.
stream_namestr, default: None: If there are several streams, specify the stream name you want to load.
block_indexint, default: None: If there are several blocks, specify the block index you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

spikeinterface.extractors.read_neuralynx(folder_path: str | Path, stream_id=None, stream_name=None, all_annotations=False, exclude_filename=None, strict_gap_mode=False, use_names_as_ids: bool = False)

Class for reading neuralynx folder

Based on neo.rawio.NeuralynxRawIO

Parameters:

folder_pathstr

The file path to load the recordings from.

stream_idstr, default: None

If there are several streams, specify the stream id you want to load.

stream_namestr, default: None

If there are several streams, specify the stream name you want to load.

all_annotationsbool, default: False

Load exhaustively all annotations from neo.

exclude_filenamelist[str], default: None

List of filename to exclude from the loading. For example, use exclude_filename=[“events.nev”] to skip loading the event file.

use_names_as_idsbool, default: False

Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

strict_gap_modebool, default: False

See neo documentation. Detect gaps using strict mode or not. * strict_gap_mode = True then a gap is consider when timstamp difference between two consecutive data packets is more than one sample interval. * strict_gap_mode = False then a gap has an increased tolerance. Some new systems with different clocks need this option otherwise, too many gaps are detected

Note that here the default is False contrary to neo.

spikeinterface.extractors.read_neuralynx_sorting(folder_path: str, sampling_frequency: float | None = None, stream_id: str | None = None, stream_name: str | None = 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_pathstr: The file path to load the recordings from.
sampling_frequencyfloat: 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_idstr, default: None: Used to extract information about the sampling frequency and t_start from the analog signal if provided.
stream_namestr, 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: bool = False, use_names_as_ids: bool = 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_pathstr: The file path to load the recordings from.
stream_idstr, 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_namestr, default: None: If there are several streams, specify the stream name you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

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_pathstr: The xml file.
stream_idstr or None: The stream id to load. If None, the first stream is loaded
keep_mua_unitsbool, default: False: Optional. Whether or not to return sorted spikes from multi-unit activity
exclude_shankslist: 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_recordingbool, default: True: If True, the recording is loaded
load_sortingbool, 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: bool = False, use_names_as_ids: bool = False)

Class for reading Nix file

Based on neo.rawio.NIXRawIO

Parameters:

file_pathstr: The file path to load the recordings from.
stream_idstr, default: None: If there are several streams, specify the stream id you want to load.
stream_namestr, default: None: If there are several streams, specify the stream name you want to load.
block_indexint, default: None: If there are several blocks, specify the block index you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

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

Read “legacy” or “binary” Open Ephys formats

Parameters:

folder_pathstr or Path: Path to openephys folder
stream_idstr, default: None: If there are several streams, specify the stream id you want to load
stream_namestr, default: None: If there are several streams, specify the stream name you want to load
block_indexint, default: None: If there are several blocks (experiments), specify the block index you want to load
all_annotationsbool, 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_namesstr, 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_errorsbool, default: False: Ignore the discontinuous timestamps errors in neo For open ephsy legacy format only

Returns:

recordingOpenEphysLegacyRecordingExtractor or OpenEphysBinaryExtractor

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

Read Open Ephys events from “binary” format.

Parameters:

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

Returns:

eventOpenEphysBinaryEventExtractor

spikeinterface.extractors.read_plexon(file_path: str | Path, stream_id=None, stream_name=None, all_annotations: bool = False, use_names_as_ids: bool = True)

Class for reading plexon plx files.

Based on neo.rawio.PlexonRawIO

Parameters:

file_pathstr | Path

The file path to load the recordings from.

stream_idstr, default: None

If there are several streams, specify the stream id you want to load.

stream_namestr, default: None

If there are several streams, specify the stream name you want to load.

all_annotationsbool, default: False

Load exhaustively all annotations from neo.

use_names_as_idsbool, default: True

Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

Example for wideband signals:: names: [“WB01”, “WB02”, “WB03”, “WB04”] ids: [“0” , “1”, “2”, “3”]

Examples

>>> from spikeinterface.extractors import read_plexon
>>> recording = read_plexon(file_path=r'my_data.plx')

spikeinterface.extractors.read_plexon_sorting(file_path)

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

Based on neo.rawio.PlexonRawIO

Parameters:

file_pathstr: The file path to load the recordings from.

spikeinterface.extractors.read_plexon2(file_path, stream_id=None, stream_name=None, use_names_as_ids=True, all_annotations=False, reading_attempts: int = 25)

Class for reading plexon pl2 files.

Based on neo.rawio.Plexon2RawIO

Parameters:

file_pathstr | Path

The file path of the plexon2 file. It should have the .pl2 extension.

stream_idstr, default: None

If there are several streams, specify the stream id you want to load.

stream_namestr, default: None

If there are several streams, specify the stream name you want to load.

use_names_as_idsbool, default: True

If True, the names of the signals are used as channel ids. If False, the channel ids are a combination of the source id and the channel index.

Example for wideband signals:: names: [“WB01”, “WB02”, “WB03”, “WB04”] ids: [“source3.1” , “source3.2”, “source3.3”, “source3.4”]

all_annotationsbool, default: False

Load exhaustively all annotations from neo.

reading_attemptsint, default: 25

Number of attempts to read the file before raising an error This opening process is somewhat unreliable and might fail occasionally. Adjust this higher if you encounter problems in opening the file.

Examples

>>> from spikeinterface.extractors import read_plexon2
>>> recording = read_plexon2(file_path=r'my_data.pl2')

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_pathstr: The file path to load the recordings from.
sampling_frequencyfloat, 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, use_names_as_ids: bool = False)

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

Based on neo.rawio.Spike2RawIO

Parameters:

file_pathstr: The file path to load the recordings from.
stream_idstr, default: None: If there are several streams, specify the stream id you want to load.
stream_namestr, default: None: If there are several streams, specify the stream name you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

spikeinterface.extractors.read_spikegadgets(file_path, stream_id=None, stream_name=None, all_annotations: bool = False, use_names_as_ids: bool = False)

Class for reading rec files from spikegadgets.

Based on neo.rawio.SpikeGadgetsRawIO

Parameters:

file_pathstr: The file path to load the recordings from.
stream_idstr or None, default: None: If there are several streams, specify the stream id you want to load.
stream_namestr or None, default: None: If there are several streams, specify the stream name you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

Examples

>>> from spikeinterface.extractors import read_spikegadgets
>>> recording = read_spikegadgets(file_path=r'my_data.rec')

spikeinterface.extractors.read_spikeglx(folder_path, load_sync_channel=False, stream_id=None, stream_name=None, all_annotations: bool = False, use_names_as_ids: bool = 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_pathstr: The folder path to load the recordings from.
load_sync_channelbool 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_idstr 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_namestr or None, default: None: If there are several streams, specify the stream name you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.

Examples

>>> from spikeinterface.extractors import read_spikeglx
>>> recording = read_spikeglx(folder_path=r'path_to_folder_with_data', load_sync_channel=False)
# we can load the sync channel, but then the probe is not loaded
>>> recording = read_spikeglx(folder_path=r'pat_to_folder_with_data', load_sync_channel=True)

spikeinterface.extractors.read_tdt(folder_path, stream_id=None, stream_name=None, block_index=None, all_annotations: bool = False, use_names_as_ids: bool = False)

Class for reading TDT folder.

Based on neo.rawio.TdTRawIO

Parameters:

folder_pathstr: The folder path to the tdt folder.
stream_idstr or None, default: None: If there are several streams, specify the stream id you want to load.
stream_namestr or None, default: None: If there are several streams, specify the stream name you want to load.
all_annotationsbool, default: False: Load exhaustively all annotations from neo.
use_names_as_idsbool, default: False: Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.
block_indexint, default: None: If there are several blocks (experiments), specify the block index you want to load

spikeinterface.extractors.read_zarr(folder_path: str | Path, storage_options: dict | None = None) → ZarrRecordingExtractor | ZarrSortingExtractor

Read recording or sorting from a zarr format

Parameters:

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

Returns:

extractorZarrExtractor: 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=None, load_sync_channel=False, stream_name='ap', cbin_file_path=None, cbin_file=None)

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_pathstr or Path: Path to ibl folder.
load_sync_channelbool, default: False: Load or not the last channel (sync). If not then the probe is loaded.
stream_name{“ap”, “lp”}, default: “ap”.: Whether to load AP or LFP band, one of “ap” or “lp”.
cbin_file_pathstr, Path or None, default None: The cbin file of the recording. If None, searches in folder_path for file.
cbin_filestr or None, default None: (deprecated) The cbin file of the recording. If None, searches in folder_path for file.

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_recording(eid: str | None = None, pid: str | None = None, stream_name: str | None = None, load_sync_channel: bool = False, cache_folder: Path | str | None = None, remove_cached: bool = True, stream: bool = True, one: one.api.OneAlyx = None, stream_type: str | None = None)

Stream IBL data as an extractor object.

Parameters:

eidstr or None, default: None

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”.

pidstr or None, default: None

Probe insertion UUID in Alyx. To retrieve the PID from a session (or eid), use the following code:

>>> from one.api import ONE
>>> one = ONE(base_url="https://openalyx.internationalbrainlab.org", password="international", silent=True)
>>> pids, _ = one.eid2pid("session_eid")
>>> pid = pids[0]

Either eid or pid must be provided.

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_channelbool, 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.

streambool, default: True

Whether or not to stream the data.

oneone.api.OneAlyx, default: None

An instance of the ONE API to use for data loading. If not provided, a default instance is created using the default parameters. If you need to use a specific instance, you can create it using the ONE API and pass it here.

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:

file_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_pathstr or Path: Path to the output Kilosort 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_groupslist 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_fnamestr, default: “raw.mda”: File name of raw file
params_fnamestr, default: “params.json”: File name of params file
geom_fnamestr, 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.

NOTE: As in the MDA format, the max_channel property indexes the channels that are given as input to the sorter. If sorting was run on a subset of channels of the recording, then the max_channel values are based on that subset, so care must be taken when associating these values with a recording. If additional sorting segments are added to this sorting extractor after initialization, then max_channel will not be updated. The max_channel indices begin at 1.

Parameters:

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

Returns:

extractorMdaRecordingExtractor: The loaded data.

spikeinterface.extractors.read_nwb_sorting(file_path: str | Path, electrical_series_path: str | None = None, sampling_frequency: float | None = None, samples_for_rate_estimation: int = 1000, stream_mode: str | None = None, stream_cache_path: str | Path | None = None, load_unit_properties: bool = True, unit_table_path: str = 'units', *, t_start: float | None = None, cache: bool = False, storage_options: dict | None = None, use_pynwb: bool = False)

Load an NWBFile as a SortingExtractor. Parameters ———- file_path : str or Path

Path to NWB file.

electrical_series_pathstr or None, default: None

The name of the ElectricalSeries (if multiple ElectricalSeries are present).

sampling_frequencyfloat or None, default: None

The sampling frequency in Hz (required if no ElectricalSeries is available).

unit_table_pathstr or None, default: “units”

The path of the unit table in the NWB file.

samples_for_rate_estimationint, default: 100000

The number of timestamp samples to use to estimate the rate. Used if “rate” is not specified in the ElectricalSeries.

stream_mode“fsspec” | “remfile” | “zarr” | None, default: None

The streaming mode to use. If None it assumes the file is on the local disk.

stream_cache_pathstr or Path or None, default: None

Local path for caching. If None it uses the system temporary directory.

load_unit_propertiesbool, default: True

If True, all the unit properties are loaded from the NWB file and stored as properties.

t_startfloat or None, default: None

This is the time at which the corresponding ElectricalSeries start. NWB stores its spikes as times and the t_start is used to convert the times to seconds. Concrently, the returned frames are computed as:

frames = (times - t_start) * sampling_frequency.

As SpikeInterface always considers the first frame to be at the beginning of the recording independently of the t_start.

When a t_start is not provided it will be inferred from the corresponding ElectricalSeries with name equal to electrical_series_path. The t_start then will be either the ElectricalSeries.starting_time or the first timestamp in the ElectricalSeries.timestamps.

cachebool, default: False

If True, the file is cached in the file passed to stream_cache_path if False, the file is not cached.

storage_optionsdict | None = None,

These are the additional kwargs (e.g. AWS credentials) that are passed to the zarr.open convenience function. This is only used on the “zarr” stream_mode.

use_pynwbbool, default: False

Uses the pynwb library to read the NWB file. Setting this to False, the default, uses h5py to read the file. Using h5py can improve performance by bypassing some of the PyNWB validations.

Returns:

sortingNwbSortingExtractor: The sorting extractor for the NWB file.

spikeinterface.extractors.read_nwb_recording(file_path: str | Path | None = None, electrical_series_name: str | None = None, load_time_vector: bool = False, samples_for_rate_estimation: int = 1000, stream_mode: Literal['fsspec', 'remfile', 'zarr'] | None = None, stream_cache_path: str | Path | None = None, electrical_series_path: str | None = None, load_channel_properties: bool = True, *, file: BinaryIO | None = None, cache: bool = False, storage_options: dict | None = None, use_pynwb: bool = False)

Load an NWBFile as a RecordingExtractor.

Parameters:

file_pathstr, Path, or None: Path to the NWB file or an s3 URL. Use this parameter to specify the file location if not using the file parameter.
electrical_series_namestr or None, default: None: Deprecated, use electrical_series_path instead.
electrical_series_pathstr or None, default: None: The name of the ElectricalSeries object within the NWB file. This parameter is crucial when the NWB file contains multiple ElectricalSeries objects. It helps in identifying which specific series to extract data from. If there is only one ElectricalSeries and this parameter is not set, that unique series will be used by default. If multiple ElectricalSeries are present and this parameter is not set, an error is raised. The electrical_series_path corresponds to the path within the NWB file, e.g., ‘acquisition/MyElectricalSeries`.
load_time_vectorbool, default: False: If set to True, the time vector is also loaded into the recording object. Useful for cases where precise timing information is required.
samples_for_rate_estimationint, default: 1000: The number of timestamp samples used for estimating the sampling rate. This is relevant when the ‘rate’ attribute is not available in the ElectricalSeries.
stream_mode“fsspec” | “remfile” | “zarr” | None, default: None: Determines the streaming mode for reading the file. Use this for optimized reading from different sources, such as local disk or remote servers.
load_channel_propertiesbool, default: True: If True, all the channel properties are loaded from the NWB file and stored as properties. For streaming purposes, it can be useful to set this to False to speed up streaming.
filefile-like object or None, default: None: A file-like object representing the NWB file. Use this parameter if you have an in-memory representation of the NWB file instead of a file path.
cachebool, default: False: Indicates whether to cache the file locally when using streaming. Caching can improve performance for remote files.
stream_cache_pathstr, Path, or None, default: None: Specifies the local path for caching the file. Relevant only if cache is True.
storage_optionsdict | None = None,: These are the additional kwargs (e.g. AWS credentials) that are passed to the zarr.open convenience function. This is only used on the “zarr” stream_mode.
use_pynwbbool, default: False: Uses the pynwb library to read the NWB file. Setting this to False, the default, uses h5py to read the file. Using h5py can improve performance by bypassing some of the PyNWB validations.

Returns:

recordingNwbRecordingExtractor: The recording extractor for the NWB file.

Examples

Run on local file:

>>> from spikeinterface.extractors.nwbextractors import NwbRecordingExtractor
>>> rec = NwbRecordingExtractor(filepath)

Run on s3 URL from the DANDI Archive:

>>> from spikeinterface.extractors.nwbextractors import NwbRecordingExtractor
>>> from dandi.dandiapi import DandiAPIClient
>>>
>>> # get s3 path
>>> dandiset_id = "001054"
>>> filepath = "sub-Dory/sub-Dory_ses-2020-09-14-004_ecephys.nwb"
>>> with DandiAPIClient() as client:
>>>     asset = client.get_dandiset(dandiset_id).get_asset_by_path(filepath)
>>>     s3_url = asset.get_content_url(follow_redirects=1, strip_query=True)
>>>
>>> rec = NwbRecordingExtractor(s3_url, stream_mode="remfile")

spikeinterface.extractors.read_nwb_timeseries(file_path: str | Path | None = None, timeseries_path: str | None = None, load_time_vector: bool = False, samples_for_rate_estimation: int = 1000, stream_mode: Literal['fsspec', 'remfile', 'zarr'] | None = None, stream_cache_path: str | Path | None = None, *, file: BinaryIO | None = None, cache: bool = False, storage_options: dict | None = None, use_pynwb: bool = False)

Load a TimeSeries from an NWBFile as a RecordingExtractor.

Parameters:

file_pathstr | Path | None: Path to NWB file or an s3 URL. Use this parameter to specify the file location if not using the file parameter.
timeseries_pathstr | None: The path to the TimeSeries object within the NWB file. This parameter is required when the NWB file contains multiple TimeSeries objects. The path corresponds to the location within the NWB file hierarchy, e.g. ‘acquisition/MyTimeSeries’.
load_time_vectorbool, default: False: If True, the time vector is loaded into the recording object. Useful when precise timing information is needed.
samples_for_rate_estimationint, default: 1000: The number of timestamps used for estimating the sampling rate when timestamps are used instead of a fixed rate.
stream_modeLiteral[“fsspec”, “remfile”, “zarr”] | None, default: None: Determines the streaming mode for reading the file.
fileBinaryIO | None, default: None: A file-like object representing the NWB file. Use this parameter if you have an in-memory representation of the NWB file instead of a file path given by file_path.
cachebool, default: False: If True, the file is cached locally when using streaming.
stream_cache_pathstr | Path | None, default: None: Local path for caching. Only used if cache is True.
storage_optionsdict | None, default: None: Additional kwargs (e.g. AWS credentials) passed to zarr.open. Only used with “zarr” stream_mode.
use_pynwbbool, default: False: If True, uses pynwb library to read the NWB file. Default False uses h5py/zarr directly for better performance.

Returns:

recordingNwbTimeSeriesExtractor: A recording extractor containing the TimeSeries data.

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

Load Phy format data as a sorting extractor.

Parameters:

folder_pathstr or Path: Path to the output Phy folder (containing the params.py).
exclude_cluster_groupslist 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:

durationfloat or list[float], default: 10: Duration in seconds. If a list is provided, it will be the duration of each segment.
num_channelsint, default: 4: Number of channels
num_unitsint, default: 10: Number of units
sampling_frequencyfloat, default: 30000: Sampling frequency
num_segmentsint, default: 2: Number of segments.
spike_timesnp.array or list[nparray] or None, default: None: Spike time in the recording
spike_labelsnp.array or list[nparray] or None, default: None: Cluster label for each spike time (needs to specified both together).
firing_ratefloat, default: 3.0: The firing rate for the units (in Hz)
seedint or None, default: None: Seed for random initialization.
upsample_factorNone or int, default: None: An upsampling factor, used only when templates are not provided.
num_columnsint, default: 1: Number of columns in probe.
average_peak_amplitudefloat, default: -100: Average peak amplitude of generated templates.
contact_spacing_umfloat, default: 40.0: Spacing between probe contacts in micrometers.

Returns:

recordingRecordingExtractor: The output recording extractor.
sortingSortingExtractor: 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, round: bool | None = 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.

Parameters:

dtypeNone | str | dtype, default: None: dtype of the output recording. If None, takes dtype from input recording.
recordingRecording: The recording extractor to be converted.
roundBool | None, default: None: If True, will round the values to the nearest integer using numpy.round. If None and dtype is an integer, will round floats to nearest integer.

Returns:

astype_recordingAstypeRecording: The converted recording extractor object

spikeinterface.preprocessing.average_across_direction(parent_recording: BaseRecording, direction: str = 'y', dtype='float32')

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:

recordingRecording

The recording extractor to be re-referenced

freq_minfloat

The highpass cutoff frequency in Hz

freq_maxfloat

The lowpass cutoff frequency in Hz

margin_msfloat

Margin in ms on border to avoid border effect

dtypedtype or None

The dtype of the returned traces. If None, the dtype of the parent recording is used

**filter_kwargsdict

Certain keyword arguments for scipy.signal filters:

filter_orderorder: The order of the filter. Note as filtering is applied with scipy’s filtfilt functions (i.e. acausal, zero-phase) the effective order will be double the filter_order.
filter_mode“sos” | “ba”, default: “sos”: Filter form of the filter coefficients: - second-order sections (“sos”) - numerator/denominator : (“ba”)
ftypestr, default: “butter”: Filter type for scipy.signal.iirfilter e.g. “butter”, “cheby1”.

Returns:

filter_recordingBandpassFilterRecording: The bandpass-filtered recording extractor object

spikeinterface.preprocessing.blank_saturation(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:

recordingRecordingExtractor: The recording extractor to be transformed Minimum value. If None, clipping is not performed on lower interval edge.
abs_thresholdfloat or None, default: None: The absolute value for considering that the signal is saturating
quantile_thresholdfloat 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_valuefloat 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_segmentint, default: 50: The number of chunks per segments to consider to estimate the threshold/fill_values
chunk_sizeint, default: 500: The chunk size to estimate the threshold/fill_values
seedint, default: 0: The seed to select the random chunks

Returns:

rescaled_tracesBlankSaturationRecording: 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:

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

Returns:

centered_tracesScaleRecording: 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:

recordingRecordingExtractor: The recording extractor to be transformed
a_minfloat or None, default: None: Minimum value. If None, clipping is not performed on lower interval edge.
a_maxfloat or None, default: None: Maximum value. If None, clipping is not performed on upper interval edge.

Returns:

rescaled_tracesClipTracesRecording: The clipped traces recording extractor object

spikeinterface.preprocessing.common_reference(recording: BaseRecording, reference: Literal['global', 'single', 'local'] = 'global', operator: Literal['median', 'average'] = 'median', groups: list | None = None, ref_channel_ids: list | str | int | None = None, local_radius: tuple[float, float] = (30.0, 55.0), dtype: str | np.dtype | None = 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:

recordingRecordingExtractor

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. To select a subset of channels, you can use the ref_channel_ids parameter. 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).

groupslist 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_idslist | str | int | None, default: None

If “global” reference, a list of channels to be used as reference. If “single” reference, a list of one channel or a single channel id is expected. If “groups” is provided, then a list of channels to be applied to each group is expected.

local_radiustuple(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.

dtypeNone or dtype, default: None

If None the parent dtype is kept.

Returns:

referenced_recordingCommonReferenceRecording: 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_segmentint, 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_recordingScaleRecording: The recording extractor with corrected LSB

spikeinterface.preprocessing.correct_motion(recording: BaseRecording, preset: Literal['dredge', 'medicine', 'dredge_fast', 'nonrigid_accurate', 'nonrigid_fast_and_accurate', 'rigid_fast', 'kilosort_like'] = 'dredge_fast', folder: str | Path | None = None, output_motion: bool = False, output_motion_info: bool = False, overwrite: bool = False, detect_kwargs: dict = {}, select_kwargs: dict = {}, localize_peaks_kwargs: dict = {}, estimate_motion_kwargs: dict = {}, interpolate_motion_kwargs: dict = {}, **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 convenient, 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 whitening before motion estimation. Since the motion interpolation requires a “float” recording, the recording is cast to float32 if necessary.

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

dredge: Official Dredge preset
medicine: Medicine method: https://jazlab.github.io/medicine/
dredge_fast: Modified and faster Dredge preset
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:

recordingRecordingExtractor

The recording extractor to be transformed

presetstr, default: “nonrigid_accurate”

The preset name

folderPath str or None, default: None

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

overwritebool, default: False

If True and folder is given, overwrite the folder if it already exists

detect_kwargsdict

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

select_kwargsdict

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

localize_peaks_kwargsdict

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

estimate_motion_kwargsdict

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

interpolate_motion_kwargsdict

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

output_motion_infobool, 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.

output_motionbool, default: False

It True, the function returns a motion object.

**job_kwargskeyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_sizeint
  Number of samples per chunk
- chunk_memorystr
  Memory usage for each job (e.g. “100M”, “1G”, “500MiB”, “2GiB”)
- total_memorystr
  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_jobsint | float
Number of jobs to use. With -1 the number of jobs is the same as number of cores. Using a float between 0 and 1 will use that fraction of the total cores.
progress_barbool
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_correctedRecording: The motion corrected recording
motionMotion: Optional output if output_motion=True.
motion_infodict: Optional output if output_motion_info=True. This dict contains several variable for for plotting. See plot_motion_info()

spikeinterface.preprocessing.get_motion_presets()

spikeinterface.preprocessing.get_motion_parameters_preset(preset)

Get the parameters tree for a given preset for motion correction.

Parameters:

presetstr, default: None: The preset name. See available presets using spikeinterface.preprocessing.get_motion_presets().

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:

parent_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
flipbool, 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: int | None = 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_thresholdfloat, default: 0.02: For coherence+psd - 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_thresholdfloat, default: -0.5: For coherence+psd - threshold for channel coherence below which channels are labeled as dead
noisy_channel_thresholdfloat, default: 1: Threshold for channel coherence above which channels are labeled as noisy (together with psd condition)
outside_channel_thresholdfloat, default: -0.75: For coherence+psd - threshold for channel coherence above which channels at the edge of the recording are marked as outside of the brain
outside_channels_location“top” | “bottom” | “both”, default: “top”: For coherence+psd - 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_neighborsint, default: 11: For coeherence+psd - number of channel neighbors to compute median filter (needs to be odd)
nyquist_thresholdfloat, default: 0.8: For coherence+psd - frequency with respect to Nyquist (Fn=1) above which the mean of the PSD is calculated and compared with psd_hf_threshold
direction“x” | “y” | “z”, default: “y”: For coherence+psd - 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')

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, direction='forward-backward')

A generic filter class based on:

For filter coefficient generation:

scipy.signal.iirfilter

For filter application:

scipy.signal.filtfilt or scipy.signal.sosfiltfilt when direction = “forward-backward”
scipy.signal.lfilter or scipy.signal.sosfilt when direction = “forward” or “backward”

BandpassFilterRecording is built on top of it.

Parameters:

recordingRecording: The recording extractor to be re-referenced
bandfloat 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_msfloat, default: 5.0: Margin in ms on border to avoid border effect
coeffarray | None, default: None: Filter coefficients in the filter_mode form.
dtypedtype or None, default: None: The dtype of the returned traces. If None, the dtype of the parent recording is used
add_reflect_paddingBool, default False: If True, uses a left and right margin during calculation.
filter_orderorder: The order of the filter for scipy.signal.iirfilter
filter_mode“sos” | “ba”, default: “sos”: Filter form of the filter coefficients for scipy.signal.iirfilter: - second-order sections (“sos”) - numerator/denominator : (“ba”)
ftypestr, default: “butter”: Filter type for scipy.signal.iirfilter e.g. “butter”, “cheby1”.
direction“forward” | “backward” | “forward-backward”, default: “forward-backward”: Direction of filtering: - “forward” - filter is applied to the timeseries in one direction, creating phase shifts - “backward” - the timeseries is reversed, the filter is applied and filtered timeseries reversed again. Creates phase shifts in the opposite direction to “forward” - “forward-backward” - Applies the filter in the forward and backward direction, resulting in zero-phase filtering. Note this doubles the effective filter order.

Returns:

filter_recordingFilterRecording: 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:

recordingBaseRecording: The recording extractor to be filtered.
freq_minfloat or None: The lower frequency cutoff for the bandpass filter. If None, the resulting object is a lowpass filter.
freq_maxfloat or None: The higher frequency cutoff for the bandpass filter. If None, the resulting object is a highpass filter.
margin_sdfloat, default: 5.0: The number of standard deviation to take for margins.

Returns:

gaussian_filtered_recordingGaussianFilterRecording: 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:

recordingRecording

The recording extractor to be re-referenced

freq_minfloat

The highpass cutoff frequency in Hz

margin_msfloat

Margin in ms on border to avoid border effect

dtypedtype or None

The dtype of the returned traces. If None, the dtype of the parent recording is used

**filter_kwargsdict

Certain keyword arguments for scipy.signal filters:

filter_orderorder: The order of the filter. Note as filtering is applied with scipy’s filtfilt functions (i.e. acausal, zero-phase) the effective order will be double the filter_order.
filter_mode“sos” | “ba”, default: “sos”: Filter form of the filter coefficients: - second-order sections (“sos”) - numerator/denominator : (“ba”)
ftypestr, default: “butter”: Filter type for scipy.signal.iirfilter e.g. “butter”, “cheby1”.

Returns:

filter_recordingHighpassFilterRecording: 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, dtype=None)

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
dtypedtype, default: None: The dtype of the output traces. If None, the dtype is the same as the input traces

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:

recordingBaseRecording: 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_recordingInterpolateBadChannelsRecording: 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:

recordingRecordingExtractor: The recording extractor to be transformed
scalefloat, default: 1.0: Scale for the output distribution
medianfloat, default: 0.0: Median for the output distribution
q1float, default: 0.01: Lower quantile used for measuring the scale
q2float, 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.
dtypestr or np.dtype, default: “float32”: The dtype of the output traces
**random_chunk_kwargsKeyword arguments for spikeinterface.core.get_random_data_chunk() function

Returns:

rescaled_tracesNormalizeByQuantileRecording: The rescaled traces recording extractor object

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

Parameters:

recordingRecordingExtractor: The recording extractor to be notch-filtered
freqint or float: The target frequency in Hz of the notch filter
qint: The quality factor of the notch filter
dtypeNone | dtype, default: None: dtype of recording. If None, will take from recording
margin_msfloat, default: 5.0: Margin in ms on border to avoid border effect

Returns:

filter_recordingNotchFilterRecording: The notch-filtered recording extractor object

spikeinterface.preprocessing.causal_filter(recording, direction='forward', 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 causal filter built on top of the filter function.

Parameters:

recordingRecording: The recording extractor to be re-referenced
direction“forward” | “backward”, default: “forward”: Direction of causal filter. The “backward” option flips the traces in time before applying the filter and then flips them back.
bandfloat 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_msfloat, default: 5.0: Margin in ms on border to avoid border effect
coeffarray | None, default: None: Filter coefficients in the filter_mode form.
dtypedtype or None, default: None: The dtype of the returned traces. If None, the dtype of the parent recording is used
add_reflect_paddingBool, default False: If True, uses a left and right margin during calculation.
filter_orderorder: The order of the filter for scipy.signal.iirfilter
filter_mode“sos” | “ba”, default: “sos”: Filter form of the filter coefficients for scipy.signal.iirfilter: - second-order sections (“sos”) - numerator/denominator : (“ba”)
ftypestr, default: “butter”: Filter type for scipy.signal.iirfilter e.g. “butter”, “cheby1”.

Returns:

filter_recordingFilterRecording: The causal-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:

recordingRecording: The recording. It need to have “inter_sample_shift” in properties.
margin_msfloat, default: 40.0: Margin in ms for computation. 40ms ensure a very small error when doing chunk processing
inter_sample_shiftNone or numpy array, default: None: If “inter_sample_shift” is not in recording properties, we can externally provide one.
dtypeNone | str | dtype, default: None: Dtype of input and output recording objects.

Returns:

filter_recordingPhaseShiftRecording: The phase shifted recording object

spikeinterface.preprocessing.rectify(recording)

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=None)

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:

recordingRecordingExtractor

The recording extractor to remove artifacts from

list_triggerslist of lists/arrays

One list per segment of int with the stimulation trigger frames

ms_beforefloat 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_afterfloat 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_labelslist of lists/arrays or None

One list per segment of labels with the stimulation labels for the given artifacts. 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_spacingfloat, 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.

artifactsdict 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)

sparsitydict 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_amplitudeFalse, 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_jitterfloat, default: 0

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

waveforms_kwargsNone

Deprecated and ignored

Returns:

removed_recordingRemoveArtifactsRecording: 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
margin_msfloat, 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_recordingResampleRecording: 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:

recordingRecordingExtractor: The recording extractor to be transformed
gainfloat or array: Scalar for the traces of the recording extractor or array with scalars for each channel
offsetfloat or array: Offset for the traces of the recording extractor or array with offsets for each channel
dtypestr or np.dtype, default: “float32”: The dtype of the output traces

Returns:

transform_tracesScaleRecording: The transformed traces recording extractor object

spikeinterface.preprocessing.silence_periods(recording, list_periods, mode='zeros', noise_levels=None, seed=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:

recordingRecordingExtractor

The recording extractor to silance periods

list_periodslist of lists/arrays

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

noise_levelsarray

Noise levels if already computed

seedint | None, default: None

Random seed for get_noise_levels and NoiseGeneratorRecording. If none, get_noise_levels uses seed=0 and NoiseGeneratorRecording generates a random seed using numpy.random.default_rng.

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_kwargsKeyword arguments for spikeinterface.core.get_random_data_chunk() function

Returns:

silence_recordingSilencedPeriodsRecording: 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:

recordingRecording: The recording to be signed.
bit_depthint 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, regularize=False, regularize_kwargs=None, mode='global', radius_um=100.0, int_scale=None, eps=None, W=None, M=None, **random_chunk_kwargs)

Whitens the recording extractor traces.

Parameters:

recordingRecordingExtractor: The recording extractor to be whitened.
dtypeNone or dtype, default: None: Datatype of the output recording (covariance matrix estimation and whitening are performed in float32). 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_umNone or float, default: None: Used for mode = “local” to get the neighborhood
apply_meanbool, 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
regularizebool, default: False: Boolean to decide if we want to regularize the covariance matrix, using a chosen method of sklearn, specified in regularize_kwargs. Default is GraphicalLassoCV
regularize_kwargs{‘method’‘GraphicalLassoCV’}: Dictionary of the parameters that could be provided to the method of sklearn, if the covariance matrix needs to be regularized. Note that sklearn covariance methods that are implemented as functions, not classes, are not supported.
**random_chunk_kwargsKeyword arguments for spikeinterface.core.get_random_data_chunk() function

Returns:

whitened_recordingWhitenRecording: The whitened recording extractor

spikeinterface.preprocessing.zero_channel_pad(recording: BaseRecording, num_channels: int, channel_mapping: list | None = None)

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:

recordingRecordingExtractor: The recording extractor to be centered
mode“median+mad” | “mean+std”, default: “median+mad”: The mode to compute the zscore
dtypeNone 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_kwargsKeyword arguments for spikeinterface.core.get_random_data_chunk() function

Returns:

centered_tracesScaleRecording: The centered traces recording extractor object

spikeinterface.postprocessing

spikeinterface.postprocessing.compute_noise_levels(sorting_analyzer, load_if_exists=None, *args, **kwargs)

Computes the noise level associated with 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 SortingAnalyzer.

Parameters:

sorting_analyzerSortingAnalyzer: A SortingAnalyzer object
**kwargsdict: Additional parameters for the spikeinterface.get_noise_levels() function

Returns:

noise_levelsnp.array: The noise level vector

spikeinterface.postprocessing.compute_template_metrics(sorting_analyzer, load_if_exists=None, *args, **kwargs)

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:

sorting_analyzerSortingAnalyzer: The SortingAnalyzer object
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
sparsityChannelSparsity 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_metricsbool, default: False: Whether to compute multi-channel metrics
delete_existing_metricsbool, default: False: If True, any template metrics attached to the sorting_analyzer are deleted. If False, any metrics which were previously calculated but are not included in metric_names are kept, provided the metric_params are unchanged.
metric_paramsdict of dicts or None, default: None: Dictionary with parameters for template metrics calculation. Default parameters can be obtained with: si.postprocessing.template_metrics.get_default_tm_params()

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(sorting_analyzer, load_if_exists=None, *args, **kwargs)

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

Parameters:

sorting_analyzerSortingAnalyzer

A SortingAnalyzer object

n_componentsint, 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

sparsityChannelSparsity or None, default: None

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

whitenbool, default: True

If True, waveforms are pre-whitened

dtypedtype, default: “float32”

Dtype of the pc scores

{}

Examples

>>> sorting_analyzer = create_sorting_analyzer(sorting, recording)
>>> sorting_analyzer.compute("principal_components", n_components=3, mode='by_channel_local')
>>> ext_pca = sorting_analyzer.get_extension("principal_components")
>>> # get pre-computed projections for unit_id=1
>>> unit_projections = ext_pca.get_projections_one_unit(unit_id=1, sparse=False)
>>> # get pre-computed projections for some units on some channels
>>> some_projections, spike_unit_indices = ext_pca.get_some_projections(channel_ids=None, unit_ids=None)
>>> # retrieve fitted pca model(s)
>>> pca_model = ext_pca.get_pca_model()
>>> # compute projections on new waveforms
>>> proj_new = ext_pca.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(sorting_analyzer, load_if_exists=None, *args, **kwargs)

AnalyzerExtension Computes the spike amplitudes.

Needs “templates” to be computed first. Computes spike amplitudes from the template’s peak channel for every spike.

Parameters:

sorting_analyzerSortingAnalyzer: A SortingAnalyzer object
peak_sign“neg” | “pos” | “both”, default: “neg”: Sign of the template to compute extremum channel used to retrieve spike amplitudes.

Returns:

spike_amplitudes: np.array: All amplitudes for all spikes and all units are concatenated (along time, like in spike vector)

spikeinterface.postprocessing.compute_unit_locations(sorting_analyzer, load_if_exists=None, *args, **kwargs)

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

Parameters:

sorting_analyzerSortingAnalyzer: A SortingAnalyzer object
method“monopolar_triangulation” | “center_of_mass” | “grid_convolution”, default: “monopolar_triangulation”: The method to use for localization
**method_kwargsdict, default: {}: Kwargs which are passed to the method function. These can be found in the docstrings of compute_center_of_mass, compute_grid_convolution and compute_monopolar_triangulation.

Returns:

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

spikeinterface.postprocessing.compute_spike_locations(sorting_analyzer, load_if_exists=None, *args, **kwargs)

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

Parameters:

sorting_analyzerSortingAnalyzer

A SortingAnalyzer object

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_kwargsdict

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: All locations for all spikes

spikeinterface.postprocessing.compute_template_similarity(sorting_analyzer, load_if_exists=None, *args, **kwargs)

Compute similarity between templates with several methods.

Similarity is defined as 1 - distance(T_1, T_2) for two templates T_1, T_2

Parameters:

sorting_analyzerSortingAnalyzer: The SortingAnalyzer object
method“cosine” | “l1” | “l2”, default: “cosine”: The method to compute the similarity. In case of “l1” or “l2”, the formula used is: - similarity = 1 - norm(T_1 - T_2)/(norm(T_1) + norm(T_2)). In case of cosine it is: - similarity = 1 - sum(T_1.T_2)/(norm(T_1)norm(T_2)).
max_lag_msfloat, default: 0: If specified, the best distance for all given lag within max_lag_ms is kept, for every template
support“dense” | “union” | “intersection”, default: “union”: Support that should be considered to compute the distances between the templates, given their sparsities. Can be either [“dense”, “union”, “intersection”]

Returns:

similarity: np.array: The similarity matrix

spikeinterface.postprocessing.compute_correlograms(sorting_analyzer_or_sorting, window_ms: float = 50.0, bin_ms: float = 1.0, method: str = 'auto')

Compute auto and cross correlograms of unit spike times.

Parameters:

sorting_analyzer_or_sortingSortingAnalyzer | Sorting

A SortingAnalyzer or Sorting object

window_msfloat, default: 50.0

The window around the spike to compute the correlation in ms. For example,: if 50 ms, the correlations will be computed at lags -25 ms … 25 ms.

bin_msfloat, default: 1.0

The bin size in ms. This determines the bin size over which to combine lags. For example, with a window size of -25 ms to 25 ms, and bin size 1 ms, the correlation will be binned as -25 ms, -24 ms, …

method“auto” | “numpy” | “numba”, default: “auto”

If “auto” and numba is installed, numba is used, otherwise numpy is used.

Returns:

correlogramnp.array: Correlograms with shape (num_units, num_units, num_bins) The diagonal of the correlogram (e.g. correlogram[A, A, :]) holds the unit auto correlograms. The off-diagonal elements are the cross-correlograms between units, where correlogram[A, B, :] and correlogram[B, A, :] represent cross-correlation between the same pair of units, applied in opposite directions, correlogram[A, B, :] = correlogram[B, A, ::-1].
binsnp.array: The bin edges in ms

Notes

In the extracellular electrophysiology context, a correlogram is a visualisation of the results of a cross-correlation between two spike trains. The cross-correlation slides one spike train along another sample-by-sample, taking the correlation at each ‘lag’. This results in a plot with ‘lag’ (i.e. time offset) on the x-axis and ‘correlation’ (i.e. how similar to two spike trains are) on the y-axis. In this implementation, the y-axis result is the ‘counts’ of spike matches per time bin (rather than a computer correlation or covariance).

In the present implementation, a ‘window’ around spikes is first specified. For example, if a window of 100 ms is taken, we will take the correlation at lags from -50 ms to +50 ms around the spike peak. In theory, we can have as many lags as we have samples. Often, this visualisation is too high resolution and instead the lags are binned (e.g. -50 to -45 ms, …, -5 to 0 ms, 0 to 5 ms, …., 45 to 50 ms). When using counts as output, binning the lags involves adding up all counts across a range of lags.

spikeinterface.postprocessing.compute_isi_histograms(sorting_analyzer, load_if_exists=None, *args, **kwargs)

Compute ISI histograms.

Parameters:

sorting_analyzerSortingAnalyzer: A SortingAnalyzer object
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:

sortingBaseSorting: The sorting to align.
unit_peak_shiftsdict: 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_sortingAlignSortingExtractor: The aligned sorting.

spikeinterface.qualitymetrics

spikeinterface.qualitymetrics.compute_quality_metrics(sorting_analyzer, load_if_exists=None, *args, **kwargs)

Compute quality metrics on a sorting_analyzer.

Parameters:

sorting_analyzerSortingAnalyzer: A SortingAnalyzer object.
metric_nameslist or None: List of quality metrics to compute.
metric_paramsdict of dicts or None: Dictionary with parameters for quality metrics calculation. Default parameters can be obtained with: si.qualitymetrics.get_default_qm_params()
skip_pc_metricsbool, default: False: If True, PC metrics computation is skipped.
delete_existing_metricsbool, default: False: If True, any quality metrics attached to the sorting_analyzer are deleted. If False, any metrics which were previously calculated but are not included in metric_names are kept.

Returns:

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

Notes

principal_components are loaded automatically if already computed.

spikeinterface.qualitymetrics.get_quality_metric_list(): Return 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) → dict

Returns default parameters for the specified sorter.

Parameters:

sorter_name_or_classstr or SorterClass: The sorter to retrieve default parameters from.

Returns:

default_paramsdict: Dictionary with default params for the specified sorter.

spikeinterface.sorters.get_sorter_params_description(sorter_name_or_class) → dict

Returns a description of the parameters for the specified sorter.

Parameters:

sorter_name_or_classstr or SorterClass: The sorter to retrieve parameters description from.

Returns:

params_descriptiondict: 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) → dict

Returns a brief description for the specified sorter.

Parameters:

sorter_name_or_classstr or SorterClass: The sorter to retrieve description from.

Returns:

params_descriptiondict: Dictionary with parameter description.

spikeinterface.sorters.run_sorter(sorter_name: str, recording: BaseRecording, folder: str | None = None, remove_existing_folder: bool = False, delete_output_folder: bool = False, verbose: bool = False, raise_error: bool = True, docker_image: bool | str | None = False, singularity_image: bool | str | None = False, delete_container_files: bool = True, with_output: bool = True, output_folder: None = None, **sorter_params)

Generic function to run a sorter via function approach.

Parameters:

sorter_namestr: The sorter name
recordingRecordingExtractor: The recording extractor to be spike sorted
folderstr or Path: Path to output folder
remove_existing_folderbool: If True and folder exists then delete.
delete_output_folderbool, default: False: If True, output folder is deleted
verbosebool, default: False: If True, output is verbose
raise_errorbool, 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_imagebool 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_imagebool 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_outputbool, default: True: If True, the output Sorting is returned as a Sorting
delete_container_filesbool, default: True: If True, the container temporary files are deleted after the sorting is done
output_folderNone, default: None: Do not use. Deprecated output function to be removed in 0.103.
**sorter_paramskeyword 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_listlist of dict: A list a dict that are propagated to run_sorter(…)
enginestr “loop”, “joblib”, “dask”, “slurm”: The engine to run the list. * “loop” : a simple loop. This engine is
engine_kwargsdict
return_outputbool, dfault False: Return a sortings or None. This also overwrite kwargs in in run_sorter(with_sorting=True/False)

Returns:

sortingsNone 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, folder, mode_if_folder_exists=None, engine='loop', engine_kwargs={}, verbose=False, docker_image=None, singularity_image=None, working_folder: None = 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_namestr

The sorter name

recordingBaseRecording

The recording to be sorted

grouping_propertyobject

Property to split by before sorting

folderstr | Path

The working directory.

mode_if_folder_existsbool 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_kwargsdict

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

verbosebool, default: False

Controls sorter verboseness

docker_imageNone or str, default: None

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

singularity_imageNone or str, default: None

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

**sorter_paramskeyword 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",
                                        folder="sort_by_group", engine="joblib",
                                        engine_kwargs={"n_jobs": 4})

spikeinterface.sorters.read_sorter_folder(folder, register_recording=True, sorting_info=True, raise_error=True)

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

Parameters:

folderPth or str: The sorter folder
register_recordingbool, default: True: Attach recording (when json or pickle) to the sorting
sorting_infobool, default: True: Attach sorting info to the sorting
raise_errorbool, detault: True: Raise an error if the spike sorting failed

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: BaseSorting, sorting2: BaseSorting, sorting1_name: str | None = None, sorting2_name: str | None = None, delta_time: float = 0.4, match_score: float = 0.5, chance_score: float = 0.1, agreement_method: str = 'count', verbose: bool = 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:

sorting1BaseSorting: The first sorting for the comparison
sorting2BaseSorting: The second sorting for the comparison
sorting1_namestr, default: None: The name of sorter 1
sorting2_name: str, default: None: The name of sorter 2
delta_timefloat, default: 0.4: Number of ms to consider coincident spikes
match_scorefloat, default: 0.5: Minimum agreement score to match units
chance_scorefloat, default: 0.1: Minimum agreement score to for a possible match
agreement_method“count” | “distance”, default: “count”: The method to compute agreement scores. The “count” method computes agreement scores from spike counts. The “distance” method computes agreement scores from spike time distance functions.
verbosebool, default: False: If True, output is verbose

Returns:

sorting_comparisonSortingComparison: 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, agreement_method='count', 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_listlist

List of sorting extractor objects to be compared

name_listlist, default: None

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

delta_timefloat, default: 0.4

Number of ms to consider coincident spikes

match_scorefloat, default: 0.5

Minimum agreement score to match units

chance_scorefloat, default: 0.1

Minimum agreement score to for a possible match

agreement_method“count” | “distance”, default: “count”

The method to compute agreement scores. The “count” method computes agreement scores from spike counts. The “distance” method computes agreement scores from spike time distance functions.

n_jobsint, 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

verbosebool, default: False

If True, output is verbose

do_matchingbool, default: True

If True, the comparison is done when the MultiSortingComparison is initialized

Returns:

multi_sorting_comparisonMultiSortingComparison: MultiSortingComparison object with the multiple sorter comparison

spikeinterface.comparison.compare_sorter_to_ground_truth(gt_sorting: BaseSorting, tested_sorting: BaseSorting, gt_name: str | None = None, tested_name: str | None = None, delta_time: float = 0.4, match_score: float = 0.5, well_detected_score: float = 0.8, redundant_score: float = 0.2, overmerged_score: float = 0.2, chance_score: float = 0.1, exhaustive_gt: bool = False, agreement_method: str = 'count', match_mode: str = 'hungarian', compute_labels: bool = False, compute_misclassifications: bool = False, verbose: bool = 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_sortingBaseSorting: The first sorting for the comparison
tested_sortingBaseSorting: The second sorting for the comparison
gt_namestr, default: None: The name of sorter 1
tested_name: str, default: None: The name of sorter 2
delta_timefloat, default: 0.4: Number of ms to consider coincident spikes. This means that two spikes are considered simultaneous if they are within delta_time of each other or mathematically abs(spike1_time - spike2_time) <= delta_time.
match_scorefloat, default: 0.5: Minimum agreement score to match units
chance_scorefloat, default: 0.1: Minimum agreement score to for a possible match
redundant_scorefloat, default: 0.2: Agreement score above which units are redundant
overmerged_scorefloat, default: 0.2: Agreement score above which units can be overmerged
well_detected_scorefloat, default: 0.8: Agreement score above which units are well detected
exhaustive_gtbool, 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
agreement_method“count” | “distance”, default: “count”: The method to compute agreement scores. The “count” method computes agreement scores from spike counts. The “distance” method computes agreement scores from spike time distance functions.
compute_labelsbool, default: False: If True, labels are computed at instantiation
compute_misclassificationsbool, default: False: If True, misclassifications are computed at instantiation
verbosebool, default: False: If True, output is verbose

Returns:

sorting_comparisonSortingComparison: The SortingComparison object

spikeinterface.comparison.compare_templates(sorting_analyzer_1, sorting_analyzer_2, name1=None, name2=None, unit_ids1=None, unit_ids2=None, match_score=0.7, chance_score=0.3, similarity_method='cosine', support='union', num_shifts=0, verbose=False)

Compares units from different sessions based on template similarity

Parameters:

sorting_analyzer_1SortingAnalyzer: The first SortingAnalyzer to get templates to compare.
sorting_analyzer_2SortingAnalyzer: The second SortingAnalyzer to get templates to compare.
unit_ids1list, default: None: List of units from sorting_analyzer_1 to compare.
unit_ids2list, default: None: List of units from sorting_analyzer_2 to compare.
name1str, default: “sess1”: Name of first session.
name2str, default: “sess2”: Name of second session.
similarity_method“cosine” | “l1” | “l2”, default: “cosine”: Method for the similarity matrix.
support“dense” | “union” | “intersection”, default: “union”: The support to compute the similarity matrix.
num_shiftsint, default: 0: Number of shifts to use to shift templates to maximize similarity.
verbosebool, default: False: If True, output is verbose.
chance_scorefloat, default: 0.3: Minimum agreement score to for a possible match
match_scorefloat, default: 0.7: Minimum agreement score to match units

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', support='union', num_shifts=0, 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_listlist: List of waveform extractor objects to be compared
name_listlist, default: None: List of session names. If not given, sorters are named as “sess0”, “sess1”, “sess2”, etc.
match_scorefloat, default: 0.8: Minimum agreement score to match units
chance_scorefloat, default: 0.3: Minimum agreement score to for a possible match
verbosebool, default: False: If True, output is verbose
do_matchingbool, default: True: If True, the comparison is done when the MultiSortingComparison is initialized
support“dense” | “union” | “intersection”, default: “union”: The support to compute the similarity matrix.
num_shiftsint, default: 0: Number of shifts to use to shift templates to maximize similarity.
similarity_method“cosine” | “l1” | “l2”, default: “cosine”: Method for the similarity matrix.

Returns:

multi_template_comparisonMultiTemplateComparison: MultiTemplateComparison object with the multiple template comparisons

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

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

Parameters:

parent_recordingBaseRecording: Existing recording to add on top of.
templatesnp.ndarray[n_units, n_samples, n_channels]: Array containing the templates to inject for all the units.
injected_sortingBaseSorting | None:: The sorting for the injected units. If None, will be generated using the following parameters.
nbeforelist[int] | int | None: Where is the center of the template for each unit? If None, will default to the highest peak.
firing_ratefloat: The firing rate of the injected units (in Hz).
amplitude_factornp.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_stdfloat: The standard deviation of the amplitude (centered at 1.0).
refractory_period_msfloat: The refractory period of the injected spike train (in ms).
injected_sorting_folderstr | 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.
seedint, default: None: Random seed for amplitude_factor

Returns:

hybrid_units_recordingHybridUnitsRecording: The recording containing real and hybrid units.

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

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

Parameters:

wvf_extractorWaveformExtractor: The waveform extractor object of the existing recording.
injected_sortingBaseSorting | None: Additional spikes to inject. If None, will generate it.
max_injected_per_unitint: If injected_sorting=None, the max number of spikes per unit that is allowed to be injected.
unit_idslist[int] | None: unit_ids to take in the wvf_extractor for spikes injection.
injected_ratefloat: If injected_sorting=None, the max fraction of spikes per unit that is allowed to be injected.
refractory_period_msfloat: If injected_sorting=None, the injected spikes need to respect this refractory period.
injected_sorting_folderstr | 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_recordingHybridSpikesRecording:: The recording containing units with real and hybrid spikes.

class spikeinterface.comparison.GroundTruthComparison(gt_sorting: BaseSorting, tested_sorting: BaseSorting, gt_name: str | None = None, tested_name: str | None = None, delta_time: float = 0.4, match_score: float = 0.5, well_detected_score: float = 0.8, redundant_score: float = 0.2, overmerged_score: float = 0.2, chance_score: float = 0.1, exhaustive_gt: bool = False, agreement_method: str = 'count', match_mode: str = 'hungarian', compute_labels: bool = False, compute_misclassifications: bool = False, verbose: bool = 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_sortingBaseSorting: The first sorting for the comparison
tested_sortingBaseSorting: The second sorting for the comparison
gt_namestr, default: None: The name of sorter 1
tested_name: str, default: None: The name of sorter 2
delta_timefloat, default: 0.4: Number of ms to consider coincident spikes. This means that two spikes are considered simultaneous if they are within delta_time of each other or mathematically abs(spike1_time - spike2_time) <= delta_time.
match_scorefloat, default: 0.5: Minimum agreement score to match units
chance_scorefloat, default: 0.1: Minimum agreement score to for a possible match
redundant_scorefloat, default: 0.2: Agreement score above which units are redundant
overmerged_scorefloat, default: 0.2: Agreement score above which units can be overmerged
well_detected_scorefloat, default: 0.8: Agreement score above which units are well detected
exhaustive_gtbool, 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
agreement_method“count” | “distance”, default: “count”: The method to compute agreement scores. The “count” method computes agreement scores from spike counts. The “distance” method computes agreement scores from spike time distance functions.
compute_labelsbool, default: False: If True, labels are computed at instantiation
compute_misclassificationsbool, default: False: If True, misclassifications are computed at instantiation
verbosebool, default: False: If True, output is verbose

Returns:

sorting_comparisonSortingComparison: The SortingComparison object

count_bad_units(): See get_bad_units

count_false_positive_units(redundant_score=None)

See get_false_positive_units().

Parameters:

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

count_overmerged_units(overmerged_score=None)

See get_overmerged_units().

Parameters:

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

count_redundant_units(redundant_score=None)

See get_redundant_units().

Parameters:

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

count_well_detected_units(well_detected_score)

Count how many well detected units. kwargs are the same as get_well_detected_units.

Parameters:

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

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_matrixpandas.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_scorefloat, 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_scorefloat, 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:

perfpandas 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_scorefloat, 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_scorefloat, 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

Parameters:

method“by_unit” | “pooled_with_average”, default: “pooled_with_average”: The method to compute performance

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.

Parameters:

well_detected_scorefloat, default: None: The agreement score above which tested units are counted as “well detected”.
redundant_scorefloat, default: None: The agreement score below which tested units are counted as “false positive”” (and not “redundant”).
overmerged_scorefloat, default: None: Tested units with 2 or more agreement scores above “overmerged_score” are counted as “overmerged”.

class spikeinterface.comparison.SymmetricSortingComparison(sorting1: BaseSorting, sorting2: BaseSorting, sorting1_name: str | None = None, sorting2_name: str | None = None, delta_time: float = 0.4, match_score: float = 0.5, chance_score: float = 0.1, agreement_method: str = 'count', verbose: bool = 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:

sorting1BaseSorting: The first sorting for the comparison
sorting2BaseSorting: The second sorting for the comparison
sorting1_namestr, default: None: The name of sorter 1
sorting2_name: str, default: None: The name of sorter 2
delta_timefloat, default: 0.4: Number of ms to consider coincident spikes
match_scorefloat, default: 0.5: Minimum agreement score to match units
chance_scorefloat, default: 0.1: Minimum agreement score to for a possible match
agreement_method“count” | “distance”, default: “count”: The method to compute agreement scores. The “count” method computes agreement scores from spike counts. The “distance” method computes agreement scores from spike time distance functions.
verbosebool, default: False: If True, output is verbose

Returns:

sorting_comparisonSortingComparison: 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)

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

class spikeinterface.comparison.MultiSortingComparison(sorting_list, name_list=None, delta_time=0.4, match_score=0.5, chance_score=0.1, agreement_method='count', 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_listlist

List of sorting extractor objects to be compared

name_listlist, default: None

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

delta_timefloat, default: 0.4

Number of ms to consider coincident spikes

match_scorefloat, default: 0.5

Minimum agreement score to match units

chance_scorefloat, default: 0.1

Minimum agreement score to for a possible match

agreement_method“count” | “distance”, default: “count”

The method to compute agreement scores. The “count” method computes agreement scores from spike counts. The “distance” method computes agreement scores from spike time distance functions.

n_jobsint, 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

verbosebool, default: False

If True, output is verbose

do_matchingbool, default: True

If True, the comparison is done when the MultiSortingComparison is initialized

Returns:

multi_sorting_comparisonMultiSortingComparison: 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_countint: Minimum number of matches among sorters to include a unit.
minimum_agreement_count_onlybool: If True, only units with agreement == “minimum_matching” are included. If False, units with an agreement >= “minimum_matching” are included

Returns:

agreement_sortingAgreementSortingExtractor: 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.

Parameters:

gt_sortingBaseSorting: The first sorting for the comparison
collision_lagfloat, default 2.0: Collision lag in ms.
tested_sortingBaseSorting: The second sorting for the comparison
nbinsint, default11: Number of collision bins
**kwargsdict: Keyword arguments for GroundTruthComparison

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.

Parameters:

gt_sortingBaseSorting: The first sorting for the comparison
tested_sortingBaseSorting: The second sorting for the comparison
bin_msfloat, default: 1.0: Size of bin for correlograms
window_msfloat, default: 100.0: The window around the spike to compute the correlation in ms.
well_detected_scorefloat, default: 0.8: Agreement score above which units are well detected
**kwargsdict: Keyword arguments for GroundTruthComparison

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_comparisonGroundTruthComparison or SymmetricSortingComparison

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

orderedbool, default: True: Order units with best agreement scores. If True, agreement scores can be seen along a diagonal
count_textbool, default: True: If True counts are displayed as text
unit_ticksbool, 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_all_amplitudes_distributions(sorting_analyzer: SortingAnalyzer, unit_ids=None, unit_colors=None, backend=None, **backend_kwargs)

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

Parameters:

sorting_analyzerSortingAnalyzer

The SortingAnalyzer

unit_idslist: List of unit ids, default None
unit_colorsdict | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_amplitudes(sorting_analyzer: SortingAnalyzer, unit_ids=None, unit_colors=None, segment_index=None, max_spikes_per_unit=None, y_lim=None, scatter_decimate=1, hide_unit_selector=False, plot_histograms=False, bins=None, plot_legend=True, backend=None, **backend_kwargs)

Plots spike amplitudes

Parameters:

sorting_analyzerSortingAnalyzer

The input waveform extractor

unit_idslist or None, default: None: List of unit ids
unit_colorsdict | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.
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
y_limtuple or None, default: None: The min and max depth to display, if None (min and max of the amplitudes).
scatter_decimateint, default: 1: If equal to n, each nth spike is kept for plotting.
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, uses 100 bins.
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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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

Plots unit cross correlograms.

Parameters:

sorting_analyzer_or_sortingSortingAnalyzer 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. For auto-correlograms plot, this is automatically set to None.
window_msfloat, default: 100.0: Window for CCGs in ms. If correlograms are already computed (e.g. with SortingAnalyzer), this argument is ignored
bin_msfloat, default: 1.0: Bin size in ms. If correlograms are already computed (e.g. with SortingAnalyzer), this argument is ignored
hide_unit_selectorbool, default: False: For sortingview backend, if True the unit selector is not displayed
unit_colorsdict | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.

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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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

Plots sorting comparison confusion matrix.

Parameters:

gt_comparisonGroundTruthComparison

The ground truth sorting comparison object

count_textbool: If True counts are displayed as text
unit_ticksbool: 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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:

compCollisionGTComparison

The collision ground truth comparison object

templatesarray: template of units
mode“heatmap” or “lines”: to see collision curves for every pairs (“heatmap”) or as lines averaged over pairs.
similarity_binsarray: if mode is “lines”, the bins used to average the pairs
cmapstring: colormap used to show averages if mode is “lines”
metric“cosine_similarity”: metric for ordering
good_onlyTrue: keep only the pairs with a non zero accuracy (found templates)
min_accuracyfloat: If good only, the minimum accuracy every cell should have, individually, to be considered in a putative pair
unit_idslist: 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_crosscorrelograms(sorting_analyzer_or_sorting: SortingAnalyzer | 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:

sorting_analyzer_or_sortingSortingAnalyzer 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. For auto-correlograms plot, this is automatically set to None.
window_msfloat, default: 100.0: Window for CCGs in ms. If correlograms are already computed (e.g. with SortingAnalyzer), this argument is ignored
bin_msfloat, default: 1.0: Bin size in ms. If correlograms are already computed (e.g. with SortingAnalyzer), this argument is ignored
hide_unit_selectorbool, default: False: For sortingview backend, if True the unit selector is not displayed
unit_colorsdict | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.

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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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:

sortingSortingExtractor

The sorting extractor object

unit_idslist: List of unit ids
bins_msint: Bin size in ms
window_msfloat: 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_motion(motion: Motion, segment_index: int | None = None, mode: str = 'line', motion_lim: float | None = None, backend: str | None = None, **backend_kwargs)

Plot the Motion object.

Parameters:

motionMotion

The motion object.

segment_indexint | None, default: None: If Motion is multi segment, the must be not None.
mode“auto” | “line” | “map”, default: “line”: How to plot the motion. “line” plots estimated motion at different depths as lines. “map” plots estimated motion at different depths as a heatmap. “auto” makes it automatic depending on the number of motion depths.

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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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_comparisonBaseMultiComparison

The multi comparison object

plot_type“pie” | “bar”, default: “pie”: The plot type
cmapmatplotlib colormap, default: “YlOrRd”: The colormap to be used for the nodes
fontsizeint, default: 9: The text fontsize
show_legendbool, 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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_comparisonBaseMultiComparison

The multi comparison object

plot_type“pie” | “bar”, default: “pie: The plot type
cmapmatplotlib colormap, default: “Reds”: The colormap to be used for the nodes
fontsizeint, default: 9: The text fontsize
show_legendbool: 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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_comparisonBaseMultiComparison

The multi comparison object

draw_labelsbool, default: False: If True unit labels are shown
node_cmapmatplotlib colormap, default: “viridis”: The colormap to be used for the nodes
edge_cmapmatplotlib colormap, default: “hot”: The colormap to be used for the edges
alpha_edgesfloat, default: 0.5: Alpha value for edges
colorbarbool, 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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, color_range=None, 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:

recordingRecordingExtractor

The recording extractor object.

peaksnumpy array with peak_dtype: The pre detected peaks (with the detect_peaks() function).
bin_duration_sNone or float, default: None: If None then static image If not None then it is an animation per bin.
with_contact_colorbool, default: True: Plot rates with contact colors
with_interpolated_mapbool, default: True: Plot rates with interpolated map
with_channel_idsbool, default: False: Add channel ids text on the probe
color_rangetuple | list | None, default: None: Sets the color bar range when animating or plotting. When None, uses the min-max of the entire time-series via imshow defaults. If tuple/list, the length must be 2 representing the range.

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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_probe_map(recording, color_channels=None, with_channel_ids=False, backend=None, **backend_or_plot_probe_kwargs)

Plot the probe of a recording.

Parameters:

recordingRecordingExtractor

The recording extractor object

color_channelslist or matplotlib color: List of colors to be associated with each channel_id, if only one color is present all channels will take the specified color
with_channel_idsbool 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_quality_metrics(sorting_analyzer: SortingAnalyzer, 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:

sorting_analyzerSortingAnalyzer

The object to get quality metrics from

unit_idslist or None, default: None: List of unit ids
include_metricslist or None, default: None: If given, a list of quality metrics to include
skip_metricslist or None, default: None: If given, a list of quality metrics to skip
unit_colorsdict | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.
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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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

Plots spike train rasters.

Parameters:

sortingSortingExtractor | None, default: None

A sorting object

sorting_analyzerSortingAnalyzer | None, default: None: A sorting analyzer object
segment_indexNone or int: The segment index.
unit_idslist: List of unit ids
time_rangelist: List with start time and end time
colormatplotlib color: The color to be used

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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_sorting_summary(sorting_analyzer: SortingAnalyzer, unit_ids=None, sparsity=None, max_amplitudes_per_unit=None, min_similarity_for_correlograms=0.2, curation=False, displayed_unit_properties=None, extra_unit_properties=None, label_choices=None, curation_dict=None, label_definitions=None, backend=None, unit_table_properties=None, **backend_kwargs)

Plots spike sorting summary. This is the main viewer to visualize the final result with several sub view. This use sortingview (in a web browser) or spikeinterface-gui (with Qt).

Parameters:

sorting_analyzerSortingAnalyzer

The SortingAnalyzer object

unit_idslist or None, default: None: List of unit ids
sparsityChannelSparsity or None, default: None: Optional ChannelSparsity to apply If SortingAnalyzer 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)
displayed_unit_propertieslist or None, default: None: List of properties to be added to the unit table. These may be drawn from the sorting extractor, and, if available, the quality_metrics/template_metrics/unit_locations extensions of the SortingAnalyzer. See all properties available with sorting.get_property_keys(), and, if available, analyzer.get_extension(“quality_metrics”).get_data().columns and analyzer.get_extension(“template_metrics”).get_data().columns.
extra_unit_propertiesdict or None, default: None: A dict with extra units properties to display. The key is the property name and the value must be a numpy.array.
curation_dictdict or None, default: None: When curation is True, optionaly the viewer can get a previous ‘curation_dict’ to continue/check previous curations on this analyzer. In this case label_definitions must be None beacuse it is already included in the curation_dict. (spikeinterface_gui backend)
label_definitionsdict or None, default: None: When curation is True, optionaly the user can provide a label_definitions dict. This replaces the label_choices in the curation_format. (spikeinterface_gui backend)

backend: str

sortingview
spikeinterface_gui

**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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_spike_locations(sorting_analyzer: SortingAnalyzer, 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:

sorting_analyzerSortingAnalyzer

The object to 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 | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.
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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_spikes_on_traces(sorting_analyzer: SortingAnalyzer, 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, scale=1, spike_width_ms=4, spike_height_um=20, with_colorbar=True, backend=None, **backend_kwargs)

Plots unit spikes/waveforms over traces.

Parameters:

sorting_analyzerSortingAnalyzer

The SortingAnalyzer

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_rangelist or None, default: None

List with start time and end time in seconds

sparsityChannelSparsity or None, default: None

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

unit_colorsdict | None, default: None

Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.

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

scalefloat, default: 1

Scale factor for the traces

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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_template_metrics(sorting_analyzer: SortingAnalyzer, 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:

sorting_analyzerSortingAnalyzer

The object to get quality 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 | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.
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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_template_similarity(sorting_analyzer: SortingAnalyzer, 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:

sorting_analyzerSortingAnalyzer

The object to 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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, events=None, events_color='gray', events_alpha=0.5, color_groups=False, color=None, clim=None, tile_size=1500, seconds_per_row=0.2, scale=1, vspacing_factor=1.5, with_colorbar=True, add_legend=True, backend=None, **backend_kwargs)

Plots recording timeseries.

Parameters:

recordingRecordingExtractor, 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_indexNone or int, default: None: The segment index (required for multi-segment recordings)
channel_idslist or None, default: None: The channel ids to display
order_channel_by_depthbool, default: False: Reorder channel by depth
time_rangelist, 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_scaledbool, default: False: If True and the recording has scaled traces, it plots the scaled traces
eventsnp.array | list[np.narray] or None, default: None: Events to display as vertical lines. The numpy arrays cen either be of dtype float, with event times in seconds, or a structured array with the “time” field, and optional “duration” and “label” fields. For multi-segment recordings, provide a list of numpy array events, one for each segment.
cmapmatplotlib colormap, default: “RdBu_r”: 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
scalefloat, default: 1: Scale factor for the traces
vspacing_factorfloat, default: 1.5: Vertical spacing between channels as a multiple of maximum channel amplitude
with_colorbarbool, default: True: When mode is “map”, a colorbar is added
tile_sizeint, default: 1500: 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
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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_unit_depths(sorting_analyzer, unit_colors=None, depth_axis=1, peak_sign='neg', backend=None, **backend_kwargs)

Plot unit depths

Parameters:

sorting_analyzerSortingAnalyzer

The SortingAnalyzer object

unit_colorsdict | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.
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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_unit_locations(sorting_analyzer: SortingAnalyzer, unit_ids: list | None = None, with_channel_ids: bool = False, unit_colors: dict | None = None, hide_unit_selector: bool = False, plot_all_units: bool = True, plot_legend: bool = False, hide_axis: bool = False, backend: str | None = None, margin: float = 50, **backend_kwargs)

Plots each unit’s location.

Parameters:

sorting_analyzerSortingAnalyzer

The SortingAnalyzer that must contains “unit_locations” extension

unit_idslist or None, default: None: List of unit ids
with_channel_idsbool, default: False: Add channel ids text on the probe
unit_colorsdict | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.
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)
marginfloat, default: 50: Amount of margin to add to plot, beyond the extremum unit locations.

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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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:

sortingSortingExtractor

The sorting extractor object

segment_indexNone or int: The segment index.
time_rangelist or None, default: None: List with start time and end time
bin_duration_sfloat, default: 0.5: Bin size (in seconds) for the heat map time axis
smooth_sigmafloat, 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_unit_probe_map(sorting_analyzer, 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:

sorting_analyzerSortingAnalyzer

unit_idslist: List of unit ids.
channel_idslist: The channel ids to display
animatedbool, default: False: Animation for amplitude on time
with_channel_idsbool, 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_unit_summary(sorting_analyzer, unit_id, unit_colors=None, sparsity=None, subwidget_kwargs=None, backend=None, **backend_kwargs)

Plot a unit summary.

If amplitudes are alreday computed, they are displayed.

Parameters:

sorting_analyzerSortingAnalyzer

The SortingAnalyzer object

unit_idint or str

The unit id to plot the summary of

unit_colorsdict | None, default: None

Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.

sparsityChannelSparsity or None, default: None

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

subwidget_kwargsdict or None, default: None

Parameters for the subwidgets in a nested dictionary

unit_locations : UnitLocationsWidget (see UnitLocationsWidget for details)

unit_waveforms : UnitWaveformsWidget (see UnitWaveformsWidget for details)

unit_waveform_density_map : UnitWaveformDensityMapWidget (see UnitWaveformDensityMapWidget for details)

autocorrelograms : AutoCorrelogramsWidget (see AutoCorrelogramsWidget for details)

amplitudes : AmplitudesWidget (see AmplitudesWidget for details)

Please note that the unit_colors should not be set in subwidget_kwargs, but directly as a parameter of plot_unit_summary.

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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_unit_templates(*args, **kargs)

Plots unit waveforms.

Parameters:

sorting_analyzer_or_templatesSortingAnalyzer | Templates

The SortingAnalyzer or Templates object. If Templates is given, the “plot_waveforms” argument is set to False

channel_idslist 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 SortingAnalyzer 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)
widen_narrow_scalefloat, default: 1: Scale factor for the x-axis of 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_colorsdict | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.
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, tuple/list of floats, or None, default: (1, 25, 75, 99): 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.
scalebarbool, default: False: Display a scale bar on the waveforms plot (matplotlib backend)
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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_unit_waveforms_density_map(sorting_analyzer, 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:

sorting_analyzerSortingAnalyzer

The SortingAnalyzer 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 SortingAnalyzer 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_colorsdict | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.
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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_unit_waveforms(sorting_analyzer_or_templates: SortingAnalyzer | Templates, channel_ids=None, unit_ids=None, plot_waveforms=True, plot_templates=True, plot_channels=False, unit_colors=None, sparsity=None, ncols=5, scale=1, widen_narrow_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, 99), scalebar=False, 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:

sorting_analyzer_or_templatesSortingAnalyzer | Templates

The SortingAnalyzer or Templates object. If Templates is given, the “plot_waveforms” argument is set to False

channel_idslist 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 SortingAnalyzer 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)
widen_narrow_scalefloat, default: 1: Scale factor for the x-axis of 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_colorsdict | None, default: None: Dict of colors with unit ids as keys and colors as values. Colors can be any type accepted by matplotlib. If None, default colors are chosen using the get_some_colors function.
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, tuple/list of floats, or None, default: (1, 25, 75, 99): 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.
scalebarbool, default: False: Display a scale bar on the waveforms plot (matplotlib backend)
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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_study_run_times(study, case_keys=None, backend=None, **backend_kwargs)

Plot sorter run times for a SorterStudy.

Parameters:

studySorterStudy

A study object.

case_keyslist 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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:

studySorterStudy

A study object.

case_keyslist 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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:

studyGroundTruthStudy

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_nameslist or tuple, default: (“accuracy”, “precision”, “recall”)

Which performances to plot (“accuracy”, “precision”, “recall”)

case_keyslist 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.widgets.plot_study_agreement_matrix(study, ordered=True, case_keys=None, backend=None, **backend_kwargs)

Plot agreement matrix.

Parameters:

studyGroundTruthStudy

A study object.

case_keyslist or None: A selection of cases to plot, if None, then all.
orderedbool: 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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:

studyGroundTruthStudy

A study object.

case_keyslist 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

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:

studyCollisionGTStudy

The collision study object.

case_keyslist or None: A selection of cases to plot, if None, then all.
metric“cosine_similarity”: metric for ordering
similarity_binsarray: if mode is “lines”, the bins used to average the pairs
cmapstring: colormap used to show averages if mode is “lines”
good_onlyFalse: keep only the pairs with a non zero accuracy (found templates)
min_accuracyfloat: 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.

Notes

When using the matplotlib backend, the returned BaseWidget contains the matplotlib fig and axis objects. This allows customization of plots using matplotlib machinery e.g. returned_widget.ax.set_xlim((0,100)).

spikeinterface.exporters

spikeinterface.exporters.export_to_phy(sorting_analyzer: SortingAnalyzer, output_folder: str | Path, compute_pc_features: bool = True, compute_amplitudes: bool = True, sparsity: ChannelSparsity | None = None, copy_binary: bool = True, remove_if_exists: bool = False, template_mode: str = 'average', add_quality_metrics: bool = True, add_template_metrics: bool = True, additional_properties: list | None = None, dtype: dtype[Any] | None | type[Any] | _SupportsDType[dtype[Any]] | str | tuple[Any, int] | tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | list[Any] | _DTypeDict | tuple[Any, Any] = None, verbose: bool = True, use_relative_path: bool = False, **job_kwargs)

Exports a sorting analyzer to the phy template-gui format.

Parameters:

sorting_analyzerSortingAnalyzer

A SortingAnalyzer object

output_folderstr | Path

The output folder where the phy template-gui files are saved

compute_pc_featuresbool, default: True

If True, pc features are computed

compute_amplitudesbool, default: True

If True, waveforms amplitudes are computed

sparsityChannelSparsity or None, default: None

The sparsity object

copy_binarybool, default: True

If True, the recording is copied and saved in the phy “output_folder”

remove_if_existsbool, default: False

If True and “output_folder” exists, it is removed and overwritten

template_modestr, default: “average”

Parameter “mode” to be given to SortingAnalyzer.get_template()

add_quality_metricsbool, default: True

If True, quality metrics (if computed) are saved as Phy tsv and will appear in the ClusterView.

add_template_metricsbool, default: True

If True, template metrics (if computed) are saved as Phy tsv and will appear in the ClusterView.

additional_propertieslist | None, default: None

List of additional properties to be saved as Phy tsv and will appear in the ClusterView.

dtypedtype or None, default: None

Dtype to save binary data

verbosebool, 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_kwargskeyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_sizeint
  Number of samples per chunk
- chunk_memorystr
  Memory usage for each job (e.g. “100M”, “1G”, “500MiB”, “2GiB”)
- total_memorystr
  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_jobsint | float
Number of jobs to use. With -1 the number of jobs is the same as number of cores. Using a float between 0 and 1 will use that fraction of the total cores.
progress_barbool
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_to_ibl_gui(sorting_analyzer: SortingAnalyzer, output_folder: str | Path, lfp_recording: BaseRecording | None = None, rms_win_length_s=3, welch_win_length_samples=16384, psd_chunk_duration_s=1, psd_num_chunks=100, good_units_query: str | None = 'amplitude_median < -40 and isi_violations_ratio < 0.5 and amplitude_cutoff < 0.2', remove_if_exists: bool = False, verbose: bool = True, **job_kwargs)

Exports a sorting analyzer to the format required by the IBL alignment GUI.

Parameters:

analyzer: SortingAnalyzer: The sorting analyzer object to use for spike information. Should also contain the pre-processed recording to use for AP-band data.
output_folder: str | Path: The output folder for the exports.
lfp_recording: BaseRecording | None, default: None: The pre-processed recording to use for LFP data. If None, the LFP data is not exported.
rms_win_length_s: float, default: 3: The window length in seconds for the RMS calculation (on the LFP data).
welch_win_length_samples: int, default: 2^14: The window length in samples for the Welch spectral density computation (on the LFP data).
psd_chunk_duration_s: float, default: 1: The chunk duration in seconds for the spectral density calculation (on the LFP data).
psd_num_chunks: int, default: 100: The number of chunks to use for the spectral density calculation (on the LFP data).
remove_if_exists: bool, default: False: If True and “output_folder” exists, it is removed and overwritten
verbose: bool, default: True: If True, output is verbose

spikeinterface.exporters.export_report(sorting_analyzer, 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. What is plotted depends on what has been calculated. Unit locations and unit waveforms are always included. Unit waveform densities, correlograms and spike amplitudes are plotted if waveforms, correlograms, and spike_amplitudes have been computed for the given sorting_analyzer.

Parameters:

sorting_analyzerSortingAnalyzer

A SortingAnalyzer object

output_folderstr

The output folder where the report files are saved

remove_if_existsbool, default: False

If True and the output folder exists, it is removed

formatstr, 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_figuresbool, default: False

If True, figures are shown. If False, figures are closed after saving

force_computationbool, default: False

Force or not some heavy computaion before exporting

**job_kwargskeyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_sizeint
  Number of samples per chunk
- chunk_memorystr
  Memory usage for each job (e.g. “100M”, “1G”, “500MiB”, “2GiB”)
- total_memorystr
  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_jobsint | float
Number of jobs to use. With -1 the number of jobs is the same as number of cores. Using a float between 0 and 1 will use that fraction of the total cores.
progress_barbool
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

spikeinterface.curation.apply_curation(sorting_or_analyzer, curation_dict, censor_ms=None, new_id_strategy='append', merging_mode='soft', sparsity_overlap=0.75, verbose=False, **job_kwargs)

Apply curation dict to a Sorting or a SortingAnalyzer.

Steps are done in this order:

Apply removal using curation_dict[“removed_units”]
Apply merges using curation_dict[“merge_unit_groups”]
Set labels using curation_dict[“manual_labels”]

A new Sorting or SortingAnalyzer (in memory) is returned. The user (an adult) has the responsability to save it somewhere (or not).

Parameters:

sorting_or_analyzerSorting | SortingAnalyzer

The Sorting object to apply merges.

curation_dictdict

The curation dict.

censor_msfloat | None, default: None

When applying the merges, any consecutive spikes within the censor_ms are removed. This can be thought of as the desired refractory period. If censor_ms=None, no spikes are discarded.

new_id_strategy“append” | “take_first”, default: “append”

The strategy that should be used, if new_unit_ids is None, to create new unit_ids.

“append” : new_units_ids will be added at the end of max(sorting.unit_ids)

“take_first” : new_unit_ids will be the first unit_id of every list of merges

merging_mode“soft” | “hard”, default: “soft”

How merges are performed for SortingAnalyzer. If the merge_mode is “soft” , merges will be approximated, with no reloading of the waveforms. This will lead to approximations. If merge_mode is “hard”, recomputations are accurately performed, reloading waveforms if needed

sparsity_overlapfloat, default 0.75

The percentage of overlap that units should share in order to accept merges. If this criteria is not achieved, soft merging will not be possible and an error will be raised. This is for use with a SortingAnalyzer input.

verbosebool, default: False

If True, output is verbose

**job_kwargsdict

Job keyword arguments for merge_units

Returns:

sorting_or_analyzerSorting | SortingAnalyzer: The curated object.

spikeinterface.curation.get_potential_auto_merge(sorting_analyzer: SortingAnalyzer, preset: str | None = 'similarity_correlograms', resolve_graph: bool = False, min_spikes: int = 100, min_snr: float = 2, max_distance_um: float = 150.0, corr_diff_thresh: float = 0.16, template_diff_thresh: float = 0.25, contamination_thresh: float = 0.2, presence_distance_thresh: float = 100, p_value: float = 0.2, cc_thresh: float = 0.1, censored_period_ms: float = 0.3, refractory_period_ms: float = 1.0, sigma_smooth_ms: float = 0.6, adaptative_window_thresh: float = 0.5, censor_correlograms_ms: float = 0.15, firing_contamination_balance: float = 1.5, k_nn: int = 10, knn_kwargs: dict | None = None, presence_distance_kwargs: dict | None = None, extra_outputs: bool = False, steps: list[str] | None = None) → list[tuple[int | str, int | str]] | Tuple[tuple[int | str, int | str], dict]

This function is deprecated. Use compute_merge_unit_groups() instead. This will be removed in 0.103.0

Algorithm to find and check potential merges between units.

The merges are proposed based on a series of steps with different criteria:

“num_spikes”: enough spikes are found in each unit for computing the correlogram (min_spikes)

“snr”: the SNR of the units is above a threshold (min_snr)

“remove_contaminated”: each unit is not contaminated (by checking auto-correlogram - contamination_thresh)

“unit_locations”: estimated unit locations are close enough (max_distance_um)

“correlogram”: the cross-correlograms of the two units are similar to each auto-corrleogram (corr_diff_thresh)

“template_similarity”: the templates of the two units are similar (template_diff_thresh)

“presence_distance”: the presence of the units is complementary in time (presence_distance_thresh)

“cross_contamination”: the cross-contamination is not significant (cc_thresh and p_value)

“knn”: the two units are close in the feature space

“quality_score”: 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)\]

IMPORTANT: internally, all computations are relying on extensions of the analyzer, that are computed with default parameters if not present (i.e. correlograms, template_similarity, …) If you want to have a finer control on these values, please precompute the extensions before applying the auto_merge

Parameters:

sorting_analyzerSortingAnalyzer

The SortingAnalyzer

preset“similarity_correlograms” | “x_contaminations” | “temporal_splits” | “feature_neighbors” | None, default: “similarity_correlograms”

The preset to use for the auto-merge. Presets combine different steps into a recipe and focus on:

“similarity_correlograms”: mainly focused on template similarity and correlograms.

It uses the following steps: “num_spikes”, “remove_contaminated”, “unit_locations”,

“template_similarity”, “correlogram”, “quality_score”
“x_contaminations”: similar to “similarity_correlograms”, but checks for cross-contamination instead of correlograms.

It uses the following steps: “num_spikes”, “remove_contaminated”, “unit_locations”,

“template_similarity”, “cross_contamination”, “quality_score”
“temporal_splits”: focused on finding temporal splits using presence distance.

It uses the following steps: “num_spikes”, “remove_contaminated”, “unit_locations”,

“template_similarity”, “presence_distance”, “quality_score”
“feature_neighbors”: focused on finding unit pairs whose spikes are close in the feature space using kNN.

It uses the following steps: “num_spikes”, “snr”, “remove_contaminated”, “unit_locations”,

“knn”, “quality_score”

If preset is None, you can specify the steps manually with the steps parameter.

resolve_graphbool, default: False

If True, the function resolves the potential unit pairs to be merged into multiple-unit merges.

min_spikesint, default: 100

Minimum number of spikes for each unit to consider a potential merge. Enough spikes are needed to estimate the correlogram

min_snrfloat, default 2

Minimum Signal to Noise ratio for templates to be considered while merging

max_distance_umfloat, default: 150

Maximum distance between units for considering a merge

corr_diff_threshfloat, default: 0.16

The threshold on the “correlogram distance metric” for considering a merge. It needs to be between 0 and 1

template_diff_threshfloat, default: 0.25

The threshold on the “template distance metric” for considering a merge. It needs to be between 0 and 1

contamination_threshfloat, default: 0.2

Threshold for not taking in account a unit when it is too contaminated.

presence_distance_threshfloat, default: 100

Parameter to control how present two units should be simultaneously.

p_valuefloat, default: 0.2

The p-value threshold for the cross-contamination test.

cc_threshfloat, default: 0.1

The threshold on the cross-contamination for considering a merge.

censored_period_msfloat, default: 0.3

Used to compute the refractory period violations aka “contamination”.

refractory_period_msfloat, default: 1

Used to compute the refractory period violations aka “contamination”.

sigma_smooth_msfloat, default: 0.6

Parameters to smooth the correlogram estimation.

adaptative_window_threshfloat, default: 0.5

Parameter to detect the window size in correlogram estimation.

censor_correlograms_msfloat, default: 0.15

The period to censor on the auto and cross-correlograms.

firing_contamination_balancefloat, default: 1.5

Parameter to control the balance between firing rate and contamination in computing unit “quality score”.

k_nnint, default 5

The number of neighbors to consider for every spike in the recording.

knn_kwargsdict, default None

The dict of extra params to be passed to knn.

extra_outputsbool, default: False

If True, an additional dictionary (outs) with processed data is returned.

stepsNone or list of str, default: None

Which steps to run, if no preset is used. Pontential steps : “num_spikes”, “snr”, “remove_contaminated”, “unit_locations”, “correlogram”, “template_similarity”, “presence_distance”, “cross_contamination”, “knn”, “quality_score” Please check steps explanations above!

presence_distance_kwargsNone|dict, default: None

A dictionary of kwargs to be passed to compute_presence_distance().

Returns:

potential_merges:: A list of tuples of 2 elements (if resolve_graph`if false) or 2+ elements (if `resolve_graph is true). List of pairs that could be merged.
outs:: Returned only when extra_outputs=True A dictionary that contains data for debugging and plotting.

References

This function is inspired and built upon similar functions from Lussac [Llobet], done by Aurelien Wyngaard and Victor Llobet. https://github.com/BarbourLab/lussac/blob/v1.0.0/postprocessing/merge_units.py

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_sorting_analyzer, 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) → BaseSorting

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_sorting_analyzerBaseSorting or SortingAnalyzer

If SortingAnalyzer, 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 SortingAnalyzer 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_outputsbool, default: False

If True, will return the redundant pairs.

unit_peak_shiftsdict

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:

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:

sortingBaseSorting: The parent sorting.
censored_period_msfloat: 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_spikesRemove_DuplicatedSpikesSorting: The sorting without any duplicated spikes.

spikeinterface.curation.remove_excess_spikes(sorting: BaseSorting, recording: BaseRecording)

Remove excess spikes from the spike trains. Excess spikes are the ones exceeding a recording number of samples, for each segment.

Parameters:

sortingBaseSorting: The parent sorting.
recordingBaseRecording: The recording to use to get the number of samples.

Returns:

sorting_without_excess_spikesSorting: The sorting without any excess spikes.

spikeinterface.curation.load_model(model_folder=None, repo_id=None, model_name=None, trust_model=False, trusted=None)

Loads a model and model_info from a HuggingFaceHub repo or a local folder.

Parameters:

model_folderstr or Path, defualt: None: The path to the folder containing the model
repo_idstr | Path, default: None: Hugging face repo id which contains the model e.g. ‘username/model’
model_name: str | Path, default: None: Filename of model e.g. ‘my_model.skops’. If None, uses first model found.
trust_modelbool, default: False: Whether to trust the model. If True, the trusted parameter that is passed to skops.load to load the model will be automatically inferred. If False, the trusted parameter must be provided to indicate the trusted objects.
trustedlist of str, default: None: Passed to skops.load. The object will be loaded only if there are only trusted objects and objects of types listed in trusted in the dumped file.

Returns:

model, model_info: A model and metadata about the model

spikeinterface.curation.auto_label_units(sorting_analyzer: SortingAnalyzer, model_folder=None, model_name=None, repo_id=None, label_conversion=None, trust_model=False, trusted=None, export_to_phy=False, enforce_metric_params=False)

Automatically labels units based on a model-based classification, either from a model hosted on HuggingFaceHub or one available in a local folder.

This function returns the predicted labels and the prediction probabilities, and populates the sorting object with the predicted labels and probabilities in the ‘classifier_label’ and ‘classifier_probability’ properties.

Parameters:

sorting_analyzerSortingAnalyzer: The sorting analyzer object containing the spike sorting results.
model_folderstr or Path, defualt: None: The path to the folder containing the model
repo_idstr | Path, default: None: Hugging face repo id which contains the model e.g. ‘username/model’
model_name: str | Path, default: None: Filename of model e.g. ‘my_model.skops’. If None, uses first model found.
label_conversiondic | None, default: None: A dictionary for converting the predicted labels (which are integers) to custom labels. If None, tries to extract from model_info.json file. The dictionary should have the format {old_label: new_label}.
export_to_phybool, default: False: Whether to export the results to Phy format. Default is False.
trust_modelbool, default: False: Whether to trust the model. If True, the trusted parameter that is passed to skops.load to load the model will be automatically inferred. If False, the trusted parameter must be provided to indicate the trusted objects.
trustedlist of str, default: None: Passed to skops.load. The object will be loaded only if there are only trusted objects and objects of types listed in trusted in the dumped file.
enforce_metric_paramsbool, default: False: If True and the parameters used to compute the metrics in sorting_analyzer are different than the parmeters used to compute the metrics used to train the model, this function will raise an error. Otherwise, a warning is raised.

Returns:

classified_unitspd.DataFrame: A dataframe containing the classified units, indexed by the unit_ids, containing the predicted label and confidence probability of each labelled unit.

Raises:

ValueError: If the pipeline is not an instance of sklearn.pipeline.Pipeline.

spikeinterface.curation.train_model(mode='analyzers', labels=None, analyzers=None, metrics_paths=None, folder=None, metric_names=None, imputation_strategies=None, scaling_techniques=None, classifiers=None, test_size=0.2, overwrite=False, seed=None, search_kwargs=None, verbose=True, enforce_metric_params=False, **job_kwargs)

Trains and evaluates machine learning models for spike sorting curation.

This function initializes a CurationModelTrainer object, loads and preprocesses the data, and evaluates the specified combinations of imputation strategies, scaling techniques, and classifiers. The evaluation results, including the best model and its parameters, are saved to the output folder.

Parameters:

mode"analyzers" | "csv", default: "analyzers": Mode to use for training.
analyzerslist of SortingAnalyzer | None, default: None: List of SortingAnalyzer objects containing the quality metrics and labels to use for training, if using "analyzers" mode.
labelslist of list | None, default: None: List of curated labels for each unit; must be in the same order as the metrics data.
metrics_pathslist of str or None, default: None: List of paths to the CSV files containing the metrics data if using "csv" mode.
folderstr | None, default: None: The folder where outputs such as models and evaluation metrics will be saved.
metric_nameslist of str | None, default: None: A list of metrics to use for training. If None, default metrics will be used.
imputation_strategieslist of str | None, default: None: A list of imputation strategies to try. Can be "knn", "iterative", or any allowed strategy passable to the sklearn.SimpleImputer. If None, the default strategies ["median", "most_frequent", "knn", "iterative"] will be used.
scaling_techniqueslist of str | None, default: None: A list of scaling techniques to try. Can be "standard_scaler", "min_max_scaler", or "robust_scaler". If None, all techniques will be used.
classifierslist of str | dict | None, default: None: A list of classifiers to evaluate. Optionally, a dictionary of classifiers and their hyperparameter search spaces can be provided. If None, default classifiers will be used. Check the get_classifier_search_space method for the default search spaces & format for custom spaces.
test_sizefloat, default: 0.2: Proportion of the dataset to include in the test split, passed to train_test_split from sklearn.
overwritebool, default: False: Overwrites the folder if it already exists.
seedint | None, default: None: Random seed for reproducibility. If None, a random seed will be generated.
search_kwargsdict or None, default: None: Keyword arguments passed to BayesSearchCV or RandomizedSearchCV from sklearn. If None, use search_kwargs = {'cv': 3, 'scoring': 'balanced_accuracy', 'n_iter': 25}.
verbosebool, default: True: If True, useful information is printed during training.
enforce_metric_paramsbool, default: False: If True and metric parameters used to calculate metrics for different sorting_analyzer objects are different, an error will be raised.

Returns:

CurationModelTrainer: The CurationModelTrainer object used for training and evaluation.

Notes

This function handles the entire workflow of initializing the trainer, loading and preprocessing the data, and evaluating the models. The evaluation results are saved to the specified output folder.

Deprecated

spikeinterface.curation.apply_sortingview_curation(sorting_or_analyzer, uri_or_json, exclude_labels=None, include_labels=None, skip_merge=False, verbose=None)

Apply curation from SortingView manual legacy curation format (before the official “curation_format”)

First, merges (if present) are applied. Then labels are loaded and units are optionally filtered based on exclude_labels and include_labels.

Parameters:

sorting_or_analyzerSorting | SortingAnalyzer: The sorting or analyzer 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)
verboseNone: Deprecated

Returns:

sorting_or_analyzer_curatedBaseSorting: The curated sorting or analyzer

class spikeinterface.curation.CurationSorting(sorting, make_graph=False, properties_policy='keep')

Class that handles curation of a Sorting object.

Parameters:

sortingBaseSorting: The sorting 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_graphbool: True to keep a Networkx graph instance with the curation history

Returns:

sortingSorting: Sorting object with the selected units merged

class spikeinterface.curation.MergeUnitsSorting(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:

sortingBaseSorting

The sorting object

units_to_mergelist/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_idsNone 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_msfloat or None

Number of ms to consider for duplicated spikes. None won’t check for duplications

Returns:

sortingSorting: Sorting object with the selected units merged

class spikeinterface.curation.SplitUnitSorting(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:

sortingBaseSorting

The sorting object

split_unit_idint

Unit id of the unit to split

indices_listlist or np.array

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). If the sorting has only one segment, indices_list can be a single array

new_unit_idsint

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:

sortingSorting: Sorting object with the selected units split

spikeinterface.generation

Core

spikeinterface.generation.generate_recording(num_channels: int = 2, sampling_frequency: float = 30000.0, durations: list[float] = [5.0, 2.5], set_probe: bool | None = True, ndim: int | None = 2, seed: int | None = None) → BaseRecording

Generate a lazy recording object. Useful for testing API and algos.

Parameters:

num_channelsint, default: 2: The number of channels in the recording.
sampling_frequencyfloat, default: 30000. (in Hz): The sampling frequency of the recording, default: 30000.
durationslist[float], default: [5.0, 2.5]: The duration in seconds of each segment in the recording. The number of segments is determined by the length of this list.
set_probebool, default: True: If true, attaches probe to the returned Recording
ndimint, default: 2: The number of dimensions of the probe, default: 2. Set to 3 to make 3 dimensional probe.
seedint | None, default: None: A seed for the np.ramdom.default_rng function

Returns:

NumpyRecording: Returns a NumpyRecording object with the specified parameters.

spikeinterface.generation.generate_sorting(num_units=5, sampling_frequency=30000.0, durations=[10.325, 3.5], firing_rates=3.0, empty_units=None, refractory_period_ms=4.0, add_spikes_on_borders=False, num_spikes_per_border=3, border_size_samples=20, seed=None)

Generates sorting object with random firings.

Parameters:

num_unitsint, default: 5: Number of units.
sampling_frequencyfloat, default: 30000.0: The sampling frequency of the recording in Hz.
durationslist, default: [10.325, 3.5]: Duration of each segment in s.
firing_ratesfloat, default: 3.0: The firing rate of each unit (in Hz).
empty_unitslist, default: None: List of units that will have no spikes. (used for testing mainly).
refractory_period_msfloat, default: 4.0: The refractory period in ms
add_spikes_on_bordersbool, default: False: If True, spikes will be added close to the borders of the segments. This is for testing some post-processing functions when they have to deal with border spikes.
num_spikes_per_borderint, default: 3: The number of spikes to add close to the borders of the segments.
border_size_samplesint, default: 20: The size of the border in samples to add border spikes.
seedint, default: None: The random seed.

Returns:

sortingNumpySorting: The sorting object.

spikeinterface.generation.generate_snippets(nbefore=20, nafter=44, num_channels=2, wf_folder=None, sampling_frequency=30000.0, durations=[10.325, 3.5], set_probe=True, ndim=2, num_units=5, empty_units=None, **job_kwargs)

Generates a synthetic Snippets object.

Parameters:

nbeforeint, default: 20: Number of samples before the peak.
nafterint, default: 44: Number of samples after the peak.
num_channelsint, default: 2: Number of channels.
wf_folderstr | Path | None, default: None: Optional folder to save the waveform snippets. If None, snippets are in memory.
sampling_frequencyfloat, default: 30000.0: The sampling frequency of the snippets in Hz.
ndimint, default: 2: The number of dimensions of the probe.
num_unitsint, default: 5: The number of units.
empty_unitslist | None, default: None: A list of units that will have no spikes.
durationsList[float], default: [10.325, 3.5]: The duration in seconds of each segment in the recording. The number of segments is determined by the length of this list.
set_probebool, default: True: If true, attaches probe to the returned snippets object
**job_kwargsdict, default: None: Job keyword arguments for snippets_from_sorting

Returns:

snippetsNumpySnippets: The snippets object.
sortingNumpySorting: The associated sorting object.

spikeinterface.generation.generate_templates(channel_locations, units_locations, sampling_frequency, ms_before, ms_after, seed=None, dtype='float32', upsample_factor=None, unit_params=None, mode='ellipsoid')

Generate some templates from the given channel positions and neuron positions.

The implementation is very naive : it generates a mono channel waveform using generate_single_fake_waveform() and duplicates this same waveform on all channel given a simple decay law per unit.

Parameters:

channel_locationsnp.ndarray

Channel locations.

units_locationsnp.ndarray

Must be 3D.

sampling_frequencyfloat

Sampling frequency.

ms_beforefloat

Cut out in ms before spike peak.

ms_afterfloat

Cut out in ms after spike peak.

seedint | None

A seed for random.

dtypenumpy.dtype, default: “float32”

Templates dtype

upsample_factorint | None, default: None

If not None then template are generated upsampled by this factor. Then a new dimention (axis=3) is added to the template with intermediate inter sample representation. This allow easy random jitter by choising a template this new dim

unit_paramsdict[np.array] | dict[float] | dict[tuple] | None, default: None

An optional dict containing parameters per units. Keys are parameter names:

“alpha”: amplitude of the action potential in a.u. (default range: (6’000-9’000))

“depolarization_ms”: the depolarization interval in ms (default range: (0.09-0.14))

“repolarization_ms”: the repolarization interval in ms (default range: (0.5-0.8))

“recovery_ms”: the recovery interval in ms (default range: (1.0-1.5))

“positive_amplitude”: the positive amplitude in a.u. (default range: (0.05-0.15)) (negative is always -1)

“smooth_ms”: the gaussian smooth in ms (default range: (0.03-0.07))

“spatial_decay”: the spatial constant (default range: (20-40))

“propagation_speed”: mimic a propagation delay with a kind of a “speed” (default range: (250., 350.)).

Values can be:

array of the same length of units
scalar, then an array is created
tuple, then this difine a range for random values.

mode“ellipsoid” | “sphere”, default: “ellipsoid”

Method used to calculate the distance between unit and channel location. Ellipsoid injects some anisotropy dependent on unit shape, sphere is equivalent to Euclidean distance.

mode“sphere” | “ellipsoid”, default: “ellipsoid”

Mode for how to calculate distances

Returns:

templates: np.array

The template array with shape

(num_units, num_samples, num_channels): standard case
(num_units, num_samples, num_channels, upsample_factor) if upsample_factor is not None

spikeinterface.generation.generate_recording_by_size(full_traces_size_GiB: float, seed: int | None = None, strategy: Literal['tile_pregenerated', 'on_the_fly'] = 'tile_pregenerated') → NoiseGeneratorRecording

Generate a large lazy recording. This is a convenience wrapper around the NoiseGeneratorRecording class where only the size in GiB (NOT GB!) is specified.

It is generated with 384 channels and a sampling frequency of 1 Hz. The duration is manipulted to produced the desired size.

Seee GeneratorRecording for more details.

Parameters:

full_traces_size_GiBfloat

The size in gigabytes (GiB) of the recording.

seedint | None, default: None

The seed for np.random.default_rng.

strategy“tile_pregenerated” | “on_the_fly”, default: “tile_pregenerated”

The strategy of generating noise chunk:

“tile_pregenerated”: pregenerate a noise chunk of noise_block_size sample and repeat it
very fast and consume only one noise block.
“on_the_fly”: generate on the fly a new noise block by combining seed + noise block index
no memory preallocation but a bit more computation (random)

Returns

——-

GeneratorRecording

A lazy random recording with the specified size.

spikeinterface.generation.generate_ground_truth_recording(durations=[10.0], sampling_frequency=25000.0, num_channels=4, num_units=10, sorting=None, probe=None, generate_probe_kwargs={'contact_shape_params': {'radius': 6}, 'contact_shapes': 'circle', 'num_columns': 2, 'xpitch': 20, 'ypitch': 20}, templates=None, ms_before=1.0, ms_after=3.0, upsample_factor=None, upsample_vector=None, generate_sorting_kwargs={'firing_rates': 15, 'refractory_period_ms': 4.0}, noise_kwargs={'noise_levels': 5.0, 'strategy': 'on_the_fly'}, generate_unit_locations_kwargs={'margin_um': 10.0, 'maximum_z': 50.0, 'minimum_distance': 20, 'minimum_z': 5.0}, generate_templates_kwargs=None, dtype='float32', seed=None)

Generate a recording with spike given a probe+sorting+templates.

Parameters:

durationslist[float], default: [10.]

Durations in seconds for all segments.

sampling_frequencyfloat, default: 25000.0

Sampling frequency.

num_channelsint, default: 4

Number of channels, not used when probe is given.

num_unitsint, default: 10

Number of units, not used when sorting is given.

sortingSorting | None

An external sorting object. If not provide, one is genrated.

probeProbe | None

An external Probe object. If not provided a probe is generated using generate_probe_kwargs.

generate_probe_kwargsdict

A dict to constuct the Probe using probeinterface.generate_multi_columns_probe().

templatesnp.array | None

The templates of units. If None they are generated. Shape can be:

(num_units, num_samples, num_channels): standard case

(num_units, num_samples, num_channels, upsample_factor): case with oversample template to introduce jitter.

ms_beforefloat, default: 1.5

Cut out in ms before spike peak.

ms_afterfloat, default: 3.0

Cut out in ms after spike peak.

upsample_factorNone | int, default: None

A upsampling factor used only when templates are not provided.

upsample_vectornp.array | None

Optional the upsample_vector can given. This has the same shape as spike_vector

generate_sorting_kwargsdict

When sorting is not provide, this dict is used to generated a Sorting.

noise_kwargsdict

Dict used to generated the noise with NoiseGeneratorRecording.

generate_unit_locations_kwargsdict

Dict used to generated template when template not provided.

generate_templates_kwargsdict

Dict used to generated template when template not provided.

dtypenp.dtype, default: “float32”

The dtype of the recording.

seedint | None

Seed for random initialization. If None a diffrent Recording is generated at every call. Note: even with None a generated recording keep internaly a seed to regenerate the same signal after dump/load.

Returns:

recordingRecording: The generated recording extractor.
sortingSorting: The generated sorting extractor.

spikeinterface.generation.add_synchrony_to_sorting(sorting, sync_event_ratio=0.3, seed=None)

Generates sorting object with added synchronous events from an existing sorting objects.

Parameters:

sortingBaseSorting: The sorting object.
sync_event_ratiofloat, default: 0.3: The ratio of added synchronous spikes with respect to the total number of spikes. E.g., 0.5 means that the final sorting will have 1.5 times number of spikes, and all the extra spikes are synchronous (same sample_index), but on different units (not duplicates).
seedint, default: None: The random seed.

Returns:

sortingTransformSorting: The sorting object, keeping track of added spikes.

spikeinterface.generation.synthesize_random_firings(num_units=20, sampling_frequency=30000.0, duration=60, refractory_period_ms=4.0, firing_rates=3.0, add_shift_shuffle=False, seed=None)

” Generate some spiketrain with random firing for one segment.

Parameters:

num_unitsint, default: 20: Number of units.
sampling_frequencyfloat, default: 30000.0: Sampling rate in Hz.
durationfloat, default: 60: Duration of the segment in seconds.
refractory_period_msfloat: Refractory period in ms.
firing_ratesfloat or list[float]: The firing rate of each unit (in Hz). If float, all units will have the same firing rate.
add_shift_shufflebool, default: False: Optionally add a small shuffle on half of the spikes to make the autocorrelogram less flat.
seedint, default: None: Seed for the generator.

Returns:

times: np.array: Concatenated and sorted times vector.
labels: np.array: Concatenated and sorted label vector.

spikeinterface.generation.inject_some_duplicate_units(sorting, num=4, max_shift=5, ratio=None, seed=None)

Inject some duplicate units in a sorting. The peak shift can be control in a range.

Parameters:

sorting: Original sorting.
numint, default: 4: Number of injected units.
max_shiftint, default: 5: range of the shift in sample.
ratiofloat | None, default: None: Proportion of original spike in the injected units.
seedint | None, default: None: Random seed for creating unit peak shifts.

Returns:

sorting_with_dup: Sorting: A sorting with more units.

spikeinterface.generation.inject_some_split_units(sorting, split_ids: list, num_split=2, output_ids=False, seed=None)

Inject some split units in a sorting.

Parameters:

sortingBaseSorting: Original sorting.
split_idslist: List of unit_ids to split.
num_splitint, default: 2: Number of split units.
output_idsbool, default: False: If True, return the new unit_ids.
seedint, default: None: Random seed.

Returns:

sorting_with_splitNumpySorting: A sorting with split units.
other_idsdict: The dictionary with the split unit_ids. Returned only if output_ids is True.

spikeinterface.generation.synthetize_spike_train_bad_isi(duration, baseline_rate, num_violations, violation_delta=1e-05)

Create a spike train. Has uniform inter-spike intervals, except where isis violations occur.

Parameters:

durationfloat: Length of simulated recording (in seconds).
baseline_ratefloat: Firing rate for “true” spikes.
num_violationsint: Number of contaminating spikes.
violation_deltafloat, default: 1e-5: Temporal offset of contaminating spikes (in seconds).

Returns:

spike_trainnp.array: Array of monotonically increasing spike times.

Class for creating a recording based on spike timings and templates. Can be just the templates or can add to an already existing recording.

Parameters:

sortingBaseSorting

Sorting object containing all the units and their spike train.

templatesnp.ndarray[n_units, n_samples, n_channels] | np.ndarray[n_units, n_samples, n_oversampling]

Array containing the templates to inject for all the units. Shape can be:

(num_units, num_samples, num_channels): standard case

(num_units, num_samples, num_channels, upsample_factor): case with oversample template to introduce sampling jitter.

nbeforelist[int] | int | None, default: None

The number of samples before the peak of the template to align the spike. If None, will default to the highest peak.

amplitude_factorlist[float] | float | None, default: None

The amplitude of each spike for each unit. Can be None (no scaling). Can be scalar all spikes have the same factor (certainly useless). Can be a vector with same shape of spike_vector of the sorting.

parent_recordingBaseRecording | None, default: None

The recording over which to add the templates. If None, will default to traces containing all 0.

num_sampleslist[int] | int | None, default: None

The number of samples in the recording per segment. You can use int for mono-segment objects.

upsample_vectornp.array | None, default: None.

When templates is 4d we can simulate a jitter. Optional the upsample_vector is the jitter index with a number per spike in range 0-templates.shape[3].

check_bordersbool, default: False

Checks if the border of the templates are zero.

Returns:

injected_recording: InjectTemplatesRecording: The recording with the templates injected.

spikeinterface.generation.noise_generator_recording(num_channels: int, sampling_frequency: float, durations: list[float], noise_levels: float | np.array = 1.0, cov_matrix: np.array | None = None, dtype: np.dtype | str | None = 'float32', seed: int | None = None, strategy: Literal['tile_pregenerated', 'on_the_fly'] = 'tile_pregenerated', noise_block_size: int = 30000)

A lazy recording that generates white noise samples if and only if get_traces is called.

This done by tiling small noise chunk.

2 strategies to be reproducible across different start/end frame calls:

“tile_pregenerated”: pregenerate a small noise block and tile it depending the start_frame/end_frame
“on_the_fly”: generate on the fly small noise chunk and tile then. seed depend also on the noise block.

Parameters:

num_channelsint

The number of channels.

sampling_frequencyfloat

The sampling frequency of the recorder.

durationslist[float]

The durations of each segment in seconds. Note that the length of this list is the number of segments.

noise_levelsfloat | np.array, default: 1.0

Std of the white noise (if an array, defined by per channels)

cov_matrixnp.array | None, default: None

The covariance matrix of the noise

dtypenp.dtype | str | None, default: “float32”

The dtype of the recording. Note that only np.float32 and np.float64 are supported.

seedint | None, default: None

The seed for np.random.default_rng.

strategy“tile_pregenerated” | “on_the_fly”, default: “tile_pregenerated”

The strategy of generating noise chunk:

“tile_pregenerated”: pregenerate a noise chunk of noise_block_size sample and repeat it
very fast and cusume only one noise block.
“on_the_fly”: generate on the fly a new noise block by combining seed + noise block index
no memory preallocation but a bit more computaion (random)

noise_block_sizeint, default: 30000

Size in sample of noise block.

Notes

If modifying this function, ensure that only one call to malloc is made per call get_traces to maintain the optimized memory profile.

Class for creating a recording based on spike timings and templates. Can be just the templates or can add to an already existing recording.

Parameters:

sortingBaseSorting

Sorting object containing all the units and their spike train.

templatesnp.ndarray[n_units, n_samples, n_channels] | np.ndarray[n_units, n_samples, n_oversampling]

Array containing the templates to inject for all the units. Shape can be:

(num_units, num_samples, num_channels): standard case

(num_units, num_samples, num_channels, upsample_factor): case with oversample template to introduce sampling jitter.

nbeforelist[int] | int | None, default: None

The number of samples before the peak of the template to align the spike. If None, will default to the highest peak.

amplitude_factorlist[float] | float | None, default: None

The amplitude of each spike for each unit. Can be None (no scaling). Can be scalar all spikes have the same factor (certainly useless). Can be a vector with same shape of spike_vector of the sorting.

parent_recordingBaseRecording | None, default: None

The recording over which to add the templates. If None, will default to traces containing all 0.

num_sampleslist[int] | int | None, default: None

The number of samples in the recording per segment. You can use int for mono-segment objects.

upsample_vectornp.array | None, default: None.

When templates is 4d we can simulate a jitter. Optional the upsample_vector is the jitter index with a number per spike in range 0-templates.shape[3].

check_bordersbool, default: False

Checks if the border of the templates are zero.

Returns:

injected_recording: InjectTemplatesRecording: The recording with the templates injected.

class spikeinterface.generation.NoiseGeneratorRecording(num_channels: int, sampling_frequency: float, durations: list[float], noise_levels: float | np.array = 1.0, cov_matrix: np.array | None = None, dtype: np.dtype | str | None = 'float32', seed: int | None = None, strategy: Literal['tile_pregenerated', 'on_the_fly'] = 'tile_pregenerated', noise_block_size: int = 30000)

A lazy recording that generates white noise samples if and only if get_traces is called.

This done by tiling small noise chunk.

2 strategies to be reproducible across different start/end frame calls:

“tile_pregenerated”: pregenerate a small noise block and tile it depending the start_frame/end_frame
“on_the_fly”: generate on the fly small noise chunk and tile then. seed depend also on the noise block.

Parameters:

num_channelsint

The number of channels.

sampling_frequencyfloat

The sampling frequency of the recorder.

durationslist[float]

The durations of each segment in seconds. Note that the length of this list is the number of segments.

noise_levelsfloat | np.array, default: 1.0

Std of the white noise (if an array, defined by per channels)

cov_matrixnp.array | None, default: None

The covariance matrix of the noise

dtypenp.dtype | str | None, default: “float32”

The dtype of the recording. Note that only np.float32 and np.float64 are supported.

seedint | None, default: None

The seed for np.random.default_rng.

strategy“tile_pregenerated” | “on_the_fly”, default: “tile_pregenerated”

The strategy of generating noise chunk:

“tile_pregenerated”: pregenerate a noise chunk of noise_block_size sample and repeat it
very fast and cusume only one noise block.
“on_the_fly”: generate on the fly a new noise block by combining seed + noise block index
no memory preallocation but a bit more computaion (random)

noise_block_sizeint, default: 30000

Size in sample of noise block.

Notes

If modifying this function, ensure that only one call to malloc is made per call get_traces to maintain the optimized memory profile.

Drift

spikeinterface.generation.generate_drifting_recording(num_units=250, duration=600.0, sampling_frequency=30000.0, probe_name='Neuropixel-128', generate_probe_kwargs=None, generate_unit_locations_kwargs={'distance_strict': False, 'margin_um': 20.0, 'max_iteration': 100, 'maximum_z': 45.0, 'minimum_distance': 18.0, 'minimum_z': 5.0}, generate_displacement_vector_kwargs={'displacement_sampling_frequency': 5.0, 'drift_start_um': [0, 20], 'drift_step_um': 1, 'drift_stop_um': [0, -20], 'motion_list': [{'drift_mode': 'zigzag', 'non_rigid_gradient': None, 'period_s': 200, 't_end_drift': None, 't_start_drift': 60.0}]}, generate_templates_kwargs={'mode': 'ellipsoid', 'ms_after': 3.0, 'ms_before': 1.5, 'unit_params': {'alpha': (150.0, 500.0), 'spatial_decay': (10, 45)}}, generate_sorting_kwargs={'firing_rates': (2.0, 8.0), 'refractory_period_ms': 4.0}, generate_noise_kwargs={'noise_levels': (12.0, 15.0), 'spatial_decay': 25.0}, extra_outputs=False, seed=None)

Generated two synthetic recordings: one static and one drifting but with same units and same spiketrains.

Parameters:

num_unitsint, default: 250: Number of units.
durationfloat, default: 600.: The duration in seconds.
sampling_frequencyfloat, dfault: 30000.: The sampling frequency.
probe_namestr, default: “Neuropixel-128”: The probe type if generate_probe_kwargs is None.
generate_probe_kwargsNone or dict: A dict to generate the probe, this supersede probe_name when not None.
generate_unit_locations_kwargsdict: Parameters given to generate_unit_locations().
generate_displacement_vector_kwargsdict: Parameters given to generate_displacement_vector().
generate_templates_kwargsdict: Parameters given to generate_templates()
generate_sorting_kwargsdict: Parameters given to generate_sorting().
generate_noise_kwargsdict: Parameters given to generate_noise().
extra_outputsbool, default False: Return optionaly a dict with more variables.
seedNone ot int: A unique seed for all steps.

Returns:

static_recordingRecording

A generated recording with no motion.

drifting_recordingRecording

A generated recording with motion.

sortingSorting

The ground trith soring object. Same for both recordings.

extra_infos:

If extra_outputs=True, then return also a dict that contain various information like:

displacement_vectors

displacement_sampling_frequency

unit_locations

displacement_unit_factor

unit_displacements

This can be helpfull for motion benchmark.

spikeinterface.generation.generate_displacement_vector(duration, unit_locations, displacement_sampling_frequency=5.0, drift_start_um=[0, 20.0], drift_stop_um=[0, -20.0], drift_step_um=1, motion_list=[{'amplitude_factor': 1.0, 'drift_mode': 'zigzag', 'non_rigid_gradient': None, 'period_s': 200, 't_end_drift': None, 't_start_drift': 60.0}], seed=None)

This creates displacement vectors and related per-unit factors. This can be used to create complex drift on a linear motion but with multiple motion shapes, like zigzag + bumps for example.

This is needed by InjectDriftingTemplatesRecording.

The amplitude of the drift is controlled by drift_start_um and drift_stop_um. These are the boundaries of the motion.

Parameters:

durationfloat: Duration of the displacement vector in seconds
unit_locationsnp.array: The unit location with shape (num_units, 3)
displacement_sampling_frequencyfloat, default: 5.: The sampling frequency of the displacement vector
drift_start_umlist of float, default: [0, 20.]: The start boundary of the motion in the x and y direction.
drift_stop_umlist of float, default: [0, -20.]: The stop boundary of the motion in the x and y direction.
drift_step_umfloat, default: 1: Use to create the displacements_steps array. This ensures an odd number of steps
motion_listlist of dict: List of dicts containing individual motion vector parameters. len(motion_list) == displacement_vectors.shape[2]
seedNone | seed, default: None: Random seed for make_one_displacement_vector

Returns:

displacement_vectorsnumpy.ndarray: 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_unit_factornumpy array | None, default: None: A array containing the factor per unit of each drift (num_units, num_motions). This is used to create non-rigid drift with a factor gradient of depending on the unit positions
displacement_sampling_frequencyfloat: The sampling frequency of drift vector
displacements_stepsnumpy array: Position of the motion steps (from start to step) with shape (num_step, 2)

spikeinterface.generation.make_one_displacement_vector(drift_mode='zigzag', duration=600.0, amplitude_factor=1.0, displacement_sampling_frequency=5.0, t_start_drift=None, t_end_drift=None, period_s=200, bump_interval_s=(30, 90.0), seed=None)

Generates a toy displacement vector with ziagzag or bumps patterns.

Parameters:

drift_mode“zigzag” | “bumps”, default: “zigzag”: The drift mode.
durationfloat, default: 600: Duration in seconds
amplitude_factorfloat, default: 1: The amplitude factor of the drift.
displacement_sampling_frequencyfloat, default: 5: Sample rate of the vector.
t_start_driftfloat | None, default: None: Time in s when drift starts.
t_end_driftfloat | None, default: None: Time in s when drift ends.
period_sfloat, default: 200.: Period of the zigzag in seconds
bump_interval_stuple, default: (30, 90.): Range interval between random bumps in seconds.
seedNone | int: The seed for the random bumps.

Returns:

displacement_vector: np.array: The discplacement vector in micrometers

spikeinterface.generation.make_linear_displacement(start, stop, num_step=10)

Generates 2D linear displacements between start and stop positions (included in returned displacements).

Parameters:

startnp.array of 2 elements: The start position.
stopnp.array of 2 elements: The stop position.
num_stepint, default: 10: The number of steps between start and stop.

Returns:

displacementsnp.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_arraynp.array: A numpy array with dense templates_array. shape = (num_templates, num_samples, num_channels)
displacementsnp.array: Displacement vector shape : (num_displacement, 2)
source_probeProbe: The Probe object on which templates_array are defined
dest_probeProbe | 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_arraynp.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_arraynp.array: A numpy array with dense templates_array. shape = (num_templates, num_samples, num_channels)
source_locationsnp.array: The channel source location corresponding to templates_array. shape = (num_channels, 2)
dest_locationsnp.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_methodstr, default “cubic”: The interpolation method.

Returns:

new_templates_arraynp.array: shape = (num_templates, num_samples, num_channels) or = (num_motions, num_templates, num_samples, num_channel)

class spikeinterface.generation.DriftingTemplates(templates_array_moved=None, displacements=None, **static_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.

Parameters:

templates_array_movednp.array: Shape is (num_displacement, num_templates, num_samples, num_channels)
displacementsnp.array: Displacement vector shape : (num_displacement, 2)
**static_kwargsdict: Keyword arguments for Templates

class spikeinterface.generation.InjectDriftingTemplatesRecording(sorting: BaseSorting, drifting_templates: DriftingTemplates, displacement_vectors: list[ndarray], displacement_sampling_frequency: float, displacement_unit_factor: ndarray | None = None, parent_recording: BaseRecording | None = None, num_samples: list[int] | None = None, amplitude_factor: list[ndarray] | ndarray | float | None = None, mode='precompute')

Class for injecting drifting templates into a recording. This is similar to InjectTemplatesRecording but with drifts.

Parameters:

sortingBaseSorting: Sorting object containing all the units and their spike train
drifting_templatesDriftingTemplates: The drifting template object
displacement_vectorslist 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_frequencyfloat: The sampling frequency of drift vector
displacement_unit_factornumpy 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_recordingBaseRecording or None, default: None: The recording over which to add the templates. If None, will default to traces containing all 0.
num_sampleslist[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_factorlist 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.
modestr, default: “precompute”: Mode for how to compute templates.

Returns:

injected_recordingInjectDriftingTemplatesRecording: The recording with the templates injected.

Hybrid

spikeinterface.generation.generate_hybrid_recording(recording: BaseRecording, sorting: BaseSorting | None = None, templates: Templates | None = None, motion: Motion | None = None, are_templates_scaled: bool = True, unit_locations: ndarray | None = None, drift_step_um: float = 1.0, upsample_factor: int | None = None, upsample_vector: ndarray | None = None, amplitude_std: float = 0.05, generate_sorting_kwargs: dict = {'firing_rates': 15, 'num_units': 10, 'refractory_period_ms': 4.0, 'seed': 2205}, generate_unit_locations_kwargs: dict = {'margin_um': 10.0, 'maximum_z': 50.0, 'minimum_distance': 20, 'minimum_z': 5.0}, generate_templates_kwargs: dict = {'ms_after': 3.0, 'ms_before': 1.0}, seed: int | None = None) → tuple[BaseRecording, BaseSorting]

Generate an hybrid recording with spike given sorting+templates.

The function starts from an existing recording and injects hybrid units in it. The templates can be provided or generated. If the templates are not provided, they are generated (using the spikeinterface.core.generate.generate_templates() function and with arguments provided in generate_templates_kwargs). The sorting can be provided or generated. If the sorting is not provided, it is generated (using the spikeinterface.core.generate.generate_sorting function and with arguments provided in generate_sorting_kwargs). The injected spikes can optionally follow a motion pattern provided by a Motion object.

Parameters:

recordingBaseRecording: The recording to inject units in.
sortingSorting | None, default: None: An external sorting object. If not provide, one is generated.
templatesTemplates | None, default: None: The templates of units. If None they are generated.
motionMotion | None, default: None: The motion object to use for the drifting templates.
are_templates_scaledbool, default: True: If True, the templates are assumed to be in uV, otherwise in the same unit as the recording. In case the recording has scaling, the templates are “unscaled” before injection.
unit_locationsnp.array, default: None: The locations at which the templates should be injected. If not provided, generated (see generate_unit_location_kwargs).
drift_step_umfloat, default: 1.0: The step in um to use for the drifting templates.
upsample_factorNone or int, default: None: A upsampling factor used only when templates are not provided.
upsample_vectornp.array or None: Optional the upsample_vector can given. This has the same shape as spike_vector
amplitude_stdfloat, default: 0.05: The standard deviation of the modulation to apply to the spikes when injecting them into the recording.
generate_sorting_kwargsdict: When sorting is not provide, this dict is used to generated a Sorting.
generate_unit_locations_kwargsdict: Dict used to generated template when template not provided.
generate_templates_kwargsdict: Dict used to generated template when template not provided.
seedint or None: Seed for random initialization. If None a diffrent Recording is generated at every call. Note: even with None a generated recording keep internaly a seed to regenerate the same signal after dump/load.

Returns:

recording: BaseRecording: The generated hybrid recording extractor.
sorting: Sorting: The generated sorting extractor for the injected units.

spikeinterface.generation.estimate_templates_from_recording(recording: BaseRecording, ms_before: float = 2, ms_after: float = 2, sorter_name: str = 'spykingcircus2', run_sorter_kwargs: dict | None = None, job_kwargs: dict | None = None)

Get dense templates from a recording. Internally, SpyKING CIRCUS 2 is used by default with the only twist that the template matching step is not launched. Instead, a Template object is returned based on the results of the clustering. Other sorters can be invoked with the sorter_name and run_sorter_kwargs parameters.

Parameters:

recordingBaseRecording: The recording to get temaples from.
ms_beforefloat: The time before peaks of templates.
ms_afterfloat: The time after peaks of templates.
sorter_namestr: The sorter to be used in order to get some fast clustering.
run_sorter_kwargsdict: The parameters to provide to the run_sorter function of spikeinterface.
job_kwargsdict: The jobe keyword arguments to be used in the estimation of the templates.

Returns:

templates: Templates: The estimated templates

spikeinterface.generation.select_templates(templates: Templates, min_amplitude: float | None = None, max_amplitude: float | None = None, min_depth: float | None = None, max_depth: float | None = None, amplitude_function: Literal['ptp', 'min', 'max'] = 'ptp', depth_direction: Literal['x', 'y'] = 'y')

Select templates from an existing Templates object based on amplitude and depth.

Parameters:

templatesTemplates: The input templates.
min_amplitudefloat | None, default: None: The minimum amplitude of the templates.
max_amplitudefloat | None, default: None: The maximum amplitude of the templates.
min_depthfloat | None, default: None: The minimum depth of the templates.
max_depthfloat | None, default: None: The maximum depth of the templates.
amplitude_function“ptp” | “min” | “max”, default: “ptp”: The function to use to compute the amplitude of the templates. Can be “ptp”, “min” or “max”.
depth_direction“x” | “y”, default: “y”: The direction in which to move the templates. Can be “x” or “y”.

Returns:

Templates: The selected templates

spikeinterface.generation.scale_template_to_range(templates: Templates, min_amplitude: float, max_amplitude: float, amplitude_function: Literal['ptp', 'min', 'max'] = 'ptp')

Scale templates to have a range with the provided minimum and maximum amplitudes.

Parameters:

templatesTemplates: The input templates.
min_amplitudefloat: The minimum amplitude of the output templates after scaling.
max_amplitudefloat: The maximum amplitude of the output templates after scaling.
amplitude_function“ptp” | “min” | “max”, default: “ptp”: The function to use to compute the amplitude of the templates. Can be “ptp”, “min” or “max”.

Returns:

Templates: The scaled templates.

spikeinterface.generation.relocate_templates(templates: Templates, min_displacement: float, max_displacement: float, margin: float = 0.0, favor_borders: bool = True, depth_direction: Literal['x', 'y'] = 'y', seed: int | None = None)

Relocates templates to have a minimum and maximum displacement.

Parameters:

templatesTemplates: The input templates
min_displacementfloat: The minimum displacement of the templates
max_displacementfloat: The maximum displacement of the templates
marginfloat, default: 0.0: The margin to keep between the templates and the borders of the probe. If greater than 0, the templates are allowed to go beyond the borders of the probe.
favor_bordersbool, default: True: If True, the templates are always moved to the borders of the probe if this is possoble based on the min_displacement and max_displacement constraints. This avoids a bias in moving templates towards the center of the probe.
depth_direction“x” | “y”, default: “y”: The direction in which to move the templates. Can be “x” or “y”
seedint or None, default: None: Seed for random initialization.

Returns:

Templates: The relocated templates.

spikeinterface.generation.fetch_template_object_from_database(dataset='test_templates.zarr') → Templates

Fetch a template dataset from the spikeinterface template database. A dataset is a collection of templates with associated metadata for one specific recording.

Parameters:

datasetstr, default: “test_templates”: The name of the dataset to fetch. The dataset must be available in the spikeinterface template database.

Returns:

Templates: The templates object.

spikeinterface.generation.fetch_templates_database_info() → pandas.DataFrame

Fetch the information about the templates in the spikeinterface template database.

Returns:

pd.DataFrame: Dataframe containing the template information.

spikeinterface.generation.list_available_datasets_in_template_database() → list

List all available datasets in the spikeinterface template database.

Returns:

list: List of available datasets.

spikeinterface.generation.query_templates_from_database(template_df: pandas.DataFrame, verbose: bool = False) → Templates

Retrieve templates from the spikeinterface template database.

Parameters:

template_dfpd.DataFrame: Dataframe containing the template information, obtained by slicing/querying the output of fetch_templates_info.
verbosebool, default: False: if True, output is verbose

Returns:

Templates: The templates object.

Noise

spikeinterface.generation.generate_noise(probe, sampling_frequency, durations, dtype='float32', noise_levels=15.0, spatial_decay=None, seed=None)

Generate a noise recording.

Parameters:

probeProbe: A probe object.
sampling_frequencyfloat: The sampling frequency of the recording.
durationslist of float: The duration(s) of the recording segment(s) in seconds.
dtypenp.dtype: The dtype of the recording.
noise_levelsfloat | np.array | tuple, default: 15.0: If scalar same noises on all channels. If array then per channels noise level. If tuple, then this represent the range.
spatial_decayfloat | None, default: None: If not None, the spatial decay of the noise used to generate the noise covariance matrix.
seedint | None, default: None: The seed for random generator.

Returns:

noiseNoiseGeneratorRecording: A lazy noise generator recording.

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) → ndarray

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:

recordingRecordingExtractor

The recording extractor object.

peaksarray

Peaks array, as returned by detect_peaks() in “compact_numpy” way.

ms_beforefloat

The number of milliseconds to include before the peak of the spike

ms_afterfloat

The number of milliseconds to include after the peak of the spike

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_kwargskeyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_sizeint
  Number of samples per chunk
- chunk_memorystr
  Memory usage for each job (e.g. “100M”, “1G”, “500MiB”, “2GiB”)
- total_memorystr
  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_jobsint | float
Number of jobs to use. With -1 the number of jobs is the same as number of cores. Using a float between 0 and 1 will use that fraction of the total cores.
progress_barbool
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='locally_exclusive', pipeline_nodes=None, gather_mode='memory', folder=None, names=None, skip_after_n_peaks=None, recording_slices=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:

recordingRecordingExtractor

The recording extractor object.

pipeline_nodesNone or list[PipelineNode]

Optional additional PipelineNode need to computed just after detection time. This avoid reading the recording multiple times.

gather_modestr

How to gather the results: * “memory”: results are returned as in-memory numpy arrays * “npy”: results are stored to .npy files in folder

folderstr or Path

If gather_mode is “npy”, the folder where the files are created.

nameslist

List of strings with file stems associated with returns.

skip_after_n_peaksNone | int

Skip the computation after n_peaks. This is not an exact because internally this skip is done per worker in average.

recording_slicesNone | list[tuple]

Optionaly give a list of slices to run the pipeline only on some chunks of the recording. It must be a list of (segment_index, frame_start, frame_stop). If None (default), the function iterates over the entire duration of the recording.

method‘by_channel’, ‘locally_exclusive’, ‘locally_exclusive_cl’, ‘by_channel_torch’, ‘locally_exclusive_torch’, ‘matched_filtering’

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.

arguments for method=’matched_filtering’

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_umfloat: The radius to use to select neighbour channels for locally exclusive detection.
prototypearray: The canonical waveform of action potentials
ms_beforefloat: The time in ms before the maximial value of the absolute prototype
weight_methoddict: 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_kwargskeyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_sizeint
  Number of samples per chunk
- chunk_memorystr
  Memory usage for each job (e.g. “100M”, “1G”, “500MiB”, “2GiB”)
- total_memorystr
  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_jobsint | float
Number of jobs to use. With -1 the number of jobs is the same as number of cores. Using a float between 0 and 1 will use that fraction of the total cores.
progress_barbool
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.

Clustering

spikeinterface.sortingcomponents.clustering.find_cluster_from_peaks(recording, peaks, method='stupid', method_kwargs={}, extra_outputs=False, **job_kwargs)

Find cluster from peaks.

Parameters:

recordingRecordingExtractor

The recording extractor object

peaksnumpy.array

The peak vector

methodstr

Which method to use (“stupid” | “XXXX”)

method_kwargsdict, default: dict()

Keyword arguments for the chosen method

extra_outputsbool, default: False

If True then debug is also return

**job_kwargskeyword arguments for parallel processing:

chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_sizeint
  Number of samples per chunk
- chunk_memorystr
  Memory usage for each job (e.g. “100M”, “1G”, “500MiB”, “2GiB”)
- total_memorystr
  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_jobsint | float
Number of jobs to use. With -1 the number of jobs is the same as number of cores. Using a float between 0 and 1 will use that fraction of the total cores.
progress_barbool
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_set: 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, verbose=False, **job_kwargs) → ndarray | tuple[ndarray, dict]

Find spike from a recording from given templates.

Parameters:

recordingRecordingExtractor: The recording extractor object
method“naive” | “tridesclous” | “circus” | “circus-omp” | “wobble”, default: “naive”: Which method to use for template matching
method_kwargsdict, optional: Keyword arguments for the chosen method
extra_outputsbool: If True then a dict is also returned is also returned
**job_kwargsdict: Parameters for ChunkRecordingExecutor
verboseBool, default: False: If True, output is verbose

Returns:

spikesndarray: Spikes found from templates.
outputs:: Optionaly returns for debug purpose.

Motion Correction

spikeinterface.sortingcomponents.motion.estimate_motion(recording, peaks=None, peak_locations=None, direction='y', rigid=False, win_shape='gaussian', win_step_um=200.0, win_scale_um=300.0, win_margin_um=None, method='decentralized', extra_outputs=False, progress_bar=False, verbose=False, margin_um=None, **method_kwargs) → Motion | tuple[Motion, dict]

Estimate motion with several possible methods.

Most of methods except dredge_lfp needs peaks and after their localization.

Note that the way you detect peak locations (center of mass/monopolar_triangulation/grid_convolution) have an impact on the result.

Parameters:

recordingBaseRecording

The recording extractor

peaksnumpy array

Peak vector (complex dtype). Needed for decentralized and iterative_template methods.

peak_locationsnumpy array

Complex dtype with “x”, “y”, “z” fields Needed for decentralized and iterative_template methods.

direction“x” | “y” | “z”, default: “y”

Dimension on which the motion is estimated. “y” is depth along the probe.

method‘decentralized’, ‘iterative_template’, ‘dredge_lfp’, ‘dredge_ap’, ‘medicine’

Method to use.

arguments for method=’decentralized’

bin_um: float, default: 10

Spatial bin size in micrometers

hist_margin_um: float, default: 0

Margin in um from histogram estimation. Positive margin extrapolate out of the probe the motion. Negative margin crop the motion on the border

bin_s: float, default 1.0

Bin duration in second

histogram_depth_smooth_um: None or float

Optional gaussian smoother on histogram on depth axis. This is given as the sigma of the gaussian in micrometers.

histogram_time_smooth_s: None or float

Optional gaussian smoother on histogram on time axis. This is given as the sigma of the gaussian in seconds.

pairwise_displacement_method: “conv” or “phase_cross_correlation”

How to estimate the displacement in the pairwise matrix.

max_displacement_um: float

Maximum possible displacement in micrometers.

weight_scale: “linear” or “exp”

For parwaise displacement, how to to rescale the associated weight matrix.

error_sigma: float, default: 0.2

In case weight_scale=”exp” this controls the sigma of the exponential.

conv_engine: “numpy” or “torch” or None, default: None

In case of pairwise_displacement_method=”conv”, what library to use to compute the underlying correlation

torch_device=None

In case of conv_engine=”torch”, you can control which device (cpu or gpu)

batch_size: int

Size of batch for the convolution. Increasing this will speed things up dramatically on GPUs and sometimes on CPU as well.

corr_threshold: float

Minimum correlation between pair of time bins in order for these to be considered when optimizing a global displacment vector to align with the pairwise displacements.

time_horizon_s: None or float

When not None the parwise discplament matrix is computed in a small time horizon. In short only pair of bins close in time. So the pariwaise matrix is super sparse and have values only the diagonal.

convergence_method: “lsmr” | “lsqr_robust” | “gradient_descent”, default: “lsmr”

Which method to use to compute the global displacement vector from the pairwise matrix.

robust_regression_sigma: float

Use for convergence_method=”lsqr_robust” for iterative selection of the regression.

temporal_priorbool, default: True

Ensures continuity across time, unless there is evidence in the recording for jumps.

spatial_priorbool, default: False

Ensures continuity across space. Not usually necessary except in recordings with glitches across space.

force_spatial_median_continuity: bool, default: False

When spatial_prior=False we can optionally apply a median continuity across spatial windows.

reference_displacementstring, one of: “mean”, “median”, “time”, “mode_search”

Strategy for picking what is considered displacement=0.

“mean” : the mean displacement is subtracted
“median” : the median displacement is subtracted
“time” : the displacement at a given time (in seconds) is subtracted
“mode_search” : an attempt is made to guess the mode. needs work.

lsqr_robust_n_iter: int

Number of iteration for convergence_method=”lsqr_robust”.

arguments for method=’iterative_template’

bin_um: float, default: 10: Spatial bin size in micrometers
hist_margin_um: float, default: 0: Margin in um from histogram estimation. Positive margin extrapolate out of the probe the motion. Negative margin crop the motion on the border
bin_s: float, default: 2.0: Bin duration in second
num_amp_bins: int, default: 20: number ob bins in the histogram on the log amplitues dimension
num_shifts_global: int, default: 15: Number of spatial bin shifts to consider for global alignment
num_iterations: int, default: 10: Number of iterations for global alignment procedure
num_shifts_block: int, default: 5: Number of spatial bin shifts to consider for non-rigid alignment
smoothing_sigma: float, default: 0.5: Sigma of gaussian for covariance matrices smoothing
kriging_sigma: float,: sigma parameter for kriging_kernel function
kriging_p: foat: p parameter for kriging_kernel function
kriging_d: float: d parameter for kriging_kernel function

arguments for method=’dredge_lfp’

lfp_recordingspikeinterface BaseRecording object: Preprocessed LFP recording. The temporal resolution of this recording will be the target resolution of the registration, so definitely use SpikeInterface to resample your recording to, say, 250Hz (or a value you like) rather than estimating motion at the original frequency (which may be high).
direction“x” | “y”, default “y”: Dimension on which the motion is estimated. “y” is depth along the probe.
rigidboolean, optional: If True, window-related arguments are ignored and we do rigid registration
win_shape, win_step_um, win_scale_um, win_margin_umfloat: Nonrigid window-related arguments The depth domain will be broken up into windows with shape controlled by win_shape, spaced by win_step_um at a margin of win_margin_um from the boundary, and with width controlled by win_scale_um.
chunk_len_sfloat: Length of chunks (in seconds) that the recording is broken into for online registration. The computational speed of the method is a function of the number of samples this corresponds to, and things can get slow if it is set high enough that the number of samples per chunk is bigger than ~10,000. But, it can’t be set too low or the algorithm doesn’t have enough data to work with. The default is set assuming sampling rate of 250Hz, leading to 2500 samples per chunk.
time_horizon_sfloat: Time-bins farther apart than this value in seconds will not be cross-correlated. Set this to at least chunk_len_s.
max_disp_umnumber, optional: This is the ceiling on the possible displacement estimates. It should be set to a number which is larger than the allowed displacement in a single chunk. Setting it as small as possible (while following that rule) can speed things up and improve the result by making it impossible to estimate motion which is too big.
mincorrfloat in [0,1]: Minimum correlation between pairs of frames such that they will be included in the optimization of the displacement estimates.
mincorr_percentile, mincorr_percentile_nneighbs: If mincorr_percentile is set to a number in [0, 100], then mincorr will be replaced by this percentile of the correlations of neighbors within mincorr_percentile_nneighbs time bins of each other.
devicestring or torch.device: Controls torch device

arguments for method=’dredge_ap’

bin_um: float: Bin duration in second
bin_sfloat: The size of the bins along depth in microns and along time in seconds. The returned object’s .displacement array will respect these bins. Increasing these can lead to more stable estimates and faster runtimes at the cost of spatial and/or temporal resolution.
max_disp_umfloat: Maximum possible displacement in microns. If you can guess a number which is larger than the largest displacement possible in your recording across a span of time_horizon_s seconds, setting this value to that number can stabilize the result and speed up the algorithm (since it can do less cross-correlating). By default, this is set to win-scale_um / 4, or 112.5 microns. Which can be a bit large!
time_horizon_sfloat: “Time horizon” parameter, in seconds. Time bins separated by more seconds than this will not be cross-correlated. So, if your data has nonstationarities or changes which could lead to bad cross-correlations at some timescale, it can help to input that value here. If this is too small, it can make the motion estimation unstable.
mincorrfloat, between 0 and 1: Correlation threshold. Pairs of frames whose maximal cross correlation value is smaller than this threshold will be ignored when solving for the global displacement estimate.
thomas_kw, xcorr_kw, raster_kw, weights_kw: These dictionaries allow setting parameters for fine control over the registration
devicestr or torch.device: What torch device to run on? E.g., “cpu” or “cuda” or “cuda:1”.

arguments for method=’medicine’

rigidbool, default: False

Compute rigid (one motion for the entire probe) or non rigid motion Rigid computation is equivalent to non-rigid with only one window with rectangular shape.

win_shape“gaussian” | “rect” | “triangle”, default: “gaussian”

The shape of the windows for non rigid. When rigid this is force to “rect” Nonrigid window-related arguments The depth domain will be broken up into windows with shape controlled by win_shape, spaced by win_step_um at a margin of win_margin_um from the boundary, and with width controlled by win_scale_um. When win_margin_um is None the margin is automatically set to -win_scale_um/2. See get_spatial_windows.

win_step_umfloat, default: 50

See win_shape

win_scale_umfloat, default: 150

See win_shape

win_margin_umNone | float, default: None

See win_shape

extra_outputsbool, default: False

If True then return an extra dict that contains variables to check intermediate steps (motion_histogram, non_rigid_windows, pairwise_displacement)

progress_barbool, default: False

Display progress bar or not

verbosebool, default: False

If True, output is verbose

**method_kwargs

Returns:

motion: Motion object: The motion object.
extra: dict: Optional output if extra_outputs=True This dict contain histogram, pairwise_displacement usefull for ploting.

spikeinterface.sortingcomponents.motion.interpolate_motion(recording, motion, border_mode='remove_channels', spatial_interpolation_method='kriging', sigma_um=20.0, p=1, num_closest=3, interpolation_time_bin_centers_s=None, interpolation_time_bin_edges_s=None, interpolation_time_bin_size_s=None, dtype=None, **spatial_interpolation_kwargs)

Interpolate the input recording’s traces to correct for motion, according to the motion estimate object motion. The interpolation is carried out “lazily” / on the fly by applying a spatial interpolation on the original traces to estimate their values at the positions of the probe’s channels after being shifted inversely to the motion.

To get a Motion object, use interpolate_motion().

By default, each frame is spatially interpolated by the motion at the nearest motion estimation time bin – in other words, the temporal resolution of the motion correction is the same as the motion estimation’s. However, this behavior can be changed by setting interpolation_time_bin_centers_s or interpolation_time_bin_size_s below. In that case, the motion estimate will be interpolated to match the interpolation time bins.

Parameters:

recordingRecording

The parent recording.

motionMotion

The motion object

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_umfloat, default: 20.0

Used in the “kriging” formula

pint, default: 1

Used in the “kriging” formula

num_closestint, 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)

interpolation_time_bin_centers_snp.array or list of np.array, optional

Spatially interpolate each frame according to the displacement estimate at its closest bin center in this array. If not supplied, this is set to the motion estimate’s time bin centers. If it’s supplied, the motion estimate is interpolated to these bin centers. If you have a multi-segment recording, pass a list of these, one per segment.

interpolation_time_bin_size_sfloat, optional

Similar to the previous argument: interpolation_time_bin_centers_s will be constructed by bins spaced by interpolation_time_bin_size_s. This is ignored if interpolation_time_bin_centers_s is supplied.

dtypestr or np.dtype, optional

Interpolation needs to convert to a floating dtype. If dtype is supplied, that will be used. If the input recording is already floating and dtype=None, then its dtype is used by default. If the input recording is integer, then float32 is used by default.

**spatial_interpolation_kwargsdict

Spatial interpolation kwargs for interpolate_motion_on_traces.

Returns:

corrected_recording: InterpolateMotionRecording: Recording after motion correction

spikeinterface.sortingcomponents.motion.correct_motion_on_peaks(peaks, peak_locations, motion, recording) → ndarray

Given the output of estimate_motion(), apply inverse motion on peak locations.

Parameters:

peaksnp.array: peaks vector
peak_locationsnp.array: peaks location vector
motionMotion: The motion object.
recordingRecording: The recording object. This is used to convert sample indices to times.

Returns:

corrected_peak_locations: np.array: Motion-corrected peak locations

spikeinterface.sortingcomponents.motion.interpolate_motion_on_traces(traces, times, channel_locations, motion, segment_index=None, channel_inds=None, interpolation_time_bin_centers_s=None, interpolation_time_bin_edges_s=None, spatial_interpolation_method='kriging', spatial_interpolation_kwargs={}, dtype=None)

Apply inverse motion with spatial interpolation on traces.

Traces can be full traces, but also waveforms snippets. Times used for looking up displacements are controlled by interpolation_time_bin_edges_s or interpolation_time_bin_centers_s, or fall back to the Motion object’s time bins by default; times in the recording outside these time bins use the closest edge bin’s displacement value during interpolation.

Parameters:

tracesnp.array

Trace snippet (num_samples, num_channels)

timesnp.array

Sample times in seconds for the frames of the traces snippet

channel_locationsnp.array 2d

Channel location with shape (n, 2) or (n, 3)

motionMotion

The motion object.

segment_indexint or None

The segment index.

channel_indsNone or list

If not None, interpolate only a subset of channels.

interpolation_time_bin_centers_sNone or np.array

Manually specify the time bins which the interpolation happens in for this segment. If None, these are the motion estimate’s time bins.

interpolation_time_bin_edges_sNone or np.array

If present, interpolation chunks will be the time bins defined by these edges rather than interpolation_time_bin_centers_s or the motion’s bins.

spatial_interpolation_method“idw” | “kriging”, default: “kriging”

The spatial interpolation method used to interpolate the channel locations:

idw : Inverse Distance Weighing
kriging : kilosort2.5 like

spatial_interpolation_kwargsdict

specific option for the interpolation method

dtypenp.dtype, default: None

The dtype of the traces. If None, interhits from traces snippet

Returns:

traces_corrected: np.array: Motion-corrected trace snippet, (num_samples, num_channels)

spikeinterface.sortingcomponents.motion.clean_motion_vector(motion, temporal_bins, bin_duration_s, speed_threshold=30, sigma_smooth_s=None)

Simple machinery to remove spurious fast bump in the motion vector. Also can apply a smoothing.

Parameters:

motionnumpy array 2d: Motion estimate in um.
temporal_binsnumpy.array 1d: temporal bins (bin center)
bin_duration_sfloat: bin duration in second
speed_thresholdfloat (units um/s): Maximum speed treshold between 2 bins allowed. Expressed in um/s
sigma_smooth_sNone or float: Optional smooting gaussian kernel.

Returns:

corrtensor

class spikeinterface.sortingcomponents.motion.InterpolateMotionRecording(recording, motion, border_mode='remove_channels', spatial_interpolation_method='kriging', sigma_um=20.0, p=1, num_closest=3, interpolation_time_bin_centers_s=None, interpolation_time_bin_edges_s=None, interpolation_time_bin_size_s=None, dtype=None, **spatial_interpolation_kwargs)

Interpolate the input recording’s traces to correct for motion, according to the motion estimate object motion. The interpolation is carried out “lazily” / on the fly by applying a spatial interpolation on the original traces to estimate their values at the positions of the probe’s channels after being shifted inversely to the motion.

To get a Motion object, use interpolate_motion().

By default, each frame is spatially interpolated by the motion at the nearest motion estimation time bin – in other words, the temporal resolution of the motion correction is the same as the motion estimation’s. However, this behavior can be changed by setting interpolation_time_bin_centers_s or interpolation_time_bin_size_s below. In that case, the motion estimate will be interpolated to match the interpolation time bins.

Parameters:

recordingRecording

The parent recording.

motionMotion

The motion object

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_umfloat, default: 20.0

Used in the “kriging” formula

pint, default: 1

Used in the “kriging” formula

num_closestint, 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)

interpolation_time_bin_centers_snp.array or list of np.array, optional

Spatially interpolate each frame according to the displacement estimate at its closest bin center in this array. If not supplied, this is set to the motion estimate’s time bin centers. If it’s supplied, the motion estimate is interpolated to these bin centers. If you have a multi-segment recording, pass a list of these, one per segment.

interpolation_time_bin_size_sfloat, optional

Similar to the previous argument: interpolation_time_bin_centers_s will be constructed by bins spaced by interpolation_time_bin_size_s. This is ignored if interpolation_time_bin_centers_s is supplied.

dtypestr or np.dtype, optional

Interpolation needs to convert to a floating dtype. If dtype is supplied, that will be used. If the input recording is already floating and dtype=None, then its dtype is used by default. If the input recording is integer, then float32 is used by default.

**spatial_interpolation_kwargsdict

Spatial interpolation kwargs for interpolate_motion_on_traces.

Returns:

corrected_recording: InterpolateMotionRecording: Recording after motion correction

API

spikeinterface.core

Low-level

Back-compatibility with WaveformExtractor (version < 0.101.0)

spikeinterface.extractors

NEO-based

Non-NEO-based

spikeinterface.preprocessing

spikeinterface.postprocessing

spikeinterface.qualitymetrics

spikeinterface.sorters

Low level

spikeinterface.comparison

spikeinterface.widgets

spikeinterface.exporters

spikeinterface.curation

Deprecated

spikeinterface.generation

Core

Drift

Hybrid

Noise

spikeinterface.sortingcomponents

Peak Localization

Peak Detection

Clustering

Template Matching

Motion Correction

Back-compatibility with `WaveformExtractor` (version < 0.101.0)