meegkit.detrend#

Robust detrending.

Functions

detrend(x, order[, w, basis, threshold, ...])

Robustly remove trend.

reduce_ringing(X, samples[, order, ...])

Subtract filter impulse response from signal at given samples.

regress(x, r[, w, threshold, return_mean])

Weighted regression.
meegkit.detrend.create_masked_weight(x, events, tmin, tmax, sfreq)#

Output a weight matrix for trial-masked detrending.

Creates a (n_times, n_channels) weight matrix with masked periods (value of zero) in order to mask the trials of interest during detrending [1].

Parameters:

  • x (ndarray, shape=(n_times, n_channels)) – Raw data matrix.

  • events (ndarray, shape=(n_events)) – Time samples of the events.

  • tmin (float) – Start time before event (in seconds).

  • tmax (float) – End time after event (in seconds).

  • sfreq (float) – The sampling frequency of the data.

Returns:

weights – Weight for each channel and each time sample (zero is masked).

Return type:

ndarray, shape=(n_times, n_channels)

References

[1]

van Driel, J., Olivers, C. N., & Fahrenfort, J. J. (2021). High-pass filtering artifacts in multivariate classification of neural time series data. Journal of Neuroscience Methods, 352, 109080.

meegkit.detrend.detrend(x, order, w=None, basis='polynomials', threshold=3, n_iter=4, show=False)#

Robustly remove trend.

The data are fit to the basis using weighted least squares. The weight is updated by setting samples for which the residual is greater than ‘thresh’ times its std to zero, and the fit is repeated at most ‘niter’-1 times.

The choice of order (and basis) determines what complexity of the trend that can be removed. It may be useful to first detrend with a low order to avoid fitting outliers, and then increase the order.

Parameters:

  • x (array, shape=(n_times, n_channels[, n_trials])) – Raw data matrix.

  • order (int) – Order of polynomial or number of sin/cosine pairs

  • w (weights, shape=(n_times[, n_channels][, n_trials])) – Sample weights for the regression. If a single channel is provided, the same weights are applied to all channels.

  • basis ({'polynomials', 'sinusoids'} | ndarray) – Basis for regression.

  • threshold (int) – Threshold for outliers, in number of standard deviations (default=3).

  • niter (int) – Number of iterations (default=5).

Returns:

  • y (array, shape=(n_times, n_channels[, n_trials])) – Detrended data.

  • w (array, shape=(n_times[, n_channels][, n_trials])) – Updated weights.

  • r (array, shape=(n_times * ntrials, order)) – Basis matrix used.

Examples

Fit a linear trend, ignoring samples > 3*sd from it, and remove it: >> y = detrend(x, 1)

Fit/remove polynomial (order=5) with initial weighting w, threshold = 4*sd: >> y = detrend(x, 5, w, ‘polynomial’, 4)

Fit/remove linear then 3rd order polynomial trend: >> [y, w]= detrend(x, 1) >> [yy, ww] = detrend(y, 3)

meegkit.detrend.reduce_ringing(X, samples, order=10, n_samples=100, extra=50, threshold=3, show=False)#

Subtract filter impulse response from signal at given samples.

Parameters:

  • X (ndarray, shape=(n_times, n_chans[, n_trials])) – Data containing ringing artifacts.

  • samples (list of ints) – Sample indices where to find ringing artifacts.

  • order (int) – Order of polynomial trend (default=10).

  • 100 (n_samples =) – Number of samples over which to estimate impulse response (default=100).

  • extra (int) – Samples before stimulus to anchor trend (default=50).

  • threshold (float) – Threshold for robust detrending (default=3).

Returns:

y – Clean data.

Return type:

ndarray, shape=(n_times, n_chans[, n_trials])

meegkit.detrend.regress(x, r, w=None, threshold=1e-07, return_mean=False)#

Weighted regression.

Parameters:

  • x (array, shape=(n_times, n_chans)) – Data.

  • r (array, shape=(n_times, n_chans)) – Regressor.

  • w (array, shape=(n_times, n_chans)) – Weight to apply to x. w is either a matrix of same size as x, or a column vector to be applied to each column of x.

  • threshold (float) – PCA threshold (default=1e-7). Dimensions of x with eigenvalue lower than this value will be discarded.

  • return_mean (bool) – If True, also return the signal mean prior to regression.

Returns:

  • b (array, shape=(n_chans, n_chans)) – Regression matrix (apply to r to approximate x).

  • z (array, shape=(n_times, n_chans)) – Regression (r @ b).