NAPLab Internal Lab Tools

Process iEEG Raw Data

naplib.naplab.process_ieeg(data_path: str, alignment_dir: str, /, *, stim_order: str | ~typing.Sequence[str] | None = None, stim_dirs: ~typing.Dict[str, str] | None = None, data_type: str = 'infer', time_range: float | ~typing.Tuple[float, float] = 0, elec_inds: ~numpy.ndarray | ~typing.Sequence[int] | None = None, elec_names: str | ~typing.Sequence[str] | None = None, rereference_grid: ~numpy.ndarray | str | None = None, rereference_method: str = 'avg', store_reference: bool = False, aud_channel: str | int = 'infer', aud_channel_infer_method: str = 'crosscorr', bands: str | ~typing.List[str] | ~typing.List[~numpy.ndarray] | ~typing.List[float] | ~numpy.ndarray = ['highgamma'], phase_amp: str = 'amp', befaft: ~typing.List | ~numpy.ndarray = [1, 1], intermediate_fs: int | None = 600, final_fs: int = 100, alignment_kwargs: dict = {}, line_noise_kwargs: dict = {}, store_sounds: bool = False, store_all_wav: bool = False, aud_fn: ~typing.Callable | ~typing.Dict[str, ~typing.Callable] | None = <function auditory_spectrogram>, aud_kwargs: dict | None = None, n_jobs: int = 1)[source]

Process raw iEEG data.

Parameters:

  • data_path (str path-like) -- String specifying data directory (for TDT) or file path for raw data file

  • alignment_dir (str path-like) -- Directory containing a set of stimulus waveforms as .wav files for alignment. This will be called 'aud'.

  • stim_order (Optional[Union[str, Sequence[str]]] path-like or sequence of strings, defaults to alignment_dir) -- If a sequence of strings, must contain the order of the stimuli names corresponding to the names of the .wav files in alignment_dir. If a file, must be either a StimOrder.mat file, or StimOrder.txt file containing the order of the stimuli names as lines in the file. If a directory, the directory must contain such a file. If None, will search for such a file within alignment_dir.

  • stim_dirs (Optional[Dict[str, str]], defaults to alignment_dir) -- If not provided, alignment_dir is assumed to contain the stimulus as well. If provided, can be used to specify additional paths from which to load sounds which will be converted to the chosen spectrotemporal features. This dict should have keys which are the name for the stimuli and values which are the path to the stimulus directory of wav files. The files within this must have the same names as those within stim_dir. E.g. {'aud': './stimuli', 'aud_spk1': './stimuli_spk1', 'aud_spk2': './stimuli_spk2'}

  • data_type (str, default='infer') -- One of {'edf', 'tdt', 'nwb', 'pkl', 'infer'}. The data type of the raw neural data to load.

  • time_range (float or (float, float), default=0) -- If a single float, the amount of time in seconds to skip at the start of the recording. If a 2-tuple (start, end), the time range of the recording to read between.

  • elec_inds (Optional[Union[np.ndarray, Sequence[int]]], default=None) -- If not None, the sorted indices of the data recording channels to keep. Important to note that this filtering is done prior to manual setting of elec_names and rereferencing, so it might affect their results.

  • elec_names (Optional[Union[str, Sequence[str]]] path-like or sequence of strings, default=None) -- Electrode labels for all data channels read from data_path. Should either be the path to a text file where each line is the label of an electrode contact, or a list of strings where each element is the label of an electrode contact. In both cases, the number of labels provided should match the number of data channels in data_path. If None, the labels included in the data file will be used.

  • rereference_grid (Optional[Union[np.ndarray, str]], default=None) -- If not None, then data are re-referenced based on this referencing scheme. If a numpy array, then should specify categorical groupings of which electrodes to be grouped together for re-referencing, and must be the same length as the number of electrodes in the raw data. If 'array', electrodes on the same electrode array will be grouped together (e.g., RT1, RT2, RT3). If 'subject', all electrodes will fall in the same group, which is equivalent to an NxN matrix of ones.

  • rereference_method (Optional[str], default='avg') -- If provided, must specify a method for common rereferencing, either 'avg' (average), 'pca' (PCA), or 'med' (median). Only used if rereference_grid is not None.

  • store_reference (bool, default=False) -- If True, include the reference which was subtracted from each channel in the output Data.

  • aud_channel (Union[str, int], default='infer',) -- If an int, specifies the index of the wav channel loaded from the raw recording which should be used for alignment. If 'infer', then this is inferred.

  • aud_channel_infer_method (str, default='crosscorr') -- Method for inferring aud channel used for alignment, either 'crosscorr','spectrum', or 'interactive'. 'crosscorr' computes cross correlation between stimulus waveform and each wav channel and selects maximum. 'spectrum' compares the power spectra of each wav channel to that of the stimulus and chooses the maximum (which is not very robust when using certain alignment stimuli like triggers). 'interactive' prints the name of each wav channel and asks the user to specify which one should be used for alignment. This is only an option when labels_wav are present, which is only for some data types (like edf).

  • bands (Union[str, list[str], list[np.ndarray], list[float], np.ndarray], default=['highgamma']) -- Frequency bands, specified as either strings or array-likes of length 2 giving the lower and upper bounds. For example, [[8, 13], np.array([30, 70]), 'highgamma'] is equivalent to ['theta', 'gamma', [30, 70]]. Or, can use 'raw' to specify raw neural data. Keep in mind, this will still be resampled according to the final_fs parameter.

  • phase_amp (str, default='amp') -- Whether to save the phase, amplitude, or both, of each extracted frequency band. Options are {'phase', 'amp', 'both'}.

  • befaft (Union[List, np.ndarray], default=[1,1]) -- Extra time (in sec.) to store from the neural data before the start of and after the end of each stimulus.

  • intermediate_fs (Optional[int], default=600) -- If provided downsamples the loaded raw neural data to this sampling rate before further preprocessing. If this is greater than the raw sampling rate, no resampling is done.

  • final_fs (int, default=100) -- Final sampling rate for neural data and spectrograms.

  • alignment_kwargs (dict, default={}) -- If provided, will be passed to naplib.naplab.align_stimulus_to_recording to override keyword arguments.

  • line_noise_kwargs (dict, default={}) -- Dict of kwargs to naplib.preprocessing.filter_line_noise

  • store_sounds (bool, default=False) -- If True, store raw sound wave for each stimulus in stim_dirs in the output Data.

  • store_all_wav (bool, default=False) -- If True, store all recorded wav channels that were stored by the neural recording hardware. This may include any other signals that were hooked up at the same time, such as EKG, triggers, etc.

  • aud_fn (optional callable or dict, default=naplib.features.auditory_spectrogram) -- Function(s) to be applied to each stimulus sound. If None, no audio transforms will be computed. By default, naplib.features.auditory_spectrogram will be used to compute an auditory spectrogram. If a callable f, the function f will be applied to each stimulus audio and should have signature (x: NDArray, sr: float, **kwargs) -> NDArray, where x is 1-D audio signal with shape (in_samples,) and sr is the sampling rate of the audio. The returned tensor should have shape (n_samples, n_features). If a dictionary, the keys should be strings and will be used in field names of the output Data object, and the values should be callable.

  • aud_kwargs (optional dict, default=None) -- Optional dictionary of extra arguments to be passed to aud_fn. Only used when aud_fn is a single callable. If aud_kwargs is not None and aud_fn is not a single callable, an error will be raised.

  • n_jobs (int, default=1) -- Number of CPU cores to use for the parallelizable processes. Higher number of jobs also uses higher memory, so there might even be a negative effect when working with large datasets.

