Utility Functions#

This section documents the utility functions and modules for data comparison, channel operations, visualization, and other helper functions.

Data Comparison#

eegprep.eeg_compare(eeg1, eeg2, verbose_level=0, trigger_error=False)

Compare two EEG-like structures (or arrays) and return a difference summary.

Per-field findings are emitted through this module’s logger; the returned value is the human-readable summary string callers print or store.

Parameters#

eeg1dict, object, or numpy.ndarray: First EEG structure (or array) to compare.
eeg2dict, object, or numpy.ndarray: Second EEG structure (or array) to compare.
verbose_levelint, optional: Level of verbosity for logged output. Default 0.
trigger_errorbool, optional: Whether to raise a ValueError if differences are found. Default False.

Returns#

str: A summary describing the differences found, or that all fields match.

Channel Operations#

eegprep.eeg_decodechan(chanlocs, chanstr, field='labels', ignoremissing=False)

Resolve channel identifiers to 0-based indices and labels.

Supports:

chanlocs as a list-like of dicts, or a dict with key “chanlocs”.
chanstr as an iterable of strings and/or integers.
Matching on the specified field (e.g., “labels” or “type”).
Numeric 0-based indices as input (returned directly after validation).
Empty chanlocs with purely numeric input (indices passthrough).

Parameters#

chanlocslist of dict or dict: Channel locations or {‘chanlocs’: […]}
chanstriterable: Channel identifiers (strings or ints)
fieldstr, optional: Field to match on (default ‘labels’)
ignoremissingbool, optional: Ignore missing channels (default False)

Returns#

chanindslist: Sorted list of 0-based indices
chanlist_outlist: List of labels/types from chanlocs for those indices or indices if empty

Visualization#

eegprep.topoplot(datavector, chan_locs, **kwargs)

Plot a 2D topographic map of EEG data.

Parameters#

datavectorarray-like

Values to plot at each channel location.

chan_locslist of dict

Channel location structures with ‘labels’, ‘theta’, and ‘radius’ fields.

kwargsdict

Additional keyword arguments for customization:

noplot : str or tuple, default ‘off’
plotgrid : str, default ‘off’
plotchans : list, default []
ELECTRODES : str, default ‘on’
intrad : float, default nan
plotrad : float, default nan
headrad : float, default 0.5
method : str, default ‘rbf’

Returns#

handlematplotlib.figure.Figure or None: Figure handle if plotted, None otherwise.

Utility Modules#

Coordinate Utilities#

Coordinate system utilities.

eegprep.plugins.EEG_BIDS.coords.coords_to_mm(coords, unit)

Convert the given coordinates array from the specified unit to millimeters.

Parameters:

coords (ndarray)
unit (str)

Return type:

ndarray

eegprep.plugins.EEG_BIDS.coords.coords_any_to_RAS(coords, x, y, z)

Convert the given coordinates (Nx3 array) to the RAS (Right-Anterior-Superior) system.

Parameters#

coordsnp.ndarray: Nx3 array of coordinates to convert.
xstr: Orientation of the X axis relative to the head in coords, e.g., ‘front’.
ystr: Orientation of the Y axis relative to the head in coords, e.g., ‘left’.
zstr: Orientation of the Z axis relative to the head in coords, e.g., ‘up’.

Returns#

coordsnp.ndarray: The transformed coordinates.

Parameters:

coords (ndarray)
x (str)
y (str)
z (str)

Return type:

ndarray

eegprep.plugins.EEG_BIDS.coords.coords_RAS_to_ALS(coords)

Convert coordinates from RAS (Right-Anterior-Superior) to ALS (Anterior-Left-Superior) convention.

Parameters:: coords (ndarray)
Return type:: ndarray

eegprep.plugins.EEG_BIDS.coords.coords_ALS_to_angular(coords)

Convert Cartesian coordinates to spherical coordinates (sph_theta, sph_phi, sph_radius) and 2d polar coordinates (polar_theta, polar_radius).

Parameters#

coordsnp.ndarray: Nx3 array of Cartesian coordinates (x, y, z).

Returns#

sph_thetanp.ndarray: Nx1 arrays of spherical coordinates.
sph_phinp.ndarray: Nx1 arrays of spherical coordinates.
sph_radiusnp.ndarray: Nx1 arrays of spherical coordinates.
polar_thetanp.ndarray: 2d polar coordinates.
polar_radiusnp.ndarray: 2d polar coordinates.

Parameters:: coords (ndarray)
Return type:: ndarray

eegprep.plugins.EEG_BIDS.coords.clear_chanloc(ch, numeric_null)

Clear a channel-location record for a single channel in-place.

Parameters:

