fab.model.lvprior package

Submodules

fab.model.lvprior.hme_bern_gate_lvprior module

class fab.model.lvprior.hme_bern_gate_lvprior.BernGateFunction(feature_ids, internal_feature_index, threshold, prob_left)

Bases: GateFunction

Bernoulli-gate function class.

If X[feature_id] < threshold, the samples are generated from the left-child in the probability of prob_left. Otherwise, from the right-child in the probability of prob_left.

Parameters:
feature_idslist[int], size = (num_gate_features).

Feature ID numbers that is used for optimizing this gating function.

internal_feature_indexint

Feature index on which samples are split into the left or right-child. Domain = [0, num_gate_features).

thresholdfloat

Threshold value for X[feature_id].

prob_leftfloat

Probability in which samples are generated from the left-child when X[feature_id] < threshold. Domain = [0, 1].

Attributes:
feature_id

Returns feature ID on which samples are split into the left or right-child.

parameter_dim

Returns parameter dimensionality of the Bernoulli-gate.

Methods

calc_logprobs_on_branches(X)

Calculates log-probabilities on both child branches.

from_dict(gate_func_dict)

Restores the gate function object from dict information.

to_dict()

Generates a dict of information of the gate function.

calc_logprobs_on_branches(X)

Calculates log-probabilities on both child branches.

Parameters:
Xnp.ndarray, size = (num_samples, num_features)

Feature data.

Returns:
left_logprobs, right_logprobs: np.array, size = (num_samples)

Log-probabilities on left and right branches.

property feature_id

Returns feature ID on which samples are split into the left or right-child.

Returns:
feature_idint

Feature ID number.

classmethod from_dict(gate_func_dict)

Restores the gate function object from dict information.

Parameters:
gate_func_dict: dict

Information on the gate function.

Returns:
gate_func: BernGateFunction

An instance of this class.

Notes

For the format of the dict (gate_func_dict), refer to an example for to_dict() method.

property parameter_dim

Returns parameter dimensionality of the Bernoulli-gate.

Bernoulli-gates has 3 parameters (feature_id, threshold, and prob_left), so the dimensionality is always 3.

Returns:
parameter_dimint

Parameter dimensionality (= 3).

to_dict()

Generates a dict of information of the gate function.

Returns:
gate_func_dictdict

Information on the Bernoulli-gate function in type of dict.

Examples

>>> gate_func.to_dict()
{
    'feature_ids': [1, 2, 3],
    'internal_feature_index': 1,
    'threshold': 2.5,
    'prob_left': 0.4
}
class fab.model.lvprior.hme_bern_gate_lvprior.HMEBernGateLVPrior(root_node=None)

Bases: HMEBinaryTreeLVPrior

Latent variable prior class for FAB/HME with Bernoulli-gates.

For this class, each gating-node (BinaryTreeGateNode) have a gating-function in the type of Bernoulli-gate function (BernGateFunction).

Parameters:
root_nodeHMEBinaryTreeNode, optional [default is None]

The root node object of the tree. num_nodes, num_comps and other attributes are updated according to the specified root node.

Attributes:
has_no_gates

Returns whether the tree has no gating-nodes.

Methods

assign_comp_by_index(X)

Assigns a component index for each sample.

calc_gate_loglikelihood(X)

Calculates log-likelihood values for each gate function, which is the probability of going down to the left-child branch from the gate.

calc_loglikelihood(X)

Calculates log-likelihood values of the latent variable.

create_gate_func(params)

Creates a Bernoulli-gate function instance.

from_dict(lvprior_dict)

Restores the latent variable prior object from dict information.

to_dict()

Generates a dict of information on the prior.

trace_nodes_from_comp(comp_index)

Traces nodes from a gating-node which is a parent of the component node having specified component index to the root node.

traverse_depth_first([preorder, gates_only])

Returns a generator traversing the nodes in the gate-tree in left (in-order) and depth first.

update_tree_attributes()

Updates the tree attributes.

classmethod create_gate_func(params)

Creates a Bernoulli-gate function instance.

Parameters:
paramsdict

Parameter values to be set for the newly created Bernoulli-gate function.