Returns:

data -- Data object containing all requested fields after preprocessing.

Return type:

nl.Data

Align Stimulus Audio to Recorded Audio

naplib.naplab.align_stimulus_to_recording(rec_audio, rec_fs, stim_dict, stim_order, use_hilbert=True, confidence_threshold=0.2, t_search=120, t_start_look=0)[source]

Find the times that correspond to the start and end time of each stimulus.

Parameters:

  • rec_audio (np.ndarray of shape (time,)) -- Recorded stimulus or triggers from hospital system

  • rec_fs (int | float) -- Sampling frequncy of recorded stimulus/triggers

  • stim_dict (dict) -- Dictionary in which keys are stimulus filenames and values are a tuple of (stimulus sampling frequency: int | float, stimulus waveform: np.ndarray (time, channels))

  • stim_order (list of strings) -- List of stimulus filenames in order of presentation

  • use_hilbert (bool, default=True) -- Whether or not to apply hilbert transform to audio for alignment

  • confidence_threshold (float in range [0,1], default=0.2) -- How large the Pearson's correlation between the recorded audio and the stimulus must be to consider the stimulus sufficiently detected

  • t_search (float, default=120) -- How much time of the recorded audio to search on each try. Increase for long breaks between trials (or for started,stoped,restarted trials)

  • t_start_look (float, default=0) -- What time of the recorded audio to begin the searching process. By default, uses 0 seconds, i.e. beginning of recorded audio

Returns:

  • alignment_times (list of tuples) -- Indices of stimulus alignment in which each list element corresponds to each trial in stim_order and each tuple contains the (start_time, end_time) of each trial

  • alignment_confidence (list of floats) -- Pearson's correlation between the stimulus and recorded audio for each trial