The Neurophysiological Biomarker Toolbox (NBT)

Class: var

Back to the tutorial homepage

This document is intended to provide a synopsis of the functionality provided by class var. For a detailed description of the class properties and methods see help var.var in MATLAB.

Basic VAR model

The var class implements the machinery necessary for generating observations from a Vector Autoregressive (VAR) process:

where is the realization at time of the _VAR observation vector_, is the coefficient matrix for lag and is the realization at time of the _innovation process_. We will often refer to the elements of vector as the _nodes_ of the model.

Typically, the innovation process is considered to be a sequence of independent and identically distributed (i.i.d.) Gaussian random variables. However, class var more generally models the innovation process as a Generalized Normal Distribution.

Measurement model

Class var also implements a linear _measurement model_ in which measurements are obtained by linearly mixing the observations of the VAR process:

where is the _measurement vector_ and is a _mixing matrix_. Note that the dimensionality of the measurement vector () does not need to be the same as the dimensionality of the underlying VAR process (). A noisy version of the measurement model is also possible:

where the noise process is i.i.d. Gaussian.

Pre-processing model

Finally, class var also incorporates a pre-processing model that that can be used to implement standard pre-processing filters. That is, if the pre-processing model is specified, the measurements are obtained as:

where is a digital filter. Digital filters are defined as filter.dfilt objects. See help filter.dfilt for more information.


In the following I will assume that the dynamics package (which contains class var) has been imported via the command:

  import dynamics.*

Objects of class var are constructed as:

obj = var('propKey', propValue)

See help dynamics.var for a detailed description of the set of accepted property key/values. A default var object can be constructed using:

obj = var

The default constructor produces a noisless mix-free model with Gaussian innovations.

data interface

Class var implements the interface data which defines the following operation to generate realizations from the model described above:

[pset, obj] = generate(obj, nSamples, nTrials)

where pset is a pointset, nSamples is the number of samples to be generated, and nTrials is the number of \\trials\\. The following code can be used to plot a single trial of 1000 samples, from a 3-dimensional VAR model of order 5:

varObj = var('NbDims', 3, 'Order', 5);
[pset, varObj] = generate(varObj, 1000);

var public interface: Modifiers

Class var implements various methods for modifying the state of var objects. For instance, method set_noisecov() can be used for modifying the covariance matrix of the noise:

obj = var('NbDims', 3);  % This is a noiseless model
obj = set_noisecov(obj, eye(3)); % Now it is a noisy one

A useful modifier method is randomize(), which can be used to randomize different properties of a var object. For instance, the following command can be used to randomize the VAR coefficients and the noise covariance matrix:

obj = randomize(obj, 'varcoeffs', true, 'noisecov', true)

It is important to note that modifying the state of a var object does not automatically trigger the re-generation of the model observations, i.e. method generate() is not automatically called after such modification of the object state.

var public interface: Other methods

sigma = acov(obj, lag)

If the innovation process of the model is Gaussian, then the covariance of the measurement vector can be obtained analytically. This functionality is provided by method acov:

obj = var('NbDims', 3);         % A 3-dimensional var object
lag = 3; 						% The covariance lag
Sigma = acov(obj, lag); 		% The 3x3 covariance matrix

value = pte(obj, gamma, phi, theta)

Using the analytical covariance, the (partial) transfer entropy or the (partial) mutual information between any set of elements of the measurement vector can also be obtained analytically (see ref. [1] below). For instance, given the 3-dimensional var object that we created above, the exact value of the transfer entropy from the second component towards the first, partialized with respect to the third is:

pteValue = pte(obj, 1, 2, 3);

Method pmi works similarly to pte and provides the exact value of the partial mutual information.


A useful property of a var object is its Topology. The topology of a var object describes the way the nodes of the model are connected to each other. The topology of a var object can be specified during construction:

obj = var('NbDims', 3, 'Topology', 'tree');

of using the modifier method set_topology():

obj = var('NbDims', 5);             % Default: 'random' topology
obj = set_topology(obj, 'sparse');  % Now it has 'sparse' topology

The figures below describe the topologies that class var implements:

random topology: The values of the VAR coefficients connecting the nodes are random sparse topology: Only half of all possible connections are active path topology: An unidirectional path with a beginning and an end node loop topology: A closed path tree topology: Each node is connected unidirectionally with two children nodes flow topology: A 'path' in which each node propagates information to all subsequent nodes in the path


[1] Barnett et al., 2009, Granger Causality and Transfer Entropy Are Equivalent for Gaussian Variables, Physical Review Letters 103, 238701 doi: 10.1103/PhysRevLett.103.238701

tutorial/tutorial_sync/class_dynamics_var.txt · Last modified: 2012/01/20 09:35 by Simon-Shlomo Poil
The NBTwiki platform - version 2.8 - 9 May 2013
Copyright (C) 2008-2015