RidgeMVAR¶
Fit an adaptive multivariate autoregressive model (MVAR) using Tikhonov-regularized (ridge) regression.
MVAR modeling is the first step in estimating connectivity (information flow or other dependencies between signals) from EEG, usually followed by estimation of a dynamical measure such as DTF or PDC. This node accepts a multi-channel time series and, in a sliding window, fits an MVAR model at each time point; the output has the same format as the Group Lasso MVAR node and can be used interchangeably as input to any of the dynamical-measure nodes. Unlike the Group Lasso MVAR node, the solutions are dense rather than sparse (every coefficient is non-zero), and fitting is done in closed form via a single SVD or Cholesky factorization per window rather than iterative optimization. This is typically more than ten times faster for the same problem size and avoids the convergence issues iterative methods can have on difficult data. The ridge estimator is also a reasonable choice when the underlying connectivity is not actually sparse, or when the downstream measure combines information across many coefficients. Two priors are supported: the default 'ridge' prior shrinks all coefficients equally toward zero (isotropic Tikhonov), while the 'minnesota' prior applies a lag-decaying penalty so that distant lags are shrunk more strongly than recent ones. The regularization strength can be set to a fixed value, chosen per window via generalized cross-validation (GCV), or chosen once on a first 'training' call and re-used thereafter (faster in a train/test setup, and numerically stable when noise levels are comparable between training and deployment). As with the Group Lasso MVAR node, estimating connectivity on scalp channels is usually less interpretable than on source-localized activity due to volume conduction; consider using a source- localization node (e.g., sLORETA or LCMV) followed by ROI extraction as a preprocessing step. More Info... Version 1.0.0
Ports/Properties¶
data¶
Data to process.
- verbose name: Data
- default value: None
- port type: DataPort
- value type: Packet (can be None)
- data direction: INOUT
window_length¶
Length of the sliding estimation windows (in seconds). Determines how many samples go into fitting the MVAR model for a given time range. Larger values give better estimates but lower time precision, since the resulting sequence of MVAR models will change more slowly over time.
- verbose name: Sliding Window Length
- default value: 0.5
- port type: FloatPort
- value type: float (can be None)
window_step¶
Sliding window step size. The amount, in seconds, by which the sliding window is shifted to estimate the next MVAR model. Larger values give a coarser output time series but will be computed faster. Very small step sizes compared to the window length yield little benefit, since the models will be very similar between adjacent windows. The largest reasonable value is 1/2 of the window length; values larger than the window length cause input samples to be skipped entirely.
- verbose name: Sliding Window Step Size
- default value: 0.1
- port type: FloatPort
- value type: float (can be None)
window_func¶
Window function to apply to the sliding window. Optionally the data in the sliding window can be tapered using a window function to emphasize the signal in the center of the window.
- verbose name: Window Function
- default value: rect
- port type: EnumPort
- value type: str (can be None)
window_param¶
Parameter for the window function. Some of the window functions are parametric, and in those cases this parameter must be specified. Needed for kaiser, gaussian, slepian, and chebwin.
- verbose name: Window Function Parameter
- default value: None
- port type: FloatPort
- value type: float (can be None)
model_order¶
MVAR model order. This is the number of 'taps' that the MVAR model uses, i.e., how many past samples it uses to predict the current sample. A good value is in the 10-15 range. Higher orders require either more data (larger window length) or stronger regularization to estimate reliably.
- verbose name: Model Order
- default value: 10
- port type: IntPort
- value type: int (can be None)
normalize_columns¶
Normalize columns of predictor and response matrices. When enabled, columns of the delay-embedded predictor matrix X and the response matrix Y are rescaled to unit norm before fitting, which removes channel-amplitude differences from the effective regularization strength.
- verbose name: Normalize Columns
- default value: False
- port type: BoolPort
- value type: bool (can be None)
prior¶
Type of prior. With 'ridge' (the default), all AR coefficients are shrunk equally toward zero (isotropic Tikhonov). With 'minnesota', a Litterman-style lag-decaying prior is used that penalizes coefficients at higher lags more strongly than at lower lags, encoding the prior belief that recent history matters more than distant history. The decay exponent is controlled by the 'minnesota_lag_decay' port.
- verbose name: Prior Type
- default value: ridge
- port type: EnumPort
- value type: str (can be None)
minnesota_lag_decay¶
Lag decay exponent for the Minnesota prior. The prior standard deviation on the coefficient at lag l scales as 1 / l^decay; a value of 1.0 yields the classical Litterman harmonic decay, 2.0 gives quadratic decay (more aggressive shrinkage of distant lags), and 0.0 disables lag-dependent shrinkage (reducing the Minnesota prior to plain ridge). Only has an effect when the 'minnesota' prior is selected.
- verbose name: Minnesota Lag Decay
- default value: 1.0
- port type: FloatPort
- value type: float (can be None)
lambda_selection¶
How the regularization strength (lambda) is picked. With 'fixed', the value of 'lambda_reg' is used directly and no data-driven tuning is performed. With 'per_segment', generalized cross-validation (GCV) is used to pick the best lambda independently on each sliding window; this is the most robust option and is still cheap since the SVD is computed only once per window. With 'first_batch', GCV is run on each window of the first non-empty call (treated as the training set), the log-median lambda is cached, and all subsequent calls use this fixed value with a much faster Cholesky solve; this is a good choice in a train/test setup where the noise level is comparable between training and deployment.
- verbose name: Lambda Selection
- default value: per_segment
- port type: EnumPort
- value type: str (can be None)
lambda_reg¶
Fixed regularization strength. Used when 'lambda_selection' is set to 'fixed'. Larger values produce smoother, more strongly shrunk models.
- verbose name: Regularization Strength
- default value: 0.01
- port type: FloatPort
- value type: float (can be None)
lambda_min¶
Minimum lambda in the GCV search grid. Only used when 'lambda_selection' is not 'fixed'.
- verbose name: Lambda Min
- default value: 1e-06
- port type: FloatPort
- value type: float (can be None)
lambda_max¶
Maximum lambda in the GCV search grid. Only used when 'lambda_selection' is not 'fixed'.
- verbose name: Lambda Max
- default value: 1000.0
- port type: FloatPort
- value type: float (can be None)
lambda_num¶
Number of lambda values in the GCV search grid (log-spaced between lambda_min and lambda_max). Only used when 'lambda_selection' is not 'fixed'.
- verbose name: Lambda Num
- default value: 40
- port type: IntPort
- value type: int (can be None)
set_breakpoint¶
Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.
- verbose name: Set Breakpoint (Debug Only)
- default value: False
- port type: BoolPort
- value type: bool (can be None)
metadata¶
User-definable meta-data associated with the node. Usually reserved for technical purposes.
- verbose name: Metadata
- default value: {}
- port type: DictPort
- value type: dict (can be None)