Returns:
gate_funcBernGateFunction

A created gate-function instance.

fab.model.lvprior.hme_binary_tree_lvprior module

class fab.model.lvprior.hme_binary_tree_lvprior.BinaryTreeComponentNode(comp_index=None, parent_node=None, node_id=None)

Bases: HMEBinaryTreeNode

Component node class for binary tree.

This class concerns component-nodes (leaf-nodes) of binary tree. Each node has a parent node and a component index number.

Parameters:
comp_indexint, optional [default: None]

Component index number.

parent_nodeHMEBinaryTreeNode

Reference for a parent node object of this node.

node_idint

The node ID.

Attributes:
is_gate_node

Returns whether the node is gating-node.

is_root_node

Returns whether the node is the root node of the tree.

Methods

to_dict()

Generates a dict of the information of the node.

to_dict()

Generates a dict of the information of the node.

Returns:
comp_node_dictdict

Component node information in dict type.

class fab.model.lvprior.hme_binary_tree_lvprior.BinaryTreeGateNode(gate_index=None, gate_func=None, parent_node=None, left_node=None, right_node=None, node_id=None)

Bases: HMEBinaryTreeNode

Gating node class for binary tree.

This class concerns gating-nodes of binary tree. Each node has a parent node, a left-child node, a right-child node, a gate function and a gate index number.

Parameters:
gate_indexint, optional [default: None]

Gate index number.

gate_funcGateFunction

Gating function object.

parent_nodeHMEBinaryTreeNode

Reference for a parent node object of this node.

left_nodeHMEBinaryTreeNode

Reference for a left-child node object of this node.

right_nodeHMEBinaryTreeNode

Reference for a right-child node object of this node.

node_idint

The node ID.

Attributes:
is_gate_node

Returns whether the node is gating-node.

is_root_node

Returns whether the node is the root node of the tree.

Methods

to_dict()

Generates a dict of the information of the node.

to_dict()

Generates a dict of the information of the node.

Returns:
gate_node_dictdict

Gate node information in dict type.

class fab.model.lvprior.hme_binary_tree_lvprior.HMEBinaryTreeLVPrior(root_node)

Bases: HMELVPrior

Latent variable prior class for FAB/HME with binary-tree form.

Parameters:
root_nodeHMEBinaryTreeNode

The root node object of the tree. num_nodes, num_comps and other attributes are updated according to the specified root node.

Attributes:
has_no_gates

Returns whether the tree has no gating-nodes.

Methods

assign_comp_by_index(X)

Assigns a component index for each sample.

calc_gate_loglikelihood(X)

Calculates log-likelihood values for each gate function, which is the probability of going down to the left-child branch from the gate.

calc_loglikelihood(X)

Calculates log-likelihood values of the latent variable.

create_gate_func(params)

Creates a gate function instance according to argument parameters.

from_dict(lvprior_dict)

Restores the latent variable prior object from dict information.

to_dict()

Generates a dict of information on the prior.

trace_nodes_from_comp(comp_index)

Traces nodes from a gating-node which is a parent of the component node having specified component index to the root node.

traverse_depth_first([preorder, gates_only])

Returns a generator traversing the nodes in the gate-tree in left (in-order) and depth first.

update_tree_attributes()

Updates the tree attributes.

assign_comp_by_index(X)

Assigns a component index for each sample.

Assigning a component for each sample is executed with the information on the latent variable prior. A component having highest probability of generation the sample is selected for each sample.

Parameters:
Xnp.ndarray, size = (num_samples, num_gate_features)

Input feature data.

Returns:
assigned_comp_indicesnp.array, size = (num_samples)

Selected component index for each sample. The range of the index = [0, num_comps).

calc_gate_loglikelihood(X)

Calculates log-likelihood values for each gate function, which is the probability of going down to the left-child branch from the gate.

Parameters:
Xnp.ndarray, size = (num_samples, num_gate_features)

Input feature data.

Returns:
loglikelihoodnp.ndarray, size = (num_samples, num_gates)

The calculated log-likelihood values for all samples.

calc_loglikelihood(X)

Calculates log-likelihood values of the latent variable.