ch (Dict[str, Any])
numeric_null (Any)

Return type:

None

eegprep.plugins.EEG_BIDS.coords.chanloc_has_coords(ch)

Check if a given channel location record has valid (Cartesian) coordinates.

Parameters:: ch (Dict[str, Any])
Return type:: bool

eegprep.plugins.EEG_BIDS.coords.chanlocs_to_coords(chanlocs)

Convert an EEGLAB chanlocs data structure to a Nx3 coordinates array.

Parameters:: chanlocs (Sequence[Dict[str, Any]])
Return type:: ndarray

Spatial Utilities#

Spatial interpolation utilities.

eegprep.plugins.clean_rawdata.private.sphericalSplineInterpolate.sphericalSplineInterpolate(src, dest, lambda_reg=1e-05, order=4, type='spline', tol=np.float64(2.220446049250313e-16))

Interpolation matrix for spherical interpolation. Python port of Jason Farquhar’s MATLAB code.

Parameters:

src (np.ndarray) – Source electrode positions [3 x N]. Assumes coordinates are in columns.
dest (np.ndarray) – Destination electrode positions [3 x M]. Assumes coordinates are in columns.
lambda_reg (float, optional) – Regularisation parameter for smoothing estimates. Defaults to 1e-5. (Renamed from ‘lambda’ to avoid clash with Python keyword).
order (int, optional) – Order of the polynomial interpolation to use. Defaults to 4.
type (str, optional) – Interpolation type, one of ‘spline’ or ‘slap’. Defaults to ‘spline’. ‘spline’ -> spherical Spline ‘slap’ -> surface Laplician (aka CSD)
tol (float, optional) – Tolerance for the Legendre polynomial approximation convergence. Defaults to machine epsilon for float.

Returns#

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
W: [M x N] linear mapping matrix between old and new coords. Gss: [N x N] interpolation matrix between source points. Gds: [M x N] interpolation matrix from source to destination points. Hds: [M x N] SLAP interpolation matrix from source to destination points.

Notes#

Based upon the paper: Perrin, F., Pernier, J., Bertrand, O., & Echallier, J. F. (1989). Spherical splines for scalp potential and current density mapping. Electroencephalography and clinical neurophysiology, 72(2), 184-187.

Original MATLAB Copyright Notice:: Copyright 2009- by Jason D.R. Farquhar (jdrf@zepler.org) Permission is granted for anyone to copy, use, or modify this software and accompanying documents, provided this copyright notice is retained, and note is made of any changes that have been made. This software and documents are distributed without any warranty, express or implied.

Statistical Utilities#

Statistical utilities for EEG data.

eegprep.plugins.clean_rawdata.private.stats.fit_eeg_distribution(X, min_clean_fraction=None, max_dropout_fraction=None, quants=None, step_sizes=None, beta=None)

Estimate the mean and standard deviation of clean EEG from contaminated data.

Mu,Sigma,Alpha,Beta = fit_eeg_distribution(X,MinCleanFraction,MaxDropoutFraction,FitQuantiles,StepSizes,ShapeRange)

This function estimates the mean and standard deviation of clean EEG from a sample of amplitude values (that have preferably been computed over short windows) that may include a large fraction of contaminated samples. The clean EEG is assumed to represent a generalized Gaussian component in a mixture with near-arbitrary artifact components. By default, at least 25% (MinCleanFraction) of the data must be clean EEG, and the rest can be contaminated. No more than 10% (MaxDropoutFraction) of the data is allowed to come from contaminations that cause lower-than-EEG amplitudes (e.g., sensor unplugged). There are no restrictions on artifacts causing larger-than-EEG amplitudes, i.e., virtually anything is handled (with the exception of a very unlikely type of distribution that combines with the clean EEG samples into a larger symmetric generalized Gaussian peak and thereby “fools” the estimator). The default parameters should be fine for a wide range of settings but may be adapted to accomodate special circumstances.

The method works by fitting a truncated generalized Gaussian whose parameters are constrained by MinCleanFraction, MaxDropoutFraction, FitQuantiles, and ShapeRange. The alpha and beta parameters of the gen. Gaussian are also returned. The fit is performed by a grid search that always finds a close-to-optimal solution if the above assumptions are fulfilled.

Parameters:

