← connectivity package

GroupLassoMVAR

Fit an adaptive multivariate autoregressive model (MVAR) using a group LASSO regression approach.

MVAR modeling is the first step in estimating connectivity (information flow or other dependencies between signals) from EEG, usually followed by estimation of one the available dynamical measures (e.g., dDTF or PDC). This node accepts a multi-channel time series, and will, in a sliding window, estimate an MVAR solution for each time point. Usually, the series of produced models will have a significantly lower sampling rate as the original time series (controlled by the sliding window step size). In order to adaptively fit MVAR models on short windows of data, regularization or control of the complexity of the solution is required, and this algorithm implements a type of regularization that leads to solutions that are more sparse, that is, have fewer interactions between signals than non-sparse models. This type of regularization is therefore also called sparsity, and its strength can be controlled using a parameter. This method is fundamentally capable of real-time operation if there are not too many channels in the input signal and the sampling rate is not too high. This node offers a variety of parameters that, while not changing the solution, offer tuning opportunities for expert users to reach that solution in fewer iterations and thus more rapidly. Please refer to the parameters and associated tooltips for more details. However, the baseline performance of this method with default settings should be usable for a wide range of typical EEG settings on 2 to 15 channels. While the method is relatively robust to settings and is not prone to producing spurious solutions due to false "local minima", there are possible failure scenarios, which can, for instance, manifest in a solution that is non-sparse, or all-zero. These issues can almost always be addressed by better choice of the various tuning parameters. Note that estimating connectivity on scalp channels, while technically not a problem, has interpretation issues due to the high likelihood of finding spurious associations between channels due to volume conduction smearing the brain activity out across channels. For this reason, this node is best on signals that better reflect the activation of individual brain sources or source areas. The most commonly used setup is to use a source-localization node such as sLORETA or LCMV beamforming (see documentation of the respective nodes for their correct use), followed by estimation of activity in regions of interest and possible merging or selection of the relevant regions, which also helps with reducing the number of input channels to this node to a reasonable number. More Info... Version 1.1.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 will give better estimates, but at the cost of less precision in time, since the resulting sequence of MVAR models will change more slowly (smoothly) 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 (e.g., less than 10% of the length) will yield little benefit, since the MVAR models for two highly overlapped windows will be very similar. The largest reasonable value is 1/2 of the window length, and if this value is larger than the window length, input data samples will 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 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. A simple and well-behaved window is the Hann window. Any non-default window will, however, require a larger window length to attain the same effective sample size (and thus estimation quality) as the default rectangular window.

• verbose name: Window Function
• default value: rect
• port type: EnumPort
• value type: str (can be None)

window_param

Parameter for 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 signal at the current sample. A good value is in the 10-15 range. Model of higher orders are harder to estimate well, and require either more data (larger window length), or stronger regularization, resulting in a more sparse model, i.e., models with fewer non-zero connections.

• 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.

• verbose name: Normalize Columns
• default value: False
• port type: BoolPort
• value type: bool (can be None)

lambda_reg

Regularization strength. This parameter governs how sparse the solution is assumed to be, where larger values yield a more sparse result. Sparse means that the connectivity solution will have few non-zero edges. Stronger regularization makes it possible to fit a more complex model (more parameters), or use less data (e.g., shorter sliding window) to fit a model of same complexity.

• verbose name: Regularization Strength
• default value: 0.1
• port type: FloatPort
• value type: float (can be None)

max_iter

Maximum number of iterations. This is used to limit for how many iterations the MVAR model fitting procedure runs to fit a single time window. On well-behaved data where the solution does not change dramatically from one sliding window to the next, the solver will typically terminate in relatively few iterations (perhaps 10 to 100) without hitting this limit, although this can vary depending on the other settings. A larger number will ensure that the solver can run to full convergence, but at the risk that it may much longer to solve for certain time windows than for others. For real-time use a good choice is around 100 to guarantee predictable performance.

• verbose name: Max Iterations
• default value: 100
• port type: IntPort
• value type: int (can be None)

abs_tolerance

Absolute convergence tolerance. Smaller values will lead the solver run to a closer approximation of the optimal solution, at the cost of increased running time. See also relative tolerance.