Parameters:
Xnp.ndarray, size = (num_samples, num_gate_features)

Input feature data.

Returns:
loglikelihoodnp.ndarray, size = (num_samples, num_comps)

The calculated log-likelihood values for all samples respect to all components.

abstract classmethod create_gate_func(params)

Creates a gate function instance according to argument parameters.

Parameters:
params

Parameter values to be set for the newly created gate function.

Returns:
gate_funcGateFunction

Created gate-function instance.

classmethod from_dict(lvprior_dict)

Restores the latent variable prior object from dict information.

Parameters:
lvprior_dictdict

Latent variable prior information in dict type.

Returns:
lvpriorHMEBinaryTreeLVPrior

An instance of this class in which tree structure and gate function parameters are set.

Notes

For the format of the dict (lvprior_dict), refer to an example for to_dict() method.

property has_no_gates

Returns whether the tree has no gating-nodes.

The tree having no gating-nodes means the number of components is only one. This method returns True too when root_node is None that means the number of components is zero.

Returns:
has_no_gatesbool

Whether the tree has no gating-nodes.

to_dict()

Generates a dict of information on the prior.

Returns:
lvprior_dictdict

Information on the latent variable prior in dict type.

Notes

For the format of the dict (gate_func_dict), refer to an example for to_dict() method of GateFunction concrete class.

Examples

>>> lvprior.to_dict()
{
    'node_info': {
        0: {
            'type': 'gate',
            'node_id': 0,
            'gate_index': 0,
            'gate_func': gate_func_dict # see notes
        },
        1: {
            'type': 'comp',
            'node_id': 1,
            'comp_index': 0
        },
        2: {
            'type': 'comp',
            'node_id': 2,
            'comp_index': 1
        }
    },
    'branch_info': {
        0: {
            'left_id': 1,
            'right_id': 2
        }
    },
    'root_id': 0
}
trace_nodes_from_comp(comp_index)

Traces nodes from a gating-node which is a parent of the component node having specified component index to the root node.

Note that a component node and a root node are excepted for.

Parameters:
comp_indexint

Component index number on which the tracing is started.

Returns:
nodesgenerator(BinaryTreeGateNode)

Nodes in the trees as a form of generator.

traverse_depth_first(preorder=True, gates_only=False)

Returns a generator traversing the nodes in the gate-tree in left (in-order) and depth first.

Parameters:
preorderbool, optional [default: True]

Indicates whether preorder traversing is enabled or disabled. If True, a node is returned in advance of its child nodes, otherwise postorder is adopted.

gates_onlybool, optional [default: False]

Indicates whether only gate nodes are traversed.

Returns:
nodesgenerator(HMEBinaryTreeNode)

Nodes in the trees as a form of generator.

Examples

>>> for node in lvprior.traverse_depth_first():
...     if node.is_gate_node:
...         print 'gate-node: id = ', node.gate_index
...     else:
...         print 'comp-node: id = ', node.comp_index
update_tree_attributes()

Updates the tree attributes.

In this method, the tree attributes (num_comps, num_gates, etc.) are updated with tracing connections between nodes from the root node.

Returns:
None
Raises:
TypeError

Unexpected node type (other than BinaryTreeComponentNode or BinaryTreeGateNode) is existing in the gate-tree of the prior.

class fab.model.lvprior.hme_binary_tree_lvprior.HMEBinaryTreeNode(parent_node, node_id)

Bases: object

An abstract class for binary tree nodes.

This class concerns nodes in a binary tree. Each node has a parent node.

Parameters:
parent_nodeHMEBinaryTreeNode

Reference for a parent node object of this node.

node_idint

The node ID.

Attributes:
is_gate_node

Returns whether the node is gating-node.

is_root_node

Returns whether the node is the root node of the tree.

Methods

to_dict()

Generates a dict of the information of the node.

property is_gate_node

Returns whether the node is gating-node.

Returns:
is_gatebool

If True, the node is gating node. Otherwise, it’s component node.

property is_root_node

Returns whether the node is the root node of the tree.

Returns:
is_rootbool

If True, the node is the root node.

abstract to_dict()

