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, reporting differences to stderr.
Parameters#
- eeg1dict or object
First EEG structure to compare.
- eeg2dict or object
Second EEG structure to compare.
- verbose_levelint, optional
Level of verbosity for output. Default 0.
- trigger_errorbool, optional
Whether to raise an error if differences are found. Default False.
Returns#
- bool
True if comparison completed (differences may still exist).
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.utils.coords.coords_to_mm(coords, unit)#
Convert the given coordinates array from the specified unit to millimeters.
- eegprep.utils.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.
- eegprep.utils.coords.coords_RAS_to_ALS(coords)#
Convert coordinates from RAS (Right-Anterior-Superior) to ALS (Anterior-Left-Superior) convention.
- eegprep.utils.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.
- eegprep.utils.coords.clear_chanloc(ch, numeric_null)#
Clear a channel-location record for a single channel in-place.
- eegprep.utils.coords.chanloc_has_coords(ch)#
Check if a given channel location record has valid (Cartesian) coordinates.
Spatial Utilities#
Spatial interpolation utilities.
- eegprep.utils.spatial.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.utils.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.utils.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.utils.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.utils.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.utils.sigproc.design_kaiser(lo, hi, atten, want_odd, use_scipy=False)#
Design a Kaiser window for a low-pass FIR filter.
- Return type:
- Parameters:
Parameters#
- lofloat
Normalized lower edge of the transition band.
- hifloat
Normalized upper edge of the transition band.
- attenfloat
Stop-band attenuation in dB (-20log10(ratio)).
- want_oddbool
Whether the desired window length shall be odd.
- use_scipybool, optional
Whether to use scipy’s kaiserord() function, which gives an approx. 2x longer window than the original function clean_rawdata.
Returns#
- np.ndarray
The Kaiser window.
- eegprep.utils.sigproc.design_fir(n, f, a, *, nfft=None, w=None, compat=True)#
Design an FIR filter using the frequency-sampling method.
The frequency response is interpolated cubically between the specified frequency points.
- Return type:
- Parameters:
Parameters#
- nint
Order of the filter.
- farray_like
Vector of frequencies at which amplitudes shall be defined (starts with 0 and goes up to 1; try to avoid too sharp transitions).
- aarray_like
Vector of amplitudes, one value per specified frequency.
- nfftint, optional
Optionally number of FFT bins to use.
- warray_like, optional
Optionally the window function to use.
- compatbool, optional
Whether to use the original MATLAB-compatible filter design (where the window is off by 1 sample).
Returns#
- np.ndarray
The filter coefficients.
- eegprep.utils.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.
- eegprep.utils.sigproc.firwsord(wintype, fs, df, dev=None)#
Estimate windowed sinc FIR filter order depending on window type and requested transition band width.
Parameters#
- wintypestr
Window type. One of ‘rectangular’, ‘hann’, ‘hamming’, ‘blackman’, or ‘kaiser’.
- fsfloat
Sampling frequency.
- dffloat
Requested transition band width.
- devfloat, optional
Maximum passband deviation/ripple (Kaiser window only).
Returns#
- mint
Estimated filter order.
- devfloat
Maximum passband deviation/ripple.
Notes#
Based on a MATLAB implementation by Andreas Widmann, University of Leipzig, 2005.
- eegprep.utils.sigproc.firws(m, f, t=None, w=None)#
Designs windowed sinc type I linear phase FIR filter.
- Return type:
- Parameters:
Parameters#
- mint
Filter order (mandatory even).
- ffloat or sequence of float
Vector or scalar of cutoff frequency/ies (-6 dB; pi rad / sample).
- tstr, optional
‘high’ for highpass, ‘stop’ for bandstop filter (default low-/bandpass).
- warray_like, optional
Vector of length m + 1 defining window (default hamming).
Returns#
- bnp.ndarray
Filter coefficients.
- afloat
Always 1 (FIR filter).
Examples#
fs = 500; cutoff = 0.5; df = 1; m = firwsord(‘hamming’, fs, df)[0] b, a = firws(m, cutoff / (fs / 2), ‘high’, scipy.signal.windows.hamming(m + 1))
Notes#
Based on a MATLAB implementation by Andreas Widmann, University of Leipzig, 2005.