The Neurophysiological Biomarker Toolbox (NBT)

# Class: var

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:

$s(t) = \sum_{\tau=1}^{p}B_{\tau}s(t-\tau)+h(t)$

where $s(t)=[s_1(t),...,s_d(t)]^{T}$ is the realization at time $t$ of the _VAR observation vector_, $B_{\tau}$ is the coefficient matrix for lag $\tau$ and $h(t)=[v_1(t),...,v_d(t)]$ is the realization at time $t$ of the _innovation process_. We will often refer to the elements of vector $s(t)$ 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 $x(t)=[x_1(t),...,x_k(t)]$ is the _measurement vector_ and $A$ is a _mixing matrix_. Note that the dimensionality of the measurement vector ($k$) does not need to be the same as the dimensionality of the underlying VAR process ($d$). A noisy version of the measurement model is also possible:

where the noise process $n(t)=[n_1(t),...,n_k(t)]$ 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 $y(t)=[y_1(t),...,y_k(t)]$ are obtained as:

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

### Construction

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);
plot(varObj.Observations{1}');

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

### Topologies

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:

### References

[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