Generates a dict of the information of the node.

Returns:
node_dictdict

Node information in dict type.

fab.model.lvprior.hme_binary_tree_lvprior.traverse_binarytree_depth_first(node, preorder=True, gates_only=False)

Returns a generator traversing the binary tree in left (in-order) and depth first.

Parameters:
nodeHMEBinaryTreeNode

The node on which traversing is started.

preorderbool, optional [default: True]

Indicates whether preorder traversing is enabled or disabled. If True, a node is returned in advance of its child nodes, otherwise postorder is adopted.

gates_onlybool, optional [default: False]

If True, only gate nodes are returned. Otherwise, both gate and component nodes are returned.

Returns:
nodesgenerator(HMEBinaryTreeNode)

The nodes in the trees as a form of generator.

fab.model.lvprior.hme_logit_gate_lvprior module

class fab.model.lvprior.hme_logit_gate_lvprior.HMELogitGateLVPrior(root_node=None)

Bases: HMEBinaryTreeLVPrior

Latent variable prior class for FAB/HME with logistic-gates.

For this class, each gating-node (BinaryTreeGateNode) has a gating-function in the type of logistic-gate function (LogitGateFunction).

Parameters:
root_nodeHMEBinaryTreeNode, optional [default is None]

The root node object of the tree. num_nodes, num_comps and other attributes are updated according to the specified root node.

Attributes:
has_no_gates

Returns whether the tree has no gating-nodes.

Methods

assign_comp_by_index(X)

Assigns a component index for each sample.

calc_gate_loglikelihood(X)

Calculates log-likelihood values for each gate function, which is the probability of going down to the left-child branch from the gate.

calc_loglikelihood(X)

Calculates log-likelihood values of the latent variable.

create_gate_func(params)

Creates a logistic-gate function instance.

from_dict(lvprior_dict)

Restores the latent variable prior object from dict information.

to_dict()

Generates a dict of information on the prior.

trace_nodes_from_comp(comp_index)

Traces nodes from a gating-node which is a parent of the component node having specified component index to the root node.

traverse_depth_first([preorder, gates_only])

Returns a generator traversing the nodes in the gate-tree in left (in-order) and depth first.

update_tree_attributes()

Updates the tree attributes.

classmethod create_gate_func(params)

Creates a logistic-gate function instance.

Parameters:
paramsdict

Parameter values to be set for the newly created logistic-gate function.

Returns:
gate_funcLogitGateFunction

A created gate-function instance.

class fab.model.lvprior.hme_logit_gate_lvprior.LogitGateFunction(feature_ids, weights, bias, hard_gate=False)

Bases: GateFunction

Logistic-gate function class.

Parameters:
feature_idslist[int], size = (num_gate_features)

Feature ID numbers.

weightsnp.array, size = (num_gate_features)

Weight values.

biasfloat

Bias value.

hard_gatebool, optional [default: False]

Whether this gate behaves as a hard-gate. If True, the probability of left and right child is either 0.0 or 1.0.

Attributes:
parameter_dim

Returns ——- parameter_dim : int Parameter dimensionality of this gate: the number of relevant features + 1 (bias).

relevant_feature_mask

Returns relevant feature mask.

Methods

calc_decision_function(X)

Calculates decision function values.

calc_logprobs_on_branches(X)

Calculates log-probabilities on both child branches.

from_dict(gate_func_dict)

Restores the gate function object from dict information.

to_dict()

Generates a dict of information of the gate function.

calc_decision_function(X)

Calculates decision function values.

Parameters:
Xnp.ndarray, size = (num_samples, num_features)

Feature data.

Returns:
decision_funcsnp.array, size = (num_samples)

Decision function values of this gate function.

calc_logprobs_on_branches(X)

Calculates log-probabilities on both child branches.

Parameters:
Xnp.ndarray, size = (num_samples, num_gate_features)

Feature data.

Returns:
left_logprobs, right_logprobs: np.array, size = (num_samples)

Log-probabilities on left and right branches.

classmethod from_dict(gate_func_dict)

Restores the gate function object from dict information.

Parameters:
gate_func_dict: dict

