spike_detection_pipeline#

class spidet.spike_detection.spike_detection_pipeline.SpikeDetectionPipeline(file_path: str, results_dir: str | None = None, save_nmf_matrices: bool = False, sparseness: float = 0.0, bad_times: ndarray[dtype[float]] | None = None, nmf_runs: int = 100, rank_range: Tuple[int, int] = (2, 5), line_length_freq: int = 50)[source]#

This class builds the heart of the automatic-spike-detection library. It provides an end-to-end pipeline that takes in a path to a file containing an iEEG recording and returns periods of abnormal activity. The pipeline is a multistep process that includes

reading the data from the provided file (supported file formats are .h5, .edf, .fif) and transforming the data into a list of Trace objects,

performing the necessary preprocessing steps by means of the preprocessing module,

applying the line-length transformation using the line_length module,

performing Nonnegative Matrix Factorization to extract the most discriminating metappatterns, done by the nmf module and

computing periods of abnormal activity by means of the thresholding module.

Parameters:

file_path: str: Path to the file containing the iEEG data.
results_dir: str: Path to the directory where the folder containing the results of the spike detection run should be saved. If None, the results folder will be saved in the user’s home directory. By default, the results contain the metrics representing the computation of the optimal rank and two plots for both the basis functions and the consensus matrices of the different ranks.
save_nmf_matrices: bool: If True, in addition to the results saved by default, the W matrix containing the basis functions and the H matrix containing the activation functions for each rank, the line-length transformed data and the standard deviation of the line length are saved.
sparseness: float: A floating point number \(\in [0, 1]\). If this parameter is non-zero, nonnegative matrix factorization is run with sparseness constraints.
bad_times: numpy.ndarray[numpy.dtype[float]]: An optional N x 2 numpy array containing periods that must be excluded before applying the line-length transformation. Each of th N rows in the array represents a period to be excluded, defined by the start and end indices of the period in the original iEEG data. The defined periods will be set to zero with the transitions being smoothed by applying a hanning window to prevent spurious patterns.
nmf_runs: int: The number of nonnegative matrix factorization runs performed for each rank, default is 100.
rank_range: Tuple[int, int]: A tuple defining the range of ranks for which to perform the nonnegative matrix factorization, default is (2, 5).
line_length_freq: int: The sampling frequency of the line-length transformed data, default is 50 hz.

run(channel_paths: List[str] | None = None, bipolar_reference: bool = False, exclude: List[str] | None = None, leads: List[str] | None = None, notch_freq: int = 50, resampling_freq: int = 500, bandpass_cutoff_low: int = 0.1, bandpass_cutoff_high: int = 200, line_length_freq: int = 50, line_length_window: int = 40) → Tuple[List[BasisFunction], List[ActivationFunction]][source]#

This method triggers a complete run of the spike detection pipline with the arguments passed to the SpikeDetectionPipeline at initialization.

Parameters:

channel_paths: List[str]: A list of paths to the traces to be included within an h5 file. This is only necessary in the case of h5 files.
bipolar_reference: bool: If True, the bipolar references of the included channels will be computed. If channels already are in bipolar form this needs to be False.
exclude: List[str]: A list of channel names that need to be excluded. This only applies in the case of .edf and .fif files.
leads: List[str]: A list of the leads included. Only necessary if bipolar_reference is True, otherwise can be None.
notch_freq: int, optional, default = 50: The frequency of the notch filter; data will be notch-filtered at this frequency and at the corresponding harmonics, e.g. notch_freq = 50 Hz -> harmonics = [50, 100, 150, etc.]
resampling_freq: int, optional, default = 500: The frequency to resample the data after filtering and rescaling
bandpass_cutoff_low: int, optional, default = 0.1: Cut-off frequency at the lower end of the passband of the bandpass filter.
bandpass_cutoff_high: int, optional, default = 200: Cut-off frequency at the higher end of the passband of the bandpass filter.
line_length_freq: int, optional, default = 50: Sampling frequency of the line-length transformed data
line_length_window: int, optional, default = 40: Window length used to for the line-length operation (in milliseconds).

Returns:

Tuple[List[BasisFunction], List[ActivationFunction]]: Two lists containing the BasisFunction and ActivationFunction, where each activation function contains the corresponding detected events.