index.html.svn-base

Probabilistic graphical models in matlab.

<p>If all your potentials are the same, or of the same type, you can just use the set_all_potentials(network, method, arguments) command. The following methods are available:

<ul>
<li> <span style="font-weight: bold;">'normal'</span>: the argument should be a matrix representing the unique potential table. To use properly this command, all potentials must have the same size, else you will get an error. The following would set all potentials to the table [0.2 0.1; 0.7 0.9], for a binary network.</li>

<p style="font-weight: bold;">my_network = set_all_potentials(my_network, 'normal', [0.2 0.1; 0.7 0.9]);</p>

<li> <span style="font-weight: bold;">'all-random'</span>: there is no requested argument. This will create potentials at random, note however that these potentials will be different from each other.</li>


</ul>

<h2>Additional operations</h2>

The next operations are identical for pairwise and factor graphs, so jump to <a href="#common">this section.</a>

<hr>

<h1><a name="factor"> Creating Factor Graphs</a></h1>

<h2>Initial setup</h2>

<p>For a factor graph, the potentials are no longer dependent on only two variables. Thus the links are not specified at the creation of the model, but later. The only thing needed at creation time is the number of random variables.</p>


<p>We can create the network by using the new_model command. The first argument to new_model is the type, and then the second argument is the number of RVs, so we type 'factor' as the first argument. Here is an example:</p>

<p style="font-weight: bold;">my_network = new_model('factor', n);</p>

where n is the number of random variables that we have in the factor graph.</p>

<h2>Providing variable sizes</h2>

<p>Note: this part is identical to the pairwise case.</p>

<p>The next step is to specify the size of every variable in the network (since it is discrete). You can do that by using the command set_variables_sizes(network, M), which takes two arguments: the first is your newly created network, the second is an array of variable sizes. For example, if you have a 5 node network:</p>

<p style="font-weight: bold;">my_network = set_variables_sizes(my_network, [2 5 7 4 2] );</p>

<p>will specify that the first Random Variable can have 2 possible values, the second 5, etc.</p>

<p>If all your RVs have the same size, you can just use the set_all_variables_sizes() command. For example, the following line will specify that all your variables are binary:</p>

<p style="font-weight: bold;">my_network = set_all_variables_sizes(my_network, 2 );</p>

<p>You could achieve exactly the same result by entering "my_network = set_variables_sizes(my_network, ones [1, number_variables] * 2 )" (number_variables being the number of variables in the graph).</p>

<h2>Providing potential tables</h2>

<p>Specifying the potential tables in the factor graph case also involves specifying the edges. A potential is associated with a certain number of random variables, and is linked to them. So the potential table must be a multi-dimensional matrix (one dimension per RV).</p>

<p>The command to enter the potential tables is set_potential(network, rv_indexes, M). rv_indexes is a vector containing the indexes of the random variables the potential will be linked to. M is the potential table. For example:</p>


<p style="font-weight: bold;">M = [0.2 0.1; 0.7 0.9];</p>
<p style="font-weight: bold;">M(:,:,2) = [0.4 0.3; 0.6 0.4];</p>
<p style="font-weight: bold;">my_network = set_potential(my_network, [1 8 23], M );</p>

<p>would set a potential between variables 1, 8 and 23 (which here, are binary) to the following table (which has three dimensions):</p>

<p>[ 0.2 0.1 ]<br>
   [ 0.7 0.9 ]</p>

<p>[ 0.4 0.3 ]<br>
   [ 0.6 0.4 ]</p>
 

<h2>Additional operations</h2>

The next operations are identical for pairwise and factor graphs, so jump to <a href="#common">the next section.</a>

<hr>

<h1><a name="common">Operations identical for Pairwise and Factor Graphs</a></h1>

<h2>Specifying observed variables</h2>

<p>You can observe variables on your network, with the command set_observation(network, variable, observed_value). For example, if you want to set the third variable to its fifth value:</p>

<p style="font-weight: bold;">my_network = set_observation(my_network, 3, 5 );</p>

<p>To revert a variable to an unobserved state, just call unset_observation(network, variable) on that variable.</p>

<p style="font-weight: bold;">my_network = unset_observation(my_network, 3);</p>

<h2>Specifying internal potentials (priors)</h2>

<p>With pgm, every random variable has an internal potential associated with it. This effectively corresponds to priors on the variables. By default, these potentials are constant, meaning that there is no prior about the variables (uniform prior). To specify a prior on one of the variable, the corresponding potential must be entered via the command set_prior(network, variable, potential). Here potential should correspond to a vector specifying the coefficients for the prior.</p>

