Infer.NET user guide : Running inference

Inference engine settings

High-level inference settings are all accessed via properties or methods of an InferenceEngine object (in the Microsoft.ML.Probabilistic namespace). The settings take effect at the point of model compilation; typically this occurs when you request a marginal value from one of your variables, at which point both model compilation and inference occur. However, you can separate out compilation and inference as discussed in Controlling how inference is performed.

You can get an instance of the InferenceEngine class via the following snippet:

InferenceEngine engine = new InferenceEngine();

Algorithm

This setting specifies the inference engine that will be used. Working with different inference algorithms describes this option in more detail. The options currently are:

// Use Expectation propagation  
engine.Algorithm = new ExpectationPropagation();

// Use Variational Message Passing  
engine.Algorithm = new VariationalMessagePassing();

// Use Gibbs sampling  
engine.Algorithm = new GibbsSampling();

The default setting for the algorithm is Expectation Propagation. You can also optionally specify the algorithm when you create the engine:

InferenceEngine engine = new InferenceEngine(new VariationalMessagePassing());

Compiler

This property holds the compiler that the inference engine uses to compile the model into efficient inference code. You cannot modify this property but you can modify properties of the returned ModelCompiler object as described in the table below.

DefaultEngine

All the defaults specified on this page can modified by changing properties of DefaultEngine which is a static property of the InferenceEngine class. For example:

InferenceEngine.DefaultEngine.Algorithm = new VariationalMessagePassing();  
InferenceEngine.DefaultEngine.ShowFactorGraph = true;

These settings will then become the default settings when a new InferenceEngine instance is created.

Group()

Allows you to specify that a set of variables are in a group. This is currently only used to manually specify the blocks in Block Gibbs Sampling. Note that groupings are automatically determined as necessary, so it is not typically necessary for you to call this method; but this does give you a manual override. A list of variables is passed to this method; the first argument is the root variable in the block which determines the order of message passing within it (first marginalisation within the block occurs towards the root, and then sampling is done away from from the root). Here is an example for a product of two Gaussians:

Variable<double> a = Variable.GaussianFromMeanAndVariance(1, 2);  
Variable<double> b = Variable.GaussianFromMeanAndVariance(2, 3);  
Variable<double> c = a * b;  
GibbsSampling gs = new GibbsSampling();  
gs.BurnIn = 100; gs.Thin = 10;  
InferenceEngine engine = new InferenceEngine(gs);  
engine.NumberOfIterations = 10000;  
engine.Group(a, c);  
engine.Group(b, c);  
var marg = engine.Infer<Gaussian>(c);

ModelName and ModelNamespace

Allows a name to be specified for the model, which is used in the class name of the generated code. ModelName defaults to “Model” and ModelNamespace defaults to “Models”.

// Change the model name  
engine.ModelName = "MyMixtureModel";
// Change the model namespace
engine.ModelNamespace = "MyNamespace";

NumberOfIterations

This specifies how many iterations the algorithm will run for. An ‘iteration’ is a single update of all the variables in a model. For the EP and VMP algorithms. only a handful of iterations are sometimes required, and the inference algorithm may converge well before the default number of 50 iterations for the two algorithms.

// Change the number of iterations  
engine.NumberOfIterations = 10;

Setting the number of iterations to -1 tells the inference engine to use the algorithm-specific default number of iterations. Note that Gibbs sampling will typically need many more iterations than EP or VMP.

This property can be used to do incremental inference. For example, suppose the NumberOfIterations is set to 10 and Infer() is called. Setting the NumberOfIterations to 20 and calling Infer() again will result in a further 10 iterations being executed. NumberOfIterations is effectively controlling the argument to Execute() on the underlying generated algorithm (see Controlling how inference is performed).

OptimiseForVariables

This property lets you specify a list of variables which the inference engine should optimise inference for. If you set this property, the inference engine will internally generate code for performing inference on exactly this set of variables, avoiding the overhead of computing or caching marginals for any other variables. If you set this property and then call Infer() on a variable not in this list, you will get an error.