X – array-like Vector of amplitude values of EEG, possible containing artifacts (coming from single samples or windowed averages).
min_clean_fraction – float, optional Minimum fraction of values in X that needs to be clean (default: 0.25).
max_dropout_fraction – float, optional Maximum fraction of values in X that can be subject to signal dropouts (e.g., sensor unplugged) (default: 0.1).
quants – tuple or list, optional Quantile range [lower,upper] of the truncated generalized Gaussian distribution that shall be fit to the EEG contents (default: (0.022, 0.6)).
step_sizes – tuple or list, optional Step size of the grid search; the first value is the stepping of the lower bound (which essentially steps over any dropout samples), and the second value is the stepping over possible scales (i.e., clean-data quantiles) (default: (0.01, 0.01)).
beta – array-like, optional Range that the clean EEG distribution’s shape parameter beta may take (default: np.arange(1.7, 3.6, 0.15)).

Returns#

tuple:

mu (float): estimated mean of the clean EEG distribution.

sig (float): estimated standard deviation of the clean EEG distribution.

alpha (float): estimated scale parameter of the generalized Gaussian
clean EEG distribution.

beta (float): estimated shape parameter of the generalized Gaussian
clean EEG distribution.

eegprep.plugins.clean_rawdata.private.stats.geometric_median(X, tol=1e-05, y=None, max_iter=500)

Calculate the geometric median for a set of observations.

This is the mean under a Laplacian noise distribution, using Weiszfeld’s algorithm.

Parameters:

X (np.ndarray) – The data, expected shape (n_samples, n_features).
tol (float, optional) – Tolerance for convergence. Defaults to 1.e-5.
y (np.ndarray, optional) – Initial value for the geometric median. Defaults to the coordinate-wise median of X.
max_iter (int, optional) – Maximum number of iterations. Defaults to 500.

Returns#

np.ndarray: The geometric median of X, shape (n_features,).

eegprep.plugins.clean_rawdata.private.stats.block_geometric_median(X, blocksize=1, tol=1e-05, y=None, max_iter=500)

Calculate a blockwise geometric median.

Faster and less memory-intensive than the regular geom_median function. This statistic is not robust to artifacts that persist over a duration that is significantly shorter than the blocksize.

Parameters:

X (np.ndarray) – The data (#observations x #variables).
blocksize (int, optional) – The number of successive samples over which a regular mean should be taken. Defaults to 1.
tol (float, optional) – Tolerance for convergence. Defaults to 1.e-5.
y (np.ndarray, optional) – Initial value for the geometric median. Defaults to the coordinate-wise median of X.
max_iter (int, optional) – Maximum number of iterations. Defaults to 500.

Returns#

np.ndarray: Geometric median over X, scaled by 1/blocksize.

Notes#

This function is noticeably faster if the length of the data is divisible by the block size.

eegprep.plugins.clean_rawdata.private.stats.mad(X, axis=0, keepdims=False)

Calculate the median absolute deviation from the median along a given axis.

Parameters:

X – array-like Input data array.
axis – int, optional Axis along which to compute the median absolute deviation. Default is 0.
keepdims – bool, optional If True, the result will have the same dimensions as X, but with the specified axis having size 1. Default is False.

Returns#

array-like:
Median absolute deviation of the input data.

Signal Processing Utilities#

Signal processing utilities.

eegprep.plugins.clean_rawdata.private.sigproc.filtfilt_fast(b, a, x)

Apply a zero-phase forward-backward filter to a signal using FFTs.

This is a drop-in replacement for scipy.signal.filtfilt() that is considerably faster for long signals.

Parameters#

bnp.ndarray: Numerator coefficients of the filter.
afloat or np.ndarray: Must be 1.
xnp.ndarray: Signal to filter (1-D array).

Returns#

np.ndarray: The filtered signal.

Parameters:

Return type:

ndarray

eegprep.plugins.clean_rawdata.private.sigproc.moving_average(X, *, N=3, axis=-1, Z=None, inplace=False, transform=None, init=None)

Lfilter()-style moving average function with support for state.

Parameters#

Xarray_like: Signal to filter.
Nint, optional: Number of points that shall be averaged (window length).
axisint, optional: Axis along which to filter; note: IF you use transform, and if it inserts additional axes, the same index needs to work before and after the transform (e.g., you can use negative indices to count from the end if needed to accomplish that).
Zobject, optional: Initial state (or None).
inplacebool, optional: Whether to overwrite the input.
transformcallable, optional: Optionally a transformation to apply to each input sample, usually to generate higher-dimensional data; one use case is to calculate covariance matrices per sample on the fly instead of having the moving average to apply to and buffer potentially very large covariance data (by passing lambda x: x[:, None] @ x[None, :]).
initint or None, optional: How to behave on the first N samples of input; if set to 0, this will behave as if the data were pre-pended by zeros; if set to None, this will average the (fewer, noisier) samples in the buffer.

Returns#

X’array_like: Filtered signal.
Z’object: Final state (can be passed into the next call to moving_average()).

License#

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.