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:

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 [Preprint]. https://doi.org/10.1101/782029

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: