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_dict: dictionary or folder or file (json, pickle)
- 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, optional
The sample index to retrieve the duration for. For multi-segment objects, it is required, by 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, optional
The index of the segment for which the memory size should be calculated. For multi-segment objects, it is required, by 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, optional
The segment index to retrieve the number of samples for. For multi-segment objects, it is required, by 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, optional
The segment index to retrieve the number of samples for. For multi-segment objects, it is required, by 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, optional
The segment index (required for multi-segment), by default None
- 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], optional
The segment index to get traces from. If recording is multi-segment, it is required, by default None
- start_frameUnion[int, None], optional
The start frame. If None, 0 is used, by default None
- end_frameUnion[int, None], optional
The end frame. If None, the number of samples in the segment is used, by default None
- channel_idsUnion[Iterable, None], optional
The channel ids. If None, all channels are used, by default None
- orderUnion[str, None], optional
The order of the traces (“C” | “F”). If None, traces are returned as they are, by default None
- return_scaledbool, optional
If True and the recording has scaling (gain_to_uV and offset_to_uV properties), traces are scaled to uV, by default False
- cast_unsignedbool, optional
If True and the traces are unsigned, they are cast to integer and centered (an offset of (2**nbits) is subtracted), by 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, optional
The segment index (required for multi-segment), by default None
- 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
- set_times(times, segment_index=None, with_warning=True)¶
Set times for a recording segment.
- Parameters
- times1d np.array
The time vector
- segment_indexint, optional
The segment index (required for multi-segment), by default None
- with_warningbool, optional
If True, a warning is printed, by default True
- class spikeinterface.core.BaseSorting(sampling_frequency: float, unit_ids: List)¶
Abstract class representing several segment several units and relative spiketrains.
- get_all_spike_trains(outputs='unit_id')¶
Return all spike trains concatenated
- get_num_samples(segment_index=None)¶
Returns the number of samples of the associated recording for a segment.
- Parameters
- segment_indexint, optional
The segment index to retrieve the number of samples for. For multi-segment objects, it is required, by default None
- 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_num_spikes()¶
Get total number of spikes for each unit across segments.
- Returns
- dict
Dictionary with unit_ids as key and number of spikes as values
- get_total_samples()¶
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.
- 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, optional
If True, assert for each segment that all spikes are within the recording’s range. By default True.
- remove_empty_units()¶
Removes units with empty spike trains
- Returns
- BaseSorting
Sorting object with non-empty units
- remove_units(remove_unit_ids)¶
Removes a subset of units
- Parameters
- remove_unit_idsnumpy.array or list
List of unit ids to remove
- Returns
- BaseSorting
Sorting object without removed units
- select_units(unit_ids, renamed_unit_ids=None)¶
Selects a subset of units
- Parameters
- unit_idsnumpy.array or list
List of unit ids to keep
- renamed_unit_idsnumpy.array or list, optional
If given, the kept unit ids are renamed, by default None
- Returns
- BaseSorting
Sorting object with selected units
- to_spike_vector(extremum_channel_inds=None)¶
Construct a unique structured numpy vector concatenating all spikes with several fields: sample_index, unit_index, segment_index.
See also get_all_spike_trains()
- Parameters
- extremum_channel_inds: None or dict
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”)
- 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, optional
The event channel id, by default None
- segment_indexint, optional
The segment index, required for multi-segment objects, by default None
- start_timefloat, optional
The start time in seconds, by default None
- end_timefloat, optional
The end time in seconds, by default None
- 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, optional
The event channel id, by default None
- segment_indexint, optional
The segment index, required for multi-segment objects, by default None
- start_timefloat, optional
The start time in seconds, by default None
- end_timefloat, optional
The end time in seconds, by default None
- 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
If true, will accept unfiltered recording. False by default.
- 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')¶
Return templates (average waveform) for multiple units.
- Parameters
- unit_ids: list or None
Unit ids to retrieve waveforms for
- mode: str
‘average’ (default) or ‘median’ , ‘std’
- 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)¶
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)¶
Return template (average waveform).
- Parameters
- unit_id: int or str
Unit id to retrieve waveforms for
- mode: str
‘average’ (default), ‘median’ , ‘std’(standard deviation)
- sparsity: ChannelSparsity, optional
Sparsity to apply to the waveforms (if WaveformExtractor is not sparse)
- force_dense: bool (False)
Return a dense template even if the waveform extractor is sparse
- 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: str
‘average’ (default), ‘median’, ‘std’(standard deviation)
- sparsity: ChannelSparsity, optional
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
If True, spike indices of extracted waveforms are returned (default False)
- cache: bool
If True, waveforms are cached to the self._waveforms dictionary (default False)
- lazy: bool
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 (default True)
- sparsity: ChannelSparsity, optional
Sparsity to apply to the waveforms (if WaveformExtractor is not sparse)
- force_dense: bool (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, optional
Sparsity to apply to the waveforms (if WaveformExtractor is not sparse)
- Returns
- wfs: np.array
The returned waveform (num_spikes, num_samples, num_channels)
- is_extension(extension_name) 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)¶
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')) None ¶
- Precompute all template for different “modes”:
average
std
median
The results is cache in memory as 3d ndarray (nunits, nsamples, nchans) and also saved as 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
- formatstr, optional
“binary”, “zarr”, by default “binary”
- overwritebool
If True and folder exists, it is deleted, by default False
- use_relative_pathbool, optional
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, by default False
- sparsityChannelSparsity, optional
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
If true, will accept unfiltered recording. False by default.
- spikeinterface.core.extract_waveforms(recording, sorting, folder=None, mode='folder', precompute_template=('average',), ms_before=3.0, ms_after=4.0, max_spikes_per_unit=500, overwrite=False, return_scaled=True, dtype=None, sparse=False, sparsity=None, num_spikes_for_sparsity=100, 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
The folder where waveforms are cached
- mode: str
“folder” (default) or “memory”. 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
Precompute average/std/median for template. If None not precompute.
- ms_before: float
Time in ms to cut before spike peak
- ms_after: float
Time in ms to cut after spike peak
- max_spikes_per_unit: int or None
Number of spikes per unit to extract waveforms from (default 500). Use None to extract waveforms for all spikes
- overwrite: bool
If True and ‘folder’ exists, the folder is removed and waveforms are recomputed. Otherwise an error is raised.
- return_scaled: bool
If True and recording has gain_to_uV/offset_to_uV properties, waveforms are converted to uV.
- dtype: dtype or None
Dtype of the output waveforms. If None, the recording dtype is maintained.
- sparse: bool (default False)
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
The sparsity used to compute waveforms. If this is given, sparse is ignored. Default None.
- num_spikes_for_sparsity: int (default 100)
The number of spikes to use to estimate sparsity (if sparse=True).
- allow_unfiltered: bool
If true, will accept an allow_unfiltered recording. False by default.
- use_relative_path: bool
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. Default is False.
- seed: int or 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: str or None
Context for multiprocessing. It can be None (default), “fork” or “spawn”. Note that “fork” is only available on UNIX 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, optional
If True, the recording is loaded, by default True. If False, the WaveformExtractor object in recordingless mode.
- sortingBaseSorting, optional
If passed, the sorting object associated to the waveform extractor, by default None
- 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.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
The axis of the time dimension (default 0: F order)
- t_starts: None or list of float
Times in seconds of the first sample for each segment
- channel_ids: list (optional)
A list of channel ids
- file_offset: int (optional)
Number of bytes in the file to offset by during memmap instantiation.
- gain_to_uV: float or array-like (optional)
The gain to apply to the traces
- offset_to_uV: float or array-like
The offset to apply to the traces
- is_filtered: bool or 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 an internal format used in spikeinterface. It is a NpzSortingExtractor + metadata contained in a folder.
It is created with the function: sorting.save(folder=’/myfolder’)
- 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(sampling_frequency, 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
Maximum allowed difference of sampling frequencies across recordings (default 0)
- 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
If True (default), time information (t_start, time_vector) is ignored when concatenating recordings.
- sampling_frequency_max_difffloat
Maximum allowed difference of sampling frequencies across recordings (default 0)
- 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
Maximum allowed difference of sampling frequencies across sortings (default 0)
- 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
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 (default None)
- 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: Path | None = None, update_if_exists: bool = False, unlock: bool = False) Path ¶
Function to download dataset from a remote repository using datalad.
- Parameters
- repostr, optional
The repository to download the dataset from, defaults to: ‘https://gin.g-node.org/NeuralEnsemble/ephy_testing_data’
- remote_pathstr
A specific subdirectory in the repository to download (e.g. Mearec, SpikeGLX, etc) defaults to: “mearec/mearec_test_10s.h5”
- local_folderstr, optional
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, optional
Forces re-download of the dataset if it already exists, by default False
- unlockbool, optional
Use to enable the edition of the downloaded file content, by default False
- Returns
- Path
The local path to the downloaded dataset
- spikeinterface.core.write_binary_recording(recording, file_paths=None, 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
The path to the file.
- dtype: dtype
Type of the saved data. Default float32.
- add_file_extension: bool
If True (default), file the ‘.raw’ file extension is added if the file name is not a ‘raw’, ‘bin’, or ‘dat’
- byte_offset: int
Offset in bytes (default 0) to for the binary file (e.g. to write a header)
- auto_cast_uint: bool
If True (default), 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: str or None
Context for multiprocessing. It can be None (default), “fork” or “spawn”. Note that “fork” is only available on UNIX 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: str or None
Context for multiprocessing. It can be None (default), “fork” or “spawn”. Note that “fork” is only available on UNIX 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
If True, returned chunks are scaled to uV
- num_chunks_per_segment: int
Number of chunks per segment
- chunk_size: int
Size of a chunk in number of frames
- concatenated: bool (default True)
If True chunk are concatenated along time axis.
- seed: int
Random seed
- 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, optional
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: str
‘mad’ or ‘std’
- 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'))¶
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 or tuple
If str, it needs to be ‘x’, ‘y’, ‘z’. If tuple, it sorts the locations in two dimensions using lexsort. This approach is recommended since there is less ambiguity, by default (‘x’, ‘y’)
- 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: str = 'neg', mode: str = 'extremum')¶
Get amplitude per channel for each unit.
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor
- peak_sign: str
Sign of the template to compute best channels (‘neg’, ‘pos’, ‘both’)
- mode: str
‘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: str = 'neg', mode: str = 'extremum', outputs: str = 'id')¶
Compute the channel with the extremum peak for each unit.
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor
- peak_sign: str
Sign of the template to compute best channels (‘neg’, ‘pos’, ‘both’)
- mode: str
‘extremum’: max or min ‘at_index’: take value at spike index
- outputs: str
‘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: str = '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: str
Sign of the template to compute best channels (‘neg’, ‘pos’, ‘both’)
- Returns
- shifts: dict
Dictionary with unit ids as keys and shifts as values
- spikeinterface.core.get_template_extremum_amplitude(waveform_extractor, peak_sign: str = 'neg', mode: str = 'at_index')¶
Computes amplitudes on the best channel.
- Parameters
- waveform_extractor: WaveformExtractor
The waveform extractor
- peak_sign: str
Sign of the template to compute best channels (‘neg’, ‘pos’, ‘both’)
- mode: str
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
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.ChannelSparsity(mask, unit_ids, channel_ids)¶
Handle channel sparsity for a set of units.
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")
- 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
- progress_bar: bool
If True, a progress bar is printed to monitor the progress of the process
- handle_returns: bool
If True, the function can return values
- gather_func: None or callable
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
Number of jobs to be used (default 1). Use -1 to use as many jobs as number of cores
- total_memory: str
Total memory (RAM) to use (e.g. “1G”, “500M”)
- chunk_memory: str
Memory per chunk (RAM) to use (e.g. “1G”, “500M”)
- chunk_size: int or 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_contextstr or None
“fork” (default) or “spawn”. If None, the context is taken by the recording.get_preferred_mp_context(). “fork” is only available on UNIX systems.
- job_name: str
Job name
- max_threads_per_process: int or None
Limit the number of thread per process using threadpoolctl modules. This used only when n_jobs>1 If None, no limits.
- Returns
- res: list
If ‘handle_returns’ is True, the results for each chunk process
spikeinterface.extractors¶
NEO-based¶
Non-NEO-based¶
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
The absolute value for considering that the signal is saturating
- quantile_threshold: float or 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: string in [‘upper’, ‘lower’, ‘both’]
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
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: str
‘median’ (default) | ‘mean’
- dtype: str or np.dtype
The dtype of the output traces. Default “float32”
- **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: str ‘global’, ‘single’ or ‘local’
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: str ‘median’ or ‘average’
- 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
Number of chunks per segment for random chunk, by default 20
- chunk_sizeint
Size of a chunk in number for random chunk, by default 10000
- seedint
Random seed for random chunk, by default None
- verbosebool
If True, estimate LSB value is printed, by default False
- 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=None, 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:
:py:func:`~spikeinterface.sortingcomponents.peak_detection.detect_peaks’
:py:func:`~spikeinterface.sortingcomponents.peak_selection.select_peaks’
:py:func:`~spikeinterface.sortingcomponents.peak_localization.localize_peaks’
:py:func:`~spikeinterface.sortingcomponents.motion_estimation.estimate_motion’
:py:func:`~spikeinterface.sortingcomponents.motion_interpolation.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
The preset name. Default “nonrigid_accurate”.
- folder: Path str or None
If not None then intermediate motion info are saved into a folder. Default None
- output_motion_info: bool
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. Default False
- 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: str or None
Context for multiprocessing. It can be None (default), “fork” or “spawn”. Note that “fork” is only available on UNIX 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'))¶
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
If str, it needs to be ‘x’, ‘y’, ‘z’. If tuple, it sorts the locations in two dimensions using lexsort. This approach is recommended since there is less ambiguity, by default (‘x’, ‘y’)
- spikeinterface.preprocessing.detect_bad_channels(recording, method='coherence+psd', std_mad_threshold=5, psd_hf_threshold=0.02, dead_channel_threshold=-0.5, noisy_channel_threshold=1.0, outside_channel_threshold=-0.75, n_neighbors=11, nyquist_threshold=0.8, direction='y', chunk_duration_s=0.3, num_random_chunks=10, welch_window_ms=10.0, highpass_filter_cutoff=300, neighborhood_r2_threshold=0.9, neighborhood_r2_radius_um=30.0, seed=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
- methodstr
The method to be used:
coeherence+psd (default, developed by IBL)
mad
std
- std_mad_threshold (mstd)float
(method std, mad) The standard deviation/mad multiplier threshold
- psd_hf_threshold (coeherence+psd)float
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, by default 0.02
- dead_channel_threshold (coeherence+psd)float, optional
Threshold for channel coherence below which channels are labeled as dead, by default -0.5
- noisy_channel_threshold (coeherence+psd)float
Threshold for channel coherence above which channels are labeled as noisy (together with psd condition), by default 1
- outside_channel_threshold (coeherence+psd)float
Threshold for channel coherence above which channels at the edge of the recording are marked as outside of the brain, by default -0.75
- n_neighbors (coeherence+psd)int
Number of channel neighbors to compute median filter (needs to be odd), by default 11
- nyquist_threshold (coeherence+psd)float
Frequency with respect to Nyquist (Fn=1) above which the mean of the PSD is calculated and compared with psd_hf_threshold, by default 0.8
- direction (coeherence+psd): str
‘x’, ‘y’, ‘z’, the depth dimension, by default ‘y’
- highpass_filter_cutofffloat
If the recording is not filtered, the cutoff frequency of the highpass filter, by default 300
- chunk_duration_sfloat
Duration of each chunk, by default 0.3
- num_random_chunksint
Number of random chunks, by default 10
- welch_window_msfloat
Window size for the scipy.signal.welch that will be converted to nperseg, by default 10ms
- 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
The random seed to extract chunks, by default None
- 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
If float, cutoff frequency in Hz for ‘highpass’ filter type If list. band (low, high) in Hz for ‘bandpass’ filter type
- btype: str
Type of the filter (‘bandpass’, ‘highpass’)
- margin_ms: float
Margin in ms on border to avoid border effect
- filter_mode: str ‘sos’ or ‘ba’
Filter form of the filter coefficients: - second-order sections (default): ‘sos’ - numerator/denominator: ‘ba’
- coef: ndarray or None
Filter coefficients in the filter_mode form.
- dtype: dtype or 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
Number of channels to pad prior to filtering. Channels are padded with mirroring. If None, no padding is applied, by default 60
- n_channel_taperint
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, by default None
- directionstr
The direction in which the spatial filter is applied, by default “y”
- apply_agcbool
It True, Automatic Gain Control is applied, by default True
- agc_window_length_sfloat
Window in seconds to compute Hanning window for AGC, by default 0.01
- highpass_butter_orderint
Order of spatial butterworth filter, by default 3
- highpass_butter_wnfloat
Critical frequency (with respect to Nyquist) of spatial butterworth filter, by default 0.01
- 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
Distance between sequential channels in um. If None, will use the most common distance between y-axis channels, by default None
- pfloat
Exponent of the Gaussian kernel. Determines rate of decay for distance weightings, by default 1.3
- weightsnp.array
The weights to give to bad_channel_ids at interpolation. If None, weights are automatically computed, by default None
- 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
- scalar: float
Scale for the output distribution
- median: float
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
- seed: int
Random seed for reproducibility
- dtype: str or np.dtype
The dtype of the output traces. Default “float32”
- **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)
margin in ms for computation 40ms ensure a very small error when doing chunk processing
- inter_sample_shift: None or numpy array
If “inter_sample_shift” is not in recording.properties we can externaly 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
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
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: str
Determines what artifacts are replaced by. Can be one of the following:
‘zeros’ (default): 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
Determines the spacing (in ms) of reference points for the cubic spline fit if mode = ‘cubic’. Default = 1ms. 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
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
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
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
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)
Margin in ms for computations, will be used to decrease edge effects.
- dtypedtype or None
The dtype of the returned traces. If None, the dtype of the parent recording is used.
- skip_checksbool
If True, checks on sampling frequencies and cutoff filter frequencies are skipped, by default False
- 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
The dtype of the output traces. Default “float32”
- 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: str
Determines what periods are replaced by. Can be one of the following:
‘zeros’ (default): 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, 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
If None the the parent dtype is kept. For integer dtype a int_scale must be also given.
- mode: ‘global’ / ‘local’
‘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
Used for mode = ‘local’ to get the neighborhood
- apply_mean: bool
Substract or not the mean matrix M before the dot product with W.
- 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 traces value to a standard deviation of 200.
- W2d np.array
Pre-computed whitening matrix, by default None
- M1d np.array or 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: str
“median+mad” (default) or “mean+std”
- 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.
- num_chunks_per_segment: int (deulf 20)
Number of chunks to estimate the noise
- chunk_size: int (default 10000)
Size of chunks in sample
- seed: int (default None)
Eventualy a seed for reproducibility.
- Returns
- noise_levels: np.array
noise level vector.
- spikeinterface.postprocessing.compute_template_metrics(waveform_extractor, load_if_exists=False, metric_names=None, peak_sign='neg', upsampling_factor=10, sparsity=None, window_slope_ms=0.7)¶
- Compute template metrics including:
peak_to_valley
peak_trough_ratio
halfwidth
repolarization_slope
recovery_slope
- Parameters
- waveform_extractorWaveformExtractor, optional
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, optional
List of metrics to compute (see si.postprocessing.get_template_metric_names()), by default None
- peak_signstr, optional
“pos” | “neg”, by default ‘neg’
- upsampling_factorint, optional
Upsample factor, by default 10
- sparsity: dict or None
Default is sparsity=None and template metric is computed on extremum channel only. If given, the dictionary should contain a unit ids as keys and a channel id or a list of channel ids as values. For more generating a sparsity dict, see the postprocessing.compute_sparsity() function.
- window_slope_ms: float
Window in ms after the positiv peak to compute slope, by default 0.7
- Returns
- tempalte_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)
- 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
Number of components fo PCA - default 5
- mode: str
‘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
default ‘by_channel_local’
- sparsity: ChannelSparsity or None
The sparsity to apply to waveforms. If waveform_extractor is already sparse, the default sparsity will be used - default None
- whiten: bool
If True, waveforms are pre-whitened - default True
- dtype: dtype
Dtype of the pc scores - default float32
- n_jobs: int
Number of jobs used to fit the PCA model (if mode is ‘by_channel_local’) - default 1
- progress_bar: bool
If True, a progress bar is shown - default False
- tmp_folder: str
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 - default None
- 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: str
- The sign to compute maximum channel:
‘neg’
‘pos’
‘both’
- return_scaled: bool
If True and recording has gain_to_uV/offset_to_uV properties, amplitudes are converted to uV.
- outputs: str
- How the output should be returned:
‘concatenated’
‘by_unit’
- {}
- 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='center_of_mass', 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: str
‘center_of_mass’ / ‘monopolar_triangulation’ / ‘grid_convolution’
- outputs: str
‘numpy’ (default) / ‘by_unit’
- 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, 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
The left window, before a peak, in milliseconds.
- ms_afterfloat
The right window, after a peak, in milliseconds.
- methodstr
‘center_of_mass’ / ‘monopolar_triangulation’ / ‘grid_convolution’
- method_kwargsdict
Other kwargs depending on the method.
- outputsstr
‘concatenated’ (default) / ‘by_unit’
- {}
- 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
Method name (‘cosine_similarity’)
- waveform_extractor_other: WaveformExtractor, optional
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 = 100.0, bin_ms: float = 5.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, optional
The window in ms, by default 100.0.
- bin_msfloat, optional
The bin size in ms, by default 5.0.
- methodstr, optional
“auto” | “numpy” | “numba”. If _auto” and numba is installed, numba is used, by default “auto”
- 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, optional
The window in ms, by default 50.0.
- bin_msfloat, optional
The bin size in ms, by default 1.0.
- methodstr, optional
“auto” | “numpy” | “numba”. If _auto” and numba is installed, numba is used, by default “auto”
- 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
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 (default) 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¶
Low level¶
spikeinterface.comparison¶
spikeinterface.widgets¶
Legacy widgets¶
These widgets are only available with the “matplotlib” backend
spikeinterface.exporters¶
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: str
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. Default: ‘keep’
- 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 of lists
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: str (‘keep’, ‘remove’)
- 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. Default: ‘keep’
- 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: str
- 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. Default: ‘keep’
- 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
Minimum number of spikes for each unit to consider a potential merge. Enough spikes are needed to estimate the correlogram, by default 1000
- maximum_distance_um: float
Minimum distance between units for considering a merge, by default 150
- peak_sign: “neg”/”pos”/”both”
Peak sign used to estimate the maximum channel of a template, by default “neg”
- bin_ms: float
Bin size in ms used for computing the correlogram, by default 0.25
- window_ms: float
Window size in ms used for computing the correlogram, by default 100
- corr_diff_thresh: float
The threshold on the “correlogram distance metric” for considering a merge. It needs to be between 0 and 1, by default 0.16
- template_diff_thresh: float
The threshold on the “template distance metric” for considering a merge. It needs to be between 0 and 1, by default 0.25
- censored_period_ms: float
Used to compute the refractory period violations aka “contamination”, by default 0
- refractory_period_ms: float
Used to compute the refractory period violations aka “contamination”, by default 1
- sigma_smooth_ms: float
Parameters to smooth the correlogram estimation, by default 0.6
- contamination_threshold: float
Threshold for not taking in account a unit when it is too contaminated, by default 0.2
- adaptative_window_threshold:: float
Parameter to detect the window size in correlogram estimation, by default 0.5
- censor_correlograms_ms: float
The period to censor on the auto and cross-correlograms, by default 0.15 ms
- num_channels: int
Number of channel to use for template similarity computation, by default 5
- num_shift: int
Number of shifts in samles to be explored for template similarity computation, by default 5
- firing_contamination_balance: float
Parameter to control the balance between firing rate and contamination in computing unit “quality score”, by default 1.5
- extra_outputs: bool
If True, an additional dictionary (outs) with processed data is returned, by default False
- steps: None or list of str
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, optional
The time in ms to consider matching spikes, by default 0.4
- agreement_thresholdfloat, optional
Threshold on the agreement scores to flag possible redundant/duplicate units, by default 0.2
- duplicate_thresholdfloat, optional
Final threshold on the portion of coincident events over the number of spikes above which the unit is flagged as duplicate/redundant, by default 0.8
- 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, optional
If True, spike trains are aligned (if a WaveformExtractor is used), by default False
- delta_timefloat, optional
The time in ms to consider matching spikes, by default 0.4
- agreement_thresholdfloat, optional
Threshold on the agreement scores to flag possible redundant/duplicate units, by default 0.2
- duplicate_thresholdfloat, optional
Final threshold on the portion of coincident events over the number of spikes above which the unit is removed, by default 0.8
- remove_strategy: str
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: str (‘neg’, ‘pos’, ‘both’)
Used when remove_strategy=’highest_amplitude’
- extra_outputs: bool
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: str in (“keep_first”, “keep_last”, “keep_first_iterative’, ‘keep_last_iterative”, random”)
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, optional
Optional list of labels to exclude (e.g. [“reject”, “noise”]). Mutually exclusive with include_labels, by default None
- include_labelslist, optional
Optional list of labels to include (e.g. [“accept”]). Mutually exclusive with exclude_labels, by default None
- skip_mergebool, optional
If True, merges are not applied (only labels), by default False
- verbosebool, optional
If True, output is verbose, by default False
- 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’
- local_radius_um: float
Radius in um for channel sparsity.
- feature: str [‘ptp’, ‘mean’, ‘energy’, ‘peak_voltage’]
Feature to consider for computation. Default is ‘ptp’
- arguments for method=’monopolar_triangulation’
- local_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: string in [‘ptp’, ‘energy’, ‘peak_voltage’]
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’
- local_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 10)
The percentage in [0, 100] of the best scalar products kept to estimate the position
- sparsity_threshold: float (default 0.1)
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: str or None
Context for multiprocessing. It can be None (default), “fork” or “spawn”. Note that “fork” is only available on UNIX 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’
Sign of the peak.
- detect_threshold: float
Threshold, in median absolute deviations (MAD), to use to detect peaks.
- exclude_sweep_ms: float or None
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, optional
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, optional
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’
Sign of the peak.
- detect_threshold: float
Threshold, in median absolute deviations (MAD), to use to detect peaks.
- exclude_sweep_ms: float or None
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, optional
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, optional
A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None.
- local_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’
Sign of the peak.
- detect_threshold: float
Threshold, in median absolute deviations (MAD), to use to detect peaks.
- exclude_sweep_ms: float or None
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, optional
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, optional
A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None.
- local_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’
Sign of the peak.
- detect_threshold: float
Threshold, in median absolute deviations (MAD), to use to detect peaks.
- exclude_sweep_ms: float or None
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, optional
Estimated noise levels to use, if already computed. If not provide then it is estimated from a random snippet of the data.
- devicestr, optional
“cpu”, “cuda”, or None. If None and cuda is available, “cuda” is selected, by default None
- return_tensorbool, optional
If True, the output is returned as a tensor, otherwise as a numpy array, by default False
- random_chunk_kwargs: dict, optional
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’
Sign of the peak.
- detect_threshold: float
Threshold, in median absolute deviations (MAD), to use to detect peaks.
- exclude_sweep_ms: float or None
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, optional
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, optional
A dict that contain option to randomize chunk for get_noise_levels(). Only used if noise_levels is None.
- local_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: str or None
Context for multiprocessing. It can be None (default), “fork” or “spawn”. Note that “fork” is only available on UNIX 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: int (0, 1, 2)
Dimension along which channel_locations are shifted (0 - x, 1 - y, 2 - z), by default 1
- spatial_interpolation_method: str
‘kriging’ or ‘idw’ or ‘nearest’. 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 nereast channel
- sigma_um: float (default 20.)
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: str
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, optional
Keyword arguments for the chosen method
- extra_outputs: bool
If True then debug is also return
- 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: str
Which method to use (‘naive’ | ‘tridesclous’ | ‘circus’ | ‘circus-omp’ | ‘wobble’)
- 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.