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