// Optimise the engine to infer variables x, y and z. 
engine.OptimiseForVariables = new[] {x,y,z};

Setting this property to null reverts the engine to its normal behaviour where it will automatically choose which variables to perform inference on.

ResetOnObservedValueChanged

This option is useful for reducing the number of iterations required when observed values change. If true (the default), calling Infer() resets messages to their initial values if an observed value has changed. This ensures that the result of inference is always the same for the same set of observed values, but requires a full set of iterations to be performed each time. If false, the messages will not be reset when an observed value has changed. Thus the result of inference may depend on the previous observed values, but convergence can be faster. This option effectively switches between using Update instead of Execute on the underlying generated algorithm (see Controlling how inference is performed).

// Do not reset the message state  
engine.ResetOnObservedValueChanged = false;  

engine.NumberOfIterations = 10;  
// Perform 10 iterations from the initial state  
engine.Infer(x);  
y.ObservedValue = 4;  
// Perform 10 additional iterations (since y has changed)  
// but from the current state  
engine.Infer(x);  
engine.NumberOfIterations = 12;  
// Perform 2 additional iterations (since 10 already done  
// for the current y)  
engine.Infer(x);  
engine.NumberOfIterations = 5;  
// Perform 5 additional iterations (since 5 < 12)  
// from the current message state  
engine.Infer(x);

ShowFactorGraph

This specifies whether to display the factor graph corresponding to the model. A factor graph is a graphical representation of a model which shows each variable as a circle and each factor or constraint as a square. If a variable participates in the factor or the constraint, then an edge is shown between the corresponding circle and square. Factor graphs are more than just a picture of the model; they are intimately related to the message passing algorithms used for inference in Infer.NET. To make the graph readable, you should attach names to the variables in the model.

By default, graphs are visualized using GraphViz in a web browser. You will need to install GraphViz yourself. On Windows, users can select the WindowsVisualizer (see below) which visualizes graphs using MSAGL.

// Show the factor graph of the model  
engine.ShowFactorGraph = true;

The default setting for this bool property is false.

SaveFactorGraphToFolder

If not null, all factor graphs generated by calls to Infer will be saved to the given folder (which will be created if it doesn’t already exist). If the folder name is an empty string (as opposed to null), the graphs will be saved to the current folder.

By default, the graph is saved in DOT format. The file name is the model name (set above), with extension “.gv”. The graph is also saved in DGML format, which can be viewed and manipulated in Visual Studio. The file name is the model name, with extension “.dgml”.

// Save all factor graphs to the 'graphs' sub-folder  
engine.SaveFactorGraphToFolder = "graphs";

The default setting for this string property is null.

ShowMsl

If this flag is set to true, the Model Specification Language (MSL) version of your model will be written to the Console. To make this code readable, you should attach names to the variables in the model.

// Show the model in the Model Specification Language  
engine.ShowMsl = true;

The default setting for this bool property is false.

ShowProgress

If this flag is set to true, progress information is written to the console, updating at each iteration.

// Print out progress information  
engine.ShowProgress = true;

The default setting for this bool property is true.

ShowTimings

If this flag is set to true, timing information is written to the console at the conclusion of the inference, showing the time taken for compilation (if compilation is done) and for inference.

// Print out timing information  
engine.ShowTimings = true;

The default setting for this bool property is false.

ShowWarnings

If this flag is set to true, any warnings encountered during inference will be printed to the console. The default setting for this bool property is true, so that you are aware of any problems encountered. To suppress warnings, set the property to false.

// Do not print out warnings  
engine.ShowWarnings = false;

Visualizer

This is a global setting that provides the implementation of ShowFactorGraph, ShowSchedule, and BrowserMode for the platform. Defaults to DefaultVisualizer.

// Custom visualization for the Windows platform
InferenceEngine.Visualizer = new WindowsVisualizer();