edu.stanford.nlp.loglinear.model

Class GraphicalModel

java.lang.Object

edu.stanford.nlp.loglinear.model.GraphicalModel

public class GraphicalModel
extends java.lang.Object

Created on 8/7/15.

Author:

keenon

A basic graphical model representation: Factors and Variables. This should be a fairly familiar interface to anybody who's taken a basic PGM course (eg https://www.coursera.org/course/pgm). The key points: - Stitching together feature factors - Attaching metadata to everything, so that different sections of the program can communicate in lots of unplanned ways. For now, the planned meta-data is a lot of routing and status information to do with LENSE.

This is really just the data structure, and inference lives elsewhere and must use public interfaces to access these models. We just provide basic utility functions here, and barely do that, because we pass through directly to maps wherever appropriate.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GraphicalModel.Factor A single factor in this graphical model.

Field Summary

Fields

Modifier and Type	Field and Description
java.util.Set<GraphicalModel.Factor>	factors
java.util.Map<java.lang.String,java.lang.String>	modelMetaData
java.util.List<java.util.Map<java.lang.String,java.lang.String>>	variableMetaData

Constructor Summary

Constructors

Constructor and Description
GraphicalModel()

Method Summary

Modifier and Type	Method and Description
GraphicalModel.Factor	addFactor(ConcatVectorTable featureTable, int[] neighborIndices) Creates an instantiated factor in this graph, with neighborIndices representing the neighbor variables by integer index.
GraphicalModel.Factor	addFactor(int[] neighborIndices, int[] neighborDimensions, java.util.function.Function<int[],ConcatVector> assignmentFeaturizer) This is the preferred way to add factors to a graphical model.
GraphicalModel	cloneModel() The point here is to allow us to save a copy of the model with a current set of factors and metadata mappings, which can come in super handy with gameplaying applications.
java.util.Map<java.lang.String,java.lang.String>	getModelMetaDataByReference()
GraphicalModelProto.GraphicalModel.Builder	getProtoBuilder()
java.util.Map<java.lang.String,java.lang.String>	getVariableMetaDataByReference(int variableIndex) Gets the metadata for a variable.
int[]	getVariableSizes()
static GraphicalModel	readFromProto(GraphicalModelProto.GraphicalModel proto) Recreates an in-memory GraphicalModel from a proto serialization, recursively creating all the ConcatVectorTable's and ConcatVector's in memory as well.
static GraphicalModel	readFromStream(java.io.InputStream stream) Static function to deserialize a graphical model from an input stream.
java.lang.String	toString() Displays a list of factors, by neighbor.
boolean	valueEquals(GraphicalModel other, double tolerance) Check that two models are deeply value-equivalent, down to the concat vectors inside the factor tables, within some tolerance.
void	writeToStream(java.io.OutputStream stream) Writes the protobuf version of this graphical model to a stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

modelMetaData

public java.util.Map<java.lang.String,java.lang.String> modelMetaData

variableMetaData

public java.util.List<java.util.Map<java.lang.String,java.lang.String>> variableMetaData

factors

public java.util.Set<GraphicalModel.Factor> factors

Constructor Detail

GraphicalModel

public GraphicalModel()

Method Detail

getModelMetaDataByReference

public java.util.Map<java.lang.String,java.lang.String> getModelMetaDataByReference()

Returns:

a reference to the model meta-data

getVariableMetaDataByReference

public java.util.Map<java.lang.String,java.lang.String> getVariableMetaDataByReference(int variableIndex)

Gets the metadata for a variable. Creates blank metadata if does not exists, then returns that. Pass by reference.

Parameters:

variableIndex - the variable number, 0 indexed, to retrieve

Returns:

the metadata map corresponding to that variable number

addFactor

public GraphicalModel.Factor addFactor(int[] neighborIndices,
                                       int[] neighborDimensions,
                                       java.util.function.Function<int[],ConcatVector> assignmentFeaturizer)

This is the preferred way to add factors to a graphical model. Specify the neighbors, their dimensions, and a function that maps from variable assignments to ConcatVector's of features, and this function will handle the data flow of constructing and populating a factor matching those specifications.

IMPORTANT: assignmentFeaturizer must be REPEATABLE and NOT HAVE SIDE EFFECTS This is because it is actually stored as a lazy closure until the full featurized vector is needed, and then it is created, used, and discarded. It CAN BE CALLED MULTIPLE TIMES, and must always return the same value in order for behavior of downstream systems to be defined.

Parameters:

neighborIndices - the names of the variables, as indices

neighborDimensions - the sizes of the neighbor variables, corresponding to the order in neighborIndices

assignmentFeaturizer - a function that maps from an assignment to the variables, represented as an array of assignments in the same order as presented in neighborIndices, to a ConcatVector of features for that assignment.

Returns:

a reference to the created factor. This can be safely ignored, as the factor is already saved in the model

addFactor

public GraphicalModel.Factor addFactor(ConcatVectorTable featureTable,
                                       int[] neighborIndices)

Creates an instantiated factor in this graph, with neighborIndices representing the neighbor variables by integer index.

Parameters:

featureTable - the feature table to use to drive the value of the factor

neighborIndices - the indices of the neighboring variables, in order

Returns:

a reference to the created factor. This can be safely ignored, as the factor is already saved in the model

getVariableSizes

public int[] getVariableSizes()

Returns:

an array of integers, indicating variable sizes given by each of the factors in the model

writeToStream

public void writeToStream(java.io.OutputStream stream)
                   throws java.io.IOException

Writes the protobuf version of this graphical model to a stream. reversible with readFromStream().

Parameters:

stream - the output stream to write to

Throws:

java.io.IOException - passed through from the stream

readFromStream

public static GraphicalModel readFromStream(java.io.InputStream stream)
                                     throws java.io.IOException

Static function to deserialize a graphical model from an input stream.

Parameters:

stream - the stream to read from, assuming protobuf encoding

Returns:

a new graphical model

Throws:

java.io.IOException - passed through from the stream

getProtoBuilder

public GraphicalModelProto.GraphicalModel.Builder getProtoBuilder()

Returns:

the proto builder corresponding to this GraphicalModel

readFromProto

public static GraphicalModel readFromProto(GraphicalModelProto.GraphicalModel proto)

Recreates an in-memory GraphicalModel from a proto serialization, recursively creating all the ConcatVectorTable's and ConcatVector's in memory as well.

Parameters:

proto - the proto to read

Returns:

an in-memory GraphicalModel

valueEquals

public boolean valueEquals(GraphicalModel other,
                           double tolerance)

Check that two models are deeply value-equivalent, down to the concat vectors inside the factor tables, within some tolerance. Mostly useful for testing.

Parameters:

other - the graphical model to compare against.

tolerance - the tolerance to accept when comparing concat vectors for value equality.

Returns:

whether the two models are tolerance equivalent

toString

public java.lang.String toString()

Displays a list of factors, by neighbor.

Overrides:

toString in class java.lang.Object

Returns:

a formatted list of factors, by neighbor

cloneModel

public GraphicalModel cloneModel()

The point here is to allow us to save a copy of the model with a current set of factors and metadata mappings, which can come in super handy with gameplaying applications. The cloned model doesn't instantiate the feature thunks inside factors, those are just taken over individually.

Returns:

a clone