API¶
spikeinterface.core¶
- spikeinterface.core.load_extractor(file_or_folder_or_dict, base_folder=None) BaseExtractor ¶
- Instantiate extractor from:
a dict
a json file
a pickle file
folder (after save)
a zarr folder (after save)
- Parameters
- file_or_folder_or_dictdictionary or folder or file (json, pickle)
The file path, folder path, or dictionary to load the extractor from
- base_folderstr | Path | bool (optional)
The base folder to make relative paths absolute. If True and file_or_folder_or_dict is a file, the parent folder of the file is used.
- Returns
- extractor: Recording or Sorting
The loaded extractor object
- class spikeinterface.core.BaseRecording(sampling_frequency: float, channel_ids: List, dtype)¶
Abstract class representing several a multichannel timeseries (or block of raw ephys traces). Internally handle list of RecordingSegment
- add_recording_segment(recording_segment)¶
Adds a recording segment.
- Parameters
- recording_segmentBaseRecordingSegment
The recording segment to add
- binary_compatible_with(dtype=None, time_axis=None, file_paths_lenght=None, file_offset=None, file_suffix=None)¶
Check is the recording is binary compatible with some constrain on
dtype
tim_axis
len(file_paths)
file_offset
file_suffix
- get_binary_description()¶
When rec.is_binary_compatible() is True this returns a dictionary describing the binary format.
- get_duration(segment_index=None) float ¶
Returns the duration in seconds.
- Parameters
- segment_indexint or None, default: None
The sample index to retrieve the duration for. For multi-segment objects, it is required, default: None With single segment recording returns the duration of the single segment
- Returns
- float
The duration in seconds
- get_memory_size(segment_index=None) int ¶
Returns the memory size of segment_index in bytes.
- Parameters
- segment_indexint or None, default: None
The index of the segment for which the memory size should be calculated. For multi-segment objects, it is required, default: None With single segment recording returns the memory size of the single segment
- Returns
- int
The memory size of the specified segment in bytes.
- get_num_frames(segment_index=None) int ¶
Returns the number of samples for a segment.
- Parameters
- segment_indexint or None, default: None
The segment index to retrieve the number of samples for. For multi-segment objects, it is required, default: None With single segment recording returns the number of samples in the segment
- Returns
- int
The number of samples
- get_num_samples(segment_index=None) int ¶
Returns the number of samples for a segment.
- Parameters
- segment_indexint or None, default: None
The segment index to retrieve the number of samples for. For multi-segment objects, it is required, default: None With single segment recording returns the number of samples in the segment
- Returns
- int
The number of samples
- get_num_segments() int ¶
Returns the number of segments.
- Returns
- int
Number of segments in the recording
- get_time_info(segment_index=None) dict ¶
Retrieves the timing attributes for a given segment index. As with other recorders this method only needs a segment index in the case of multi-segment recordings.
- Returns
- dict
A dictionary containing the following key-value pairs:
“sampling_frequency”: The sampling frequency of the RecordingSegment.
“t_start”: The start time of the RecordingSegment.
“time_vector”: The time vector of the RecordingSegment.
Notes
The keys are always present, but the values may be None.
- get_times(segment_index=None)¶
Get time vector for a recording segment.
If the segment has a time_vector, then it is returned. Otherwise a time_vector is constructed on the fly with sampling frequency. If t_start is defined and the time vector is constructed on the fly, the first time will be t_start. Otherwise it will start from 0.
- Parameters
- segment_indexint or None, default: None
The segment index (required for multi-segment)
- Returns
- np.array
The 1d times array
- get_total_duration() float ¶
Returns the total duration in seconds
- Returns
- float
The duration in seconds
- get_total_memory_size() int ¶
Returns the sum in bytes of all the memory sizes of the segments.
- Returns
- int
The total memory size in bytes for all segments.
- get_total_samples() int ¶
Returns the sum of the number of samples in each segment.
- Returns
- int
The total number of samples
- get_traces(segment_index: Optional[int] = None, start_frame: Optional[int] = None, end_frame: Optional[int] = None, channel_ids: Optional[Iterable] = None, order: Optional[str] = None, return_scaled=False, cast_unsigned=False)¶
Returns traces from recording.
- Parameters
- segment_indexUnion[int, None], default: None
The segment index to get traces from. If recording is multi-segment, it is required, default: None
- start_frameUnion[int, None], default: None
The start frame. If None, 0 is used, default: None
- end_frameUnion[int, None], default: None
The end frame. If None, the number of samples in the segment is used, default: None
- channel_idsUnion[Iterable, None], default: None
The channel ids. If None, all channels are used, default: None
- orderUnion[str, None], default: None
The order of the traces (“C” | “F”). If None, traces are returned as they are, default: None
- return_scaledbool, default: None
If True and the recording has scaling (gain_to_uV and offset_to_uV properties), traces are scaled to uV, default: False
- cast_unsignedbool, default: None
If True and the traces are unsigned, they are cast to integer and centered (an offset of (2**nbits) is subtracted), default: False
- 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()¶
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()¶
Inform is this recording is “binary” compatible. To be used before calling rec.get_binary_description()
- Returns
- bool
True if the underlying recording is binary
- sample_index_to_time(sample_ind, segment_index=None)¶
Transform sample index into time in seconds
- set_times(times, segment_index=None, with_warning=True)¶
Set times for a recording segment.
- Parameters
- times1d np.array
The time vector
- segment_indexint or None, default: None
The segment index (required for multi-segment)
- with_warningbool, default: True
If True, a warning is printed
- class spikeinterface.core.BaseSorting(sampling_frequency: float, unit_ids: List)¶
Abstract class representing several segment several units and relative spiketrains.
- count_num_spikes_per_unit(outputs='dict')¶
For each unit : get number of spikes across segments.
- Parameters
- outputs: “dict” | “array”, default: “dict”
Control the type of the returned object: a dict (keys are unit_ids) or an numpy array.
- Returns
- dict or numpy.array
Dict : Dictionary with unit_ids as key and number of spikes as values Numpy array : array of size len(unit_ids) in the same order as unit_ids.
- count_total_num_spikes() int ¶
Get total number of spikes in the sorting.
This is the sum of all spikes in all segments across all units.
- Returns
- total_num_spikes: int
The total number of spike
- get_all_spike_trains(outputs='unit_id')¶
Return all spike trains concatenated. This is deprecated and will be removed in spikeinterface 0.102 use sorting.to_spike_vector() instead
- get_num_samples(segment_index=None) int ¶
Returns the number of samples of the associated recording for a segment.
- Parameters
- segment_indexint or None, default: None
The segment index to retrieve the number of samples for. For multi-segment objects, it is required
- Returns
- int
The number of samples
- get_times(segment_index=None)¶
Get time vector for a registered recording segment.
- If a recording is registered:
if the segment has a time_vector, then it is returned
if not, a time_vector is constructed on the fly with sampling frequency
If there is no registered recording it returns None
- get_total_duration()¶
Returns the total duration in s of the associated recording.
- Returns
- float
The duration in seconds
- get_total_samples() int ¶
Returns the total number of samples of the associated recording.
- Returns
- int
The total number of samples
- has_time_vector(segment_index=None)¶
Check if the segment of the registered recording has a time vector.
- precompute_spike_trains(from_spike_vector=None)¶
Pre-computes and caches all spike trains for this sorting
- Parameters
- from_spike_vector: None | bool, default: None
If None, then it is automatic depending on whether the spike vector is cached. If True, will compute it from the spike vector. If False, will call get_unit_spike_train for each segment for each unit.
- register_recording(recording, check_spike_frames=True)¶
Register a recording to the sorting.
- Parameters
- recordingBaseRecording
Recording with the same number of segments as current sorting. Assigned to self._recording.
- check_spike_framesbool, default: True
If True, assert for each segment that all spikes are within the recording’s range.
- remove_empty_units()¶
Returns a new sorting object which contains only units with at least one spike. For multi-segments, a unit is considered empty if it contains no spikes in all segments.
- Returns
- BaseSorting
Sorting object with non-empty units
- remove_units(remove_unit_ids) BaseSorting ¶
Returns a new sorting object with contains only a selected subset of units.
- Parameters
- remove_unit_idsnumpy.array or list
List of unit ids to remove
- Returns
- BaseSorting
Sorting without the removed units
- rename_units(new_unit_ids: numpy.ndarray | list) BaseSorting ¶
Returns a new sorting object with renamed units.
- Parameters
- new_unit_idsnumpy.array or list
List of new names for unit ids. They should map positionally to the existing unit ids.
- Returns
- BaseSorting
Sorting object with renamed units
- select_units(unit_ids, renamed_unit_ids=None) BaseSorting ¶
Returns a new sorting object which contains only a selected subset of units.
- Parameters
- unit_idsnumpy.array or list
List of unit ids to keep
- renamed_unit_idsnumpy.array or list, default: None
If given, the kept unit ids are renamed
- Returns
- BaseSorting
Sorting object with selected units
- to_multiprocessing(n_jobs)¶
When necessary turn sorting object into: * NumpySorting when n_jobs=1 * SharedMemorySorting when n_jobs>1
If the sorting is already NumpySorting, SharedMemorySorting or NumpyFolderSorting then this return the sortign itself, no transformation so.
- Parameters
- n_jobs: int
The number of jobs.
- Returns
- ——-
- sharable_sorting:
A sorting that can be used for multiprocessing.
- to_numpy_sorting(propagate_cache=True)¶
Turn any sorting in a NumpySorting. useful to have it in memory with a unique vector representation.
- Parameters
- propagate_cachebool
Propagate the cache of indivudual spike trains.
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)¶
Construct a unique structured numpy vector concatenating all spikes with several fields: sample_index, unit_index, segment_index.
- Parameters
- concatenated: bool, default: True
With concatenated=True the output is one numpy “spike vector” with spikes from all segments. With concatenated=False the output is a list “spike vector” by segment.
- extremum_channel_inds: None or dict, default: None
If a dictionnary of unit_id to channel_ind is given then an extra field “channel_index”. This can be convinient for computing spikes postion after sorter. This dict can be computed with get_template_extremum_channel(we, outputs=”index”)
- use_cache: bool, default: True
When True the spikes vector is cached as an attribute of the object (_cached_spike_vector). This caching only occurs when extremum_channel_inds=None.
- Returns
- spikes: np.array
Structured numpy array (“sample_index”, “unit_index”, “segment_index”) with all spikes Or (“sample_index”, “unit_index”, “segment_index”, “channel_index”) if extremum_channel_inds is given
- class spikeinterface.core.BaseSnippets(sampling_frequency: float, nbefore: Optional[int], snippet_len: int, channel_ids: list, dtype)¶
Abstract class representing several multichannel snippets.
- class spikeinterface.core.BaseEvent(channel_ids, structured_dtype)¶
Abstract class representing events.
- Parameters
- channel_idslist or np.array
The channel ids
- structured_dtypedtype or dict
The dtype of the events. If dict, each key is the channel_id and values must be the dtype of the channel (also structured). If dtype, each channel is assigned the same dtype. In case of structured dtypes, the “time” or “timestamp” field name must be present.
- get_event_times(channel_id=None, segment_index=None, start_time=None, end_time=None)¶
Return events timestamps of a channel in seconds.
- Parameters
- channel_idint or str, default: None
The event channel id
- segment_indexint or None, default: None
The segment index, required for multi-segment objects
- start_timefloat, default: None
The start time in seconds
- end_timefloat, default: None
The end time in seconds
- Returns
- np.array
1d array of timestamps for the event channel
- get_events(channel_id=None, segment_index=None, start_time=None, end_time=None)¶
Return events of a channel in its native structured type.
- Parameters
- channel_idint or str, default: None
The event channel id
- segment_indexint or None, default: None
The segment index, required for multi-segment objects
- start_timefloat, default: None
The start time in seconds
- end_timefloat, default: None
The end time in seconds
- Returns
- np.array
Structured np.array of dtype get_dtype(channel_id)
- class spikeinterface.core.WaveformExtractor(recording: Optional[BaseRecording], sorting: BaseSorting, folder=None, rec_attributes=None, allow_unfiltered: bool = False, sparsity=None)¶
Class to extract waveform on paired Recording-Sorting objects. Waveforms are persistent on disk and cached in memory.
- Parameters
- recording: Recording | None
The recording object
- sorting: Sorting
The sorting object
- folder: Path
The folder where waveforms are cached
- rec_attributes: None or dict
When recording is None then a minimal dict with some attributes is needed.
- allow_unfiltered: bool, default: False
If true, will accept unfiltered recording.
- Returns
- ——-
- we: WaveformExtractor
The WaveformExtractor object
Examples
>>> # Instantiate >>> we = WaveformExtractor.create(recording, sorting, folder)
>>> # Compute >>> we = we.set_params(...) >>> we = we.run_extract_waveforms(...)
>>> # Retrieve >>> waveforms = we.get_waveforms(unit_id) >>> template = we.get_template(unit_id, mode="median")
>>> # Load from folder (in another session) >>> we = WaveformExtractor.load(folder)
- delete_extension(extension_name) None ¶
Deletes an existing extension.
- Parameters
- extension_name: str
The extension name.
- delete_waveforms() None ¶
Deletes waveforms folder.
- get_all_templates(unit_ids: Optional[Iterable] = None, mode='average', percentile: Optional[float] = None)¶
Return templates (average waveforms) for multiple units.
- Parameters
- unit_ids: list or None
Unit ids to retrieve waveforms for
- mode: “average” | “median” | “std” | “percentile”, default: “average”
The mode to compute the templates
- percentile: float, default: None
Percentile to use for mode=”percentile”
- Returns
- templates: np.array
The returned templates (num_units, num_samples, num_channels)
- get_available_extension_names()¶
Return a list of loaded or available extension names either in memory or in persistent extension folders. Then instances can be loaded with we.load_extension(extension_name)
Importante note: extension modules need to be loaded (and so registered) before this call, otherwise extensions will be ignored even if the folder exists.
- Returns
- extension_names_in_folder: list
A list of names of computed extension in this folder
- get_extension_class(extension_name: str)¶
Get extension class from name and check if registered.
- Parameters
- extension_name: str
The extension name.
- Returns
- ext_class:
The class of the extension.
- get_sampled_indices(unit_id)¶
Return sampled spike indices of extracted waveforms
- Parameters
- unit_id: int or str
Unit id to retrieve indices for
- Returns
- sampled_indices: np.array
The sampled indices
- get_template(unit_id, mode='average', sparsity=None, force_dense: bool = False, percentile: Optional[float] = None)¶
Return template (average waveform).
- Parameters
- unit_id: int or str
Unit id to retrieve waveforms for
- mode: “average” | “median” | “std” | “percentile”, default: “average”
The mode to compute the template
- sparsity: ChannelSparsity, default: None
Sparsity to apply to the waveforms (if WaveformExtractor is not sparse)
- force_dense: bool, default: False
Return a dense template even if the waveform extractor is sparse
- percentile: float, default: None
Percentile to use for mode=”percentile”. Values must be between 0 and 100 inclusive
- Returns
- template: np.array
The returned template (num_samples, num_channels)
- get_template_segment(unit_id, segment_index, mode='average', sparsity=None)¶
Return template for the specified unit id computed from waveforms of a specific segment.
- Parameters
- unit_id: int or str
Unit id to retrieve waveforms for
- segment_index: int
The segment index to retrieve template from
- mode: “average” | “median” | “std”, default: “average”
The mode to compute the template
- sparsity: ChannelSparsity, default: None
Sparsity to apply to the waveforms (if WaveformExtractor is not sparse).
- Returns
- template: np.array
The returned template (num_samples, num_channels)
- get_waveforms(unit_id, with_index: bool = False, cache: bool = False, lazy: bool = True, sparsity=None, force_dense: bool = False)¶
Return waveforms for the specified unit id.
- Parameters
- unit_id: int or str
Unit id to retrieve waveforms for
- with_index: bool, default: False
If True, spike indices of extracted waveforms are returned
- cache: bool, default: False
If True, waveforms are cached to the self._waveforms dictionary
- lazy: bool, default: True
If True, waveforms are loaded as memmap objects (when format=”binary”) or Zarr datasets (when format=”zarr”). If False, waveforms are loaded as np.array objects
- sparsity: ChannelSparsity, default: None
Sparsity to apply to the waveforms (if WaveformExtractor is not sparse)
- force_dense: bool, default: False
Return dense waveforms even if the waveform extractor is sparse
- Returns
- wfs: np.array
The returned waveform (num_spikes, num_samples, num_channels)
- indices: np.array
If “with_index” is True, the spike indices corresponding to the waveforms extracted
- get_waveforms_segment(segment_index: int, unit_id, sparsity)¶
Return waveforms from a specified segment and unit_id.
- Parameters
- segment_index: int
The segment index to retrieve waveforms from
- unit_id: int or str
Unit id to retrieve waveforms for
- sparsity: ChannelSparsity, default: None
Sparsity to apply to the waveforms (if WaveformExtractor is not sparse)
- Returns
- wfs: np.array
The returned waveform (num_spikes, num_samples, num_channels)
- has_extension(extension_name: str) bool ¶
Check if the extension exists in memory or in the folder.
- Parameters
- extension_name: str
The extension name.
- Returns
- exists: bool
Whether the extension exists or not
- load_extension(extension_name: str)¶
Load an extension from its name. The module of the extension must be loaded and registered.
- Parameters
- extension_name: str
The extension name.
- Returns
- ext_instanace:
The loaded instance of the extension
- precompute_templates(modes=('average', 'std', 'median', 'percentile'), percentile=None) None ¶
- Precompute all templates for different “modes”:
average
std
median
percentile
- Parameters
- modes: list
The modes to compute the templates
- percentile: float, default: None
Percentile to use for mode=”percentile”
- The results is cached in memory as a 3d ndarray (nunits, nsamples, nchans)
- and also saved as an npy file in the folder to avoid recomputation each time.
- classmethod register_extension(extension_class) None ¶
This maintains a list of possible extensions that are available. It depends on the imported submodules (e.g. for postprocessing module).
For instance: import spikeinterface as si si.WaveformExtractor.extensions == []
from spikeinterface.postprocessing import WaveformPrincipalComponent si.WaveformExtractor.extensions == [WaveformPrincipalComponent, …]
- save(folder, format='binary', use_relative_path: bool = False, overwrite: bool = False, sparsity=None, **kwargs) WaveformExtractor ¶
Save WaveformExtractor object to disk.
- Parameters
- folderstr or Path
The output waveform folder
- format“binary” | “zarr”, default: “binary”
The backend to use for saving the waveforms
- overwritebool
If True and folder exists, it is deleted, default: False
- use_relative_pathbool, default: False
If True, the recording and sorting paths are relative to the waveforms folder. This allows portability of the waveform folder provided that the relative paths are the same, but forces all the data files to be in the same drive
- sparsityChannelSparsity, default: None
If given and WaveformExtractor is not sparse, it makes the returned WaveformExtractor sparse
- select_units(unit_ids, new_folder=None, use_relative_path: bool = False) WaveformExtractor ¶
Filters units by creating a new waveform extractor object in a new folder.
Extensions are also updated to filter the selected unit ids.
- Parameters
- unit_idslist or array
The unit ids to keep in the new WaveformExtractor object
- new_folderPath or None
The new folder where selected waveforms are copied
- Returns
- weWaveformExtractor
The newly create waveform extractor with the selected units
- set_params(ms_before: float = 1.0, ms_after: float = 2.0, max_spikes_per_unit: int = 500, return_scaled: bool = False, dtype=None) None ¶
Set parameters for waveform extraction
- Parameters
- ms_before: float
Cut out in ms before spike time
- ms_after: float
Cut out in ms after spike time
- max_spikes_per_unit: int
Maximum number of spikes to extract per unit
- return_scaled: bool
If True and recording has gain_to_uV/offset_to_uV properties, waveforms are converted to uV.
- dtype: np.dtype
The dtype of the computed waveforms
- set_recording(recording: Optional[BaseRecording], rec_attributes: Optional[dict] = None, allow_unfiltered: bool = False) None ¶
Sets the recording object and attributes for the WaveformExtractor.
- Parameters
- recording: Recording | None
The recording object
- rec_attributes: None or dict
When recording is None then a minimal dict with some attributes is needed.
- allow_unfiltered: bool, default: False
If true, will accept unfiltered recording.
- spikeinterface.core.extract_waveforms(recording, sorting, folder=None, mode='folder', precompute_template=('average',), ms_before=1.0, ms_after=2.0, max_spikes_per_unit=500, overwrite=False, return_scaled=True, dtype=None, sparse=True, sparsity=None, sparsity_temp_folder=None, num_spikes_for_sparsity=100, unit_batch_size=200, allow_unfiltered=False, use_relative_path=False, seed=None, load_if_exists=None, **kwargs)¶
Extracts waveform on paired Recording-Sorting objects. Waveforms can be persistent on disk (mode`=”folder”) or in-memory (`mode`=”memory”). By default, waveforms are extracted on a subset of the spikes (`max_spikes_per_unit) and on all channels (dense). If the sparse parameter is set to True, a sparsity is estimated using a small number of spikes (num_spikes_for_sparsity) and waveforms are extracted and saved in sparse mode.
- Parameters
- recording: Recording
The recording object
- sorting: Sorting
The sorting object
- folder: str or Path or None, default: None
The folder where waveforms are cached
- mode: “folder” | “memory, default: “folder”
The mode to store waveforms. If “folder”, waveforms are stored on disk in the specified folder. The “folder” argument must be specified in case of mode “folder”. If “memory” is used, the waveforms are stored in RAM. Use this option carefully!
- precompute_template: None or list, default: [“average”]
Precompute average/std/median for template. If None, no templates are precomputed
- ms_before: float, default: 1.0
Time in ms to cut before spike peak
- ms_after: float, default: 2.0
Time in ms to cut after spike peak
- max_spikes_per_unit: int or None, default: 500
Number of spikes per unit to extract waveforms from Use None to extract waveforms for all spikes
- overwrite: bool, default: False
If True and “folder” exists, the folder is removed and waveforms are recomputed Otherwise an error is raised.
- return_scaled: bool, default: True
If True and recording has gain_to_uV/offset_to_uV properties, waveforms are converted to uV
- dtype: dtype or None, default: None
Dtype of the output waveforms. If None, the recording dtype is maintained
- sparse: bool, default: True
If True, before extracting all waveforms the precompute_sparsity() function is run using a few spikes to get an estimate of dense templates to create a ChannelSparsity object. Then, the waveforms will be sparse at extraction time, which saves a lot of memory. When True, you must some provide kwargs handle precompute_sparsity() to control the kind of sparsity you want to apply (by radius, by best channels, …).
- sparsity: ChannelSparsity or None, default: None
The sparsity used to compute waveforms. If this is given, sparse is ignored. Default None.
- sparsity_temp_folder: str or Path or None, default: None
If sparse is True, this is the temporary folder where the dense waveforms are temporarily saved. If None, dense waveforms are extracted in memory in batches (which can be controlled by the unit_batch_size parameter. With a large number of units (e.g., > 400), it is advisable to use a temporary folder.
- num_spikes_for_sparsity: int, default: 100
The number of spikes to use to estimate sparsity (if sparse=True).
- unit_batch_size: int, default: 200
The number of units to process at once when extracting dense waveforms (if sparse=True and sparsity_temp_folder is None).
- allow_unfiltered: bool
If true, will accept an allow_unfiltered recording.
- use_relative_path: bool, default: False
If True, the recording and sorting paths are relative to the waveforms folder. This allows portability of the waveform folder provided that the relative paths are the same, but forces all the data files to be in the same drive.
- seed: int or None, default: None
Random seed for spike selection
- sparsity kwargs:
- method: str
- “best_channels”: N best channels with the largest amplitude. Use the “num_channels” argument to specify the
number of channels.
“radius”: radius around the best channel. Use the “radius_um” argument to specify the radius in um
- “snr”: threshold based on template signal-to-noise ratio. Use the “threshold” argument
to specify the SNR threshold (in units of noise levels)
- “ptp”: threshold based on the peak-to-peak values on every channels. Use the “threshold” argument
to specify the ptp threshold (in units of noise levels)
- “energy”: threshold based on the expected energy that should be present on the channels,
given their noise levels. Use the “threshold” argument to specify the SNR threshold (in units of noise levels)
- “by_property”: sparsity is given by a property of the recording and sorting(e.g. “group”).
Use the “by_property” argument to specify the property name.
- peak_sign: str
Sign of the template to compute best channels (“neg”, “pos”, “both”)
- num_channels: int
Number of channels for “best_channels” method
- radius_um: float
Radius in um for “radius” method
- threshold: float
Threshold in SNR “threshold” method
- by_property: object
Property name for “by_property” method
- job kwargs:
- **job_kwargs: keyword arguments for parallel processing:
- chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
Number of samples per chunk
- chunk_memory: str
Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
- n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
- progress_bar: bool
If True, a progress bar is printed
- mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems
- Returns
- we: WaveformExtractor
The WaveformExtractor object
Examples
>>> import spikeinterface as si
>>> # Extract dense waveforms and save to disk >>> we = si.extract_waveforms(recording, sorting, folder="waveforms")
>>> # Extract dense waveforms with parallel processing and save to disk >>> job_kwargs = dict(n_jobs=8, chunk_duration="1s", progress_bar=True) >>> we = si.extract_waveforms(recording, sorting, folder="waveforms", **job_kwargs)
>>> # Extract dense waveforms on all spikes >>> we = si.extract_waveforms(recording, sorting, folder="waveforms-all", max_spikes_per_unit=None)
>>> # Extract dense waveforms in memory >>> we = si.extract_waveforms(recording, sorting, folder=None, mode="memory")
>>> # Extract sparse waveforms (with radius-based sparsity of 50um) and save to disk >>> we = si.extract_waveforms(recording, sorting, folder="waveforms-sparse", mode="folder", >>> sparse=True, num_spikes_for_sparsity=100, method="radius", radius_um=50)
- spikeinterface.core.load_waveforms(folder, with_recording: bool = True, sorting: Optional[BaseSorting] = None) WaveformExtractor ¶
Load a waveform extractor object from disk.
- Parameters
- folderstr or Path
The folder / zarr folder where the waveform extractor is stored
- with_recordingbool, default: True
If True, the recording is loaded. If False, the WaveformExtractor object in recordingless mode.
- sortingBaseSorting, default: None
If passed, the sorting object associated to the waveform extractor
- Returns
- we: WaveformExtractor
The loaded waveform extractor
- spikeinterface.core.compute_sparsity(waveform_extractor, method='radius', peak_sign='neg', num_channels=5, radius_um=100.0, threshold=5, by_property=None)¶
Get channel sparsity (subset of channels) for each template with several methods.
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor
- method: str
- “best_channels”: N best channels with the largest amplitude. Use the “num_channels” argument to specify the
number of channels.
“radius”: radius around the best channel. Use the “radius_um” argument to specify the radius in um
- “snr”: threshold based on template signal-to-noise ratio. Use the “threshold” argument
to specify the SNR threshold (in units of noise levels)
- “ptp”: threshold based on the peak-to-peak values on every channels. Use the “threshold” argument
to specify the ptp threshold (in units of noise levels)
- “energy”: threshold based on the expected energy that should be present on the channels,
given their noise levels. Use the “threshold” argument to specify the SNR threshold (in units of noise levels)
- “by_property”: sparsity is given by a property of the recording and sorting(e.g. “group”).
Use the “by_property” argument to specify the property name.
- peak_sign: str
Sign of the template to compute best channels (“neg”, “pos”, “both”)
- num_channels: int
Number of channels for “best_channels” method
- radius_um: float
Radius in um for “radius” method
- threshold: float
Threshold in SNR “threshold” method
- by_property: object
Property name for “by_property” method
- Returns
- sparsity: ChannelSparsity
The estimated sparsity
- class spikeinterface.core.ChannelSparsity(mask, unit_ids, channel_ids)¶
Handle channel sparsity for a set of units. That is, for every unit, it indicates which channels are used to represent the waveform and the rest of the non-represented channels are assumed to be zero.
Internally, sparsity is stored as a boolean mask.
The ChannelSparsity object can also provide other sparsity representations:
ChannelSparsity.unit_id_to_channel_ids : unit_id to channel_ids
ChannelSparsity.unit_id_to_channel_indices : unit_id channel_inds
By default it is constructed with a boolean array:
>>> sparsity = ChannelSparsity(mask, unit_ids, channel_ids)
But can be also constructed from a dictionary:
>>> sparsity = ChannelSparsity.from_unit_id_to_channel_ids(unit_id_to_channel_ids, unit_ids, channel_ids)
- Parameters
- mask: np.array of bool
The sparsity mask (num_units, num_channels)
- unit_ids: list or array
Unit ids vector or list
- channel_ids: list or array
Channel ids vector or list
Examples
The class can also be used to construct/estimate the sparsity from a Waveformextractor with several methods:
Using the N best channels (largest template amplitude):
>>> sparsity = ChannelSparsity.from_best_channels(we, num_channels, peak_sign="neg")
Using a neighborhood by radius:
>>> sparsity = ChannelSparsity.from_radius(we, radius_um, peak_sign="neg")
Using a SNR threshold: >>> sparsity = ChannelSparsity.from_snr(we, threshold, peak_sign=”neg”)
Using a template energy threshold: >>> sparsity = ChannelSparsity.from_energy(we, threshold)
Using a recording/sorting property (e.g. “group”):
>>> sparsity = ChannelSparsity.from_property(we, by_property="group")
- classmethod create_dense(we)¶
Create a sparsity object with all selected channel for all units.
- densify_waveforms(waveforms: ndarray, unit_id: str | int) ndarray ¶
Densify sparse waveforms that were sparisified according to a unit’s channel sparsity.
Given a unit_id its sparsified waveform, this method places the waveform back into its original form within a dense array.
- Parameters
- waveformsnp.array
The sparsified waveforms array of shape (num_waveforms, num_samples, num_active_channels) or a single sparse waveform (template) with shape (num_samples, num_active_channels).
- unit_idstr
The unit_id that was used to sparsify the waveform.
- Returns
- densified_waveformsnp.array
The densified waveforms array of shape (num_waveforms, num_samples, num_channels) or a single dense waveform (template) with shape (num_samples, num_channels).
- classmethod from_best_channels(we, num_channels, peak_sign='neg')¶
Construct sparsity from N best channels with the largest amplitude. Use the “num_channels” argument to specify the number of channels.
- classmethod from_energy(we, threshold)¶
Construct sparsity from a threshold based on per channel energy ratio. Use the “threshold” argument to specify the SNR threshold.
- classmethod from_property(we, by_property)¶
Construct sparsity witha property of the recording and sorting(e.g. “group”). Use the “by_property” argument to specify the property name.
- classmethod from_ptp(we, threshold)¶
Construct sparsity from a thresholds based on template peak-to-peak values. Use the “threshold” argument to specify the SNR threshold.
- classmethod from_radius(we, radius_um, peak_sign='neg')¶
Construct sparsity from a radius around the best channel. Use the “radius_um” argument to specify the radius in um
- classmethod from_snr(we, threshold, peak_sign='neg')¶
Construct sparsity from a thresholds based on template signal-to-noise ratio. Use the “threshold” argument to specify the SNR threshold.
- classmethod from_unit_id_to_channel_ids(unit_id_to_channel_ids, unit_ids, channel_ids)¶
Create a sparsity object from dict unit_id to channel_ids.
- sparsify_waveforms(waveforms: ndarray, unit_id: str | int) ndarray ¶
Sparsify the waveforms according to a unit_id corresponding sparsity.
Given a unit_id, this method selects only the active channels for that unit and removes the rest.
- Parameters
- waveformsnp.array
Dense waveforms with shape (num_waveforms, num_samples, num_channels) or a single dense waveform (template) with shape (num_samples, num_channels).
- unit_idstr
The unit_id for which to sparsify the waveform.
- Returns
- sparsified_waveformsnp.array
Sparse waveforms with shape (num_waveforms, num_samples, num_active_channels) or a single sparsified waveform (template) with shape (num_samples, num_active_channels).
- to_dict()¶
Return a serializable dict.
- class spikeinterface.core.BinaryRecordingExtractor(file_paths, sampling_frequency, dtype, num_channels=None, t_starts=None, channel_ids=None, time_axis=0, file_offset=0, gain_to_uV=None, offset_to_uV=None, is_filtered=None, num_chan=None)¶
RecordingExtractor for a binary format
- Parameters
- file_paths: str or Path or list
Path to the binary file
- sampling_frequency: float
The sampling frequency
- num_channels: int
Number of channels
- num_chan: int [deprecated, use num_channels instead, will be removed as early as v0.100.0]
Number of channels
- dtype: str or dtype
The dtype of the binary file
- time_axis: int, default: 0
The axis of the time dimension
- t_starts: None or list of float, default: None
Times in seconds of the first sample for each segment
- channel_ids: list, default: None
A list of channel ids
- file_offset: int, default: 0
Number of bytes in the file to offset by during memmap instantiation.
- gain_to_uV: float or array-like, default: None
The gain to apply to the traces
- offset_to_uV: float or array-like, default: None
The offset to apply to the traces
- is_filtered: bool or None, default: None
If True, the recording is assumed to be filtered. If None, is_filtered is not set.
- Returns
- recording: BinaryRecordingExtractor
The recording Extractor
Notes
When both num_channels and num_chan are provided, num_channels is used and num_chan is ignored.
- class spikeinterface.core.ZarrRecordingExtractor(root_path: Union[Path, str], storage_options=None)¶
RecordingExtractor for a zarr format
- Parameters
- root_path: str or Path
Path to the zarr root file
- storage_options: dict or None
Storage options for zarr store. E.g., if “s3://” or “gcs://” they can provide authentication methods, etc.
- Returns
- recording: ZarrRecordingExtractor
The recording Extractor
- class spikeinterface.core.BinaryFolderRecording(folder_path)¶
BinaryFolderRecording is an internal format used in spikeinterface. It is a BinaryRecordingExtractor + metadata contained in a folder.
It is created with the function: recording.save(format=”binary”, folder=”/myfolder”)
- Parameters
- folder_path: str or Path
- Returns
- recording: BinaryFolderRecording
The recording
- class spikeinterface.core.NpzFolderSorting(folder_path)¶
NpzFolderSorting is the old internal format used in spikeinterface (<=0.98.0)
This a folder that contains:
“sorting_cached.npz” file in the NpzSortingExtractor format
“npz.json” which the json description of NpzSortingExtractor
a metadata folder for units properties.
It is created with the function: sorting.save(folder=”/myfolder”, format=”npz_folder”)
- Parameters
- folder_path: str or Path
- Returns
- sorting: NpzFolderSorting
The sorting
- class spikeinterface.core.NpyFolderSnippets(folder_path)¶
NpyFolderSnippets is an internal format used in spikeinterface. It is a NpySnippetsExtractor + metadata contained in a folder.
It is created with the function: snippets.save(format=”npy”, folder=”/myfolder”)
- Parameters
- folder_path: str or Path
The path to the folder
- Returns
- snippets: NpyFolderSnippets
The snippets
- class spikeinterface.core.NumpyRecording(traces_list, sampling_frequency, t_starts=None, channel_ids=None)¶
In memory recording. Contrary to previous version this class does not handle npy files.
- Parameters
- traces_list: list of array or array (if mono segment)
The traces to instantiate a mono or multisegment Recording
- sampling_frequency: float
The sampling frequency in Hz
- t_starts: None or list of float
Times in seconds of the first sample for each segment
- channel_ids: list
An optional list of channel_ids. If None, linear channels are assumed
- class spikeinterface.core.NumpySorting(spikes, sampling_frequency, unit_ids)¶
In memory sorting object. The internal representation is always done with a long “spike vector”.
- But we have convenient class methods to instantiate from:
other sorting object: NumpySorting.from_sorting()
from time+labels: NumpySorting.from_times_labels()
from dict of list: NumpySorting.from_unit_dict()
from neo: NumpySorting.from_neo_spiketrain_list()
- Parameters
- spikes: numpy.array
A numpy vector, the one given by Sorting.to_spike_vector().
- sampling_frequency: float
The sampling frequency in Hz
- channel_ids: list
A list of unit_ids.
- class spikeinterface.core.NumpySnippets(snippets_list, spikesframes_list, sampling_frequency, nbefore=None, channel_ids=None)¶
In memory recording. Contrary to previous version this class does not handle npy files.
- Parameters
- snippets_list: list of array or array (if mono segment)
The snippets to instantiate a mono or multisegment basesnippet
- spikesframes_list: list of array or array (if mono segment)
Frame of each snippet
- sampling_frequency: float
The sampling frequency in Hz
- channel_ids: list
An optional list of channel_ids. If None, linear channels are assumed
- class spikeinterface.core.AppendSegmentRecording(recording_list, sampling_frequency_max_diff=0)¶
Takes as input a list of parent recordings each with multiple segments and returns a single multi-segment recording that “appends” all segments from all parent recordings.
For instance, given one recording with 2 segments and one recording with 3 segments, this class will give one recording with 5 segments
- Parameters
- recording_listlist of BaseRecording
A list of recordings
- sampling_frequency_max_difffloat, default: 0
Maximum allowed difference of sampling frequencies across recordings
- class spikeinterface.core.ConcatenateSegmentRecording(recording_list, ignore_times=True, sampling_frequency_max_diff=0)¶
Return a recording that “concatenates” all segments from all parent recordings into one recording with a single segment. The operation is lazy.
For instance, given one recording with 2 segments and one recording with 3 segments, this class will give one recording with one large segment made by concatenating the 5 segments.
Time information is lost upon concatenation. By default ignore_times is True. If it is False, you get an error unless:
all segments DO NOT have times, AND
all segment have t_start=None
- Parameters
- recording_listlist of BaseRecording
A list of recordings
- ignore_times: bool, default: True
If True, time information (t_start, time_vector) is ignored when concatenating recordings
- sampling_frequency_max_difffloat, default: 0
Maximum allowed difference of sampling frequencies across recordings
- class spikeinterface.core.SelectSegmentRecording(recording: BaseRecording, segment_indices: Union[int, List[int]])¶
Return a new recording with a subset of segments from a multi-segment recording.
- Parameters
- recordingBaseRecording
The multi-segment recording
- segment_indiceslist of 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: Union[int, List[int]])¶
Return a new sorting with a single segment from a multi-segment sorting.
- Parameters
- sortingBaseSorting
The multi-segment sorting
- segment_indiceslist of int
The segment indices to select
- spikeinterface.core.download_dataset(repo: str = 'https://gin.g-node.org/NeuralEnsemble/ephy_testing_data', remote_path: str = 'mearec/mearec_test_10s.h5', local_folder: Optional[Path] = None, update_if_exists: bool = False, unlock: bool = False) Path ¶
Function to download dataset from a remote repository using datalad.
- Parameters
- repostr, default: “https://gin.g-node.org/NeuralEnsemble/ephy_testing_data”
The repository to download the dataset from
- remote_pathstr, default: “mearec/mearec_test_10s.h5”
A specific subdirectory in the repository to download (e.g. Mearec, SpikeGLX, etc)
- local_folderstr, default: None
The destination folder / directory to download the dataset to. defaults to the path “get_global_dataset_folder()” / f{repo_name} (see spikeinterface.core.globals)
- update_if_existsbool, default: False
Forces re-download of the dataset if it already exists, default: False
- unlockbool, default: False
Use to enable the edition of the downloaded file content, default: False
- Returns
- Path
The local path to the downloaded dataset
- spikeinterface.core.write_binary_recording(recording, file_paths, dtype=None, add_file_extension=True, byte_offset=0, auto_cast_uint=True, **job_kwargs)¶
Save the trace of a recording extractor in several binary .dat format.
- Note :
time_axis is always 0 (contrary to previous version. to get time_axis=1 (which is a bad idea) use write_binary_recording_file_handle()
- Parameters
- recording: RecordingExtractor
The recording extractor object to be saved in .dat format
- file_path: str or list[str]
The path to the file.
- dtype: dtype or None, default: None
Type of the saved data If True, file the “.raw” file extension is added if the file name is not a “raw”, “bin”, or “dat”
- byte_offset: int, default: 0
Offset in bytes to for the binary file (e.g. to write a header)
- auto_cast_uint: bool, default: True
If True, unsigned integers are automatically cast to int if the specified dtype is signed
- **job_kwargs: keyword arguments for parallel processing:
- chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
Number of samples per chunk
- chunk_memory: str
Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
- n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
- progress_bar: bool
If True, a progress bar is printed
- mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems
- spikeinterface.core.set_global_tmp_folder(folder)¶
Set the global path temporary folder.
- spikeinterface.core.set_global_dataset_folder(folder)¶
Set the global dataset folder.
- spikeinterface.core.set_global_job_kwargs(**job_kwargs)¶
Set the global job kwargs.
- Parameters
- **job_kwargs: keyword arguments for parallel processing:
- chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
Number of samples per chunk
- chunk_memory: str
Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
- n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
- progress_bar: bool
If True, a progress bar is printed
- mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems
- spikeinterface.core.get_random_data_chunks(recording, return_scaled=False, num_chunks_per_segment=20, chunk_size=10000, concatenated=True, seed=0, margin_frames=0)¶
Extract random chunks across segments
This is used for instance in get_noise_levels() to estimate noise on traces.
- Parameters
- recording: BaseRecording
The recording to get random chunks from
- return_scaled: bool, default: False
If True, returned chunks are scaled to uV
- num_chunks_per_segment: int, default: 20
Number of chunks per segment
- chunk_size: int, default: 10000
Size of a chunk in number of frames
- concatenated: bool, default: True
If True chunk are concatenated along time axis
- seed: int, default: 0
Random seed
- margin_frames: int, default: 0
Margin in number of frames to avoid edge effects
- Returns
- chunk_list: np.array
Array of concatenate chunks per segment
- spikeinterface.core.get_channel_distances(recording)¶
Distance between channel pairs
- spikeinterface.core.get_closest_channels(recording, channel_ids=None, num_channels=None)¶
Get closest channels + distances
- Parameters
- recording: RecordingExtractor
The recording extractor to get closest channels
- channel_ids: list
List of channels ids to compute there near neighborhood
- num_channels: int, default: None
Maximum number of neighborhood channels to return
- Returns
- closest_channels_indsarray (2d)
Closest channel indices in ascending order for each channel id given in input
- dists: array (2d)
Distance in ascending order for each channel id given in input
- spikeinterface.core.get_noise_levels(recording: BaseRecording, return_scaled: bool = True, method: Literal['mad', 'std'] = 'mad', force_recompute: bool = False, **random_chunk_kwargs)¶
Estimate noise for each channel using MAD methods. You can use standard deviation with method=”std”
Internally it samples some chunk across segment. And then, it use MAD estimator (more robust than STD)
- Parameters
- recording: BaseRecording
The recording extractor to get noise levels
- return_scaled: bool
If True, returned noise levels are scaled to uV
- method: “mad” | “std”, default: “mad”
The method to use to estimate noise levels
- force_recompute: bool
If True, noise levels are recomputed even if they are already stored in the recording extractor
- random_chunk_kwargs: dict
Kwargs for get_random_data_chunks
- Returns
- noise_levels: array
Noise levels for each channel
- spikeinterface.core.get_chunk_with_margin(rec_segment, start_frame, end_frame, channel_indices, margin, add_zeros=False, add_reflect_padding=False, window_on_margin=False, dtype=None)¶
Helper to get chunk with margin
The margin is extracted from the recording when possible. If at the edge of the recording, no margin is used unless one of add_zeros or add_reflect_padding is True. In the first case zero padding is used, in the second case np.pad is called with mod=”reflect”.
- spikeinterface.core.order_channels_by_depth(recording, channel_ids=None, dimensions=('x', 'y'), flip=False)¶
Order channels by depth, by first ordering the x-axis, and then the y-axis.
- Parameters
- recordingBaseRecording
The input recording
- channel_idslist/array or None
If given, a subset of channels to order locations for
- dimensionsstr, tuple, or list, default: (‘x’, ‘y’)
If str, it needs to be ‘x’, ‘y’, ‘z’. If tuple or list, it sorts the locations in two dimensions using lexsort. This approach is recommended since there is less ambiguity
- flip: bool, default: False
If flip is False then the order is bottom first (starting from tip of the probe). If flip is True then the order is upper first.
- Returns
- order_fnp.array
Array with sorted indices
- order_rnp.array
Array with indices to revert sorting
- spikeinterface.core.get_template_amplitudes(waveform_extractor, peak_sign: neg' | 'pos' | 'both = 'neg', mode: extremum' | 'at_index = 'extremum')¶
Get amplitude per channel for each unit.
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Sign of the template to compute best channels
- mode: “extremum” | “at_index”, default: “extremum”
“extremum”: max or min “at_index”: take value at spike index
- Returns
- peak_values: dict
Dictionary with unit ids as keys and template amplitudes as values
- spikeinterface.core.get_template_extremum_channel(waveform_extractor, peak_sign: neg' | 'pos' | 'both = 'neg', mode: extremum' | 'at_index = 'extremum', outputs: id' | 'index = 'id')¶
Compute the channel with the extremum peak for each unit.
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Sign of the template to compute best channels
- mode: “extremum” | “at_index”, default: “extremum”
“extremum”: max or min “at_index”: take value at spike index
- outputs: “id” | “index”, default: “id”
“id”: channel id
“index”: channel index
- Returns
- extremum_channels: dict
Dictionary with unit ids as keys and extremum channels (id or index based on “outputs”) as values
- spikeinterface.core.get_template_extremum_channel_peak_shift(waveform_extractor, peak_sign: neg' | 'pos' | 'both = 'neg')¶
In some situations spike sorters could return a spike index with a small shift related to the waveform peak. This function estimates and return these alignment shifts for the mean template. This function is internally used by compute_spike_amplitudes() to accurately retrieve the spike amplitudes.
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Sign of the template to compute best channels
- Returns
- shifts: dict
Dictionary with unit ids as keys and shifts as values
- spikeinterface.core.get_template_extremum_amplitude(waveform_extractor, peak_sign: neg' | 'pos' | 'both = 'neg', mode: extremum' | 'at_index = 'at_index')¶
Computes amplitudes on the best channel.
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor
- peak_sign: “neg” | “pos” | “both”
Sign of the template to compute best channels
- mode: “extremum” | “at_index”, default: “at_index”
Where the amplitude is computed “extremum”: max or min “at_index”: take value at spike index
- Returns
- amplitudes: dict
Dictionary with unit ids as keys and amplitudes as values
- spikeinterface.core.append_recordings(recording_list, sampling_frequency_max_diff=0)¶
Takes as input a list of parent recordings each with multiple segments and returns a single multi-segment recording that “appends” all segments from all parent recordings.
For instance, given one recording with 2 segments and one recording with 3 segments, this class will give one recording with 5 segments
- Parameters
- recording_listlist of BaseRecording
A list of recordings
- sampling_frequency_max_difffloat, default: 0
Maximum allowed difference of sampling frequencies across recordings
- spikeinterface.core.concatenate_recordings(recording_list, ignore_times=True, sampling_frequency_max_diff=0)¶
Return a recording that “concatenates” all segments from all parent recordings into one recording with a single segment. The operation is lazy.
For instance, given one recording with 2 segments and one recording with 3 segments, this class will give one recording with one large segment made by concatenating the 5 segments.
Time information is lost upon concatenation. By default ignore_times is True. If it is False, you get an error unless:
all segments DO NOT have times, AND
all segment have t_start=None
- Parameters
- recording_listlist of BaseRecording
A list of recordings
- ignore_times: bool, default: True
If True, time information (t_start, time_vector) is ignored when concatenating recordings
- sampling_frequency_max_difffloat, default: 0
Maximum allowed difference of sampling frequencies across recordings
- spikeinterface.core.split_recording(recording: BaseRecording)¶
Return a list of mono-segment recordings from a multi-segment recording.
- Parameters
- recordingBaseRecording
The multi-segment recording
- Returns
- recording_list
A list of mono-segment recordings
- spikeinterface.core.select_segment_recording(recording: BaseRecording, segment_indices: Union[int, List[int]])¶
Return a new recording with a subset of segments from a multi-segment recording.
- Parameters
- recordingBaseRecording
The multi-segment recording
- segment_indiceslist of 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: Union[int, List[int]])¶
Return a new sorting with a single segment from a multi-segment sorting.
- Parameters
- sortingBaseSorting
The multi-segment sorting
- segment_indiceslist of int
The segment indices to select
- spikeinterface.core.read_binary(file_paths, sampling_frequency, dtype, num_channels=None, t_starts=None, channel_ids=None, time_axis=0, file_offset=0, gain_to_uV=None, offset_to_uV=None, is_filtered=None, num_chan=None)¶
RecordingExtractor for a binary format
- Parameters
- file_paths: str or Path or list
Path to the binary file
- sampling_frequency: float
The sampling frequency
- num_channels: int
Number of channels
- num_chan: int [deprecated, use num_channels instead, will be removed as early as v0.100.0]
Number of channels
- dtype: str or dtype
The dtype of the binary file
- time_axis: int, default: 0
The axis of the time dimension
- t_starts: None or list of float, default: None
Times in seconds of the first sample for each segment
- channel_ids: list, default: None
A list of channel ids
- file_offset: int, default: 0
Number of bytes in the file to offset by during memmap instantiation.
- gain_to_uV: float or array-like, default: None
The gain to apply to the traces
- offset_to_uV: float or array-like, default: None
The offset to apply to the traces
- is_filtered: bool or None, default: None
If True, the recording is assumed to be filtered. If None, is_filtered is not set.
- Returns
- recording: BinaryRecordingExtractor
The recording Extractor
Notes
When both num_channels and num_chan are provided, num_channels is used and num_chan is ignored.
- spikeinterface.core.read_zarr(root_path: Union[Path, str], storage_options=None)¶
RecordingExtractor for a zarr format
- Parameters
- root_path: str or Path
Path to the zarr root file
- storage_options: dict or None
Storage options for zarr store. E.g., if “s3://” or “gcs://” they can provide authentication methods, etc.
- Returns
- recording: ZarrRecordingExtractor
The recording Extractor
Low-level¶
- class spikeinterface.core.BaseWaveformExtractorExtension(waveform_extractor)¶
This the base class to extend the waveform extractor. It handles persistency to disk any computations related to a waveform extractor.
- For instance:
principal components
spike amplitudes
quality metrics
The design is done via a WaveformExtractor.register_extension(my_extension_class), so that only imported modules can be used as extension.
It also enables any custum computation on top on waveform extractor to be implemented by the user.
- An extension needs to inherit from this class and implement some abstract methods:
_reset
_set_params
_run
The subclass must also save to the self.extension_folder any file that needs to be reloaded when calling _load_extension_data
The subclass must also set an extension_name attribute which is not None by default.
- class spikeinterface.core.ChunkRecordingExecutor(recording, func, init_func, init_args, verbose=False, progress_bar=False, handle_returns=False, gather_func=None, n_jobs=1, total_memory=None, chunk_size=None, chunk_memory=None, chunk_duration=None, mp_context=None, job_name='', max_threads_per_process=1)¶
Core class for parallel processing to run a “function” over chunks on a recording.
- It supports running a function:
in loop with chunk processing (low RAM usage)
at once if chunk_size is None (high RAM usage)
in parallel with ProcessPoolExecutor (higher speed)
The initializer (“init_func”) allows to set a global context to avoid heavy serialization (for examples, see implementation in core.WaveformExtractor).
- Parameters
- recording: RecordingExtractor
The recording to be processed
- func: function
Function that runs on each chunk
- init_func: function
Initializer function to set the global context (accessible by “func”)
- init_args: tuple
Arguments for init_func
- verbose: bool
If True, output is verbose
- job_name: str, default: “”
Job name
- handle_returns: bool, default: False
If True, the function can return values
- gather_func: None or callable, default: None
Optional function that is called in the main thread and retrieves the results of each worker. This function can be used instead of handle_returns to implement custom storage on-the-fly.
- n_jobs: int, default: 1
Number of jobs to be used. Use -1 to use as many jobs as number of cores
- total_memory: str, default: None
Total memory (RAM) to use (e.g. “1G”, “500M”)
- chunk_memory: str, default: None
Memory per chunk (RAM) to use (e.g. “1G”, “500M”)
- chunk_size: int or None, default: None
Size of each chunk in number of samples. If “total_memory” or “chunk_memory” are used, it is ignored.
- chunk_durationstr or float or None
Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
- mp_context“fork” | “spawn” | None, default: None
“fork” or “spawn”. If None, the context is taken by the recording.get_preferred_mp_context(). “fork” is only safely available on LINUX systems.
- max_threads_per_process: int or None, default: None
Limit the number of thread per process using threadpoolctl modules. This used only when n_jobs>1 If None, no limits.
- progress_bar: bool, default: False
If True, a progress bar is printed to monitor the progress of the process
- Returns
- res: list
If “handle_returns” is True, the results for each chunk process
spikeinterface.extractors¶
NEO-based¶
- spikeinterface.extractors.read_alphaomega(folder_path, lsx_files=None, stream_id='RAW', stream_name=None, all_annotations=False)¶
Class for reading from AlphaRS and AlphaLab SnR boards.
Based on
neo.rawio.AlphaOmegaRawIO
- Parameters
- folder_path: str or Path-like
The folder path to the AlphaOmega recordings.
- lsx_files: list of strings or None, default: None
A list of listings files that refers to mpx files to load.
- stream_id: {“RAW”, “LFP”, “SPK”, “ACC”, “AI”, “UD”}, default: “RAW”
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_alphaomega_event(folder_path)¶
Class for reading events from AlphaOmega MPX file format
- spikeinterface.extractors.read_axona(file_path, all_annotations=False)¶
Class for reading Axona RAW format.
Based on
neo.rawio.AxonaRawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_biocam(file_path, mea_pitch=None, electrode_width=None, stream_id=None, stream_name=None, block_index=None, all_annotations=False)¶
Class for reading data from a Biocam file from 3Brain.
Based on
neo.rawio.BiocamRawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- mea_pitch: float, default: None
The inter-electrode distance (pitch) between electrodes.
- electrode_width: float, default: None
Width of the electrodes in um.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_binary(file_paths, sampling_frequency, dtype, num_channels=None, t_starts=None, channel_ids=None, time_axis=0, file_offset=0, gain_to_uV=None, offset_to_uV=None, is_filtered=None, num_chan=None)¶
RecordingExtractor for a binary format
- Parameters
- file_paths: str or Path or list
Path to the binary file
- sampling_frequency: float
The sampling frequency
- num_channels: int
Number of channels
- num_chan: int [deprecated, use num_channels instead, will be removed as early as v0.100.0]
Number of channels
- dtype: str or dtype
The dtype of the binary file
- time_axis: int, default: 0
The axis of the time dimension
- t_starts: None or list of float, default: None
Times in seconds of the first sample for each segment
- channel_ids: list, default: None
A list of channel ids
- file_offset: int, default: 0
Number of bytes in the file to offset by during memmap instantiation.
- gain_to_uV: float or array-like, default: None
The gain to apply to the traces
- offset_to_uV: float or array-like, default: None
The offset to apply to the traces
- is_filtered: bool or None, default: None
If True, the recording is assumed to be filtered. If None, is_filtered is not set.
- Returns
- recording: BinaryRecordingExtractor
The recording Extractor
Notes
When both num_channels and num_chan are provided, num_channels is used and num_chan is ignored.
- spikeinterface.extractors.read_blackrock(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False, use_names_as_ids=False)¶
Class for reading BlackRock data.
Based on
neo.rawio.BlackrockRawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_ced(file_path, stream_id=None, stream_name=None, all_annotations=False)¶
Class for reading smr/smrw CED file.
Based on
neo.rawio.CedRawIO
/ sonpyAlternative to read_spike2 which does not handle smrx
- Parameters
- file_path: str
The file path to the smr or smrx file.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- block_index: int, default: None
If there are several blocks, specify the block index you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_intan(file_path, stream_id=None, stream_name=None, all_annotations=False, use_names_as_ids=False)¶
Class for reading data from a intan board. Supports rhd and rhs format.
Based on
neo.rawio.IntanRawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_maxwell(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False, rec_name=None, install_maxwell_plugin=False)¶
Class for reading data from Maxwell device. It handles MaxOne (old and new format) and MaxTwo.
Based on
neo.rawio.MaxwellRawIO
- Parameters
- file_path: str
The file path to the maxwell h5 file.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load. For MaxTwo when there are several wells at the same time you need to specify stream_id=’well000’ or ‘well0001’, etc.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- rec_name: str, default: None
When the file contains several recordings you need to specify the one you want to extract. (rec_name=’rec0000’).
- install_maxwell_plugin: bool, default: False
If True, install the maxwell plugin for neo.
- spikeinterface.extractors.read_mearec(file_path)¶
Read a MEArec file.
- Parameters
- file_path: str or Path
Path to MEArec h5 file
- Returns
- recording: MEArecRecordingExtractor
The recording extractor object
- sorting: MEArecSortingExtractor
The sorting extractor object
- spikeinterface.extractors.read_mcsraw(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False)¶
Class for reading data from “Raw” Multi Channel System (MCS) format. This format is NOT the native MCS format (.mcd). This format is a raw format with an internal binary header exported by the “MC_DataTool binary conversion” with the option header selected.
Based on
neo.rawio.RawMCSRawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- block_index: int, default: None
If there are several blocks, specify the block index you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_neuralynx(folder_path, stream_id=None, stream_name=None, all_annotations=False)¶
Class for reading neuralynx folder
Based on
neo.rawio.NeuralynxRawIO
- Parameters
- folder_path: str
The file path to load the recordings from.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_neuralynx_sorting(folder_path: str, sampling_frequency: Optional[float] = None, stream_id: Optional[str] = None, stream_name: Optional[str] = None)¶
Class for reading spike data from a folder with neuralynx spiking data (i.e .nse and .ntt formats).
Based on
neo.rawio.NeuralynxRawIO
- Parameters
- folder_path: str
The file path to load the recordings from.
- sampling_frequency: float
The sampling frequency for the spiking channels. When the signal data is available (.ncs) those files will be used to extract the frequency. Otherwise, the sampling frequency needs to be specified for this extractor.
- stream_id: str, default: None
Used to extract information about the sampling frequency and t_start from the analog signal if provided.
- stream_name: str, default: None
Used to extract information about the sampling frequency and t_start from the analog signal if provided.
- spikeinterface.extractors.read_neuroexplorer(file_path, stream_id=None, stream_name=None, all_annotations=False)¶
Class for reading NEX (NeuroExplorer data format) files.
Based on
neo.rawio.NeuroExplorerRawIO
Importantly, at the moment, this recorder only extracts one channel of the recording. This is because the NeuroExplorerRawIO class does not support multi-channel recordings as in the NeuroExplorer format they might have different sampling rates.
Consider extracting all the channels and then concatenating them with the aggregate_channels function.
>>> from spikeinterface.extractors.neoextractors.neuroexplorer import NeuroExplorerRecordingExtractor >>> from spikeinterface.core import aggregate_channels >>> >>> file_path="/the/path/to/your/nex/file.nex" >>> >>> streams = NeuroExplorerRecordingExtractor.get_streams(file_path=file_path) >>> stream_names = streams[0] >>> >>> your_signal_stream_names = "Here goes the logic to filter from stream names the ones that you know have the same sampling rate and you want to aggregate" >>> >>> recording_list = [NeuroExplorerRecordingExtractor(file_path=file_path, stream_name=stream_name) for stream_name in your_signal_stream_names] >>> recording = aggregate_channels(recording_list)
- Parameters
- file_path: str
The file path to load the recordings from.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load. For this neo reader streams are defined by their sampling frequency.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_neuroscope(file_path, stream_id=None, keep_mua_units=False, exclude_shanks=None, load_recording=True, load_sorting=False)¶
Read neuroscope recording and sorting. This function assumses that all .res and .clu files are in the same folder as the .xml file.
- Parameters
- file_path: str
The xml file.
- stream_id: str or None
The stream id to load. If None, the first stream is loaded
- keep_mua_units: bool, default: False
Optional. Whether or not to return sorted spikes from multi-unit activity
- exclude_shanks: list
Optional. List of indices to ignore. The set of all possible indices is chosen by default, extracted as the final integer of all the .res. % i and .clu. % i pairs.
- load_recording: bool, default: True
If True, the recording is loaded
- load_sorting: bool, default: False
If True, the sorting is loaded
- spikeinterface.extractors.read_nix(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False)¶
Class for reading Nix file
Based on
neo.rawio.NIXRawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- block_index: int, default: None
If there are several blocks, specify the block index you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_openephys(folder_path, **kwargs)¶
Read “legacy” or “binary” Open Ephys formats
- Parameters
- folder_path: str or Path
Path to openephys folder
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load
- block_index: int, default: None
If there are several blocks (experiments), specify the block index you want to load
- all_annotations: bool, default: False
Load exhaustively all annotation from neo
- load_sync_channelbool, default: False
If False (default) and a SYNC channel is present (e.g. Neuropixels), this is not loaded. If True, the SYNC channel is loaded and can be accessed in the analog signals. For open ephsy binary format only
- load_sync_timestampsbool, default: False
If True, the synchronized_timestamps are loaded and set as times to the recording. If False (default), only the t_start and sampling rate are set, and timestamps are assumed to be uniform and linearly increasing. For open ephsy binary format only
- experiment_names: str, list, or None, default: None
If multiple experiments are available, this argument allows users to select one or more experiments. If None, all experiements are loaded as blocks. E.g. experiment_names=”experiment2”, experiment_names=[“experiment1”, “experiment2”] For open ephsy binary format only
- ignore_timestamps_errors: bool, default: False
Ignore the discontinuous timestamps errors in neo For open ephsy legacy format only
- Returns
- recording: OpenEphysLegacyRecordingExtractor or OpenEphysBinaryExtractor
- spikeinterface.extractors.read_openephys_event(folder_path, block_index=None)¶
Read Open Ephys events from “binary” format.
- Parameters
- folder_path: str or Path
Path to openephys folder
- block_index: int, default: None
If there are several blocks (experiments), specify the block index you want to load.
- Returns
- event: OpenEphysBinaryEventExtractor
- spikeinterface.extractors.read_plexon(file_path, stream_id=None, stream_name=None, all_annotations=False)¶
Class for reading plexon plx files.
Based on
neo.rawio.PlexonRawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_plexon_sorting(file_path)¶
Class for reading plexon spiking data (.plx files).
Based on
neo.rawio.PlexonRawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- spikeinterface.extractors.read_plexon2(file_path, stream_id=None, stream_name=None, all_annotations=False)¶
Class for reading plexon pl2 files.
Based on
neo.rawio.Plexon2RawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_plexon2_sorting(file_path, sampling_frequency=None)¶
Class for reading plexon spiking data from .pl2 files.
Based on
neo.rawio.Plexon2RawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- sampling_frequency: float, default: None
The sampling frequency of the sorting (required for multiple streams with different sampling frequencies).
- spikeinterface.extractors.read_spike2(file_path, stream_id=None, stream_name=None, all_annotations=False)¶
Class for reading spike2 smr files. smrx are not supported with this, prefer CedRecordingExtractor instead.
Based on
neo.rawio.Spike2RawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- stream_id: str, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_spikegadgets(file_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False)¶
Class for reading rec files from spikegadgets.
Based on
neo.rawio.SpikeGadgetsRawIO
- Parameters
- file_path: str
The file path to load the recordings from.
- stream_id: str or None, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str or None, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_spikeglx(folder_path, load_sync_channel=False, stream_id=None, stream_name=None, all_annotations=False)¶
Class for reading data saved by SpikeGLX software. See https://billkarsh.github.io/SpikeGLX/
Based on
neo.rawio.SpikeGLXRawIO
Contrary to older verions, this reader is folder-based. If the folder contains several streams (e.g., “imec0.ap”, “nidq” ,”imec0.lf”), then the stream has to be specified with “stream_id” or “stream_name”.
- Parameters
- folder_path: str
The folder path to load the recordings from.
- load_sync_channel: bool default: False
Whether or not to load the last channel in the stream, which is typically used for synchronization. If True, then the probe is not loaded.
- stream_id: str or None, default: None
If there are several streams, specify the stream id you want to load. For example, “imec0.ap”, “nidq”, or “imec0.lf”.
- stream_name: str or None, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_tdt(folder_path, stream_id=None, stream_name=None, block_index=None, all_annotations=False)¶
Class for reading TDT folder.
Based on
neo.rawio.TdTRawIO
- Parameters
- folder_path: str
The folder path to the tdt folder.
- stream_id: str or None, default: None
If there are several streams, specify the stream id you want to load.
- stream_name: str or None, default: None
If there are several streams, specify the stream name you want to load.
- all_annotations: bool, default: False
Load exhaustively all annotations from neo.
- spikeinterface.extractors.read_zarr(root_path: Union[Path, str], storage_options=None)¶
RecordingExtractor for a zarr format
- Parameters
- root_path: str or Path
Path to the zarr root file
- storage_options: dict or None
Storage options for zarr store. E.g., if “s3://” or “gcs://” they can provide authentication methods, etc.
- Returns
- recording: ZarrRecordingExtractor
The recording Extractor
Non-NEO-based¶
- spikeinterface.extractors.read_alf_sorting(folder_path, sampling_frequency=30000)¶
Load ALF format data as a sorting extractor.
- Parameters
- folder_pathstr or Path
Path to the ALF folder.
- sampling_frequencyint, default: 30000
The sampling frequency.
- Returns
- extractorALFSortingExtractor
The loaded data.
- spikeinterface.extractors.read_bids(folder_path)¶
Load a BIDS folder of data into extractor objects.
The following files are considered:
_channels.tsv
_contacts.tsv
_ephys.nwb
_probes.tsv
- Parameters
- folder_pathstr or Path
Path to the BIDS folder.
- Returns
- extractorslist of extractors
The loaded data, with attached Probes.
- spikeinterface.extractors.read_cbin_ibl(folder_path, load_sync_channel=False, stream_name='ap')¶
Load IBL data as an extractor object.
IBL have a custom format - compressed binary with spikeglx meta.
The format is like spikeglx (have a meta file) but contains:
“cbin” file (instead of “bin”)
“ch” file used by mtscomp for compression info
- Parameters
- folder_path: str or Path
Path to ibl folder.
- load_sync_channel: bool, default: False
Load or not the last channel (sync). If not then the probe is loaded.
- stream_name: str, default: “ap”.
Whether to load AP or LFP band, one of “ap” or “lp”.
- Returns
- recordingCompressedBinaryIblExtractor
The loaded data.
- spikeinterface.extractors.read_combinato(folder_path, sampling_frequency=None, user='simple', det_sign='both', keep_good_only=True)¶
Load Combinato format data as a sorting extractor.
- Parameters
- folder_pathstr or Path
Path to the Combinato folder.
- sampling_frequencyint, default: 30000
The sampling frequency.
- userstr, default: “simple”
The username that ran the sorting
- det_sign“both”, “pos”, “neg”, default: “both”
Which sign was used for detection.
- keep_good_onlybool, default: True
Whether to only keep good units.
- Returns
- extractorCombinatoSortingExtractor
The loaded data.
- spikeinterface.extractors.read_ibl_streaming_recording(session: str, stream_name: str, load_sync_channel: bool = False, cache_folder: Optional[Union[Path, str]] = None, remove_cached: bool = True)¶
Stream IBL data as an extractor object.
- Parameters
- sessionstr
The session ID to extract recordings for. In ONE, this is sometimes referred to as the “eid”. When doing a session lookup such as
>>> from one.api import ONE >>> one = ONE(base_url="https://openalyx.internationalbrainlab.org", password="international", silent=True) >>> sessions = one.alyx.rest("sessions", "list", tag="2022_Q2_IBL_et_al_RepeatedSite")
each returned value in sessions refers to it as the “id”.
- stream_namestr
The name of the stream to load for the session. These can be retrieved from calling StreamingIblExtractor.get_stream_names(session=”<your session ID>”).
- load_sync_channelsbool, default: false
Load or not the last channel (sync). If not then the probe is loaded.
- cache_folderstr or None, default: None
The location to temporarily store chunks of data during streaming. The default uses the folder designated by ONE.alyx._par.CACHE_DIR / “cache”, which is typically the designated “Downloads” folder on your operating system. As long as remove_cached is set to True, the only files that will persist in this folder are the metadata header files and the chunk of data being actively streamed and used in RAM.
- remove_cachedbool, default: True
Whether or not to remove streamed data from the cache immediately after it is read. If you expect to reuse fetched data many times, and have the disk space available, it is recommended to set this to False.
- Returns
- recordingIblStreamingRecordingExtractor
The recording extractor which allows access to the traces.
- spikeinterface.extractors.read_hdsort(file_path, keep_good_only=True)¶
Load HDSort format data as a sorting extractor.
- Parameters
- file_pathstr or Path
Path to HDSort mat file.
- keep_good_onlybool, default: True
Whether to only keep good units.
- Returns
- extractorHDSortSortingExtractor
The loaded data.
- spikeinterface.extractors.read_herdingspikes(file_path, load_unit_info=True)¶
Load HerdingSpikes format data as a sorting extractor.
- Parameters
- folder_pathstr or Path
Path to the ALF folder.
- load_unit_infobool, default: True
Whether to load the unit info from the file.
- Returns
- extractorHerdingSpikesSortingExtractor
The loaded data.
- spikeinterface.extractors.read_kilosort(folder_path: Path | str, keep_good_only: bool = False, remove_empty_units: bool = True)¶
Load Kilosort format data as a sorting extractor.
- Parameters
- folder_path: str or Path
Path to the output Phy folder (containing the params.py).
- keep_good_onlybool, default: True
Whether to only keep good units. If True, only Kilosort-labeled ‘good’ units are returned.
- remove_empty_unitsbool, default: True
If True, empty units are removed from the sorting extractor.
- Returns
- extractorKiloSortSortingExtractor
The loaded Sorting object.
- spikeinterface.extractors.read_klusta(file_or_folder_path, exclude_cluster_groups=None)¶
Load Klusta format data as a sorting extractor.
- Parameters
- file_or_folder_pathstr or Path
Path to the ALF folder.
- exclude_cluster_groups: list or str, default: None
Cluster groups to exclude (e.g. “noise” or [“noise”, “mua”]).
- Returns
- extractorKlustaSortingExtractor
The loaded data.
- spikeinterface.extractors.read_mcsh5(file_path, stream_id=0)¶
Load a MCS H5 file as a recording extractor.
- Parameters
- file_pathstr or Path
The path to the MCS h5 file.
- stream_idint, default: 0
The stream ID to load.
- Returns
- recordingMCSH5RecordingExtractor
The loaded data.
- spikeinterface.extractors.read_mda_recording(folder_path, raw_fname='raw.mda', params_fname='params.json', geom_fname='geom.csv')¶
Load MDA format data as a recording extractor.
- Parameters
- folder_pathstr or Path
Path to the MDA folder.
- raw_fname: str, default: “raw.mda”
File name of raw file
- params_fname: str, default: “params.json”
File name of params file
- geom_fname: str, default: “geom.csv”
File name of geom file
- Returns
- extractorMdaRecordingExtractor
The loaded data.
- spikeinterface.extractors.read_mda_sorting(file_path, sampling_frequency)¶
Load MDA format data as a sorting extractor.
- Parameters
- file_pathstr or Path
Path to the MDA file.
- sampling_frequencyint
The sampling frequency.
- Returns
- extractorMdaRecordingExtractor
The loaded data.
- spikeinterface.extractors.read_nwb(file_path, load_recording=True, load_sorting=False, electrical_series_name=None)¶
Reads NWB file into SpikeInterface extractors.
- Parameters
- file_path: str or Path
Path to NWB file.
- load_recordingbool, default: True
If True, the recording object is loaded.
- load_sortingbool, default: False
If True, the recording object is loaded.
- electrical_series_name: str or None, default: None
The name of the ElectricalSeries (if multiple ElectricalSeries are present)
- Returns
- extractors: extractor or tuple
Single RecordingExtractor/SortingExtractor or tuple with both (depending on “load_recording”/”load_sorting”) arguments.
- spikeinterface.extractors.read_phy(folder_path: Path | str, exclude_cluster_groups: Optional[list[str] | str] = None, load_all_cluster_properties: bool = True)¶
Load Phy format data as a sorting extractor.
- Parameters
- folder_path: str or Path
Path to the output Phy folder (containing the params.py).
- exclude_cluster_groups: list or str, default: None
Cluster groups to exclude (e.g. “noise” or [“noise”, “mua”]).
- load_all_cluster_propertiesbool, default: True
If True, all cluster properties are loaded from the tsv/csv files.
- Returns
- extractorPhySortingExtractor
The loaded Sorting object.
- spikeinterface.extractors.read_shybrid_recording(file_path)¶
Load SHYBRID format data as a recording extractor.
- Parameters
- file_pathstr or Path
Path to the SHYBRID file.
- Returns
- extractorSHYBRIDRecordingExtractor
Loaded data.
- spikeinterface.extractors.read_shybrid_sorting(file_path, sampling_frequency, delimiter=',')¶
Load SHYBRID format data as a sorting extractor.
- Parameters
- file_pathstr or Path
Path to the SHYBRID file.
- sampling_frequencyint
The sampling frequency.
- delimiterstr
The delimiter to use for loading the file.
- Returns
- extractorSHYBRIDSortingExtractor
Loaded data.
- spikeinterface.extractors.read_spykingcircus(folder_path)¶
Load SpykingCircus format data as a recording extractor.
- Parameters
- folder_pathstr or Path
Path to the SpykingCircus folder.
- Returns
- extractorSpykingCircusSortingExtractor
Loaded data.
- spikeinterface.extractors.toy_example(duration=10, num_channels=4, num_units=10, sampling_frequency=30000.0, num_segments=2, average_peak_amplitude=-100, upsample_factor=None, contact_spacing_um=40.0, num_columns=1, spike_times=None, spike_labels=None, firing_rate=3.0, seed=None)¶
Returns a generated dataset with “toy” units and spikes on top on white noise. This is useful to test api, algos, postprocessing and visualization without any downloading.
This a rewrite (with the lazy approach) of the old spikeinterface.extractor.toy_example() which itself was also a rewrite from the very old spikeextractor.toy_example() (from Jeremy Magland). In this new version, the recording is totally lazy and so it does not use disk space or memory. It internally uses NoiseGeneratorRecording + generate_templates + InjectTemplatesRecording.
For better control, you should use the generate_ground_truth_recording(), but provides better control over the parameters.
- Parameters
- duration: float or list[float], default: 10
Duration in seconds. If a list is provided, it will be the duration of each segment.
- num_channels: int, default: 4
Number of channels
- num_units: int, default: 10
Number of units
- sampling_frequency: float, default: 30000
Sampling frequency
- num_segments: int, default: 2
Number of segments.
- spike_times: np.array or list[nparray] or None, default: None
Spike time in the recording
- spike_labels: np.array or list[nparray] or None, default: None
Cluster label for each spike time (needs to specified both together).
- # score_detection: int (between 0 and 1)
- # Generate the sorting based on a subset of spikes compare with the trace generation
- firing_rate: float, default: 3.0
The firing rate for the units (in Hz)
- seed: int or None, default: None
Seed for random initialization.
- Returns
- recording: RecordingExtractor
The output recording extractor.
- sorting: SortingExtractor
The output sorting extractor.
- spikeinterface.extractors.read_tridesclous(folder_path, chan_grp=None)¶
Load Tridesclous format data as a sorting extractor.
- Parameters
- folder_pathstr or Path
Path to the Tridesclous folder.
- chan_grplist or None, default: None
The channel group(s) to load.
- Returns
- extractorTridesclousSortingExtractor
Loaded data.
- spikeinterface.extractors.read_waveclus(file_path, keep_good_only=True)¶
Load WaveClus format data as a sorting extractor.
- Parameters
- file_pathstr or Path
Path to the WaveClus file.
- keep_good_onlybool, default: True
Whether to only keep good units.
- Returns
- extractorWaveClusSortingExtractor
Loaded data.
- spikeinterface.extractors.read_yass(folder_path)¶
Load YASS format data as a sorting extractor.
- Parameters
- folder_pathstr or Path
Path to the ALF folder.
- Returns
- extractorYassSortingExtractor
Loaded data.
spikeinterface.preprocessing¶
- spikeinterface.preprocessing.astype(recording, dtype=None)¶
The spikeinterface analog of numpy.astype
Converts a recording to another dtype on the fly.
For recording with an unsigned dtype, please use the unsigned_to_signed preprocessing function.
- spikeinterface.preprocessing.average_across_direction(parent_recording: BaseRecording, direction: str = 'y', dtype='float32')¶
Abstract class representing several a multichannel timeseries (or block of raw ephys traces). Internally handle list of RecordingSegment
- spikeinterface.preprocessing.bandpass_filter(recording, freq_min=300.0, freq_max=6000.0, margin_ms=5.0, dtype=None, **filter_kwargs)¶
Bandpass filter of a recording
- Parameters
- recording: Recording
The recording extractor to be re-referenced
- freq_min: float
The highpass cutoff frequency in Hz
- freq_max: float
The lowpass cutoff frequency in Hz
- margin_ms: float
Margin in ms on border to avoid border effect
- dtype: dtype or None
The dtype of the returned traces. If None, the dtype of the parent recording is used
- {}
- Returns
- ——-
- filter_recording: BandpassFilterRecording
The bandpass-filtered recording extractor object
- spikeinterface.preprocessing.blank_staturation(recording, abs_threshold=None, quantile_threshold=None, direction='upper', fill_value=None, num_chunks_per_segment=50, chunk_size=500, seed=0)¶
Find and remove parts of the signal with extereme values. Some arrays may produce these when amplifiers enter saturation, typically for short periods of time. To remove these artefacts, values below or above a threshold are set to the median signal value. The threshold is either be estimated automatically, using the lower and upper 0.1 signal percentile with the largest deviation from the median, or specificed. Use this function with caution, as it may clip uncontaminated signals. A warning is printed if the data range suggests no artefacts.
- Parameters
- recording: RecordingExtractor
The recording extractor to be transformed Minimum value. If None, clipping is not performed on lower interval edge.
- abs_threshold: float or None, default: None
The absolute value for considering that the signal is saturating
- quantile_threshold: float or None, default: None
Tha value in [0, 1] used if abs_threshold is None to automatically set the abs_threshold given the data. Must be provided if abs_threshold is None
- direction: “upper” | “lower” | “both”, default: “upper”
Only values higher than the detection threshold are set to fill_value (“higher”), or only values lower than the detection threshold (“lower”), or both (“both”)
- fill_value: float or None, default: None
The value to write instead of the saturating signal. If None, then the value is automatically computed as the median signal value
- num_chunks_per_segment: int, default: 50
The number of chunks per segments to consider to estimate the threshold/fill_values
- chunk_size: int, default: 500
The chunk size to estimate the threshold/fill_values
- seed: int, default: 0
The seed to select the random chunks
- Returns
- rescaled_traces: BlankSaturationRecording
The filtered traces recording extractor object
- spikeinterface.preprocessing.center(recording, mode='median', dtype='float32', **random_chunk_kwargs)¶
Centers traces from the given recording extractor by removing the median/mean of each channel.
- Parameters
- recording: RecordingExtractor
The recording extractor to be centered
- mode: “median” | “mean”, default: “median”
The method used to center the traces
- dtype: str or np.dtype, default: “float32”
The dtype of the output traces
- **random_chunk_kwargs: Keyword arguments for `spikeinterface.core.get_random_data_chunk()` function
- Returns
- centered_traces: ScaleRecording
The centered traces recording extractor object
- spikeinterface.preprocessing.clip(recording, a_min=None, a_max=None)¶
Limit the values of the data between a_min and a_max. Values exceeding the range will be set to the minimum or maximum, respectively.
- Parameters
- recording: RecordingExtractor
The recording extractor to be transformed
- a_min: float or None, default: None
Minimum value. If None, clipping is not performed on lower interval edge.
- a_max: float or None, default: None
Maximum value. If None, clipping is not performed on upper interval edge.
- Returns
- rescaled_traces: ClipTracesRecording
The clipped traces recording extractor object
- spikeinterface.preprocessing.common_reference(recording, reference='global', operator='median', groups=None, ref_channel_ids=None, local_radius=(30, 55), verbose=False, dtype=None)¶
Re-references the recording extractor traces.
- Parameters
- recording: RecordingExtractor
The recording extractor to be re-referenced
- reference: “global” | “single” | “local”, default: “global”
If “global” then CMR/CAR is used either by groups or all channel way. If “single”, the selected channel(s) is remove from all channels. operator is no used in that case. If “local”, an average CMR/CAR is implemented with only k channels selected the nearest outside of a radius around each channel
- operator: “median” | “average”, default: “median”
- If “median”, common median reference (CMR) is implemented (the median of
the selected channels is removed for each timestamp).
- If “average”, common average reference (CAR) is implemented (the mean of the selected channels is removed
for each timestamp).
- groups: list
List of lists containing the channel ids for splitting the reference. The CMR, CAR, or referencing with respect to single channels are applied group-wise. However, this is not applied for the local CAR. It is useful when dealing with different channel groups, e.g. multiple tetrodes.
- ref_channel_ids: list or int
If no “groups” are specified, all channels are referenced to “ref_channel_ids”. If “groups” is provided, then a list of channels to be applied to each group is expected. If “single” reference, a list of one channel or an int is expected.
- local_radius: tuple(int, int)
Use in the local CAR implementation as the selecting annulus (exclude radius, include radius)
- verbose: bool
If True, output is verbose
- dtype: None or dtype
If None the parent dtype is kept.
- Returns
- referenced_recording: CommonReferenceRecording
The re-referenced recording extractor object
- spikeinterface.preprocessing.correct_lsb(recording, num_chunks_per_segment=20, chunk_size=10000, seed=None, verbose=False)¶
Estimates the LSB of the recording and divide traces by LSB to ensure LSB = 1. Medians are also subtracted to avoid rounding errors.
- Parameters
- recordingRecordingExtractor
The recording extractor to be LSB-corrected.
- num_chunks_per_segment: int, default: 20
Number of chunks per segment for random chunk
- chunk_sizeint, default: 10000
Size of a chunk in number for random chunk
- seedint or None, default: None
Random seed for random chunk
- verbosebool, default: False
If True, estimate LSB value is printed
- Returns
- correct_lsb_recording: ScaleRecording
The recording extractor with corrected LSB
- spikeinterface.preprocessing.correct_motion(recording, preset='nonrigid_accurate', folder=None, output_motion_info=False, detect_kwargs={}, select_kwargs={}, localize_peaks_kwargs={}, estimate_motion_kwargs={}, interpolate_motion_kwargs={}, **job_kwargs)¶
High-level function that estimates the motion and interpolates the recording.
- This function has some intermediate steps that can be controlled one by one with parameters:
detect peaks
(optional) sub-sample peaks to speed up the localization
localize peaks
estimate the motion
create and return a InterpolateMotionRecording recording object
Even if this function is convinient, we recommend to run all step separately for fine tuning.
Optionally, this function can create a folder with files and figures ready to check.
This function depends on several modular components of
spikeinterface.sortingcomponents
.If select_kwargs is None then all peak are used for localized.
The recording must be preprocessed (filter and denoised at least), and we recommend to not use whithening before motion estimation.
Parameters for each step are handled as separate dictionaries. For more information please check the documentation of the following functions:
select_peaks()
estimate_motion()
interpolate_motion()
- Possible presets:
nonrigid_accurate: method by Paninski lab (monopolar_triangulation + decentralized)
rigid_fast: Rigid and not super accurate but fast. Use center of mass.
kilosort_like: Mimic the drift correction of kilosrt (grid_convolution + iterative_template)
- Parameters
- recording: RecordingExtractor
The recording extractor to be transformed
- preset: str, default: “nonrigid_accurate”
The preset name
- folder: Path str or None, default: None
If not None then intermediate motion info are saved into a folder
- output_motion_info: bool, default: False
If True, then the function returns a motion_info dictionary that contains variables to check intermediate steps (motion_histogram, non_rigid_windows, pairwise_displacement) This dictionary is the same when reloaded from the folder
- detect_kwargs: dict
Optional parameters to overwrite the ones in the preset for “detect” step.
- select_kwargs: dict
If not None, optional parameters to overwrite the ones in the preset for “select” step. If None, the “select” step is skipped.
- localize_peaks_kwargs: dict
Optional parameters to overwrite the ones in the preset for “localize” step.
- estimate_motion_kwargs: dict
Optional parameters to overwrite the ones in the preset for “estimate_motion” step.
- interpolate_motion_kwargs: dict
Optional parameters to overwrite the ones in the preset for “detect” step.
- **job_kwargs: keyword arguments for parallel processing:
- chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
Number of samples per chunk
- chunk_memory: str
Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
- n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
- progress_bar: bool
If True, a progress bar is printed
- mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems
- Returns
- recording_corrected: Recording
The motion corrected recording
- motion_info: dict
Optional output if output_motion_info=True
- spikeinterface.preprocessing.depth_order(parent_recording, channel_ids=None, dimensions=('x', 'y'), flip=False)¶
Re-orders the recording (channel IDs, channel locations, and traces)
Sorts channels lexicographically according to the dimensions in dimensions. See the documentation for order_channels_by_depth.
- Parameters
- recordingBaseRecording
The recording to re-order.
- channel_idslist/array or None
If given, a subset of channels to order locations for
- dimensionsstr or tuple, list, default: (“x”, “y”)
If str, it needs to be “x”, “y”, “z”. If tuple or list, it sorts the locations in two dimensions using lexsort. This approach is recommended since there is less ambiguity
- flip: bool, default: False
If flip is False then the order is bottom first (starting from tip of the probe). If flip is True then the order is upper first.
- spikeinterface.preprocessing.detect_bad_channels(recording: BaseRecording, method: str = 'coherence+psd', std_mad_threshold: float = 5, psd_hf_threshold: float = 0.02, dead_channel_threshold: float = -0.5, noisy_channel_threshold: float = 1.0, outside_channel_threshold: float = -0.75, outside_channels_location: Literal['top', 'bottom', 'both'] = 'top', n_neighbors: int = 11, nyquist_threshold: float = 0.8, direction: Literal['x', 'y', 'z'] = 'y', chunk_duration_s: float = 0.3, num_random_chunks: int = 100, welch_window_ms: float = 10.0, highpass_filter_cutoff: float = 300, neighborhood_r2_threshold: float = 0.9, neighborhood_r2_radius_um: float = 30.0, seed: Optional[int] = None)¶
Perform bad channel detection. The recording is assumed to be filtered. If not, a highpass filter is applied on the fly.
Different methods are implemented:
- stdthrehshold on channel standard deviations
If the standard deviation of a channel is greater than std_mad_threshold times the median of all channels standard deviations, the channel is flagged as noisy
mad : same as std, but using median absolute deviations instead
- coeherence+psdmethod developed by the International Brain Laboratory that detects bad channels of three types:
Dead channels are those with low similarity to the surrounding channels (n=`n_neighbors` median)
Noise channels are those with power at >80% Nyquist above the psd_hf_threshold (default 0.02 uV^2 / Hz) and a high coherence with “far away” channels”
Out of brain channels are contigious regions of channels dissimilar to the median of all channels at the top end of the probe (i.e. large channel number)
- neighborhood_r2
A method tuned for LFP use-cases, where channels should be highly correlated with their spatial neighbors. This method estimates the correlation of each channel with the median of its spatial neighbors, and considers channels bad when this correlation is too small.
- Parameters
- recordingBaseRecording
The recording for which bad channels are detected
- method“coeherence+psd” | “std” | “mad” | “neighborhood_r2”, default: “coeherence+psd”
The method to be used for bad channel detection
- std_mad_thresholdfloat, default: 5
The standard deviation/mad multiplier threshold
- psd_hf_threshold (coeherence+psd)float, default: 0.02
An absolute threshold (uV^2/Hz) used as a cutoff for noise channels. Channels with average power at >80% Nyquist larger than this threshold will be labeled as noise
- dead_channel_threshold (coeherence+psd)float, default: -0.5
Threshold for channel coherence below which channels are labeled as dead
- noisy_channel_threshold (coeherence+psd)float, default: 1
Threshold for channel coherence above which channels are labeled as noisy (together with psd condition)
- outside_channel_threshold (coeherence+psd)float, default: -0.75
Threshold for channel coherence above which channels at the edge of the recording are marked as outside of the brain
- outside_channels_location (coeherence+psd)“top” | “bottom” | “both”, default: “top”
Location of the outside channels. If “top”, only the channels at the top of the probe can be marked as outside channels. If “bottom”, only the channels at the bottom of the probe can be marked as outside channels. If “both”, both the channels at the top and bottom of the probe can be marked as outside channels
- n_neighbors (coeherence+psd)int, default: 11
Number of channel neighbors to compute median filter (needs to be odd)
- nyquist_threshold (coeherence+psd)float, default: 0.8
Frequency with respect to Nyquist (Fn=1) above which the mean of the PSD is calculated and compared with psd_hf_threshold
- direction (coeherence+psd): “x” | “y” | “z”, default: “y”
The depth dimension
- highpass_filter_cutofffloat, default: 300
If the recording is not filtered, the cutoff frequency of the highpass filter
- chunk_duration_sfloat, default: 0.5
Duration of each chunk
- num_random_chunksint, default: 100
Number of random chunks Having many chunks is important for reproducibility.
- welch_window_msfloat, default: 10
Window size for the scipy.signal.welch that will be converted to nperseg
- neighborhood_r2_thresholdfloat, default: 0.95
R^2 threshold for the neighborhood_r2 method.
- neighborhood_r2_radius_umfloat, default: 30
Spatial radius below which two channels are considered neighbors in the neighborhood_r2 method.
- seedint or None, default: None
The random seed to extract chunks
- Returns
- bad_channel_idsnp.array
The identified bad channel ids
- channel_labelsnp.array of str
- Channels labels depending on the method:
(coeherence+psd) good/dead/noise/out
(std, mad) good/noise
Notes
For details refer to: International Brain Laboratory et al. (2022). Spike sorting pipeline for the International Brain Laboratory. https://www.internationalbrainlab.com/repro-ephys
Examples
>>> import spikeinterface.preprocessing as spre >>> bad_channel_ids, channel_labels = spre.detect_bad_channels(recording, method="coherence+psd") >>> # remove bad channels >>> recording_clean = recording.remove_channels(bad_channel_ids)
- spikeinterface.preprocessing.directional_derivative(recording: BaseRecording, direction: str = 'y', order: int = 1, edge_order: int = 1, dtype='float32')¶
Abstract class representing several a multichannel timeseries (or block of raw ephys traces). Internally handle list of RecordingSegment
- spikeinterface.preprocessing.filter(recording, band=[300.0, 6000.0], btype='bandpass', filter_order=5, ftype='butter', filter_mode='sos', margin_ms=5.0, add_reflect_padding=False, coeff=None, dtype=None)¶
Generic filter class based on:
scipy.signal.iirfilter
scipy.signal.filtfilt or scipy.signal.sosfilt
BandpassFilterRecording is built on top of it.
- Parameters
- recording: Recording
The recording extractor to be re-referenced
- band: float or list, default: [300.0, 6000.0]
If float, cutoff frequency in Hz for “highpass” filter type If list. band (low, high) in Hz for “bandpass” filter type
- btype: “bandpass” | “highpass”, default: “bandpass”
Type of the filter
- margin_ms: float, default: 5.0
Margin in ms on border to avoid border effect
- filter_mode: “sos” | “ba”, default: “sos”
Filter form of the filter coefficients: - second-order sections (“sos”) - numerator/denominator: (“ba”)
- coef: array or None, default: None
Filter coefficients in the filter_mode form.
- dtype: dtype or None, default: None
The dtype of the returned traces. If None, the dtype of the parent recording is used
- {}
- Returns
- filter_recording: FilterRecording
The filtered recording extractor object
- spikeinterface.preprocessing.gaussian_bandpass_filter(recording: BaseRecording, freq_min: float = 300.0, freq_max: float = 5000.0)¶
Class for performing a bandpass gaussian filtering/smoothing on a recording. This is done by a convolution with a Gaussian kernel, which acts as a lowpass-filter. The highpass-filter can be computed by subtracting the result.
Here, the bandpass is computed in the Fourier domain to accelerate the computation.
- Parameters
- recording: BaseRecording
The recording extractor to be filtered.
- freq_min: float
The lower frequency cutoff for the bandpass filter.
- freq_max: float
The higher frequency cutoff for the bandpass filter.
- Returns
- gaussian_bandpass_filtered_recording: GaussianBandpassFilterRecording
The filtered recording extractor object.
- spikeinterface.preprocessing.highpass_filter(recording, freq_min=300.0, margin_ms=5.0, dtype=None, **filter_kwargs)¶
Highpass filter of a recording
- Parameters
- recording: Recording
The recording extractor to be re-referenced
- freq_min: float
The highpass cutoff frequency in Hz
- margin_ms: float
Margin in ms on border to avoid border effect
- dtype: dtype or None
The dtype of the returned traces. If None, the dtype of the parent recording is used
- {}
- Returns
- ——-
- filter_recording: HighpassFilterRecording
The highpass-filtered recording extractor object
- spikeinterface.preprocessing.highpass_spatial_filter(recording, n_channel_pad=60, n_channel_taper=0, direction='y', apply_agc=True, agc_window_length_s=0.1, highpass_butter_order=3, highpass_butter_wn=0.01)¶
Perform destriping with high-pass spatial filtering. Uses the kfilt() function of the International Brain Laboratory.
Median average filtering, by removing the median of signal across channels, assumes noise is constant across all channels. However, noise have exhibit low-frequency changes across nearby channels.
Alternative to median filtering across channels, in which the cut-band is extended from 0 to the 0.01 Nyquist corner frequency using butterworth filter. This allows removal of contaminating stripes that are not constant across channels.
Performs filtering on the 0 axis (across channels), with optional padding (mirrored) and tapering (cosine taper) prior to filtering. Applies a butterworth filter on the 0-axis with tapering / padding.
- Parameters
- recordingBaseRecording
The parent recording
- n_channel_padint, default: 60
Number of channels to pad prior to filtering. Channels are padded with mirroring. If None, no padding is applied
- n_channel_taperint, default: 0
Number of channels to perform cosine tapering on prior to filtering. If None and n_channel_pad is set, n_channel_taper will be set to the number of padded channels. Otherwise, the passed value will be used
- direction“x” | “y” | “z”, default: “y”
The direction in which the spatial filter is applied
- apply_agcbool, default: True
It True, Automatic Gain Control is applied
- agc_window_length_sfloat, default: 0.1
Window in seconds to compute Hanning window for AGC
- highpass_butter_orderint, default: 3
Order of spatial butterworth filter
- highpass_butter_wnfloat, default: 0.01
Critical frequency (with respect to Nyquist) of spatial butterworth filter
- Returns
- highpass_recordingHighpassSpatialFilterRecording
The recording with highpass spatial filtered traces
References
Details of the high-pass spatial filter function (written by Olivier Winter) used in the IBL pipeline can be found at: International Brain Laboratory et al. (2022). Spike sorting pipeline for the International Brain Laboratory. https://www.internationalbrainlab.com/repro-ephys
- spikeinterface.preprocessing.interpolate_bad_channels(recording, bad_channel_ids, sigma_um=None, p=1.3, weights=None)¶
Interpolate the channel labeled as bad channels using linear interpolation. This is based on the distance (Gaussian kernel) from the bad channel, as determined from x,y channel coordinates.
Details of the interpolation function (written by Olivier Winter) used in the IBL pipeline can be found at:
International Brain Laboratory et al. (2022). Spike sorting pipeline for the International Brain Laboratory. https://www.internationalbrainlab.com/repro-ephys
- Parameters
- recording: BaseRecording
The parent recording
- bad_channel_idslist or 1d np.array
Channel ids of the bad channels to interpolate.
- sigma_umfloat or None, default: None
Distance between sequential channels in um. If None, will use the most common distance between y-axis channels
- pfloat, default: 1.3
Exponent of the Gaussian kernel. Determines rate of decay for distance weightings
- weightsnp.array or None, default: None
The weights to give to bad_channel_ids at interpolation. If None, weights are automatically computed
- Returns
- interpolated_recording: InterpolateBadChannelsRecording
The recording object with interpolated bad channels
- spikeinterface.preprocessing.normalize_by_quantile(recording, scale=1.0, median=0.0, q1=0.01, q2=0.99, mode='by_channel', dtype='float32', **random_chunk_kwargs)¶
Rescale the traces from the given recording extractor with a scalar and offset. First, the median and quantiles of the distribution are estimated. Then the distribution is rescaled and offset so that the scale is given by the distance between the quantiles (1st and 99th by default) is set to scale, and the median is set to the given median.
- Parameters
- recording: RecordingExtractor
The recording extractor to be transformed
- scale: float, default: 1.0
Scale for the output distribution
- median: float, default: 0.0
Median for the output distribution
- q1: float, default: 0.01
Lower quantile used for measuring the scale
- q1: float, default: 0.99
Upper quantile used for measuring the
- mode: “by_channel” | “pool_channel”, default: “by_channel”
If “by_channel” each channel is rescaled independently.
- dtype: str or np.dtype, default: “float32”
The dtype of the output traces
- **random_chunk_kwargs: Keyword arguments for `spikeinterface.core.get_random_data_chunk()` function
- Returns
- rescaled_traces: NormalizeByQuantileRecording
The rescaled traces recording extractor object
- spikeinterface.preprocessing.notch_filter(recording, freq=3000, q=30, margin_ms=5.0, dtype=None)¶
- Parameters
- recording: RecordingExtractor
The recording extractor to be notch-filtered
- freq: int or float
The target frequency in Hz of the notch filter
- q: int
The quality factor of the notch filter
- {}
- Returns
- ——-
- filter_recording: NotchFilterRecording
The notch-filtered recording extractor object
- spikeinterface.preprocessing.phase_shift(recording, margin_ms=40.0, inter_sample_shift=None, dtype=None)¶
This apply a phase shift to a recording to cancel the small sampling delay across for some recording system.
This is particularly relevant for neuropixel recording.
This code is inspired from from IBL lib. https://github.com/int-brain-lab/ibllib/blob/master/ibllib/dsp/fourier.py and also the one from spikeglx https://billkarsh.github.io/SpikeGLX/help/dmx_vs_gbl/dmx_vs_gbl/
- Parameters
- recording: Recording
The recording. It need to have “inter_sample_shift” in properties.
- margin_ms: float, default: 40.0
Margin in ms for computation. 40ms ensure a very small error when doing chunk processing
- inter_sample_shift: None or numpy array, default: None
If “inter_sample_shift” is not in recording properties, we can externally provide one.
- Returns
- filter_recording: PhaseShiftRecording
The phase shifted recording object
- spikeinterface.preprocessing.rectify(recording)¶
Abstract class representing several a multichannel timeseries (or block of raw ephys traces). Internally handle list of RecordingSegment
- spikeinterface.preprocessing.remove_artifacts(recording, list_triggers, ms_before=0.5, ms_after=3.0, mode='zeros', fit_sample_spacing=1.0, list_labels=None, artifacts=None, sparsity=None, scale_amplitude=False, time_jitter=0, waveforms_kwargs={'allow_unfiltered': True, 'mode': 'memory'})¶
Removes stimulation artifacts from recording extractor traces. By default, artifact periods are zeroed-out (mode = “zeros”). This is only recommended for traces that are centered around zero (e.g. through a prior highpass filter); if this is not the case, linear and cubic interpolation modes are also available, controlled by the “mode” input argument. Note that several artifacts can be removed at once (potentially with distinct duration each), if labels are specified
- Parameters
- recording: RecordingExtractor
The recording extractor to remove artifacts from
- list_triggers: list of lists/arrays
One list per segment of int with the stimulation trigger frames
- ms_before: float or None, default: 0.5
Time interval in ms to remove before the trigger events. If None, then also ms_after must be None and a single sample is removed
- ms_after: float or None, default: 3.0
Time interval in ms to remove after the trigger events. If None, then also ms_before must be None and a single sample is removed
- list_labels: list of lists/arrays or None
One list per segment of labels with the stimulation labels for the given artefacs. labels should be strings, for JSON serialization. Required for “median” and “average” modes.
- mode: “zeros”, “linear”, “cubic”, “average”, “median”, default: “zeros”
Determines what artifacts are replaced by. Can be one of the following:
“zeros”: Artifacts are replaced by zeros.
- “median”: The median over all artifacts is computed and subtracted for
each occurence of an artifact
- “average”: The mean over all artifacts is computed and subtracted for each
occurence of an artifact
- “linear”: Replacement are obtained through Linear interpolation between
the trace before and after the artifact. If the trace starts or ends with an artifact period, the gap is filled with the closest available value before or after the artifact.
- “cubic”: Cubic spline interpolation between the trace before and after
the artifact, referenced to evenly spaced fit points before and after the artifact. This is an option thatcan be helpful if there are significant LFP effects around the time of the artifact, but visual inspection of fit behaviour with your chosen settings is recommended. The spacing of fit points is controlled by “fit_sample_spacing”, with greater spacing between points leading to a fit that is less sensitive to high frequency fluctuations but at the cost of a less smooth continuation of the trace. If the trace starts or ends with an artifact, the gap is filled with the closest available value before or after the artifact.
- fit_sample_spacing: float, default: 1.0
Determines the spacing (in ms) of reference points for the cubic spline fit if mode = “cubic”. Note: The actual fit samples are the median of the 5 data points around the time of each sample point to avoid excessive influence from hyper-local fluctuations.
- artifacts: dict or None, default: None
If provided (when mode is “median” or “average”) then it must be a dict with keys that are the labels of the artifacts, and values the artifacts themselves, on all channels (and thus bypassing ms_before and ms_after)
- sparsity: dict or None, default: None
If provided (when mode is “median” or “average”) then it must be a dict with keys that are the labels of the artifacts, and values that are boolean mask of the channels where the artifacts should be considered (for subtraction/scaling)
- scale_amplitude: False, default: False
If true, then for mode “median” or “average” the amplitude of the template will be scaled in amplitude at each time occurence to minimize residuals
- time_jitter: float, default: 0
If non 0, then for mode “median” or “average”, a time jitter in ms can be allowed to minimize the residuals
- waveforms_kwargs: dict or None, default: None
The arguments passed to the WaveformExtractor object when extracting the artifacts, for mode “median” or “average”. By default, the global job kwargs are used, in addition to {“allow_unfiltered” : True, “mode”:”memory”}. To estimate sparse artifact
- Returns
- removed_recording: RemoveArtifactsRecording
The recording extractor after artifact removal
- spikeinterface.preprocessing.resample(recording, resample_rate, margin_ms=100.0, dtype=None, skip_checks=False)¶
Resample the recording extractor traces.
If the original sampling rate is multiple of the resample_rate, it will use the signal.decimate method from scipy. In other cases, it uses signal.resample. In the later case, the resulting signal can have issues on the edges, mainly on the rightmost.
- Parameters
- recordingRecording
The recording extractor to be re-referenced
- resample_rateint
The resampling frequency
- marginfloat, default: 100.0
Margin in ms for computations, will be used to decrease edge effects.
- dtypedtype or None, default: None
The dtype of the returned traces. If None, the dtype of the parent recording is used.
- skip_checksbool, default: False
If True, checks on sampling frequencies and cutoff filter frequencies are skipped
- Returns
- resample_recording: ResampleRecording
The resampled recording extractor object.
- spikeinterface.preprocessing.scale(recording, gain=1.0, offset=0.0, dtype='float32')¶
Scale traces from the given recording extractor with a scalar and offset. New traces = traces*scalar + offset.
- Parameters
- recording: RecordingExtractor
The recording extractor to be transformed
- gain: float or array
Scalar for the traces of the recording extractor or array with scalars for each channel
- offset: float or array
Offset for the traces of the recording extractor or array with offsets for each channel
- dtype: str or np.dtype, default: “float32”
The dtype of the output traces
- Returns
- transform_traces: ScaleRecording
The transformed traces recording extractor object
- spikeinterface.preprocessing.silence_periods(recording, list_periods, mode='zeros', **random_chunk_kwargs)¶
Silence user-defined periods from recording extractor traces. By default, periods are zeroed-out (mode = “zeros”). You can also fill the periods with noise. Note that both methods assume that traces that are centered around zero. If this is not the case, make sure you apply a filter or center function prior to silencing periods.
- Parameters
- recording: RecordingExtractor
The recording extractor to silance periods
- list_periods: list of lists/arrays
One list per segment of tuples (start_frame, end_frame) to silence
- mode: “zeros” | “noise, default: “zeros”
Determines what periods are replaced by. Can be one of the following:
“zeros”: Artifacts are replaced by zeros.
- “noise”: The periods are filled with a gaussion noise that has the
same variance that the one in the recordings, on a per channel basis
- **random_chunk_kwargs: Keyword arguments for `spikeinterface.core.get_random_data_chunk()` function
- Returns
- silence_recording: SilencedPeriodsRecording
The recording extractor after silencing some periods
- spikeinterface.preprocessing.unsigned_to_signed(recording)¶
Converts a recording with unsigned traces to a signed one.
- spikeinterface.preprocessing.whiten(recording, dtype=None, apply_mean=False, mode='global', radius_um=100.0, int_scale=None, eps=None, W=None, M=None, **random_chunk_kwargs)¶
Whitens the recording extractor traces.
- Parameters
- recording: RecordingExtractor
The recording extractor to be whitened.
- dtype: None or dtype, default: None
If None the the parent dtype is kept. For integer dtype a int_scale must be also given.
- mode: “global” | “local”, default: “global”
“global” use the entire covariance matrix to compute the W matrix “local” use local covariance (by radius) to compute the W matrix
- radius_um: None or float, default: None
Used for mode = “local” to get the neighborhood
- apply_mean: bool, default: False
Substract or not the mean matrix M before the dot product with W.
- int_scaleNone or float, default: None
Apply a scaling factor to fit the integer range. This is used when the dtype is an integer, so that the output is scaled. For example, a value of int_scale=200 will scale the traces value to a standard deviation of 200.
- epsfloat or None, default: None
Small epsilon to regularize SVD. If None, eps is defaulted to 1e-8. If the data is float type and scaled down to very small values, then the eps is automatically set to a small fraction (1e-3) of the median of the squared data.
- W2d np.array or None, default: None
Pre-computed whitening matrix
- M1d np.array or None, default: None
Pre-computed means. M can be None when previously computed with apply_mean=False
- **random_chunk_kwargsKeyword arguments for spikeinterface.core.get_random_data_chunk() function
- Returns
- whitened_recording: WhitenRecording
The whitened recording extractor
- spikeinterface.preprocessing.zero_channel_pad(parent_recording: BaseRecording, num_channels: int, channel_mapping: Optional[list] = None)¶
Abstract class representing several a multichannel timeseries (or block of raw ephys traces). Internally handle list of RecordingSegment
- spikeinterface.preprocessing.zscore(recording, mode='median+mad', gain=None, offset=None, int_scale=None, dtype='float32', **random_chunk_kwargs)¶
Centers traces from the given recording extractor by removing the median of each channel and dividing by the MAD.
- Parameters
- recording: RecordingExtractor
The recording extractor to be centered
- mode: “median+mad” | “mean+std”, default: “median+mad”
The mode to compute the zscore
- dtype: None or dtype
If None the the parent dtype is kept. For integer dtype a int_scale must be also given.
- gainNone or np.array
Pre-computed gain.
- offsetNone or np.array
Pre-computed offset
- int_scaleNone or float
Apply a scaling factor to fit the integer range. This is used when the dtype is an integer, so that the output is scaled. For example, a value of int_scale=200 will scale the zscore value to a standard deviation of 200.
- **random_chunk_kwargs: Keyword arguments for `spikeinterface.core.get_random_data_chunk()` function
- Returns
- centered_traces: ScaleRecording
The centered traces recording extractor object
spikeinterface.postprocessing¶
- spikeinterface.postprocessing.compute_noise_levels(waveform_extractor, load_if_exists=False, **params)¶
Computes the noise level associated to each recording channel.
This function will wraps the get_noise_levels(recording) to make the noise levels persistent on disk (folder or zarr) as a WaveformExtension. The noise levels do not depend on the unit list, only the recording, but it is a convenient way to retrieve the noise levels directly ine the WaveformExtractor.
Note that the noise levels can be scaled or not, depending on the return_scaled parameter of the WaveformExtractor.
- Parameters
- waveform_extractor: WaveformExtractor
A waveform extractor object
- load_if_exists: bool, default: False
If True, the noise levels are loaded if they already exist
- **params: dict with additional parameters
- Returns
- noise_levels: np.array
noise level vector.
- spikeinterface.postprocessing.compute_template_metrics(waveform_extractor, load_if_exists: bool = False, metric_names: Optional[list[str]] = None, peak_sign: Optional[str] = 'neg', upsampling_factor: int = 10, sparsity: Optional[ChannelSparsity] = None, include_multi_channel_metrics: bool = False, metrics_kwargs: Optional[dict] = None)¶
- Compute template metrics including:
peak_to_valley
peak_trough_ratio
halfwidth
repolarization_slope
recovery_slope
num_positive_peaks
num_negative_peaks
- Optionally, the following multi-channel metrics can be computed (when include_multi_channel_metrics=True):
velocity_above
velocity_below
exp_decay
spread
- Parameters
- waveform_extractorWaveformExtractor
The waveform extractor used to compute template metrics
- load_if_existsbool, default: False
Whether to load precomputed template metrics, if they already exist.
- metric_nameslist or None, default: None
List of metrics to compute (see si.postprocessing.get_template_metric_names())
- peak_sign{“neg”, “pos”}, default: “neg”
Whether to use the positive (“pos”) or negative (“neg”) peaks to estimate extremum channels.
- upsampling_factorint, default: 10
The upsampling factor to upsample the templates
- sparsity: ChannelSparsity or None, default: None
If None, template metrics are computed on the extremum channel only. If sparsity is given, template metrics are computed on all sparse channels of each unit. For more on generating a ChannelSparsity, see the ~spikeinterface.compute_sparsity() function.
- include_multi_channel_metrics: bool, default: False
Whether to compute multi-channel metrics
- metrics_kwargs: dict
- Additional arguments to pass to the metric functions. Including:
recovery_window_ms: the window in ms after the peak to compute the recovery_slope, default: 0.7
peak_relative_threshold: the relative threshold to detect positive and negative peaks, default: 0.2
peak_width_ms: the width in samples to detect peaks, default: 0.2
depth_direction: the direction to compute velocity above and below, default: “y” (see notes)
min_channels_for_velocity: the minimum number of channels above or below to compute velocity, default: 5
min_r2_velocity: the minimum r2 to accept the velocity fit, default: 0.7
exp_peak_function: the function to use to compute the peak amplitude for the exp decay, default: “ptp”
min_r2_exp_decay: the minimum r2 to accept the exp decay fit, default: 0.5
spread_threshold: the threshold to compute the spread, default: 0.2
spread_smooth_um: the smoothing in um to compute the spread, default: 20
- column_range: the range in um in the horizontal direction to consider channels for velocity, default: None
If None, all channels all channels are considered
If 0 or 1, only the “column” that includes the max channel is considered
If > 1, only channels within range (+/-) um from the max channel horizontal position are used
- Returns
- template_metricspd.DataFrame
Dataframe with the computed template metrics. If “sparsity” is None, the index is the unit_id. If “sparsity” is given, the index is a multi-index (unit_id, channel_id)
Notes
If any multi-channel metric is in the metric_names or include_multi_channel_metrics is True, sparsity must be None, so that one metric value will be computed per unit. For multi-channel metrics, 3D channel locations are not supported. By default, the depth direction is “y”.
- spikeinterface.postprocessing.compute_principal_components(waveform_extractor, load_if_exists=False, n_components=5, mode='by_channel_local', sparsity=None, whiten=True, dtype='float32', tmp_folder=None, **job_kwargs)¶
Compute PC scores from waveform extractor. The PCA projections are pre-computed only on the sampled waveforms available from the WaveformExtractor.
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor
- load_if_exists: bool
If True and pc scores are already in the waveform extractor folders, pc scores are loaded and not recomputed.
- n_components: int, default: 5
Number of components fo PCA
- mode: “by_channel_local” | “by_channel_global” | “concatenated”, default: “by_channel_local”
- The PCA mode:
“by_channel_local”: a local PCA is fitted for each channel (projection by channel)
“by_channel_global”: a global PCA is fitted for all channels (projection by channel)
“concatenated”: channels are concatenated and a global PCA is fitted
- sparsity: ChannelSparsity or None, default: None
The sparsity to apply to waveforms. If waveform_extractor is already sparse, the default sparsity will be used
- whiten: bool, default: True
If True, waveforms are pre-whitened
- dtype: dtype, default: “float32”
Dtype of the pc scores
- tmp_folder: str or Path or None, default: None
The temporary folder to use for parallel computation. If you run several compute_principal_components functions in parallel with mode “by_channel_local”, you need to specify a different tmp_folder for each call, to avoid overwriting to the same folder
- n_jobs: int, default: 1
Number of jobs used to fit the PCA model (if mode is “by_channel_local”)
- progress_bar: bool, default: False
If True, a progress bar is shown
- Returns
- pc: WaveformPrincipalComponent
The waveform principal component object
Examples
>>> we = si.extract_waveforms(recording, sorting, folder='waveforms') >>> pc = st.compute_principal_components(we, n_components=3, mode='by_channel_local') >>> # get pre-computed projections for unit_id=1 >>> projections = pc.get_projections(unit_id=1) >>> # get all pre-computed projections and labels >>> all_projections, all_labels = pc.get_all_projections() >>> # retrieve fitted pca model(s) >>> pca_model = pc.get_pca_model() >>> # compute projections on new waveforms >>> proj_new = pc.project_new(new_waveforms) >>> # run for all spikes in the SortingExtractor >>> pc.run_for_all_spikes(file_path="all_pca_projections.npy")
- spikeinterface.postprocessing.compute_spike_amplitudes(waveform_extractor, load_if_exists=False, peak_sign='neg', return_scaled=True, outputs='concatenated', **job_kwargs)¶
Computes the spike amplitudes from a WaveformExtractor.
The waveform extractor is used to determine the max channel per unit.
Then a “peak_shift” is estimated because for some sorters the spike index is not always at the peak.
Amplitudes are extracted in chunks (parallel or not)
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor object
- load_if_existsbool, default: False
Whether to load precomputed spike amplitudes, if they already exist.
- peak_sign: “neg” | “pos” | “both”, default: “neg
The sign to compute maximum channel
- return_scaled: bool
If True and recording has gain_to_uV/offset_to_uV properties, amplitudes are converted to uV.
- outputs: “concatenated” | “by_unit”, default: “concatenated”
How the output should be returned
- {}
- Returns
- amplitudes: np.array or list of dict
- The spike amplitudes.
If “concatenated” all amplitudes for all spikes and all units are concatenated
If “by_unit”, amplitudes are returned as a list (for segments) of dictionaries (for units)
- spikeinterface.postprocessing.compute_unit_locations(waveform_extractor, load_if_exists=False, method='monopolar_triangulation', outputs='numpy', **method_kwargs)¶
Localize units in 2D or 3D with several methods given the template.
- Parameters
- waveform_extractor: WaveformExtractor
A waveform extractor object
- load_if_existsbool, default: False
Whether to load precomputed unit locations, if they already exist
- method: “center_of_mass” | “monopolar_triangulation” | “grid_convolution”, default: “center_of_mass”
The method to use for localization
- outputs: “numpy” | “by_unit”, default: “numpy”
The output format
- method_kwargs:
Other kwargs depending on the method
- Returns
- unit_locations: np.array
unit location with shape (num_unit, 2) or (num_unit, 3) or (num_unit, 3) (with alpha)
- spikeinterface.postprocessing.compute_spike_locations(waveform_extractor, load_if_exists=False, ms_before=0.5, ms_after=0.5, spike_retriver_kwargs={'channel_from_template': True, 'peak_sign': 'neg', 'radius_um': 50}, method='center_of_mass', method_kwargs={}, outputs='concatenated', **job_kwargs)¶
Localize spikes in 2D or 3D with several methods given the template.
- Parameters
- waveform_extractorWaveformExtractor
A waveform extractor object
- load_if_existsbool, default: False
Whether to load precomputed spike locations, if they already exist
- ms_beforefloat, default: 0.5
The left window, before a peak, in milliseconds
- ms_afterfloat, default: 0.5
The right window, after a peak, in milliseconds
- spike_retriver_kwargs: dict
A dictionary to control the behavior for getting the maximum channel for each spike This dictionary contains:
- channel_from_template: bool, default: True
For each spike is the maximum channel computed from template or re estimated at every spikes channel_from_template = True is old behavior but less acurate channel_from_template = False is slower but more accurate
- radius_um: float, default: 50
In case channel_from_template=False, this is the radius to get the true peak
- peak_sign, default: “neg”
In case channel_from_template=False, this is the peak sign.
- method“center_of_mass” | “monopolar_triangulation” | “grid_convolution”, default: “center_of_mass”
The localization method to use
- method_kwargsdict, default: dict()
Other kwargs depending on the method.
- outputs“concatenated” | “by_unit”, default: “concatenated”
The output format
- {}
- Returns
- spike_locations: np.array or list of dict
- The spike locations.
If “concatenated” all locations for all spikes and all units are concatenated
If “by_unit”, locations are returned as a list (for segments) of dictionaries (for units)
- spikeinterface.postprocessing.compute_template_similarity(waveform_extractor, load_if_exists=False, method='cosine_similarity', waveform_extractor_other=None)¶
Compute similarity between templates with several methods.
- Parameters
- waveform_extractor: WaveformExtractor
A waveform extractor object
- load_if_existsbool, default: False
Whether to load precomputed similarity, if is already exists.
- method: str, default: “cosine_similarity”
The method to compute the similarity
- waveform_extractor_other: WaveformExtractor, default: None
A second waveform extractor object
- Returns
- similarity: np.array
The similarity matrix
- spikeinterface.postprocessing.compute_correlograms(waveform_or_sorting_extractor, load_if_exists=False, window_ms: float = 50.0, bin_ms: float = 1.0, method: str = 'auto')¶
Compute auto and cross correlograms.
- Parameters
- waveform_or_sorting_extractorWaveformExtractor or BaseSorting
If WaveformExtractor, the correlograms are saved as WaveformExtensions
- load_if_existsbool, default: False
Whether to load precomputed crosscorrelograms, if they already exist
- window_msfloat, default: 100.0
The window in ms
- bin_msfloat, default: 5
The bin size in ms
- method“auto” | “numpy” | “numba”, default: “auto”
If “auto” and numba is installed, numba is used, otherwise numpy is used
- Returns
- ccgsnp.array
Correlograms with shape (num_units, num_units, num_bins) The diagonal of ccgs is the auto correlogram. ccgs[A, B, :] is the symetrie of ccgs[B, A, :] ccgs[A, B, :] have to be read as the histogram of spiketimesA - spiketimesB
- binsnp.array
The bin edges in ms
- spikeinterface.postprocessing.compute_isi_histograms(waveform_or_sorting_extractor, load_if_exists=False, window_ms: float = 50.0, bin_ms: float = 1.0, method: str = 'auto')¶
Compute ISI histograms.
- Parameters
- waveform_or_sorting_extractorWaveformExtractor or BaseSorting
If WaveformExtractor, the ISI histograms are saved as WaveformExtensions
- load_if_existsbool, default: False
Whether to load precomputed crosscorrelograms, if they already exist
- window_msfloat, default: 50
The window in ms
- bin_msfloat, default: 1
The bin size in ms
- method“auto” | “numpy” | “numba”, default: “auto”
. If “auto” and numba is installed, numba is used, otherwise numpy is used
- Returns
- isi_histogramsnp.array
IDI_histograms with shape (num_units, num_bins)
- binsnp.array
The bin edges in ms
- spikeinterface.postprocessing.get_template_metric_names()¶
- spikeinterface.postprocessing.align_sorting(sorting, unit_peak_shifts)¶
Class to shift a unit (generally to align the template on the peak) given the shifts for each unit.
- Parameters
- sorting: BaseSorting
The sorting to align.
- unit_peak_shifts: dict
Dictionary mapping the unit_id to the unit’s shift (in number of samples). A positive shift means the spike train is shifted back in time, while a negative shift means the spike train is shifted forward.
- Returns
- aligned_sorting: AlignSortingExtractor
The aligned sorting.
spikeinterface.qualitymetrics¶
- spikeinterface.qualitymetrics.compute_quality_metrics(waveform_extractor, load_if_exists=False, metric_names=None, qm_params=None, peak_sign=None, seed=None, sparsity=None, skip_pc_metrics=False, verbose=False, **job_kwargs)¶
Compute quality metrics on waveform extractor.
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor to compute metrics on.
- load_if_existsbool, default: False
Whether to load precomputed quality metrics, if they already exist.
- metric_nameslist or None
List of quality metrics to compute.
- qm_paramsdict or None
Dictionary with parameters for quality metrics calculation. Default parameters can be obtained with: si.qualitymetrics.get_default_qm_params()
- sparsitydict or None, default: None
If given, the sparse channel_ids for each unit in PCA metrics computation. This is used also to identify neighbor units and speed up computations. If None all channels and all units are used for each unit.
- skip_pc_metricsbool
If True, PC metrics computation is skipped.
- n_jobsint
Number of jobs (used for PCA metrics)
- verbosebool
If True, output is verbose.
- progress_barbool
If True, progress bar is shown.
- Returns
- metrics: pandas.DataFrame
Data frame with the computed metrics
- spikeinterface.qualitymetrics.get_quality_metric_list()¶
Get a list of the available quality metrics.
- spikeinterface.qualitymetrics.get_quality_pca_metric_list()¶
Get a list of the available PCA-based quality metrics.
- spikeinterface.qualitymetrics.get_default_qm_params()¶
Return default dictionary of quality metrics parameters.
- Returns
- dict
Default qm parameters with metric name as key and parameter dictionary as values.
spikeinterface.sorters¶
- spikeinterface.sorters.available_sorters()¶
Lists available sorters.
- spikeinterface.sorters.installed_sorters()¶
Lists installed sorters.
- spikeinterface.sorters.get_default_sorter_params(sorter_name_or_class)¶
Returns default parameters for the specified sorter.
- Parameters
- sorter_name_or_class: str or SorterClass
The sorter to retrieve default parameters from.
- Returns
- default_params: dict
Dictionary with default params for the specified sorter.
- spikeinterface.sorters.get_sorter_params_description(sorter_name_or_class)¶
Returns a description of the parameters for the specified sorter.
- Parameters
- sorter_name_or_class: str or SorterClass
The sorter to retrieve parameters description from.
- Returns
- params_description: dict
Dictionary with parameter description
- spikeinterface.sorters.print_sorter_versions()¶
“Prints the versions of the installed sorters.
- spikeinterface.sorters.get_sorter_description(sorter_name_or_class)¶
Returns a brief description for the specified sorter.
- Parameters
- sorter_name_or_class: str or SorterClass
The sorter to retrieve description from.
- Returns
- params_description: dict
Dictionary with parameter description.
- spikeinterface.sorters.run_sorter(sorter_name: str, recording: BaseRecording, output_folder: Optional[str] = None, remove_existing_folder: bool = False, delete_output_folder: bool = False, verbose: bool = False, raise_error: bool = True, docker_image: Optional[Union[bool, str]] = False, singularity_image: Optional[Union[bool, str]] = False, delete_container_files: bool = True, with_output: bool = True, **sorter_params)¶
Generic function to run a sorter via function approach.
- Parameters
- sorter_name: str
The sorter name
- recording: RecordingExtractor
The recording extractor to be spike sorted
- output_folder: str or Path
Path to output folder
- remove_existing_folder: bool
If True and output_folder exists yet then delete.
- delete_output_folder: bool, default: False
If True, output folder is deleted
- verbose: bool, default: False
If True, output is verbose
- raise_error: bool, default: True
If True, an error is raised if spike sorting fails If False, the process continues and the error is logged in the log file.
- docker_image: bool or str, default: False
If True, pull the default docker container for the sorter and run the sorter in that container using docker. Use a str to specify a non-default container. If that container is not local it will be pulled from docker hub. If False, the sorter is run locally
- singularity_image: bool or str, default: False
If True, pull the default docker container for the sorter and run the sorter in that container using singularity. Use a str to specify a non-default container. If that container is not local it will be pulled from Docker Hub. If False, the sorter is run locally
- delete_container_files: bool, default: True
If True, the container temporary files are deleted after the sorting is done
- with_output: bool, default: True
If True, the output Sorting is returned as a Sorting
- **sorter_params: keyword args
Spike sorter specific arguments (they can be retrieved with get_default_sorter_params(sorter_name_or_class))
- Returns
- sortingextractor: SortingExtractor
The spike sorted data
Examples
>>> sorting = run_sorter("tridesclous", recording)
- spikeinterface.sorters.run_sorter_jobs(job_list, engine='loop', engine_kwargs={}, return_output=False)¶
Run several
run_sorter()
sequentially or in parallel given a list of jobs.For engine=”loop” this is equivalent to:
..code:
for job in job_list: run_sorter(**job)
- The following engines block the I/O:
“loop”
“joblib”
“multiprocessing”
“dask”
- The following engines are asynchronous:
“slurm”
Where blocking means that this function is blocking until the results are returned. This is in opposition to asynchronous, where the function returns None almost immediately (aka non-blocking), but the results must be retrieved by hand when jobs are finished. No mechanisim is provided here to be know when jobs are finish. In this asynchronous case, the
read_sorter_folder()
helps to retrieve individual results.- Parameters
- job_list: list of dict
A list a dict that are propagated to run_sorter(…)
- engine: str “loop”, “joblib”, “dask”, “slurm”
The engine to run the list. * “loop”: a simple loop. This engine is
- engine_kwargs: dict
- return_output: bool, dfault False
Return a sortings or None. This also overwrite kwargs in in run_sorter(with_sorting=True/False)
- Returns
- sortings: None or list of sorting
With engine=”loop” or “joblib” you can optional get directly the list of sorting result if return_output=True.
- spikeinterface.sorters.run_sorters(sorter_list, recording_dict_or_list, working_folder, sorter_params={}, mode_if_folder_exists='raise', engine='loop', engine_kwargs={}, verbose=False, with_output=True, docker_images={}, singularity_images={})¶
This function is deprecated and will be removed in version 0.100 Please use run_sorter_jobs() instead.
- Parameters
- sorter_list: list of str
List of sorter names.
- recording_dict_or_list: dict or list
If a dict of recording, each key should be the name of the recording. If a list, the names should be recording_0, recording_1, etc.
- working_folder: str
The working directory.
- sorter_params: dict of dict with sorter_name as key
This allow to overwrite default params for sorter.
- mode_if_folder_exists: “raise” | “overwrite” | “keep”, default: “raise”
- The mode when the subfolder of recording/sorter already exists.
“raise” : raise error if subfolder exists
“overwrite” : delete and force recompute
“keep” : do not compute again if f=subfolder exists and log is OK
- engine: “loop” | “joblib” | “dask”, default: “loop”
Which engine to use to run sorter.
- engine_kwargs: dict
- This contains kwargs specific to the launcher engine:
“loop” : no kwargs
“joblib” : {“n_jobs” : } number of processes
“dask” : {“client”:} the dask client for submitting task
- verbose: bool
Controls sorter verboseness.
- with_output: bool
Whether to return the output.
- docker_images: dict
A dictionary {sorter_name : docker_image} to specify if some sorters should use docker images.
- singularity_images: dict
A dictionary {sorter_name : singularity_image} to specify if some sorters should use singularity images
- Returns
- resultsdict
The output is nested dict[(rec_name, sorter_name)] of SortingExtractor.
- spikeinterface.sorters.run_sorter_by_property(sorter_name, recording, grouping_property, working_folder, mode_if_folder_exists=None, engine='loop', engine_kwargs={}, verbose=False, docker_image=None, singularity_image=None, **sorter_params)¶
Generic function to run a sorter on a recording after splitting by a “grouping_property” (e.g. “group”).
- Internally, the function works as follows:
the recording is split based on the provided “grouping_property” (using the “split_by” function)
the “run_sorters” function is run on the split recordings
sorting outputs are aggregated using the “aggregate_units” function
the “grouping_property” is added as a property to the SortingExtractor
- Parameters
- sorter_name: str
The sorter name
- recording: BaseRecording
The recording to be sorted
- grouping_property: object
Property to split by before sorting
- working_folder: str
The working directory.
- mode_if_folder_exists: bool or None, default: None
Must be None. This is deprecated. If not None then a warning is raise. Will be removed in next release.
- engine: “loop” | “joblib” | “dask”, default: “loop”
Which engine to use to run sorter.
- engine_kwargs: dict
- This contains kwargs specific to the launcher engine:
“loop” : no kwargs
“joblib” : {“n_jobs” : } number of processes
“dask” : {“client”:} the dask client for submitting task
- verbose: bool, default: False
Controls sorter verboseness
- docker_image: None or str, default: None
If str run the sorter inside a container (docker) using the docker package
- **sorter_params: keyword args
Spike sorter specific arguments (they can be retrieved with get_default_sorter_params(sorter_name_or_class))
- Returns
- sortingUnitsAggregationSorting
The aggregated SortingExtractor.
Examples
This example shows how to run spike sorting split by group using the “joblib” backend with 4 jobs for parallel processing.
>>> sorting = si.run_sorter_by_property("tridesclous", recording, grouping_property="group", working_folder="sort_by_group", engine="joblib", engine_kwargs={"n_jobs": 4})
- spikeinterface.sorters.read_sorter_folder(output_folder, register_recording=True, sorting_info=True, raise_error=True)¶
Load a sorting object from a spike sorting output folder. The ‘output_folder’ must contain a valid ‘spikeinterface_log.json’ file
- Parameters
- output_folder: Pth or str
The sorter folder
- register_recording: bool, default: True
Attach recording (when json or pickle) to the sorting
- sorting_info: bool, default: True
Attach sorting info to the sorting.
Low level¶
- class spikeinterface.sorters.BaseSorter(recording=None, output_folder=None, verbose=False, remove_existing_folder=False, delete_output_folder=False)¶
Base Sorter object.
spikeinterface.comparison¶
- spikeinterface.comparison.compare_two_sorters(sorting1, sorting2, sorting1_name=None, sorting2_name=None, delta_time=0.4, match_score=0.5, chance_score=0.1, n_jobs=-1, verbose=False)¶
Compares two spike sorter outputs.
Spike trains are matched based on their agreement scores
Individual spikes are labelled as true positives (TP), false negatives (FN), false positives 1 (FP from spike train 1), false positives 2 (FP from spike train 2), misclassifications (CL)
It also allows to get confusion matrix and agreement fraction, false positive fraction and false negative fraction.
- Parameters
- sorting1: SortingExtractor
The first sorting for the comparison
- sorting2: SortingExtractor
The second sorting for the comparison
- sorting1_name: str, default: None
The name of sorter 1
- sorting2_name:str, default: None
The name of sorter 2
- delta_time: float, default: 0.4
Number of ms to consider coincident spikes
- match_score: float, default: 0.5
Minimum agreement score to match units
- chance_score: float, default: 0.1
Minimum agreement score to for a possible match
- n_jobs: int, default: -1
Number of cores to use in parallel. Uses all available if -1
- verbose: bool, default: False
If True, output is verbose
- Returns
- sorting_comparison: SortingComparison
The SortingComparison object
- spikeinterface.comparison.compare_multiple_sorters(sorting_list, name_list=None, delta_time=0.4, match_score=0.5, chance_score=0.1, n_jobs=-1, spiketrain_mode='union', verbose=False, do_matching=True)¶
Compares multiple spike sorting outputs based on spike trains.
Pair-wise comparisons are made
An agreement graph is built based on the agreement score
It allows to return a consensus-based sorting extractor with the get_agreement_sorting() method.
- Parameters
- sorting_list: list
List of sorting extractor objects to be compared
- name_list: list, default: None
List of spike sorter names. If not given, sorters are named as “sorter0”, “sorter1”, “sorter2”, etc.
- delta_time: float, default: 0.4
Number of ms to consider coincident spikes
- match_score: float, default: 0.5
Minimum agreement score to match units
- chance_score: float, default: 0.1
Minimum agreement score to for a possible match
- n_jobs: int, default: -1
Number of cores to use in parallel. Uses all available if -1
- spiketrain_mode: “union” | “intersection”, default: “union”
- Mode to extract agreement spike trains:
“union”: spike trains are the union between the spike trains of the best matching two sorters
- “intersection”: spike trains are the intersection between the spike trains of the
best matching two sorters
- verbose: bool, default: False
if True, output is verbose
- Returns
- multi_sorting_comparison: MultiSortingComparison
MultiSortingComparison object with the multiple sorter comparison
- spikeinterface.comparison.compare_sorter_to_ground_truth(gt_sorting, tested_sorting, gt_name=None, tested_name=None, delta_time=0.4, sampling_frequency=None, match_score=0.5, well_detected_score=0.8, redundant_score=0.2, overmerged_score=0.2, chance_score=0.1, exhaustive_gt=False, n_jobs=-1, match_mode='hungarian', compute_labels=False, compute_misclassifications=False, verbose=False)¶
Compares a sorter to a ground truth.
- This class can:
compute a “match between gt_sorting and tested_sorting
compute optionally the score label (TP, FN, CL, FP) for each spike
count by unit of GT the total of each (TP, FN, CL, FP) into a Dataframe GroundTruthComparison.count
compute the confusion matrix .get_confusion_matrix()
compute some performance metric with several strategy based on the count score by unit
count well detected units
count false positive detected units
count redundant units
count overmerged units
summary all this
- Parameters
- gt_sorting: SortingExtractor
The first sorting for the comparison
- tested_sorting: SortingExtractor
The second sorting for the comparison
- gt_name: str, default: None
The name of sorter 1
- tested_name:str, default: None
The name of sorter 2
- delta_time: float, default: 0.4
Number of ms to consider coincident spikes
- match_score: float, default: 0.5
Minimum agreement score to match units
- chance_score: float, default: 0.1
Minimum agreement score to for a possible match
- redundant_score: float, default: 0.2
Agreement score above which units are redundant
- overmerged_score: float, default: 0.2
Agreement score above which units can be overmerged
- well_detected_score: float, default: 0.8
Agreement score above which units are well detected
- exhaustive_gt: bool, default: False
Tell if the ground true is “exhaustive” or not. In other world if the GT have all possible units. It allows more performance measurement. For instance, MEArec simulated dataset have exhaustive_gt=True
- match_mode: “hungarian” | “best”, default: “hungarian”
The method to match units
- n_jobs: int, default: -1
Number of cores to use in parallel. Uses all available if -1
- compute_labels: bool, default: False
If True, labels are computed at instantiation
- compute_misclassifications: bool, default: False
If True, misclassifications are computed at instantiation
- verbose: bool, default: False
If True, output is verbose
- Returns
- sorting_comparison: SortingComparison
The SortingComparison object
- spikeinterface.comparison.compare_templates(we1, we2, we1_name=None, we2_name=None, unit_ids1=None, unit_ids2=None, match_score=0.7, chance_score=0.3, similarity_method='cosine_similarity', sparsity_dict=None, verbose=False)¶
Compares units from different sessions based on template similarity
- Parameters
- we1WaveformExtractor
The first waveform extractor to get templates to compare
- we2WaveformExtractor
The second waveform extractor to get templates to compare
- unit_ids1list, default: None
List of units from we1 to compare
- unit_ids2list, default: None
List of units from we2 to compare
- similarity_methodstr, default: “cosine_similarity”
Method for the similaroty matrix
- sparsity_dictdict, default: None
Dictionary for sparsity
- verbosebool, default: False
If True, output is verbose
- Returns
- comparisonTemplateComparison
The output TemplateComparison object
- spikeinterface.comparison.compare_multiple_templates(waveform_list, name_list=None, match_score=0.8, chance_score=0.3, verbose=False, similarity_method='cosine_similarity', sparsity_dict=None, do_matching=True)¶
Compares multiple waveform extractors using template similarity.
Pair-wise comparisons are made
An agreement graph is built based on the agreement score
- Parameters
- waveform_list: list
List of waveform extractor objects to be compared
- name_list: list, default: None
List of session names. If not given, sorters are named as “sess0”, “sess1”, “sess2”, etc.
- match_score: float, default: 0.8
Minimum agreement score to match units
- chance_score: float, default: 0.3
Minimum agreement score to for a possible match
- verbose: bool, default: False
if True, output is verbose
- Returns
- multi_template_comparison: MultiTemplateComparison
MultiTemplateComparison object with the multiple template comparisons
- spikeinterface.comparison.create_hybrid_units_recording(parent_recording: BaseRecording, templates: ndarray, injected_sorting: Optional[BaseSorting] = None, nbefore: Optional[Union[List[int], int]] = None, firing_rate: float = 10, amplitude_factor: Optional[ndarray] = None, amplitude_std: float = 0.0, refractory_period_ms: float = 2.0, injected_sorting_folder: Optional[Union[str, Path]] = None, seed=None)¶
Class for creating a hybrid recording where additional units are added to an existing recording.
- Parameters
- parent_recording: BaseRecording
Existing recording to add on top of.
- templates: np.ndarray[n_units, n_samples, n_channels]
Array containing the templates to inject for all the units.
- injected_sorting: BaseSorting | None:
The sorting for the injected units. If None, will be generated using the following parameters.
- nbefore: list[int] | int | None
Where is the center of the template for each unit? If None, will default to the highest peak.
- firing_rate: float
The firing rate of the injected units (in Hz).
- amplitude_factor: np.ndarray | None:
The amplitude factor for each spike. If None, will be generated as a gaussian centered at 1.0 and with an std of amplitude_std.
- amplitude_std: float
The standard deviation of the amplitude (centered at 1.0).
- refractory_period_ms: float
The refractory period of the injected spike train (in ms).
- injected_sorting_folder: str | Path | None
If given, the injected sorting is saved to this folder. It must be specified if injected_sorting is None or not serialisable to file.
- Returns
- hybrid_units_recording: HybridUnitsRecording
The recording containing real and hybrid units.
- spikeinterface.comparison.create_hybrid_spikes_recording(wvf_extractor: Union[WaveformExtractor, Path], injected_sorting: Optional[BaseSorting] = None, unit_ids: Optional[List[int]] = None, max_injected_per_unit: int = 1000, injected_rate: float = 0.05, refractory_period_ms: float = 1.5, injected_sorting_folder: Optional[Union[str, Path]] = None) None ¶
Class for creating a hybrid recording where additional spikes are added to already existing units.
- Parameters
- wvf_extractor: WaveformExtractor
The waveform extractor object of the existing recording.
- injected_sorting: BaseSorting | None
Additional spikes to inject. If None, will generate it.
- max_injected_per_unit: int
If injected_sorting=None, the max number of spikes per unit that is allowed to be injected.
- unit_ids: list[int] | None
unit_ids to take in the wvf_extractor for spikes injection.
- injected_rate: float
If injected_sorting=None, the max fraction of spikes per unit that is allowed to be injected.
- refractory_period_ms: float
If injected_sorting=None, the injected spikes need to respect this refractory period.
- injected_sorting_folder: str | Path | None
If given, the injected sorting is saved to this folder. It must be specified if injected_sorting is None or not serializable to file.
- Returns
- hybrid_spikes_recording: HybridSpikesRecording:
The recording containing units with real and hybrid spikes.
- class spikeinterface.comparison.GroundTruthComparison(gt_sorting, tested_sorting, gt_name=None, tested_name=None, delta_time=0.4, sampling_frequency=None, match_score=0.5, well_detected_score=0.8, redundant_score=0.2, overmerged_score=0.2, chance_score=0.1, exhaustive_gt=False, n_jobs=-1, match_mode='hungarian', compute_labels=False, compute_misclassifications=False, verbose=False)¶
Compares a sorter to a ground truth.
- This class can:
compute a “match between gt_sorting and tested_sorting
compute optionally the score label (TP, FN, CL, FP) for each spike
count by unit of GT the total of each (TP, FN, CL, FP) into a Dataframe GroundTruthComparison.count
compute the confusion matrix .get_confusion_matrix()
compute some performance metric with several strategy based on the count score by unit
count well detected units
count false positive detected units
count redundant units
count overmerged units
summary all this
- Parameters
- gt_sorting: SortingExtractor
The first sorting for the comparison
- tested_sorting: SortingExtractor
The second sorting for the comparison
- gt_name: str, default: None
The name of sorter 1
- tested_name:str, default: None
The name of sorter 2
- delta_time: float, default: 0.4
Number of ms to consider coincident spikes
- match_score: float, default: 0.5
Minimum agreement score to match units
- chance_score: float, default: 0.1
Minimum agreement score to for a possible match
- redundant_score: float, default: 0.2
Agreement score above which units are redundant
- overmerged_score: float, default: 0.2
Agreement score above which units can be overmerged
- well_detected_score: float, default: 0.8
Agreement score above which units are well detected
- exhaustive_gt: bool, default: False
Tell if the ground true is “exhaustive” or not. In other world if the GT have all possible units. It allows more performance measurement. For instance, MEArec simulated dataset have exhaustive_gt=True
- match_mode: “hungarian” | “best”, default: “hungarian”
The method to match units
- n_jobs: int, default: -1
Number of cores to use in parallel. Uses all available if -1
- compute_labels: bool, default: False
If True, labels are computed at instantiation
- compute_misclassifications: bool, default: False
If True, misclassifications are computed at instantiation
- verbose: bool, default: False
If True, output is verbose
- Returns
- sorting_comparison: SortingComparison
The SortingComparison object
- count_bad_units()¶
See get_bad_units
- count_false_positive_units(redundant_score=None)¶
See get_false_positive_units().
- count_overmerged_units(overmerged_score=None)¶
See get_overmerged_units().
- count_redundant_units(redundant_score=None)¶
See get_redundant_units().
- count_well_detected_units(well_detected_score)¶
Count how many well detected units. kwargs are the same as get_well_detected_units.
- get_bad_units()¶
Return units list of “bad units”.
“bad units” are defined as units in tested that are not in the best match list of GT units.
So it is the union of “false positive units” + “redundant units”.
Need exhaustive_gt=True
- get_confusion_matrix()¶
Computes the confusion matrix.
- Returns
- confusion_matrix: pandas.DataFrame
The confusion matrix
- get_false_positive_units(redundant_score=None)¶
Return units list of “false positive units” from tested_sorting.
“false positive units” are defined as units in tested that are not matched at all in GT units.
Need exhaustive_gt=True
- Parameters
- redundant_score: float, default: None
The agreement score below which tested units are counted as “false positive”” (and not “redundant”).
- get_overmerged_units(overmerged_score=None)¶
Return “overmerged units”
“overmerged units” are defined as units in tested that match more than one GT unit with an agreement score larger than overmerged_score.
- Parameters
- overmerged_score: float, default: None
Tested units with 2 or more agreement scores above “overmerged_score” are counted as “overmerged”.
- get_performance(method='by_unit', output='pandas')¶
- Get performance rate with several method:
“raw_count” : just render the raw count table
“by_unit” : render perf as rate unit by unit of the GT
“pooled_with_average” : compute rate unit by unit and average
- Parameters
- method: “by_unit” | “pooled_with_average”, default: “by_unit”
The method to compute performance
- output: “pandas” | “dict”, default: “pandas”
The output format
- Returns
- perf: pandas dataframe/series (or dict)
dataframe/series (based on “output”) with performance entries
- get_redundant_units(redundant_score=None)¶
Return “redundant units”
“redundant units” are defined as units in tested that match a GT units with a big agreement score but it is not the best match. In other world units in GT that detected twice or more.
- Parameters
- redundant_score=None: float, default: None
The agreement score above which tested units are counted as “redundant” (and not “false positive” ).
- get_well_detected_units(well_detected_score=None)¶
Return units list of “well detected units” from tested_sorting.
“well detected units” are defined as units in tested that are well matched to GT units.
- Parameters
- well_detected_score: float, default: None
The agreement score above which tested units are counted as “well detected”.
- print_performance(method='pooled_with_average')¶
Print performance with the selected method
- print_summary(well_detected_score=None, redundant_score=None, overmerged_score=None)¶
- Print a global performance summary that depend on the context:
exhaustive= True/False
how many gt units (one or several)
This summary mix several performance metrics.
- class spikeinterface.comparison.SymmetricSortingComparison(sorting1, sorting2, sorting1_name=None, sorting2_name=None, delta_time=0.4, match_score=0.5, chance_score=0.1, n_jobs=-1, verbose=False)¶
Compares two spike sorter outputs.
Spike trains are matched based on their agreement scores
Individual spikes are labelled as true positives (TP), false negatives (FN), false positives 1 (FP from spike train 1), false positives 2 (FP from spike train 2), misclassifications (CL)
It also allows to get confusion matrix and agreement fraction, false positive fraction and false negative fraction.
- Parameters
- sorting1: SortingExtractor
The first sorting for the comparison
- sorting2: SortingExtractor
The second sorting for the comparison
- sorting1_name: str, default: None
The name of sorter 1
- sorting2_name:str, default: None
The name of sorter 2
- delta_time: float, default: 0.4
Number of ms to consider coincident spikes
- match_score: float, default: 0.5
Minimum agreement score to match units
- chance_score: float, default: 0.1
Minimum agreement score to for a possible match
- n_jobs: int, default: -1
Number of cores to use in parallel. Uses all available if -1
- verbose: bool, default: False
If True, output is verbose
- Returns
- sorting_comparison: SortingComparison
The SortingComparison object
- get_agreement_fraction(unit1=None, unit2=None)¶
- get_best_unit_match1(unit1)¶
- get_best_unit_match2(unit2)¶
- get_matching()¶
- get_matching_event_count(unit1, unit2)¶
- get_matching_unit_list1(unit1)¶
- get_matching_unit_list2(unit2)¶
- class spikeinterface.comparison.GroundTruthStudy(study_folder)¶
This class is an helper function to run any comparison on several “cases” for many ground-truth dataset.
- “cases” refer to:
several sorters for comparisons
same sorter with differents parameters
any combination of these (and more)
For increased flexibility, cases keys can be a tuple so that we can vary complexity along several “levels” or “axis” (paremeters or sorters). In this case, the result dataframes will have MultiIndex to handle the different levels.
A ground-truth dataset is made of a Recording and a Sorting object. For example, it can be a simulated dataset with MEArec or internally generated (see
generate_ground_truth_recording()
).This GroundTruthStudy have been refactor in version 0.100 to be more flexible than previous versions. Note that the underlying folder structure is not backward compatible!
- compute_metrics(case_keys=None, metric_names=['snr', 'firing_rate'], force=False)¶
- copy_sortings(case_keys=None, force=True)¶
- classmethod create(study_folder, datasets={}, cases={}, levels=None)¶
- extract_waveforms_gt(case_keys=None, **extract_kwargs)¶
- get_count_units(case_keys=None, well_detected_score=None, redundant_score=None, overmerged_score=None)¶
- get_metrics(key)¶
- get_performance_by_unit(case_keys=None)¶
- get_run_times(case_keys=None)¶
- get_templates(key, mode='average')¶
- get_units_snr(key)¶
- get_waveform_extractor(case_key=None, dataset_key=None)¶
- key_to_str(key)¶
- remove_sorting(key)¶
- run_comparisons(case_keys=None, comparison_class=<class 'spikeinterface.comparison.paircomparisons.GroundTruthComparison'>, **kwargs)¶
- run_sorters(case_keys=None, engine='loop', engine_kwargs={}, keep=True, verbose=False)¶
- scan_folder()¶
- class spikeinterface.comparison.MultiSortingComparison(sorting_list, name_list=None, delta_time=0.4, match_score=0.5, chance_score=0.1, n_jobs=-1, spiketrain_mode='union', verbose=False, do_matching=True)¶
Compares multiple spike sorting outputs based on spike trains.
Pair-wise comparisons are made
An agreement graph is built based on the agreement score
It allows to return a consensus-based sorting extractor with the get_agreement_sorting() method.
- Parameters
- sorting_list: list
List of sorting extractor objects to be compared
- name_list: list, default: None
List of spike sorter names. If not given, sorters are named as “sorter0”, “sorter1”, “sorter2”, etc.
- delta_time: float, default: 0.4
Number of ms to consider coincident spikes
- match_score: float, default: 0.5
Minimum agreement score to match units
- chance_score: float, default: 0.1
Minimum agreement score to for a possible match
- n_jobs: int, default: -1
Number of cores to use in parallel. Uses all available if -1
- spiketrain_mode: “union” | “intersection”, default: “union”
- Mode to extract agreement spike trains:
“union”: spike trains are the union between the spike trains of the best matching two sorters
- “intersection”: spike trains are the intersection between the spike trains of the
best matching two sorters
- verbose: bool, default: False
if True, output is verbose
- Returns
- multi_sorting_comparison: MultiSortingComparison
MultiSortingComparison object with the multiple sorter comparison
- get_agreement_sorting(minimum_agreement_count=1, minimum_agreement_count_only=False)¶
Returns AgreementSortingExtractor with units with a “minimum_matching” agreement.
- Parameters
- minimum_agreement_count: int
Minimum number of matches among sorters to include a unit.
- minimum_agreement_count_only: bool
If True, only units with agreement == “minimum_matching” are included. If False, units with an agreement >= “minimum_matching” are included
- Returns
- agreement_sorting: AgreementSortingExtractor
The output AgreementSortingExtractor
- class spikeinterface.comparison.CollisionGTComparison(gt_sorting, tested_sorting, collision_lag=2.0, nbins=11, **kwargs)¶
This class is an extension of GroundTruthComparison by focusing to benchmark spike in collision.
This class needs maintenance and need a bit of refactoring.
- collision_lag: float
Collision lag in ms.
- class spikeinterface.comparison.CorrelogramGTComparison(gt_sorting, tested_sorting, window_ms=100.0, bin_ms=1.0, well_detected_score=0.8, **kwargs)¶
This class is an extension of GroundTruthComparison by focusing to benchmark correlation reconstruction.
This class needs maintenance and need a bit of refactoring.
- class spikeinterface.comparison.CollisionGTStudy(study_folder)¶
- class spikeinterface.comparison.CorrelogramGTStudy(study_folder)¶
spikeinterface.widgets¶
- spikeinterface.widgets.set_default_plotter_backend(backend)¶
- spikeinterface.widgets.get_default_plotter_backend()¶
Return the default backend for spikeinterface widgets. The default backend is “matplotlib” at init. It can be be globally set with set_default_plotter_backend(backend)
- spikeinterface.widgets.plot_agreement_matrix(sorting_comparison, ordered=True, count_text=True, unit_ticks=True, backend=None, **backend_kwargs)¶
Plots sorting comparison agreement matrix.
- Parameters
- sorting_comparison: GroundTruthComparison or SymmetricSortingComparison
The sorting comparison object. Can optionally be symmetric if given a SymmetricSortingComparison
- ordered: bool, default: True
Order units with best agreement scores. If True, agreement scores can be seen along a diagonal
- count_text: bool, default: True
If True counts are displayed as text
- unit_ticks: bool, default: True
If True unit tick labels are displayed
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_all_amplitudes_distributions(waveform_extractor: WaveformExtractor, unit_ids=None, unit_colors=None, backend=None, **backend_kwargs)¶
Plots distributions of amplitudes as violin plot for all or some units.
- Parameters
- waveform_extractor: WaveformExtractor
The input waveform extractor
- unit_ids: list
List of unit ids, default None
- unit_colors: None or dict
Dict of colors with key: unit, value: color, default None
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_amplitudes(waveform_extractor: WaveformExtractor, unit_ids=None, unit_colors=None, segment_index=None, max_spikes_per_unit=None, hide_unit_selector=False, plot_histograms=False, bins=None, plot_legend=True, backend=None, **backend_kwargs)¶
Plots spike amplitudes
- Parameters
- waveform_extractorWaveformExtractor
The input waveform extractor
- unit_idslist or None, default: None
List of unit ids
- segment_indexint or None, default: None
The segment index (or None if mono-segment)
- max_spikes_per_unitint or None, default: None
Number of max spikes per unit to display. Use None for all spikes
- hide_unit_selectorbool, default: False
If True the unit selector is not displayed (sortingview backend)
- plot_histogrambool, default: False
If True, an histogram of the amplitudes is plotted on the right axis (matplotlib backend)
- binsint or None, default: None
If plot_histogram is True, the number of bins for the amplitude histogram. If None this is automatically adjusted
- plot_legendbool, default: True
True includes legend in plot
- backend: str
[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
ipywidgets:
width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_autocorrelograms(*args, **kargs)¶
Plots unit cross correlograms.
- Parameters
- waveform_or_sorting_extractorWaveformExtractor or BaseSorting
The object to compute/get crosscorrelograms from
- unit_ids list or None, default: None
List of unit ids
- window_msfloat, default: 100.0
Window for CCGs in ms
- bin_msfloat, default: 1.0
Bin size in ms
- hide_unit_selectorbool, default: False
For sortingview backend, if True the unit selector is not displayed
- unit_colors: dict or None, default: None
If given, a dictionary with unit ids as keys and colors as values
- backend: str
[‘matplotlib’, ‘sortingview’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_confusion_matrix(gt_comparison, count_text=True, unit_ticks=True, backend=None, **backend_kwargs)¶
Plots sorting comparison confusion matrix.
- Parameters
- gt_comparison: GroundTruthComparison
The ground truth sorting comparison object
- count_text: bool
If True counts are displayed as text
- unit_ticks: bool
If True unit tick labels are displayed
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_comparison_collision_by_similarity(comp, templates, unit_ids=None, metric='cosine_similarity', figure=None, ax=None, mode='heatmap', similarity_bins=array([-4.00000000e-01, -2.00000000e-01, -5.55111512e-17, 2.00000000e-01, 4.00000000e-01, 6.00000000e-01, 8.00000000e-01, 1.00000000e+00]), cmap='winter', good_only=False, min_accuracy=0.9, show_legend=False, ylim=(0, 1), backend=None, **backend_kwargs)¶
Plots CollisionGTComparison pair by pair orderer by cosine_similarity
- Parameters
- comp: CollisionGTComparison
The collision ground truth comparison object
- templates: array
template of units
- mode: “heatmap” or “lines”
to see collision curves for every pairs (“heatmap”) or as lines averaged over pairs.
- similarity_bins: array
if mode is “lines”, the bins used to average the pairs
- cmap: string
colormap used to show averages if mode is “lines”
- metric: “cosine_similarity”
metric for ordering
- good_only: True
keep only the pairs with a non zero accuracy (found templates)
- min_accuracy: float
If good only, the minimum accuracy every cell should have, individually, to be considered in a putative pair
- unit_ids: list
List of considered units
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_crosscorrelograms(waveform_or_sorting_extractor: Union[WaveformExtractor, BaseSorting], unit_ids=None, window_ms=100.0, bin_ms=1.0, hide_unit_selector=False, unit_colors=None, backend=None, **backend_kwargs)¶
Plots unit cross correlograms.
- Parameters
- waveform_or_sorting_extractorWaveformExtractor or BaseSorting
The object to compute/get crosscorrelograms from
- unit_ids list or None, default: None
List of unit ids
- window_msfloat, default: 100.0
Window for CCGs in ms
- bin_msfloat, default: 1.0
Bin size in ms
- hide_unit_selectorbool, default: False
For sortingview backend, if True the unit selector is not displayed
- unit_colors: dict or None, default: None
If given, a dictionary with unit ids as keys and colors as values
- backend: str
[‘matplotlib’, ‘sortingview’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_isi_distribution(sorting, unit_ids=None, window_ms=100.0, bin_ms=1.0, backend=None, **backend_kwargs)¶
Plots spike train ISI distribution.
- Parameters
- sorting: SortingExtractor
The sorting extractor object
- unit_ids: list
List of unit ids
- bins_ms: int
Bin size in ms
- window_ms: float
Window size in ms
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_motion(motion_info, recording=None, depth_lim=None, motion_lim=None, color_amplitude=False, scatter_decimate=None, amplitude_cmap='inferno', amplitude_clim=None, amplitude_alpha=1, backend=None, **backend_kwargs)¶
Plot unit depths
- Parameters
- motion_info: dict
The motion info return by correct_motion() or load back with load_motion_info()
- recordingRecordingExtractor, default: None
The recording extractor object (only used to get “real” times)
- sampling_frequencyfloat, default: None
The sampling frequency (needed if recording is None)
- depth_limtuple or None, default: None
The min and max depth to display, if None (min and max of the recording)
- motion_limtuple or None, default: None
The min and max motion to display, if None (min and max of the motion)
- color_amplitudebool, default: False
If True, the color of the scatter points is the amplitude of the peaks
- scatter_decimateint, default: None
If > 1, the scatter points are decimated
- amplitude_cmapstr, default: “inferno”
The colormap to use for the amplitude
- amplitude_climtuple or None, default: None
The min and max amplitude to display, if None (min and max of the amplitudes)
- amplitude_alphafloat, default: 1
The alpha of the scatter points
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_multicomparison_agreement(multi_comparison, plot_type='pie', cmap='YlOrRd', fontsize=9, show_legend=True, backend=None, **backend_kwargs)¶
Plots multi comparison agreement as pie or bar plot.
- Parameters
- multi_comparison: BaseMultiComparison
The multi comparison object
- plot_type: “pie” | “bar”, default: “pie”
The plot type
- cmap: matplotlib colormap, default: “YlOrRd”
The colormap to be used for the nodes
- fontsize: int, default: 9
The text fontsize
- show_legend: bool, default: True
If True a legend is shown
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_multicomparison_agreement_by_sorter(multi_comparison, plot_type='pie', cmap='YlOrRd', fontsize=9, show_legend=True, backend=None, **backend_kwargs)¶
Plots multi comparison agreement as pie or bar plot.
- Parameters
- multi_comparison: BaseMultiComparison
The multi comparison object
- plot_type: “pie” | “bar”, default: “pie
The plot type
- cmap: matplotlib colormap, default: “Reds”
The colormap to be used for the nodes
- fontsize: int, default: 9
The text fontsize
- show_legend: bool
Show the legend in the last axes
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_multicomparison_graph(multi_comparison, draw_labels=False, node_cmap='viridis', edge_cmap='hot', alpha_edges=0.5, colorbar=False, backend=None, **backend_kwargs)¶
Plots multi comparison graph.
- Parameters
- multi_comparison: BaseMultiComparison
The multi comparison object
- draw_labels: bool, default: False
If True unit labels are shown
- node_cmap: matplotlib colormap, default: “viridis”
The colormap to be used for the nodes
- edge_cmap: matplotlib colormap, default: “hot”
The colormap to be used for the edges
- alpha_edges: float, default: 0.5
Alpha value for edges
- colorbar: bool, default: False
If True a colorbar for the edges is plotted
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_peak_activity(recording, peaks, bin_duration_s=None, with_contact_color=True, with_interpolated_map=True, with_channel_ids=False, with_color_bar=True, backend=None, **backend_kwargs)¶
Plots spike rate (estimated with detect_peaks()) as 2D activity map.
Can be static (bin_duration_s=None) or animated (bin_duration_s=60.)
- Parameters
- recording: RecordingExtractor
The recording extractor object.
- peaks: None or numpy array
Optionally can give already detected peaks to avoid multiple computation.
- detect_peaks_kwargs: None or dict, default: None
If peaks is None here the kwargs for detect_peak function.
- bin_duration_s: None or float, default: None
If None then static image If not None then it is an animation per bin.
- with_contact_color: bool, default: True
Plot rates with contact colors
- with_interpolated_map: bool, default: True
Plot rates with interpolated map
- with_channel_ids: bool, default: False
Add channel ids text on the probe
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_probe_map(recording, channel_ids=None, with_channel_ids=False, backend=None, **backend_or_plot_probe_kwargs)¶
Plot the probe of a recording.
- Parameters
- recording: RecordingExtractor
The recording extractor object
- channel_ids: list
The channel ids to display
- with_channel_ids: bool False default
Add channel ids text on the probe
- **plot_probe_kwargs: keyword arguments for probeinterface.plotting.plot_probe_group() function
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_quality_metrics(waveform_extractor: WaveformExtractor, unit_ids=None, include_metrics=None, skip_metrics=None, unit_colors=None, hide_unit_selector=False, backend=None, **backend_kwargs)¶
Plots quality metrics distributions.
- Parameters
- waveform_extractorWaveformExtractor
The object to compute/get quality metrics from
- unit_ids: list or None, default: None
List of unit ids
- include_metrics: list or None, default: None
If given, a list of quality metrics to include
- skip_metrics: list or None, default: None
If given, a list of quality metrics to skip
- unit_colorsdict or None, default: None
If given, a dictionary with unit ids as keys and colors as values
- hide_unit_selectorbool, default: False
For sortingview backend, if True the unit selector is not displayed
- backend: str
[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
ipywidgets:
width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_rasters(sorting, segment_index=None, unit_ids=None, time_range=None, color='k', backend=None, **backend_kwargs)¶
Plots spike train rasters.
- Parameters
- sorting: SortingExtractor
The sorting extractor object
- segment_index: None or int
The segment index.
- unit_ids: list
List of unit ids
- time_range: list
List with start time and end time
- color: matplotlib color
The color to be used
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_sorting_summary(waveform_extractor: WaveformExtractor, unit_ids=None, sparsity=None, max_amplitudes_per_unit=None, curation=False, unit_table_properties=None, label_choices=None, backend=None, **backend_kwargs)¶
Plots spike sorting summary
- Parameters
- waveform_extractorWaveformExtractor
The waveform extractor object
- unit_idslist or None, default: None
List of unit ids
- sparsityChannelSparsity or None, default: None
Optional ChannelSparsity to apply If WaveformExtractor is already sparse, the argument is ignored
- max_amplitudes_per_unitint or None, default: None
Maximum number of spikes per unit for plotting amplitudes. If None, all spikes are plotted
- curationbool, default: False
If True, manual curation is enabled (sortingview backend)
- unit_table_propertieslist or None, default: None
List of properties to be added to the unit table
- label_choiceslist or None, default: None
List of labels to be added to the curation table
- unit_table_propertieslist or None, default: None
List of properties to be added to the unit table (sortingview backend)
- backend: str
[‘sortingview’]
- **backend_kwargs: kwargs
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_spike_locations(waveform_extractor: WaveformExtractor, unit_ids=None, segment_index=None, max_spikes_per_unit=500, with_channel_ids=False, unit_colors=None, hide_unit_selector=False, plot_all_units=True, plot_legend=False, hide_axis=False, backend=None, **backend_kwargs)¶
Plots spike locations.
- Parameters
- waveform_extractorWaveformExtractor
The object to compute/get spike locations from
- unit_idslist or None, default: None
List of unit ids
- segment_indexint or None, default: None
The segment index (or None if mono-segment)
- max_spikes_per_unitint or None, default: 500
Number of max spikes per unit to display. Use None for all spikes.
- with_channel_idsbool, default: False
Add channel ids text on the probe
- unit_colorsdict or None, default: None
If given, a dictionary with unit ids as keys and colors as values
- hide_unit_selectorbool, default: False
For sortingview backend, if True the unit selector is not displayed
- plot_all_unitsbool, default: True
If True, all units are plotted. The unselected ones (not in unit_ids), are plotted in grey (matplotlib backend)
- plot_legendbool, default: False
If True, the legend is plotted (matplotlib backend)
- hide_axisbool, default: False
If True, the axis is set to off (matplotlib backend)
- backend: str
[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
ipywidgets:
width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_spikes_on_traces(waveform_extractor: WaveformExtractor, segment_index=None, channel_ids=None, unit_ids=None, order_channel_by_depth=False, time_range=None, unit_colors=None, sparsity=None, mode='auto', return_scaled=False, cmap='RdBu', show_channel_ids=False, color_groups=False, color=None, clim=None, tile_size=512, seconds_per_row=0.2, with_colorbar=True, backend=None, **backend_kwargs)¶
Plots unit spikes/waveforms over traces.
- Parameters
- waveform_extractorWaveformExtractor
The waveform extractor
- channel_idslist or None, default: None
The channel ids to display
- unit_idslist or None, default: None
List of unit ids
- order_channel_by_depthbool, default: False
If true orders channel by depth
- time_range: list or None, default: None
List with start time and end time in seconds
- sparsityChannelSparsity or None, default: None
Optional ChannelSparsity to apply If WaveformExtractor is already sparse, the argument is ignored
- unit_colorsdict or None, default: None
If given, a dictionary with unit ids as keys and colors as values If None, then the get_unit_colors() is internally used. (matplotlib backend)
- mode“line” | “map” | “auto”, default: “auto”
“line”: classical for low channel count
“map”: for high channel count use color heat map
“auto”: auto switch depending on the channel count (“line” if less than 64 channels, “map” otherwise)
- return_scaledbool, default: False
If True and the recording has scaled traces, it plots the scaled traces
- cmapstr, default: “RdBu”
matplotlib colormap used in mode “map”
- show_channel_idsbool, default: False
Set yticks with channel ids
- color_groupsbool, default: False
If True groups are plotted with different colors
- colorstr or None, default: None
The color used to draw the traces
- climNone, tuple or dict, default: None
When mode is “map”, this argument controls color limits. If dict, keys should be the same as recording keys
- with_colorbarbool, default: True
When mode is “map”, a colorbar is added
- tile_sizeint, default: 512
For sortingview backend, the size of each tile in the rendered image
- seconds_per_rowfloat, default: 0.2
For “map” mode and sortingview backend, seconds to render in each row
- backend: str
[‘matplotlib’, ‘ipywidgets’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
ipywidgets:
width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_template_metrics(waveform_extractor: WaveformExtractor, unit_ids=None, include_metrics=None, skip_metrics=None, unit_colors=None, hide_unit_selector=False, backend=None, **backend_kwargs)¶
Plots template metrics distributions.
- Parameters
- waveform_extractorWaveformExtractor
The object to compute/get template metrics from
- unit_idslist or None, default: None
List of unit ids
- include_metricslist or None, default: None
If given list of quality metrics to include
- skip_metricslist or None or None, default: None
If given, a list of quality metrics to skip
- unit_colorsdict or None, default: None
If given, a dictionary with unit ids as keys and colors as values
- hide_unit_selectorbool, default: False
For sortingview backend, if True the unit selector is not displayed
- backend: str
[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
ipywidgets:
width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_template_similarity(waveform_extractor: WaveformExtractor, unit_ids=None, cmap='viridis', display_diagonal_values=False, show_unit_ticks=False, show_colorbar=True, backend=None, **backend_kwargs)¶
Plots unit template similarity.
- Parameters
- waveform_extractorWaveformExtractor
The object to compute/get template similarity from
- unit_idslist or None, default: None
List of unit ids default: None
- display_diagonal_valuesbool, default: False
If False, the diagonal is displayed as zeros. If True, the similarity values (all 1s) are displayed
- cmapmatplotlib colormap, default: “viridis”
The matplotlib colormap
- show_unit_ticksbool, default: False
If True, ticks display unit ids
- show_colorbarbool, default: True
If True, color bar is displayed
- backend: str
[‘matplotlib’, ‘sortingview’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_traces(recording, segment_index=None, channel_ids=None, order_channel_by_depth=False, time_range=None, mode='auto', return_scaled=False, cmap='RdBu_r', show_channel_ids=False, color_groups=False, color=None, clim=None, tile_size=1500, seconds_per_row=0.2, with_colorbar=True, add_legend=True, backend=None, **backend_kwargs)¶
Plots recording timeseries.
- Parameters
- recording: RecordingExtractor, dict, or list
The recording extractor object. If dict (or list) then it is a multi-layer display to compare, for example, different processing steps
- segment_index: None or int, default: None
The segment index (required for multi-segment recordings)
- channel_ids: list or None, default: None
The channel ids to display
- order_channel_by_depth: bool, default: False
Reorder channel by depth
- time_range: list, tuple or None, default: None
List with start time and end time
- mode: “line” | “map” | “auto”, default: “auto”
Three possible modes * “line”: classical for low channel count * “map”: for high channel count use color heat map * “auto”: auto switch depending on the channel count (“line” if less than 64 channels, “map” otherwise)
- return_scaled: bool, default: False
If True and the recording has scaled traces, it plots the scaled traces
- cmap: matplotlib colormap, default: “RdBu_r”
matplotlib colormap used in mode “map”
- show_channel_ids: bool, default: False
Set yticks with channel ids
- color_groups: bool, default: False
If True groups are plotted with different colors
- color: str or None, default: None
The color used to draw the traces
- clim: None, tuple or dict, default: None
When mode is “map”, this argument controls color limits. If dict, keys should be the same as recording keys
- with_colorbar: bool, default: True
When mode is “map”, a colorbar is added
- tile_size: int, default: 1500
For sortingview backend, the size of each tile in the rendered image
- seconds_per_row: float, default: 0.2
For “map” mode and sortingview backend, seconds to render in each row
- add_legendbool, default: True
If True adds legend to figures
- backend: str
[‘matplotlib’, ‘sortingview’, ‘ipywidgets’, ‘ephyviewer’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
ipywidgets:
width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_unit_depths(waveform_extractor, unit_colors=None, depth_axis=1, peak_sign='neg', backend=None, **backend_kwargs)¶
Plot unit depths
- Parameters
- waveform_extractorWaveformExtractor
The input waveform extractor
- unit_colorsdict or None, default: None
If given, a dictionary with unit ids as keys and colors as values
- depth_axisint, default: 1
The dimension of unit_locations that is depth
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Sign of peak for amplitudes
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_unit_locations(waveform_extractor: WaveformExtractor, unit_ids=None, with_channel_ids=False, unit_colors=None, hide_unit_selector=False, plot_all_units=True, plot_legend=False, hide_axis=False, backend=None, **backend_kwargs)¶
Plots each unit’s location.
- Parameters
- waveform_extractorWaveformExtractor
The object to compute/get unit locations from
- unit_idslist or None, default: None
List of unit ids
- with_channel_idsbool, default: False
Add channel ids text on the probe
- unit_colorsdict or None, default: None
If given, a dictionary with unit ids as keys and colors as values
- hide_unit_selectorbool, default: False
If True, the unit selector is not displayed (sortingview backend)
- plot_all_unitsbool, default: True
If True, all units are plotted. The unselected ones (not in unit_ids), are plotted in grey (matplotlib backend)
- plot_legendbool, default: False
If True, the legend is plotted (matplotlib backend)
- hide_axisbool, default: False
If True, the axis is set to off (matplotlib backend)
- backend: str
[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
ipywidgets:
width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_unit_presence(sorting, segment_index=None, time_range=None, bin_duration_s=0.05, smooth_sigma=4.5, backend=None, **backend_kwargs)¶
Estimates of the probability density function for each unit using Gaussian kernels,
- Parameters
- sorting: SortingExtractor
The sorting extractor object
- segment_index: None or int
The segment index.
- time_range: list or None, default: None
List with start time and end time
- bin_duration_s: float, default: 0.5
Bin size (in seconds) for the heat map time axis
- smooth_sigma: float, default: 4.5
Sigma for the Gaussian kernel (in number of bins)
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_unit_probe_map(waveform_extractor, unit_ids=None, channel_ids=None, animated=None, with_channel_ids=False, colorbar=True, backend=None, **backend_kwargs)¶
Plots unit map. Amplitude is color coded on probe contact.
Can be static (animated=False) or animated (animated=True)
- Parameters
- waveform_extractor: WaveformExtractor
- unit_ids: list
List of unit ids.
- channel_ids: list
The channel ids to display
- animated: bool, default: False
Animation for amplitude on time
- with_channel_ids: bool, default: False
add channel ids text on the probe
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_unit_summary(waveform_extractor, unit_id, unit_colors=None, sparsity=None, radius_um=100, backend=None, **backend_kwargs)¶
Plot a unit summary.
If amplitudes are alreday computed they are displayed.
- Parameters
- waveform_extractorWaveformExtractor
The waveform extractor object
- unit_idint or str
The unit id to plot the summary of
- unit_colorsdict or None, default: None
If given, a dictionary with unit ids as keys and colors as values,
- sparsityChannelSparsity or None, default: None
Optional ChannelSparsity to apply. If WaveformExtractor is already sparse, the argument is ignored
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_unit_templates(*args, **kargs)¶
Plots unit waveforms.
- Parameters
- waveform_extractorWaveformExtractor
The input waveform extractor
- channel_ids: list or None, default: None
The channel ids to display
- unit_idslist or None, default: None
List of unit ids
- plot_templatesbool, default: True
If True, templates are plotted over the waveforms
- sparsityChannelSparsity or None, default: None
Optional ChannelSparsity to apply If WaveformExtractor is already sparse, the argument is ignored
- set_titlebool, default: True
Create a plot title with the unit number if True
- plot_channelsbool, default: False
Plot channel locations below traces
- unit_selected_waveformsNone or dict, default: None
A dict key is unit_id and value is the subset of waveforms indices that should be be displayed (matplotlib backend)
- max_spikes_per_unitint or None, default: 50
If given and unit_selected_waveforms is None, only max_spikes_per_unit random units are displayed per waveform, (matplotlib backend)
- scalefloat, default: 1
Scale factor for the waveforms/templates (matplotlib backend)
- axis_equalbool, default: False
Equal aspect ratio for x and y axis, to visualize the array geometry to scale
- lw_waveformsfloat, default: 1
Line width for the waveforms, (matplotlib backend)
- lw_templatesfloat, default: 2
Line width for the templates, (matplotlib backend)
- unit_colorsNone or dict, default: None
A dict key is unit_id and value is any color format handled by matplotlib. If None, then the get_unit_colors() is internally used. (matplotlib / ipywidgets backend)
- alpha_waveformsfloat, default: 0.5
Alpha value for waveforms (matplotlib backend)
- alpha_templatesfloat, default: 1
Alpha value for templates, (matplotlib backend)
- shade_templatesbool, default: True
If True, templates are shaded, see templates_percentile_shading argument
- templates_percentile_shadingfloat, list of floats, or None, default: [1, 25, 75, 98]
It controls the shading of the templates. If None, the shading is +/- the standard deviation of the templates. If float, it controls the percentile of the template values used to shade the templates. Note that it is one-sided: if 5 is given, the 5th and 95th percentiles are used to shade the templates. If list of floats, it needs to be have an even number of elements which control the lower and upper percentile used to shade the templates. The first half of the elements are used for the lower bounds, and the second half for the upper bounds. Inner elements produce darker shadings. For sortingview backend only 2 or 4 elements are supported.
- hide_unit_selectorbool, default: False
For sortingview backend, if True the unit selector is not displayed
- same_axisbool, default: False
If True, waveforms and templates are displayed on the same axis (matplotlib backend)
- x_offset_unitsbool, default: False
In case same_axis is True, this parameter allow to x-offset the waveforms for different units (recommended for a few units) (matlotlib backend)
- plot_legendbool, default: True
Display legend (matplotlib backend)
- backend: str
[‘matplotlib’, ‘sortingview’, ‘ipywidgets’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
sortingview:
generate_url: If True, the figurl URL is generated and printed, default: True
display: If True and in jupyter notebook/lab, the widget is displayed in the cell, default: True.
figlabel: The figurl figure label, default: None
height: The height of the sortingview View in jupyter, default: None
ipywidgets:
width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_unit_waveforms_density_map(waveform_extractor, channel_ids=None, unit_ids=None, sparsity=None, same_axis=False, use_max_channel=False, peak_sign='neg', unit_colors=None, backend=None, **backend_kwargs)¶
Plots unit waveforms using heat map density.
- Parameters
- waveform_extractorWaveformExtractor
The waveformextractor for calculating waveforms
- channel_idslist or None, default: None
The channel ids to display
- unit_idslist or None, default: None
List of unit ids
- sparsityChannelSparsity or None, default: None
Optional ChannelSparsity to apply If WaveformExtractor is already sparse, the argument is ignored
- use_max_channelbool, default: False
Use only the max channel
- peak_sign“neg” | “pos” | “both”, default: “neg”
Used to detect max channel only when use_max_channel=True
- unit_colorsNone or dict, default: None
A dict key is unit_id and value is any color format handled by matplotlib. If None, then the get_unit_colors() is internally used
- same_axisbool, default: False
If True then all density are plot on the same axis and then channels is the union all channel per units
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_unit_waveforms(waveform_extractor: WaveformExtractor, channel_ids=None, unit_ids=None, plot_waveforms=True, plot_templates=True, plot_channels=False, unit_colors=None, sparsity=None, ncols=5, scale=1, lw_waveforms=1, lw_templates=2, axis_equal=False, unit_selected_waveforms=None, max_spikes_per_unit=50, set_title=True, same_axis=False, shade_templates=True, templates_percentile_shading=[1, 25, 75, 98], x_offset_units=False, alpha_waveforms=0.5, alpha_templates=1, hide_unit_selector=False, plot_legend=True, backend=None, **backend_kwargs)¶
Plots unit waveforms.
- Parameters
- waveform_extractorWaveformExtractor
The input waveform extractor
- channel_ids: list or None, default: None
The channel ids to display
- unit_idslist or None, default: None
List of unit ids
- plot_templatesbool, default: True
If True, templates are plotted over the waveforms
- sparsityChannelSparsity or None, default: None
Optional ChannelSparsity to apply If WaveformExtractor is already sparse, the argument is ignored
- set_titlebool, default: True
Create a plot title with the unit number if True
- plot_channelsbool, default: False
Plot channel locations below traces
- unit_selected_waveformsNone or dict, default: None
A dict key is unit_id and value is the subset of waveforms indices that should be be displayed (matplotlib backend)
- max_spikes_per_unitint or None, default: 50
If given and unit_selected_waveforms is None, only max_spikes_per_unit random units are displayed per waveform, (matplotlib backend)
- scalefloat, default: 1
Scale factor for the waveforms/templates (matplotlib backend)
- axis_equalbool, default: False
Equal aspect ratio for x and y axis, to visualize the array geometry to scale
- lw_waveformsfloat, default: 1
Line width for the waveforms, (matplotlib backend)
- lw_templatesfloat, default: 2
Line width for the templates, (matplotlib backend)
- unit_colorsNone or dict, default: None
A dict key is unit_id and value is any color format handled by matplotlib. If None, then the get_unit_colors() is internally used. (matplotlib / ipywidgets backend)
- alpha_waveformsfloat, default: 0.5
Alpha value for waveforms (matplotlib backend)
- alpha_templatesfloat, default: 1
Alpha value for templates, (matplotlib backend)
- shade_templatesbool, default: True
If True, templates are shaded, see templates_percentile_shading argument
- templates_percentile_shadingfloat, list of floats, or None, default: [1, 25, 75, 98]
It controls the shading of the templates. If None, the shading is +/- the standard deviation of the templates. If float, it controls the percentile of the template values used to shade the templates. Note that it is one-sided: if 5 is given, the 5th and 95th percentiles are used to shade the templates. If list of floats, it needs to be have an even number of elements which control the lower and upper percentile used to shade the templates. The first half of the elements are used for the lower bounds, and the second half for the upper bounds. Inner elements produce darker shadings. For sortingview backend only 2 or 4 elements are supported.
- hide_unit_selectorbool, default: False
For sortingview backend, if True the unit selector is not displayed
- same_axisbool, default: False
If True, waveforms and templates are displayed on the same axis (matplotlib backend)
- x_offset_unitsbool, default: False
In case same_axis is True, this parameter allow to x-offset the waveforms for different units (recommended for a few units) (matlotlib backend)
- plot_legendbool, default: True
Display legend (matplotlib backend)
- backend: str
[‘matplotlib’, ‘ipywidgets’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
ipywidgets:
width_cm: Width of the figure in cm, default: 10
height_cm: Height of the figure in cm, default 6
display: If True, widgets are immediately displayed, default: True
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_study_run_times(study, case_keys=None, backend=None, **backend_kwargs)¶
Plot sorter run times for a GroundTruthStudy
- Parameters
- study: GroundTruthStudy
A study object.
- case_keys: list or None
A selection of cases to plot, if None, then all.
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_study_unit_counts(study, case_keys=None, backend=None, **backend_kwargs)¶
Plot unit counts for a study: “num_well_detected”, “num_false_positive”, “num_redundant”, “num_overmerged”
- Parameters
- study: GroundTruthStudy
A study object.
- case_keys: list or None
A selection of cases to plot, if None, then all.
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_study_performances(study, mode='ordered', performance_names=('accuracy', 'precision', 'recall'), case_keys=None, backend=None, **backend_kwargs)¶
Plot performances over case for a study.
- Parameters
- study: GroundTruthStudy
A study object.
- mode: “ordered” | “snr” | “swarm”, default: “ordered”
Which plot mode to use:
“ordered”: plot performance metrics vs unit indices ordered by decreasing accuracy
“snr”: plot performance metrics vs snr
“swarm”: plot performance metrics as a swarm plot (see seaborn.swarmplot for details)
- performance_names: list or tuple, default: (“accuracy”, “precision”, “recall”)
Which performances to plot (“accuracy”, “precision”, “recall”)
- case_keys: list or None
A selection of cases to plot, if None, then all.
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_study_agreement_matrix(study, ordered=True, case_keys=None, backend=None, **backend_kwargs)¶
Plot agreement matrix.
- Parameters
- study: GroundTruthStudy
A study object.
- case_keys: list or None
A selection of cases to plot, if None, then all.
- ordered: bool
Order units with best agreement scores. This enable to see agreement on a diagonal.
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_study_summary(study, case_keys=None, backend=None, **backend_kwargs)¶
Plot a summary of a ground truth study. Internally this plotting function runs:
plot_study_run_times
plot_study_unit_counts
plot_study_performances
plot_study_agreement_matrix
- Parameters
- study: GroundTruthStudy
A study object.
- case_keys: list or None, default: None
A selection of cases to plot, if None, then all.
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
- spikeinterface.widgets.plot_study_comparison_collision_by_similarity(study, case_keys=None, metric='cosine_similarity', similarity_bins=array([-4.00000000e-01, -2.00000000e-01, -5.55111512e-17, 2.00000000e-01, 4.00000000e-01, 6.00000000e-01, 8.00000000e-01, 1.00000000e+00]), show_legend=False, ylim=(0.5, 1), good_only=False, min_accuracy=0.9, cmap='winter', backend=None, **backend_kwargs)¶
Plots CollisionGTComparison pair by pair orderer by cosine_similarity for all cases in a study.
- Parameters
- study: CollisionGTStudy
The collision study object.
- case_keys: list or None
A selection of cases to plot, if None, then all.
- metric: “cosine_similarity”
metric for ordering
- similarity_bins: array
if mode is “lines”, the bins used to average the pairs
- cmap: string
colormap used to show averages if mode is “lines”
- good_only: False
keep only the pairs with a non zero accuracy (found templates)
- min_accuracy: float
If good only, the minimum accuracy every cell should have, individually, to be considered in a putative pair
- backend: str
[‘matplotlib’]
- **backend_kwargs: kwargs
matplotlib:
figure: Matplotlib figure. When None, it is created, default: None
ax: Single matplotlib axis. When None, it is created, default: None
axes: Multiple matplotlib axes. When None, they is created, default: None
ncols: Number of columns to create in subplots, default: 5
figsize: Size of matplotlib figure, default: None
figtitle: The figure title, default: None
- Returns
- wBaseWidget
The output widget object.
spikeinterface.exporters¶
- spikeinterface.exporters.export_to_phy(waveform_extractor: WaveformExtractor, output_folder: str | pathlib.Path, compute_pc_features: bool = True, compute_amplitudes: bool = True, sparsity: Optional[ChannelSparsity] = None, copy_binary: bool = True, remove_if_exists: bool = False, peak_sign: Literal['both', 'neg', 'pos'] = 'neg', template_mode: str = 'median', dtype: Union[dtype[Any], None, type[Any], _SupportsDType[dtype[Any]], str, tuple[Any, int], tuple[Any, Union[SupportsIndex, collections.abc.Sequence[SupportsIndex]]], list[Any], _DTypeDict, tuple[Any, Any]] = None, verbose: bool = True, use_relative_path: bool = False, **job_kwargs)¶
Exports a waveform extractor to the phy template-gui format.
- Parameters
- waveform_extractor: a WaveformExtractor or None
If WaveformExtractor is provide then the compute is faster otherwise
- output_folder: str | Path
The output folder where the phy template-gui files are saved
- compute_pc_features: bool, default: True
If True, pc features are computed
- compute_amplitudes: bool, default: True
If True, waveforms amplitudes are computed
- sparsity: ChannelSparsity or None, default: None
The sparsity object
- copy_binary: bool, default: True
If True, the recording is copied and saved in the phy “output_folder”
- remove_if_exists: bool, default: False
If True and “output_folder” exists, it is removed and overwritten
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Used by compute_spike_amplitudes
- template_mode: str, default: “median”
Parameter “mode” to be given to WaveformExtractor.get_template()
- dtype: dtype or None, default: None
Dtype to save binary data
- verbose: bool, default: True
If True, output is verbose
- use_relative_pathbool, default: False
If True and copy_binary=True saves the binary file dat_path in the params.py relative to output_folder (ie dat_path=r”recording.dat”). If copy_binary=False, then uses a path relative to the output_folder If False, uses an absolute path in the params.py (ie dat_path=r”path/to/the/recording.dat”)
- **job_kwargs: keyword arguments for parallel processing:
- chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
Number of samples per chunk
- chunk_memory: str
Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
- n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
- progress_bar: bool
If True, a progress bar is printed
- mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems
- spikeinterface.exporters.export_report(waveform_extractor, output_folder, remove_if_exists=False, format='png', show_figures=False, peak_sign='neg', force_computation=False, **job_kwargs)¶
Exports a SI spike sorting report. The report includes summary figures of the spike sorting output (e.g. amplitude distributions, unit localization and depth VS amplitude) as well as unit-specific reports, that include waveforms, templates, template maps, ISI distributions, and more.
- Parameters
- waveform_extractor: a WaveformExtractor or None
If WaveformExtractor is provide then the compute is faster otherwise
- output_folder: str
The output folder where the report files are saved
- remove_if_exists: bool, default: False
If True and the output folder exists, it is removed
- format: str, default: “png”
The output figure format (any format handled by matplotlib)
- peak_sign: “neg” or “pos”, default: “neg”
used to compute amplitudes and metrics
- show_figures: bool, default: False
If True, figures are shown. If False, figures are closed after saving
- force_computation: bool, default: False
Force or not some heavy computaion before exporting
- **job_kwargs: keyword arguments for parallel processing:
- chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
Number of samples per chunk
- chunk_memory: str
Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
- n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
- progress_bar: bool
If True, a progress bar is printed
- mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems
spikeinterface.curation¶
- class spikeinterface.curation.CurationSorting(parent_sorting, make_graph=False, properties_policy='keep')¶
Class that handles curation of a Sorting object.
- Parameters
- parent_sorting: Recording
The recording object
- properties_policy: “keep” | “remove”, default: “keep”
Policy used to propagate properties after split and merge operation. If “keep” the properties will be passed to the new units (if the original units have the same value). If “remove” the new units will have an empty value for all the properties
- make_graph: bool
True to keep a Networkx graph instance with the curation history
- Returns
- ——-
- sorting: Sorting
Sorting object with the selected units merged
- class spikeinterface.curation.MergeUnitsSorting(parent_sorting, units_to_merge, new_unit_ids=None, properties_policy='keep', delta_time_ms=0.4)¶
Class that handles several merges of units from a Sorting object based on a list of lists of unit_ids.
- Parameters
- parent_sorting: Recording
The sorting object
- units_to_merge: list/tuple of lists/tuples
A list of lists for every merge group. Each element needs to have at least two elements (two units to merge), but it can also have more (merge multiple units at once).
- new_unit_ids: None or list
A new unit_ids for merged units. If given, it needs to have the same length as units_to_merge
- properties_policy: “keep” | “remove”, default: “keep”
- Policy used to propagate properties. If “keep” the properties will be passed to the new units
(if the units_to_merge have the same value). If “remove” the new units will have an empty value for all the properties of the new unit.
- delta_time_ms: float or None
Number of ms to consider for duplicated spikes. None won’t check for duplications
- Returns
- sorting: Sorting
Sorting object with the selected units merged
- class spikeinterface.curation.SplitUnitSorting(parent_sorting, split_unit_id, indices_list, new_unit_ids=None, properties_policy='keep')¶
Class that handles spliting of a unit. It creates a new Sorting object linked to parent_sorting.
- Parameters
- parent_sorting: Recording
The recording object
- parent_unit_id: int
Unit id of the unit to split
- indices_list: list
A list of index arrays selecting the spikes to split in each segment. Each array can contain more than 2 indices (e.g. for splitting in 3 or more units) and it should be the same length as the spike train (for each segment)
- new_unit_ids: int
Unit ids of the new units to be created.
- properties_policy: “keep” | “remove”, default: “keep”
- Policy used to propagate properties. If “keep” the properties will be passed to the new units
(if the units_to_merge have the same value). If “remove” the new units will have an empty value for all the properties of the new unit.
- Returns
- ——-
- sorting: Sorting
Sorting object with the selected units split
- spikeinterface.curation.get_potential_auto_merge(waveform_extractor, minimum_spikes=1000, maximum_distance_um=150.0, peak_sign='neg', bin_ms=0.25, window_ms=100.0, corr_diff_thresh=0.16, template_diff_thresh=0.25, censored_period_ms=0.3, refractory_period_ms=1.0, sigma_smooth_ms=0.6, contamination_threshold=0.2, adaptative_window_threshold=0.5, censor_correlograms_ms: float = 0.15, num_channels=5, num_shift=5, firing_contamination_balance=1.5, extra_outputs=False, steps=None)¶
Algorithm to find and check potential merges between units.
This is taken from lussac version 1 done by Aurelien Wyngaard and Victor Llobet. https://github.com/BarbourLab/lussac/blob/v1.0.0/postprocessing/merge_units.py
The merges are proposed when the following criteria are met:
STEP 1: enough spikes are found in each units for computing the correlogram (minimum_spikes)
STEP 2: each unit is not contaminated (by checking auto-correlogram - contamination_threshold)
STEP 3: estimated unit locations are close enough (maximum_distance_um)
STEP 4: the cross-correlograms of the two units are similar to each auto-corrleogram (corr_diff_thresh)
STEP 5: the templates of the two units are similar (template_diff_thresh)
STEP 6: the unit “quality score” is increased after the merge.
The “quality score” factors in the increase in firing rate (f) due to the merge and a possible increase in contamination (C), wheighted by a factor k (firing_contamination_balance).
\[Q = f(1 - (k + 1)C)\]- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor
- minimum_spikes: int, default: 1000
Minimum number of spikes for each unit to consider a potential merge. Enough spikes are needed to estimate the correlogram
- maximum_distance_um: float, default: 150
Minimum distance between units for considering a merge
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Peak sign used to estimate the maximum channel of a template
- bin_ms: float, default: 0.25
Bin size in ms used for computing the correlogram
- window_ms: float, default: 100
Window size in ms used for computing the correlogram
- corr_diff_thresh: float, default: 0.16
The threshold on the “correlogram distance metric” for considering a merge. It needs to be between 0 and 1
- template_diff_thresh: float, default: 0.25
The threshold on the “template distance metric” for considering a merge. It needs to be between 0 and 1
- censored_period_ms: float, default: 0.3
Used to compute the refractory period violations aka “contamination”
- refractory_period_ms: float, default: 1
Used to compute the refractory period violations aka “contamination”
- sigma_smooth_ms: float, default: 0.6
Parameters to smooth the correlogram estimation
- contamination_threshold: float, default: 0.2
Threshold for not taking in account a unit when it is too contaminated
- adaptative_window_threshold:: float, default: 0.5
Parameter to detect the window size in correlogram estimation
- censor_correlograms_ms: float, default: 0.15
The period to censor on the auto and cross-correlograms
- num_channels: int, default: 5
Number of channel to use for template similarity computation
- num_shift: int, default: 5
Number of shifts in samles to be explored for template similarity computation
- firing_contamination_balance: float, default: 1.5
Parameter to control the balance between firing rate and contamination in computing unit “quality score”
- extra_outputs: bool, default: False
If True, an additional dictionary (outs) with processed data is returned
- steps: None or list of str, default: None
which steps to run (gives flexibility to running just some steps) If None all steps are done. Pontential steps: “min_spikes”, “remove_contaminated”, “unit_positions”, “correlogram”, “template_similarity”, “check_increase_score”. Please check steps explanations above!
- Returns
- potential_merges:
A list of tuples of 2 elements. List of pairs that could be merged.
- outs:
Returned only when extra_outputs=True A dictionary that contains data for debugging and plotting.
- spikeinterface.curation.find_redundant_units(sorting, delta_time: float = 0.4, agreement_threshold=0.2, duplicate_threshold=0.8)¶
Finds redundant or duplicate units by comparing the sorting output with itself.
- Parameters
- sortingBaseSorting
The input sorting object
- delta_timefloat, default: 0.4
The time in ms to consider matching spikes
- agreement_thresholdfloat, default: 0.2
Threshold on the agreement scores to flag possible redundant/duplicate units
- duplicate_thresholdfloat, default: 0.8
Final threshold on the portion of coincident events over the number of spikes above which the unit is flagged as duplicate/redundant
- Returns
- list
The list of duplicate units
- list of 2-element lists
The list of duplicate pairs
- spikeinterface.curation.remove_redundant_units(sorting_or_waveform_extractor, align=True, unit_peak_shifts=None, delta_time=0.4, agreement_threshold=0.2, duplicate_threshold=0.8, remove_strategy='minimum_shift', peak_sign='neg', extra_outputs=False)¶
Removes redundant or duplicate units by comparing the sorting output with itself.
When a redundant pair is found, there are several strategies to choose which unit is the best:
“minimum_shift”
“highest_amplitude”
“max_spikes”
- Parameters
- sorting_or_waveform_extractorBaseSorting or WaveformExtractor
If WaveformExtractor, the spike trains can be optionally realigned using the peak shift in the template to improve the matching procedure. If BaseSorting, the spike trains are not aligned.
- alignbool, default: False
If True, spike trains are aligned (if a WaveformExtractor is used)
- delta_timefloat, default: 0.4
The time in ms to consider matching spikes
- agreement_thresholdfloat, default: 0.2
Threshold on the agreement scores to flag possible redundant/duplicate units
- duplicate_thresholdfloat, default: 0.8
Final threshold on the portion of coincident events over the number of spikes above which the unit is removed
- remove_strategy: “minimum_shift” | “highest_amplitude” | “max_spikes”, default: “minimum_shift”
Which strategy to remove one of the two duplicated units:
- “minimum_shift”: keep the unit with best peak alignment (minimum shift)
If shifts are equal then the “highest_amplitude” is used
“highest_amplitude”: keep the unit with the best amplitude on unshifted max.
“max_spikes”: keep the unit with more spikes
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Used when remove_strategy=”highest_amplitude”
- extra_outputs: bool, default: False
If True, will return the redundant pairs.
- Returns
- BaseSorting
Sorting object without redundant units
- spikeinterface.curation.remove_duplicated_spikes(sorting: BaseSorting, censored_period_ms: float = 0.3, method: str = 'keep_first') None ¶
Class to remove duplicated spikes from the spike trains. Spikes are considered duplicated if they are less than x ms apart where x is the censored period.
- Parameters
- sorting: BaseSorting
The parent sorting.
- censored_period_ms: float
The censored period to consider 2 spikes to be duplicated (in ms).
- method: “keep_first” | “keep_last” | “keep_first_iterative” | “keep_last_iterative” | “random”, default: “keep_first”
Method used to remove the duplicated spikes. If method = “random”, will randomly choose to remove the first or last spike. If method = “keep_first”, for each ISI violation, will remove the second spike. If method = “keep_last”, for each ISI violation, will remove the first spike. If method = “keep_first_iterative”, will iteratively keep the first spike and remove the following violations. If method = “keep_last_iterative”, does the same as “keep_first_iterative” but starting from the end. In the iterative methods, if there is a triplet A, B, C where (A, B) and (B, C) are in the censored period (but not (A, C)), then only B is removed. In the non iterative methods however, only one spike remains.
- Returns
- sorting_without_duplicated_spikes: Remove_DuplicatedSpikesSorting
The sorting without any duplicated spikes.
- spikeinterface.curation.remove_excess_spikes(sorting, recording)¶
Remove excess spikes from the spike trains. Excess spikes are the ones exceeding a recording number of samples, for each segment.
- Parameters
- sorting: BaseSorting
The parent sorting.
- recording: BaseRecording
The recording to use to get the number of samples.
- Returns
- sorting_without_excess_spikes: Sorting
The sorting without any excess spikes.
- spikeinterface.curation.apply_sortingview_curation(sorting, uri_or_json, exclude_labels=None, include_labels=None, skip_merge=False, verbose=False)¶
Apply curation from SortingView manual curation. First, merges (if present) are applied. Then labels are loaded and units are optionally filtered based on exclude_labels and include_labels.
- Parameters
- sortingBaseSorting
The sorting object to be curated
- uri_or_jsonstr or Path
The URI curation link from SortingView or the path to the curation json file
- exclude_labelslist, default: None
Optional list of labels to exclude (e.g. [“reject”, “noise”]). Mutually exclusive with include_labels
- include_labelslist, default: None
Optional list of labels to include (e.g. [“accept”]). Mutually exclusive with exclude_labels, by default None
- skip_mergebool, default: False
If True, merges are not applied (only labels)
- verbosebool, default: False
If True, output is verbose
- Returns
- sorting_curatedBaseSorting
The curated sorting
spikeinterface.sortingcomponents¶
Peak Localization¶
Sorting components: peak localization.
- spikeinterface.sortingcomponents.peak_localization.localize_peaks(recording, peaks, method='center_of_mass', ms_before=0.5, ms_after=0.5, **kwargs)¶
Localize peak (spike) in 2D or 3D depending the method.
- When a probe is 2D then:
X is axis 0 of the probe
Y is axis 1 of the probe
Z is orthogonal to the plane of the probe
- Parameters
- recording: RecordingExtractor
The recording extractor object.
- peaks: array
Peaks array, as returned by detect_peaks() in “compact_numpy” way.
- method: ‘center_of_mass’, ‘monopolar_triangulation’, ‘grid_convolution’
Method to use.
- arguments for method=’center_of_mass’
- radius_um: float
Radius in um for channel sparsity.
- feature: “ptp” | “mean” | “energy” | “peak_voltage”, default: “ptp”
Feature to consider for computation
- arguments for method=’monopolar_triangulation’
- radius_um: float
For channel sparsity.
- max_distance_um: float, default: 1000
Boundary for distance estimation.
- enforce_decreasebool, default: True
Enforce spatial decreasingness for PTP vectors
- feature: “ptp”, “energy”, “peak_voltage”, default: “ptp”
The available features to consider for estimating the position via monopolar triangulation are peak-to-peak amplitudes (ptp, default), energy (“energy”, as L2 norm) or voltages at the center of the waveform (peak_voltage)
- arguments for method=’grid_convolution’
- radius_um: float
Radius in um for channel sparsity.
- upsampling_um: float
Upsampling resolution for the grid of templates
- sigma_um: np.array
Spatial decays of the fake templates
- sigma_ms: float
The temporal decay of the fake templates
- margin_um: float
The margin for the grid of fake templates
- prototype: np.array
Fake waveforms for the templates. If None, generated as Gaussian
- percentile: float, default: 5
The percentage in [0, 100] of the best scalar products kept to estimate the position
- sparsity_threshold: float, default: 0.01
The sparsity threshold (in [0-1]) below which weights should be considered as 0
- **job_kwargs: keyword arguments for parallel processing:
- chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
Number of samples per chunk
- chunk_memory: str
Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
- n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
- progress_bar: bool
If True, a progress bar is printed
- mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems
- Returns
- peak_locations: ndarray
Array with estimated location for each spike. The dtype depends on the method. (“x”, “y”) or (“x”, “y”, “z”, “alpha”).
Peak Detection¶
Sorting components: peak detection.
- spikeinterface.sortingcomponents.peak_detection.detect_peaks(recording, method='by_channel', pipeline_nodes=None, gather_mode='memory', folder=None, names=None, **kwargs)¶
Peak detection based on threshold crossing in term of k x MAD.
In “by_channel” : peak are detected in each channel independently In “locally_exclusive” : a single best peak is taken from a set of neighboring channels
- Parameters
- recording: RecordingExtractor
The recording extractor object.
- pipeline_nodes: None or list[PipelineNode]
Optional additional PipelineNode need to computed just after detection time. This avoid reading the recording multiple times.
- gather_mode: str
How to gather the results: * “memory”: results are returned as in-memory numpy arrays * “npy”: results are stored to .npy files in folder
- folder: str or Path
If gather_mode is “npy”, the folder where the files are created.
- names: list
List of strings with file stems associated with returns.
- method: ‘by_channel’, ‘locally_exclusive’, ‘locally_exclusive_cl’, ‘by_channel_torch’, ‘locally_exclusive_torch’
Method to use.
- arguments for method=’by_channel’
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Sign of the peak
- detect_threshold: float, default: 5
Threshold, in median absolute deviations (MAD), to use to detect peaks
- exclude_sweep_ms: float, default: 0.1
Time, in ms, during which the peak is isolated. Exclusive param with exclude_sweep_size For example, if exclude_sweep_ms is 0.1, a peak is detected if a sample crosses the threshold, and no larger peaks are located during the 0.1ms preceding and following the peak
- noise_levels: array or None, default: None
Estimated noise levels to use, if already computed If not provide then it is estimated from a random snippet of the data
- random_chunk_kwargs: dict, default: dict()
A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None
- arguments for method=’locally_exclusive’
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Sign of the peak
- detect_threshold: float, default: 5
Threshold, in median absolute deviations (MAD), to use to detect peaks
- exclude_sweep_ms: float, default: 0.1
Time, in ms, during which the peak is isolated. Exclusive param with exclude_sweep_size For example, if exclude_sweep_ms is 0.1, a peak is detected if a sample crosses the threshold, and no larger peaks are located during the 0.1ms preceding and following the peak
- noise_levels: array or None, default: None
Estimated noise levels to use, if already computed If not provide then it is estimated from a random snippet of the data
- random_chunk_kwargs: dict, default: dict()
A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None
- radius_um: float
The radius to use to select neighbour channels for locally exclusive detection.
- arguments for method=’locally_exclusive_cl’
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Sign of the peak
- detect_threshold: float, default: 5
Threshold, in median absolute deviations (MAD), to use to detect peaks
- exclude_sweep_ms: float, default: 0.1
Time, in ms, during which the peak is isolated. Exclusive param with exclude_sweep_size For example, if exclude_sweep_ms is 0.1, a peak is detected if a sample crosses the threshold, and no larger peaks are located during the 0.1ms preceding and following the peak
- noise_levels: array or None, default: None
Estimated noise levels to use, if already computed If not provide then it is estimated from a random snippet of the data
- random_chunk_kwargs: dict, default: dict()
A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None
- radius_um: float
The radius to use to select neighbour channels for locally exclusive detection.
- opencl_context_kwargs: None or dict
kwargs to create the opencl context
- arguments for method=’by_channel_torch’
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Sign of the peak
- detect_threshold: float, default: 5
Threshold, in median absolute deviations (MAD), to use to detect peaks
- exclude_sweep_ms: float, default: 0.1
Time, in ms, during which the peak is isolated. Exclusive param with exclude_sweep_size For example, if exclude_sweep_ms is 0.1, a peak is detected if a sample crosses the threshold, and no larger peaks are located during the 0.1ms preceding and following the peak
- noise_levels: array or None, default: None
Estimated noise levels to use, if already computed. If not provide then it is estimated from a random snippet of the data
- devicestr or None, default: None
“cpu”, “cuda”, or None. If None and cuda is available, “cuda” is selected
- return_tensorbool, default: False
If True, the output is returned as a tensor, otherwise as a numpy array
- random_chunk_kwargs: dict, default: dict()
A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None.
- arguments for method=’locally_exclusive_torch’
- peak_sign: “neg” | “pos” | “both”, default: “neg”
Sign of the peak
- detect_threshold: float, default: 5
Threshold, in median absolute deviations (MAD), to use to detect peaks
- exclude_sweep_ms: float, default: 0.1
Time, in ms, during which the peak is isolated. Exclusive param with exclude_sweep_size For example, if exclude_sweep_ms is 0.1, a peak is detected if a sample crosses the threshold, and no larger peaks are located during the 0.1ms preceding and following the peak
- noise_levels: array or None, default: None
Estimated noise levels to use, if already computed If not provide then it is estimated from a random snippet of the data
- random_chunk_kwargs: dict, default: dict()
A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None
- radius_um: float
The radius to use to select neighbour channels for locally exclusive detection.
- **job_kwargs: keyword arguments for parallel processing:
- chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
Number of samples per chunk
- chunk_memory: str
Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
- n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
- progress_bar: bool
If True, a progress bar is printed
- mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems
- Returns
- peaks: array
Detected peaks.
Notes
This peak detection ported from tridesclous into spikeinterface.
Motion Correction¶
- class spikeinterface.sortingcomponents.motion_interpolation.InterpolateMotionRecording(recording, motion, temporal_bins, spatial_bins, direction=1, border_mode='remove_channels', spatial_interpolation_method='kriging', sigma_um=20.0, p=1, num_closest=3)¶
Recording that corrects motion on-the-fly given a motion vector estimation (rigid or non-rigid). This internally applies a spatial interpolation on the original traces after reversing the motion. estimate_motion() must be called before this to estimate the motion vector.
- Parameters
- recording: Recording
The parent recording.
- motion: np.array 2D
The motion signal obtained with estimate_motion() motion.shape[0] must correspond to temporal_bins.shape[0] motion.shape[1] is 1 when “rigid” motion and spatial_bins.shape[0] when “non-rigid”
- temporal_bins: np.array
Temporal bins in second.
- spatial_bins: None or np.array
Bins for non-rigid motion. If None, rigid motion is used
- direction: 0 | 1 | 2, default: 1
Dimension along which channel_locations are shifted (0 - x, 1 - y, 2 - z)
- spatial_interpolation_method: “kriging” | “idw” | “nearest”, default: “kriging”
The spatial interpolation method used to interpolate the channel locations. See spikeinterface.preprocessing.get_spatial_interpolation_kernel() for more details. Choice of the method:
“kriging” : the same one used in kilosort
“idw” : inverse distance weighted
“nearest” : use neareast channel
- sigma_um: float, default: 20.0
Used in the “kriging” formula
- p: int, default: 1
Used in the “kriging” formula
- num_closest: int, default: 3
Number of closest channels used by “idw” method for interpolation.
- border_mode: “remove_channels” | “force_extrapolate” | “force_zeros”, default: “remove_channels”
Control how channels are handled on border:
“remove_channels”: remove channels on the border, the recording has less channels
“force_extrapolate”: keep all channel and force extrapolation (can lead to strange signal)
“force_zeros”: keep all channel but set zeros when outside (force_extrapolate=False)
- Returns
- corrected_recording: InterpolateMotionRecording
Recording after motion correction
Clustering¶
- spikeinterface.sortingcomponents.clustering.find_cluster_from_peaks(recording, peaks, method='stupid', method_kwargs={}, extra_outputs=False, **job_kwargs)¶
Find cluster from peaks.
- Parameters
- recording: RecordingExtractor
The recording extractor object
- peaks: WaveformExtractor
The waveform extractor
- method: str
Which method to use (“stupid” | “XXXX”)
- method_kwargs: dict, default: dict()
Keyword arguments for the chosen method
- extra_outputs: bool, default: False
If True then debug is also return
- **job_kwargs: keyword arguments for parallel processing:
- chunk_duration or chunk_size or chunk_memory or total_memory
- chunk_size: int
Number of samples per chunk
- chunk_memory: str
Memory usage for each job (e.g. “100M”, “1G”)
- total_memory: str
Total memory usage (e.g. “500M”, “2G”)
- chunk_durationstr or float or None
Chunk duration in s if float or with units if str (e.g. “1s”, “500ms”)
- n_jobs: int
Number of jobs to use. With -1 the number of jobs is the same as number of cores
- progress_bar: bool
If True, a progress bar is printed
- mp_context: “fork” | “spawn” | None, default: None
Context for multiprocessing. It can be None, “fork” or “spawn”. Note that “fork” is only safely available on LINUX systems
- Returns
- labels: ndarray of int
possible clusters list
- peak_labels: array of int
peak_labels.shape[0] == peaks.shape[0]
Template Matching¶
- spikeinterface.sortingcomponents.matching.find_spikes_from_templates(recording, method='naive', method_kwargs={}, extra_outputs=False, **job_kwargs)¶
Find spike from a recording from given templates.
- Parameters
- recording: RecordingExtractor
The recording extractor object
- method: “naive” | “tridesclous” | “circus” | “circus-omp” | “wobble”
Which method to use for template matching
- method_kwargs: dict, optional
Keyword arguments for the chosen method
- extra_outputs: bool
If True then method_kwargs is also returned
- job_kwargs: dict
Parameters for ChunkRecordingExecutor
- Returns
- spikes: ndarray
Spikes found from templates.
- method_kwargs:
Optionaly returns for debug purpose.
Notes
For all methods except “wobble”, templates are represented as a WaveformExtractor in method_kwargs so statistics can be extracted. For “wobble” templates are represented as a numpy.ndarray.