clean_asr#

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. A calibration recording that is too short for the generalized-Gaussian fit still drops high-power windows; the window scale is then the median and MAD of each channel’s window RMS. EEGLAB’s fit throws in that situation and calibrates on every sample. A recording that is too short for EEGLAB’s calibration-time RMS fit, which indexes a zero window width, is still calibrated here. Fewer than two calibration RMS windows raises ValueError naming the window count, the sample count, and the window length. EEGLAB raises an error that asks for different BurstCriterionRefTolerances in that case, and when the calibration is shorter than one window. A sampling rate whose default spectral breakpoints are not monotonic raises ASRCalibrationError.

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) – Riemannian ASR variant. None or 'off' uses Euclidean ASR. 'calib' uses a Riemannian covariance estimate at calibration time and the Euclidean processor. True or 'on' runs Riemannian calibration and Riemannian processing. Default: None.

  • 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#

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