pyeeg.models.TRFEstimator

class pyeeg.models.TRFEstimator(times=(0.0,), tmin=None, tmax=None, srate=1.0, alpha=None, fit_intercept=True, verbose=False, quadratic_reg=None, block_order='lags', loss='linear', robust_solver='irls', robust_sigma=None, robust_max_iter=20, robust_tol=1e-06, robust_damping=1.0, robust_inner_solver='svd', robust_inner_tol=1e-08, robust_inner_max_iter=None, feature_alphas=None, solver=None, cache_lagged=False, max_cache_size=1000000000)

Temporal Response Function (TRF) Estimator Class.

This class allows to estimate TRF from a set of feature signals and an EEG dataset in the same fashion than mne.decoding.ReceptiveFieldEstimator does in MNE. However, an arbitrary set of lags can be given. Namely, it can be used in two ways

  • calling with tmin and tmax arguments will compute lags spanning from tmin to tmax.

  • with the times argument, one can request an arbitrary set of time lags at which to compute the coefficients of the TRF.

Parameters:

  • times (tuple of float) – Time-lags (in seconds) at which to compute the TRF coefficients. Used when tmin and tmax are not given.

  • tmin (float or None) – Minimum lag in seconds. When both tmin and tmax are given, lags span from tmin to tmax.

  • tmax (float or None) – Maximum lag in seconds.

  • srate (float) – Sampling rate.

  • alpha (float, 1d-array, or None) – Regularisation strength. An array fits several regularisation values at once (requires pyeeg.solvers.SVDSolver; see xfit()). When quadratic_reg is given, alpha scales the quadratic matrix and defaults to 1; otherwise None means unregularized (plain least squares).

  • fit_intercept (bool) – Whether a column of ones should be added to the design matrix to fit an intercept.

  • verbose (bool) – Whether to log progress information.

  • quadratic_reg (str, ndarray, or None) – Quadratic regularization: a 'smoothness'/'laplacian' string or a custom matrix. Replaces the L2 (alpha) regularization; see _build_quadratic_regularizer().

  • block_order (str) – Ordering of the lagged columns: 'lags' or 'features'.

  • loss (str) – Loss function: 'linear' (ordinary least squares / ridge) or 'cauchy' (robust fitting).

  • robust_solver (str) – Solver used for robust fitting: 'irls' (default) or 'least_squares' (SciPy nonlinear Cauchy solver).

  • robust_sigma (float or None) – Scale parameter of the Cauchy loss; when None (default), the scale is estimated from the data (median absolute deviation).

  • robust_max_iter (int) – Maximum number of iterations for the IRLS robust solver.

  • robust_tol (float) – Convergence tolerance for the IRLS robust solver.

  • robust_damping (float) – Damping factor in (0, 1] applied to the IRLS updates.

  • robust_inner_solver (str) – Inner linear solver used by IRLS: 'svd' or 'cg'.

  • robust_inner_tol (float) – Tolerance for the inner linear solver.

  • robust_inner_max_iter (int or None) – Maximum number of iterations for the inner solver.

  • feature_alphas (1d-array or None) – Optional per-feature ridge strengths; each value is repeated over all lags following block_order. Cannot be combined with quadratic_reg or with an alpha path.

  • solver (Solver or None) – Optional pyeeg.solvers.Solver instance for dependency injection; when None the estimator auto-selects the solver based on loss, alpha, and quadratic_reg.

  • cache_lagged (bool) – Whether to cache the lagged design matrix so repeated fit() calls with the same X skip re-lagging. See clear_cache().

  • max_cache_size (int) – Maximum size (in bytes) of the lagged-X cache.

lags

Array of int, corresponding to lag in samples at which the TRF coefficients are computed

Type:

1d-array

times

Array of float, corresponding to lag in seconds at which the TRF coefficients are computed

Type:

1d-array

srate

Sampling rate

Type:

float

use_regularisation

Whether or not regularisation is used to compute the TRF