<p style="font-weight: bold;">my_network = set_prior(my_network, 2, [1.00 2.20 6.50 4.58 0.25 );</p>

<p>would enter a suitable prior for the second variable with a size of 5.</p>

<h2>Using a timer</h2>

<p>By default, pgm will make the inference computations using a given number of steps. If we would rather see the algorithm run for a specified number of seconds, we can tell pgm to do so by entering the command:</p>

<p style="font-weight: bold;">my_network = use_timer(my_network);</p>

<p>We can disable the timer and revert to default mode with the command:</p>

<p style="font-weight: bold;">my_network = disable_timer(my_network);</p>

<hr>

<h1><a name="inference">Running Inference</a></h1>

<p >After you are sure that you have entered *all* the potential tables (don't forget one!), you are ready to run inference on the graph. The command is simple:
</p>

<p style="font-weight: bold;">my_network = compute_inference(my_network, 'method', method_argument );</p>

<p>Currently the following methods are available:</p>

<ul>
<li> Exact Belief Propagation (on a tree only!): type <span style="font-weight: bold;">'exact_bp'</span> as the method name;</li>
<li> Loopy Belief Propagation: <span style="font-weight: bold;">'loopy'</span>, and you need to pass an extra argument, the number of loopy steps to be performed;</li>
<li> Gibbs sampling: <span style="font-weight: bold;">'gibbs'</span>, with an extra argument representing the number of Gibbs Steps;</li>
<li> General Tree MCMC : <span style="font-weight: bold;">'tree_mcmc'</span>, with an extra argument representing the number of Gibbs Steps.</li>
</ul>

<p>If all goes well, this command will run the actual inference program and you will obtain results, in terms of marginals. If something goes wrong, and you are sure you didn't make any mistake entering your network, then it is likely that either the loader or the actual inference executable are not correctly installed.</p>

<p>After inference, the marginals are just stored in the network structure. So to see the marginals of the variable whose index is a, you can  just type:</p>

<p style="font-weight: bold;">my_network.marginals{a}</p>

<p>To just see all marginals:</p>

<p style="font-weight: bold;">my_network.marginals{:}</p>

<hr>


<h1><a name="examples">Examples</a></h1>

<p>Below are just some examples of the use of the Matlab interface. You can copy-and-paste them in Matlab to understand how the interface works. Once you get hold of it, it is simple to use.</p>

<p><span  style="font-weight: bold;">Example 1.</span> Very simple pairwise graph.</p>

<img style="vertical-align: bottom;" src="very_simple.png" alt="Simple 3 Nodes pairwise graph.">

<p >M = [ 0 1 0; 0 0 1; 0 0 0];
<br> my_network = new_model('pairwise', M);
<br> my_network = set_variables_sizes(my_network, [2 3 5]);
<br> my_network = set_potential(my_network, 1, 2, [0.2 0.1 0.3; 0.7 0.9 0.4]);
<br> my_network = set_potential(my_network, 2, 3, [1 7 6 2 3; 5 6 5 1 2; 9 4 6 9 8]);
<br> my_network = compute_inference(my_network, 'exact_bp');
<br> my_network.marginals{:}
<br> my_network = compute_inference(my_network, 'gibbs', 100);
<br> my_network.marginals{:}
</p>

<p><span  style="font-weight: bold;">Example 2.</span> 10 by 10 MRF square lattice.</p>

<p > my_network = new_model('pairwise', 'mrf', 10, 10 );
<br> my_network = set_all_variables_sizes(my_network, 3);
<br> my_network = set_all_potentials(my_network,  'normal', [1 7 2 ; 5 6 2; 9 9 8]);
<br> my_network = compute_inference(my_network, 'gibbs', 1000);
<br> my_network.marginals{:}
<br> my_network = compute_inference(my_network, 'loopy', 100);
<br>my_network.marginals{:}
</p>

<p><span  style="font-weight: bold;">Example 3.</span> A factor graph with 6 random variables, 3 potentials.</p>

<p > my_network = new_model('factor', 6 );
<br> my_network = set_all_variables_sizes(my_network, 2);
<br> M = [0.2 0.1; 0.7 0.9];
<br> M (:,:,2) = [0.4 0.3; 0.6 0.4];
<br> my_network = set_potential(my_network, [1 3 5], M);
<br> my_network = set_potential(my_network, [1 2], [2 0.6; 1.1 1.3] );
<br> M = [0.8 0.6; 0.4 0.2];
<br> M (:,:,2) = [0.4 0.5; 0.5 0.05];
<br> my_network = set_potential(my_network, [3 4 6], M );
<br> my_network = set_observation(my_network, 2 , 2 );
<br> my_network = use_timer(my_network);
<br> my_network = compute_inference(my_network, 'gibbs', 5);
<br> my_network.marginals{:}
<br> my_network = compute_inference(my_network, 'tree_mcmc', 2);
<br> my_network.marginals{:}
</p>


<hr>

<h1><a name="bugs">Bugs and Problems</a></h1>

<p>This is a preliminary interface, so e-mail me at: <img style="vertical-align: bottom;" src="../email_x.png" alt="E-Mail"> with any problem you should encounter.</p>

<hr>

<h1><a name="source">PGM Source Code</a></h1>

<p>You can get <a href="probabilistic-graphical-models.tar.bz2">a complete package here</a>. It contains the C++ source as well as the Matlab Interface M-files.</p>

<p>There is also a subversion repository (containing the latest code) available at svn://svn.elvanor.net/probabilistic-graphical-models/.</p>

<p>To build the code, you will need to have gcc &gt;= 3.4 and to install the Boost C++ libraries (1.33.1 or later). This archive contains an Eclipse project and a Makefile.</p>

<p>As with most academical works, this code is messy. I learnt C++ while writing this toolbox and this can easily be spotted by someone having a look at the code. If anyone needs to dig into the code, improve it or make changes, you should mail me first as I can get you started and also tell you what I think should be done first.</p>

<hr>

<h1><a name="development">Developer Documentation</a></h1>

<ul>
<li><a href="reference.html">PGM Input File Format Reference</a></li>
</ul>

</body></html>