eegprep.clean_asr#

eegprep.clean_asr(EEG, cutoff=5.0, window_len=None, step_size=None, max_dims=0.66, ref_maxbadchannels=0.075, ref_tolerances=(-3.5, 5.5), ref_wndlen=1.0, use_gpu=False, useriemannian=None, maxmem=64)#

Run the Artifact Subspace Reconstruction (ASR) method on EEG data.

This is an automated artifact rejection function that ensures that the data contains no events that have abnormally strong power; the subspaces on which those events occur are reconstructed (interpolated) based on the rest of the EEG signal during these time periods.

Parameters:

  • EEG (Dict[str, Any]) – EEG data structure. Expected fields: ‘data’ (np.ndarray): Channels x Samples matrix. ‘srate’ (float): Sampling rate in Hz. ‘nbchan’ (int): Number of channels. It’s assumed the data is zero-mean (e.g., high-pass filtered).

  • cutoff (float, optional) – Standard deviation cutoff for rejection. Data portions whose variance is larger than this threshold relative to the calibration data are considered artifactual and removed. Aggressive: 3, Default: 5, Conservative: 20.

  • window_len (float, optional) – Length of the statistics window in seconds. Should not be much longer than artifact timescale. Samples in window should be >= 1.5x channels. Default: max(0.5, 1.5 * nbchan / srate).

  • step_size (int, optional) – Step size for processing in samples. Reconstruction matrix updated every step_size samples. If None, defaults to window_len / 2 samples.

  • max_dims (float, optional) – Maximum dimensionality/fraction of dimensions to reconstruct. Default: 0.66.

  • ref_maxbadchannels (Union[float, str, np.ndarray], optional) – Parameter for automatic calibration data selection. float: Max fraction (0-1) of bad channels tolerated in a window for it to be used as calibration data. Lower is more aggressive (e.g., 0.05). Default: 0.075. ‘off’: Use all data for calibration. Assumes artifact contamination < ~30-50%. np.ndarray: Directly provides the calibration data (channels x samples).

  • ref_tolerances (Union[Tuple[float, float], str], optional) – Power tolerances (lower, upper) in SDs from robust EEG power for a channel to be considered ‘bad’ during calibration data selection. Default: (-3.5, 5.5). Use ‘off’ to disable.

  • ref_wndlen (Union[float, str], optional) – Window length in seconds for calibration data selection granularity. Default: 1.0. Use ‘off’ to disable.

  • use_gpu (bool, optional) – Whether to try using GPU (requires compatible hardware and libraries, currently ignored). Default: False.

  • useriemannian (str, optional) – Option to use a Riemannian ASR variant. Can be set to ‘calib’ to use a Riemannian estimate at calibration time; this make somewhat different statistical tradeoffs than the default, resulting in a somewhat different baseline rejection threshold; as a result it is suggested to visually check results and adjust the cutoff as needed. Default: None (disabled).

  • maxmem (Optional[int], optional) – Maximum memory in MB (passed to asr_calibrate/process, but chunking based on it is not implemented in Python port). Default: 64.

Return type:

Dict[str, Any]

Returns#

Dict[str, Any] : The EEG dictionary with the ‘data’ field containing the cleaned data.

Raises#

NotImplementedError : If useriemannian is True. ImportError : If automatic calibration data selection is needed (ref_maxbadchannels is float) but clean_windows cannot be imported. ValueError : If input arguments are invalid or calibration fails critically.

On this page