Previous  Up  Next

Module Bn

module Bn: sig .. end
The BN library reads, writes, and represents Bayesian networks (BNs) and dependency networks (DNs) with conditional probability distributions (CPDs) that are tree-structured, tables, or arbitrary sets of factors.

Data structures

type schema_t = int array
A domain schema specifies the cardinality of each (discrete) variable.
type variable = BnType.variable = {
   vname : string; (*Variable name.*)
   idx : int; (*Variable index in the network (the variable is located at network.vars.(idx)).*)
   range : int; (*The cardinality of the variable.*)
   valnames : string array; (*String name for each possible value of the variable.*)
}
A BN variable structure includes additional information about variable and value names, for compatibility with some standard BN file formats. (Variable and value names are not supported by most of Libra.)
type cpnode = BnType.cpnode =
| Leaf of float array (*Array contains log conditional probabilities for this leaf*)
| Vertex of int * int * cpnode * cpnode (*Split var, value, true branch, false branch*)
Represents a node in a tree-structured CPD.
type cpd = BnType.cpd =
| Table of float array array (*Table representation of CPDs.*)
| Tree of cpnode (*Tree representation of CPDs.*)
| FactorSet of Mn.Factor.factor list (*Factor representation of CPDs.*)
A CPD can be represented as a table, tree, or set of factors.
type network = BnType.network = {
   name : string; (*Name of the network or domain. Arbitrary and mostly unused.*)
   mutable acyclic : bool; (*True if network is a BN; false for DNs.*)
   vars : variable array; (*Set of variables in the network.*)
   parents : int list array; (*Indices of parents for each var.*)
   dists : cpd array; (*Set of CPDs in the network.*)
   children : int list array; (*Indices of children for each var.*)
   name_to_varidx : (string, int) Ext.Hashtbl.t; (*Map from variable names to indices.*)
   name_to_validx : (string, int) Ext.Hashtbl.t array; (*Map from the names of each variable's values to their indices.*)
   topo_vars : variable array; (*Set of variables in the network, sorted in topologocal order.*)
}
Represents a Bayesian network or dependency network. The fields children, name_to_varidx, name_to_validx, and topo_vars can all be derived from the previous fields using provided functions. This makes them redundant, but they exist for convenience.

Utility methods

val get_range : network -> int -> int
get_range bn i
Returns the cardinality of variable i in network bn.
val schema : network -> schema_t
Returns the schema of the given network.
val tree_params : cpnode -> int
Returns the number of parameters in the given tree CPD.
val dist_params : cpd -> int
Returns the number of parameters in the given CPD.
val tree_parents : int -> cpnode -> int list
tree_parents numvars root
Returns the list of nodes that have at least one child, given a tree with the root node root
val numvars : network -> int
Returns the number of variables in the network.
val varname : network -> int -> string
varname bn idx
Returns the variable name of the variable at index idx of array bn.vars.
val idx : variable -> int
Returns the index of the variable.
val parents : network -> int -> int list
parents bn idx
Returns the list of parents of the variable with index idx in network bn.
val children : network -> int -> int list
children bn idx
Returns the list of children of the variable with index idx in network bn.
val numparents : network -> int -> int
numparents bn idx
Returns the number of parents of the variable with index idx in network bn.
val numchildren : network -> int -> int
numchildren bn idx
Returns the number of children of the variable with index idx in network bn.
val numparams : network -> int -> int
numparams bn idx
Returns the number of children of the variable with index idx in network bn.

Create/Modify BN structure and distribution

val create_var : int -> int -> variable
create_var idx dim
Returns a Bn.variable whose idx is idx and range is dim.
val create_default_cpt : variable -> cpd
Returns a table cpd which represents a uniform distribution for the given variable.
val build_namehashes : variable array ->
       (string, int) Ext.Hashtbl.t * (string, int) Ext.Hashtbl.t array
Create hash maps from variable name -> index, and from each variable's values -> value index.
val make_children : int list array -> int list array
Creates an array of child lists, given an array of parent lists
val make_topo_vars : variable array -> 'a list array -> int list array -> variable array
Creates list of variables in topographic order
val create_empty_network : int array -> network
create_empty_network s creates an empty network with given variable schema s
val update_children_and_topo_vars : network -> unit
Updates the children lists and topological variable order
val set_cpt : network -> int -> int list -> float array array -> unit
set_cpt bn var_idx parents cpt_values updates a CPT. Modifies BN in-place by replacing the parents of var_idx with parents and the distribtion of var_idx with cpt_values
val set_cptree : network -> int -> cpnode -> unit
set_cptree bn var_idx root updates the CPD of variable var_idx in network bn with a CPD with root node root. Modifies bn in-place.
val set_factorset : network -> int -> Mn.Factor.factor list -> unit
set_factorset bn var_idx fl updates the CPD of variable var_idx in network bn with factor list fl. Modifies bn in-place.
val cpd_to_factors : network -> Mn.Factor.variable -> cpd -> Mn.Factor.factor list
cpd_to_factors bn cvar cpd converts cpd associated with variable cvar of network bn to Markov network factors
val to_mn : network -> Mn.network
Converts the Bayesian network to a Markov network by introducing one factor for each CPD.
val simplify : network -> Mn.Factor.varvalue array -> network
simplify bn ev simplifies CPDs of netwprk bn given evidence ev if the CPDs are represented using trees or factor sets. This speeds up inference slightly by reducing the depth of each tree. This modifies the BN. NOTE: Resulting CPDs may not be normalized, and hence be merely potential functions, not conditional probability distributions.

Evaluation of BNs

val tree_logprob : int array -> cpnode -> float array
tree_logprob x cpdnode
Returns a log conditional probability from a tree-based CPD cpdnode for example x.
val node_logscore : network -> Mn.Factor.varvalue array -> int -> float
node_logscore bn x v
Returns log conditional probability of the current state of variable v given its parents for example x.
val mb_logprob : network -> Mn.Factor.varvalue array -> int -> float array
mb_logprob bn x i
Returns log probability of X_i given its Markov blanket.
val mb_prob : network -> Mn.Factor.varvalue array -> int -> float array
mb_prob bn x i
Returns probability of X_i given its Markov blanket.
val cond_prob : network -> Mn.Factor.varvalue array -> int -> float array
cond_prob bn x i
Returns probability of X_i given its parents.
val loglikelihood : network -> Mn.Factor.varvalue array -> float
loglikelihood bn x computes the log-likelihood of the network on a single example x. Note: All values must be specified -- no missing data!
val pll : network -> Mn.Factor.varvalue array -> float
pll bn x computes the pseudo-log-likelihood of the network on a single example x. Note: All values must be specified -- no missing data!
val sample_array : float array -> int
Utility function for sampling a multinomial given an array containing the probability of each state.
val sample : network -> Mn.Factor.varvalue array
Generates a single iid sample from the BN probability distribution.

Read/Write BNs

val load_bif : Pervasives.in_channel -> BnType.network
Input a BN in BIF format.
val output_bif : Pervasives.out_channel -> BnType.network -> unit
Output a BN in BIF format.
val load_xmod : Pervasives.in_channel -> BnType.network
Input a BN in .xmod format.
val output_xmod : Pervasives.out_channel -> BnType.network -> unit
Output a BN in .xmod format.
val load_cn : Pervasives.in_channel -> BnType.network
Input a BN in CN format.
val output_cn : Pervasives.out_channel -> BnType.network -> unit
Output a BN in CN format.
val filename_is_xmod : string -> bool
Checks whether the filename ends with .xmod
val filename_is_bif : string -> bool
Checks whether the filename ends with .bif
val filename_is_cn : string -> bool
Checks whether the filename ends with .cn, .dn, or .bn
val filename_is_dn : string -> bool
Checks whether the filename ends with .dn
val load_auto : string -> BnType.network
Read a BN from a file, inferring the format from filename. See Section 4 of the user manual.
val write_auto : string -> BnType.network -> unit
Write the BN to a file, inferring the format from filename. See Section 4 of the user manual.