Type:

bool

feature_alphas

Optional per-feature ridge strengths. Each value is repeated over all lags, following block_order.

Type:

1d-array or None

fit_intercept

Whether a column of ones should be added to the design matrix to fit an intercept

Type:

bool

fitted

True once the TRF has been fitted on EEG data

Type:

bool

intercept_

Intercepts

Type:

1d array (nchans, )

coef_

Actual TRF coefficients

Type:

ndarray (nlags, nfeats, nchans)

tvals_

t-statistics in the flattened canonical ordering of coef_.

Type:

ndarray (nlags * nfeats, nchans)

pvals_

Two-sided p-values in the flattened canonical ordering of coef_.

Type:

ndarray (nlags * nfeats, nchans)

n_feats_

Number of word level features in TRF

Type:

int

n_chans_

Number of EEG channels in TRF

Type:

int

feat_names_

Names of each word level features

Type:

list

solver

Optional pyeeg.solvers.Solver instance for dependency injection. When None (default), the estimator auto-selects the solver based on loss, alpha, and quadratic_reg. When a solver instance is provided, it is used directly via solver.solve(X, y, alpha, M).

Type:

Solver or None

Notes

  • Attributes with a _ suffix are only set once the TRF has been fitted on EEG data (i.e. after the method TRFEstimator.fit() has been called).

  • Can fit on a list of multiple dataset, where we have a list of target Y and a single stimulus matrix of features X, then the computation is made such that the coefficients computed are similar to those obtained by concatenating all matrices

Examples

>>> trf = TRFEstimator(tmin=-0.5, tmax=1.2, srate=125)
>>> x = np.random.randn(1000, 3)
>>> y = np.random.randn(1000, 2)
>>> trf.fit(x, y, lagged=False)

See also

_svd_regress()

Methods

TRFEstimator.apply_func(func)

Apply a function over all values in coef_ and intercept_.

TRFEstimator.clear_cache()

Clear the lagged-X cache (if any).

TRFEstimator.copy()

Return a copy of the estimator.

TRFEstimator.fill_lags()

Fill the lags attributes.

TRFEstimator.fit(X, y[, lagged, drop, ...])

Fit the TRF model.

TRFEstimator.fromArray(tmin, tmax, fs)

Creates a TRF instance from a 3D array.

TRFEstimator.get_metadata_routing()

Get metadata routing of this object.

TRFEstimator.get_params([deep])

Get parameters for this estimator.

TRFEstimator.load()

Load and return a TRF instance from numpy archive file (created with trf.save)

TRFEstimator.multialpha_score(X, y)

Score the fitted multi-alpha models against held-out data.

TRFEstimator.plot([feat_id, ax, ...])

Plot the TRF of the feature requested as a butterfly plot.

TRFEstimator.plot_multialpha_scores(X, y)

Plot the score against different alphas to visualise effect of regularisation.

TRFEstimator.plot_topomap(time_lag, feat_id, ...)

Plot the topomap of the TRF at a given time-lag.

TRFEstimator.predict(X)

Compute output based on fitted coefficients and feature matrix X.

TRFEstimator.save(filename)

Save the current trf object to file.

TRFEstimator.score(Xtest, ytrue[, scoring, ...])

Compute a score of the model given true target and estimated target from Xtest.

TRFEstimator.select_best_coefs(best_index[, ...])

This method can be used to select the best set of coefficients when the TRF model has been trained with several regularisation parmaters.

TRFEstimator.set_fit_request(*[, ...])

Configure whether metadata should be requested to be passed to the fit method.

TRFEstimator.set_params(**params)

Set the parameters of this estimator.

TRFEstimator.set_score_request(*[, Xtest, ...])

Configure whether metadata should be requested to be passed to the score method.

TRFEstimator.xfit(X, y[, n_splits, lagged, ...])

Apply a cross-validation procedure to find the best regularisation parameters among the list of alphas given (ndim alpha must be == 1, and len(alphas)>1).