• verbose name: Absolute Tolerance
• default value: 0.0001
• port type: FloatPort
• value type: float (can be None)

rel_tolerance

Relative convergence tolerance. Smaller values will lead the solver run to a closer approximation of the optimal solution, at the cost of increased running time. In contrast to the absolute tolerance, this value is relative to the magnitude of the regression weights. Note that the used method works best when the desired accuracy is not excessive, and merely a good approximation is sought.

• verbose name: Relative Tolerance
• default value: 0.01
• port type: FloatPort
• value type: float (can be None)

verbose

Produce verbose output.

• verbose name: Verbose
• default value: False
• port type: BoolPort
• value type: bool (can be None)

rho

Initial value of augmented Lagrangian parameter. This parameter, which is specific to the used solver, can be auto-tuned, which makes the method is relatively robust to the initial value. However, slight adjustments in the 0.1 to 10 range can reduce the number of iterations required for convergence and thereby the running time. However, choosing a grossly inappropriate value can cause the method to fail to converge, which is easily diagnosed by having a solution that is essentially non-sparse.

• verbose name: Solver Rho
• default value: 1.0
• port type: FloatPort
• value type: float (can be None)

alpha

Over-relaxation parameter (alpha). Like rho, this parameter is a highly technical detail of the used solver. A value in the default range is known to modestly improve the time-to-solution of the algorithm in many cases compared to setting the value to 1.0, which effectively disables over-relaxation.

• verbose name: Solver Alpha
• default value: 1.7
• port type: FloatPort
• value type: float (can be None)

rho_update

Auto-tune rho parameter. Whether to update the solver's rho parameter dynamically. This can be used to achieve faster convergence times in highly time-sensitive setups, but there is a modest risk that on some data the solution can 'blow up', although this could potentially be overcome by tuning the other solver parameters related to the rho update logic.

• verbose name: Auto-Tune Solver Rho
• default value: True
• port type: BoolPort
• value type: bool (can be None)

rho_cutoff

Rho update trigger threshold. This determines how frequently updates to the solver rho parameter can be triggered. A larger value will lead to rho changing less frequently. This parameter is essentially a tradeoff between the solver adapting more quickly to settings that are optimal for convergence (using a lower value) versus preventing settings from changing too erratically (using a higher value) and thus prompting stalls or convergence failures on difficult data.

• verbose name: Solver Rho Update Threshold
• default value: 10.0
• port type: FloatPort
• value type: float (can be None)

rho_incr

Rho update increment factor. When rho is being increased, this is the factor by which it is changed. Larger values can lead to quicker adaptation if the initial value is off or solutions change rapidly, at an increased risk of overshooting.

• verbose name: Solver Rho Increment Factor
• default value: 2.0
• port type: FloatPort
• value type: float (can be None)

rho_decr

Rho update decrement factor. When rho is being decreased, this is the factor by which it is divided. Larger values can lead to quicker adaptation if the initial value is off or solutions change rapidly, at an increased risk of overshooting.

• verbose name: Solver Rho Decrement Factor
• default value: 2.0
• port type: FloatPort
• value type: float (can be None)

lambda_update

Auto-tune regularization strength. Whether to adjust the regularization strength dynamically if convergence is slow. This is a somewhat experimental feature, but it can reduce the need to adjust the lambda parameter by hand.

• verbose name: Auto-Tune Regularization Strength
• default value: False
• port type: BoolPort
• value type: bool (can be None)

lambda_update_thresh

Threshold for triggering regularization strength (lambda) updates. Only in effect if auto-tuning for this parameter is enabled. Larger values make it less likely that an update is triggered spuriously.

• verbose name: Lambda Update Threshold
• default value: 1e-05
• port type: FloatPort
• value type: float (can be None)

lambda_update_count

Number of iterations before updating lambda. Update lambda convergence has not significantly improved after this many iterations.

• verbose name: Lambda Update Count
• default value: 10
• port type: IntPort
• value type: int (can be None)

lambda_update_factor

Update factor by which to divide lambda.

• verbose name: Lambda Update Factor
• default value: 10
• port type: FloatPort
• value type: float (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)