Information on the gate function.

Returns:
gate_func: LogitGateFunction

An instance of this class.

Notes

For the format of the dict (gate_func_dict), refer to an example for to_dict() method.

property parameter_dim
Returns:
parameter_dimint

Parameter dimensionality of this gate: the number of relevant features + 1 (bias).

property relevant_feature_mask

Returns relevant feature mask.

Features whose weights are nonzero are classified as relevant features. The bias terms is always relevant, therefore its flag is not included on the result.

Returns:
relevant_idsnp.array(dtype=bool), size = (num_features)

List of flags for all features. If True, the feature is relevant that means the weight value for the feature is nonzero.

to_dict()

Generates a dict of information of the gate function.

Returns:
gate_func_dictdict

Information on the logistic-gate function in type of dict.

Examples

>>> gate_func.to_dict()
{
    'feature_ids': [1, 2, 3],
    'weights': np.array([1.2, 0.8, 3.2]),
    'bias': 2.5,
    'hard_gate': True
}

fab.model.lvprior.hme_lvprior module

class fab.model.lvprior.hme_lvprior.GateFunction

Bases: object

An abstract class for gating-functions.

Attributes:
parameter_dim

Returns parameter dimensionality of the gating-function.

Methods

calc_logprobs_on_branches(X)

Calculates log-probabilities on each child branches.

from_dict(gate_func_dict)

Restores the gate function object from dict information.

to_dict()

Generates a dict of information of the gating function.

abstract calc_logprobs_on_branches(X)

Calculates log-probabilities on each child branches.

Parameters:
Xnp.ndarray, shape = (num_samples, num_features)

Feature data.

Returns:
logprobs_b1, logprobs_b2, …np.array, size = (num_samples)

Log-probabilities on each child branches.

abstract classmethod from_dict(gate_func_dict)

Restores the gate function object from dict information.

Parameters:
gate_func_dict: dict

Information on the gate function.

Returns:
gate_func: GateFunction

An instance of this class.

abstract property parameter_dim

Returns parameter dimensionality of the gating-function.

Returns:
parameter_dimint

Parameter dimensionality of the gating-function.

abstract to_dict()

Generates a dict of information of the gating function.

Returns:
gate_dictdict

Information on the gating function.

Notes

The dict should contains a key ‘type’ which means a type of the gating function.

class fab.model.lvprior.hme_lvprior.HMELVPrior

Bases: object

An abstract class for latent variable priors of HME model.

Methods

assign_comp_by_index(X)

Assign a component index for each sample.

calc_loglikelihood(X)

Calculates the log-likelihood values of this latent variable prior with respect to the input feature data, X.

from_dict(lvprior_dict)

Restores the latent variable prior object from dict information.

to_dict()

Generates a dict of information on the prior.

update_tree_attributes()

Updates the tree attributes.

abstract assign_comp_by_index(X)

Assign a component index for each sample.

Assigning a component for each sample is executed using the information on the latent variable prior. Only one component is selected for each sample.

Parameters:
Xnp.ndarray, size = (num_samples, num_gate_features)

Input feature data.

Returns:
assigned_comp_indicesnp.array, size = (num_samples)

Selected component indices for all samples.

abstract calc_loglikelihood(X)

Calculates the log-likelihood values of this latent variable prior with respect to the input feature data, X.

Parameters:
Xnp.ndarray, size = (num_samples, num_gate_features)

Input feature data.

Returns:
loglikelihoodnp.ndarray, size = (num_samples, num_comps)

The calculated log-likelihood values for all samples with respect to all components.

abstract classmethod from_dict(lvprior_dict)

Restores the latent variable prior object from dict information.

Parameters:
lvprior_dictdict

Latent variable prior information in dict type.

Returns:
lvpriorHMELVPrior

An instance of this class.

abstract to_dict()

Generates a dict of information on the prior.

Returns:
lvprior_dictdict

Information on the latent variable prior in dict type.

abstract update_tree_attributes()

Updates the tree attributes.

In this method, the tree attributes (num_comps, num_gates, etc.) are updated with tracing nodes’ connections from the root node.

Returns:
None

Module contents