ToMCAT-TMM

Authors

• Paulo Soares
• Adarsh Pyarelal

This repository contains the code for ToMCAT's Team Mind Module (TMM), which performs probabilistic inference to determine latent measures of team coordination and affect, and predict future team actions.

P.S.: This document is being updated incrementally at every new pull request. If you need some clarification about any functionality not yet covered here, please send an email to [email protected].

Installation

$ git clone [email protected]:ml4ai/tomcat-tmm.git
$ cd tools
$ make install

If the dependencies were already installed previously, you can disable their intallation by setting the environment variable INSTALL_DEPENDENCIES to 0 before executing make install.

Dynamic Bayes Net Lib

Part of this repository is comprised of data structures and multi-thread algorithms to perform offline training and online/offline inference in discrete-time finite-space Dynamic Bayes Net (DBN). It supports both Markov and Semi-Markov models with explicit duration. At this point, both probabilistic graphical model (PGM) and components inherent to the ToMCAT project are in this repository to facilitate deployment as this is still an ongoing project. However, the components that define a PGM are isolated and will be moved to a proper repository in the future to form a proper library. This means that any project can use the PGM part of this repository to work with dynamical probabilistic models.

State Space

This implementation supports mostly discrete state space,. Continuous distributions can only be used as parameter priors, on CPDs of leaf nodes. That is, given two random variables $X$ and $Y$, $X|Y \sim \mathcal{D}$, $\mathcal{D}$ can only be a continuous distribution if $Y$ is discrete and $X$ has no child node, if $X$ is a parameter of another CPD or if $X$ is a timer node that controls the duration of states of another random variable.

The following distributions are available:

Discrete

• Categorical
• Poisson
• Geometric

Continuous

• Dirichlet
• Gaussian
• Gamma
• Inverse Gamma

Parameter Learning

Parameters of the distributions that define CPDs are learned from data using Gibbs Sampling. This implementation only supports parameter learning if the parameters are sampled from conjugate priors. For instance, let $X$ and $Y$ be two random variables. Suppose $X |Y \sim $ Categorical($\mathbf{\theta}$). Then, we require that $\theta_i \sim$ Dirichlet($\mathbf{\alpha}$), where $\mathbf{\alpha}$ is the parameter vector of a Dirichlet distribution and it is provided in advance, and $i \in {0, \dots, |Y| - 1}$ ($|Y|$ is the cardinality of $Y$). This version does not support learning $\mathbf{\alpha}$.

With this requirement, we can get a closed form solution for the posterior of the parameters based on the sufficient statistics of their priors given the samples generated by the random variables they are part of the CPD of. Technically, the parameters are also random variables, so we shall make a distinction between them and the random variables that represent hidden and observables nodes in the model. We will call the former parameter nodes and the latter data nodes.

Finally, the training phase is executed offline, given a matrix of observations over time.

Inference Methods

Inference is performed by sequencial filtering, that is, posteriors are updated in a forward manner. At the current version, no filter smoothing is performed.

Inference can be executed online via messages sent by an external source through MQTT protocol and translated by a custom adaptor, or offline given a matrix of observations over time.

Exact

Inference can be computed exactly using sum-product if the unrolled model has no cycles. Running this type of inference on a coupled model will not result in an error but the marginals might not be correct as messages are passed downwards and upwards across the nodes for each time step and never backwards in time.

Semi-Markov models can also use this type of inference if the nodes that control the duration of states (timer nodes) have no parent dependency besides the node it controls (and possibly other data nodes that have no parents).

Approximate

Approximate inference is performed with Rao-Blackwellized Particle Filter. This inference method is preferable as it works with coupled models, is more extensible to all sorts of distributions as the library gains more functionality and achieves marginals close enough to the exact figures assuming enough particles are used during the process.

Model Definition

The DBN structure can be completely defined in a json file with a language we created for this library. Nodes, CPDs and connections are defined in such a file and are translated to the proper data structures by a model parser. A json schema is provided for consultation in /specs and a series of examples bellow show how to define all sorts of models.

Usage

We demonstrate how to use the DBN library with a series of examples increasing the level of complexities of the models.

... Continue

License

... Continue