meegkit.dss#

Denoising source separation.

Functions

dss0(c0, c1[, keep1, keep2, return_unmixing])

DSS base function.

dss1(X[, weights, keep1, keep2])

DSS to maximise repeatability across trials.

dss_line(X, fline, sfreq[, nremove, nfft, ...])

Apply DSS to remove power line artifacts.

dss_line_iter(data, fline, sfreq[, win_sz, ...])

Remove power line artifact iteratively.
meegkit.dss.dss0(c0, c1, keep1=None, keep2=1e-09, return_unmixing=True)#

DSS base function.

This function allows specifying arbitrary bias functions (as compared to the function:dss1, which forces the bias to be the mean over trials).

Parameters:

  • c0 (array, shape=(n_chans, n_chans)) – Baseline covariance.

  • c1 (array, shape=(n_chans, n_chans)) – Biased covariance.

  • keep1 (int | None) – Number of PCs to retain (default=None, which keeps all).

  • keep2 (float) – Ignore PCs smaller than keep2 (default=1e-9).

  • return_unmixing (bool) – If True (default), return the unmixing matrix.

Returns:

  • todss (array, shape=(n_chans, n_dss_components)) – Matrix to convert X to normalized DSS components.

  • fromdss (array, shape=(n_dss_components, n_chans)) – Matrix to transform back to original space. Only returned if return_unmixing is True.

  • pwr0 (array) – Power per component (baseline).

  • pwr1 (array) – Power per component (biased).

Notes

The data mean is NOT removed prior to processing.

meegkit.dss.dss1(X, weights=None, keep1=None, keep2=1e-12)#

DSS to maximise repeatability across trials.

Evoked-biased DSS denoising.

Parameters:

  • X (array, shape=(n_samples, n_chans, n_trials)) – Data to denoise.

  • weights (array) – Weights.

  • keep1 (int) – Number of PCs to retain in function:dss0 (default=all).

  • keep2 (float) – Ignore PCs smaller than keep2 in function:dss0 (default=1e-12).

Returns:

  • todss (array, shape=(n_dss_components, n_chans)) – Denoising matrix to convert X to normalized DSS components.

  • from (array, shape=(n_dss_components, n_chans)) – Matrix to convert DSS components back to sensor space.

  • pwr0 (array) – Power per component (raw).

  • pwr1 (array) – Power per component (averaged).

meegkit.dss.dss_line(X, fline, sfreq, nremove=1, nfft=1024, nkeep=None, blocksize=None, show=False)#

Apply DSS to remove power line artifacts.

Implements the ZapLine algorithm described in [1].

Parameters:

  • X (data, shape=(n_samples, n_chans, n_trials)) – Input data.

  • fline (float) – Line frequency (normalized to sfreq, if sfreq == 1).

  • sfreq (float) – Sampling frequency (default=1, which assymes fline is normalised).

  • nremove (int) – Number of line noise components to remove (default=1).

  • nfft (int) – FFT size (default=1024).

  • nkeep (int) – Number of components to keep in DSS (default=None).

  • blocksize (int) – If not None (default), covariance is computed on blocks of blocksize samples. This may improve performance for large datasets.

  • show (bool) – If True, show DSS results (default=False).

Returns:

  • y (array, shape=(n_samples, n_chans, n_trials)) – Denoised data.

  • artifact (array, shape=(n_samples, n_chans, n_trials)) – Artifact

Examples

Apply to X, assuming line frequency=50Hz and sampling rate=1000Hz, plot results: >>> dss_line(X, 50/1000)

Removing 4 line-dominated components: >>> dss_line(X, 50/1000, 4)

Truncating PCs beyond the 30th to avoid overfitting: >>> dss_line(X, 50/1000, 4, nkeep=30);

Return cleaned data in y, noise in yy, do not plot: >>> [y, artifact] = dss_line(X, 60/1000)

References

[1]

de Cheveigné, A. (2019). ZapLine: A simple and effective method to remove power line artifacts. NeuroImage, 116356. https://doi.org/10.1016/j.neuroimage.2019.116356

meegkit.dss.dss_line_iter(data, fline, sfreq, win_sz=10, spot_sz=2.5, nfft=512, show=False, prefix='dss_iter', n_iter_max=100)#

Remove power line artifact iteratively.

This method applies dss_line() until the artifact has been smoothed out from the spectrum.

Parameters:

  • data (data, shape=(n_samples, n_chans, n_trials)) – Input data.

  • fline (float) – Line frequency.

  • sfreq (float) – Sampling frequency.

  • win_sz (float) – Half of the width of the window around the target frequency used to fit the polynomial (default=10).

  • spot_sz (float) – Half of the width of the window around the target frequency used to remove the peak and interpolate (default=2.5).

  • nfft (int) – FFT size for the internal PSD calculation (default=512).

  • show (bool) – Produce a visual output of each iteration (default=False).

  • prefix (str) – Path and first part of the visualisation output file “{prefix}_{iteration number}.png” (default=”dss_iter”).

  • n_iter_max (int) – Maximum number of iterations (default=100).

Returns:

  • data (array, shape=(n_samples, n_chans, n_trials)) – Denoised data.

  • iterations (int) – Number of iterations.