zhusuan.framework¶

BayesianNet¶

class StochasticTensor(bn, name, dist, observation=None, **kwargs)¶

Bases: zhusuan.utils.TensorArithmeticMixin

The StochasticTensor class represents the stochastic nodes in a BayesianNet.

We can use any distribution available in zhusuan.distributions to construct a stochastic node in a BayesianNet. For example:

bn = zs.BayesianNet()
x = bn.normal("x", 0., std=1.)

will build a stochastic node in bn with the Normal distribution. The returned x will be a StochasticTensor. The second line is equivalent to:

dist = zs.distributions.Normal(0., std=1.)
x = bn.stochastic("x", dist)

StochasticTensor instances are Tensor-like, which means that they can be passed into any Tensorflow operations. This makes it easy to build Bayesian networks by mixing stochastic nodes and Tensorflow primitives.

See also

For more information, please refer to Basic Concepts in ZhuSuan.

Parameters:

bn – A BayesianNet.
name – A string. The name of the StochasticTensor. Must be unique in a BayesianNet.
dist – A Distribution instance that determines the distribution used in this stochastic node.
observation – A Tensor, which matches the shape of dist. If specified, then the StochasticTensor is observed and the tensor property will return the observation. This argument will overwrite the observation provided in zhusuan.framework.meta_bn.MetaBayesianNet.observe().
n_samples – A 0-D int32 Tensor. Number of samples generated by this StochasticTensor.

bn¶

The BayesianNet where the StochasticTensor lives.

Returns:	A `BayesianNet` instance.

cond_log_p¶

The conditional log probability of the StochasticTensor, evaluated at its current value (given by tensor).

Returns:	A Tensor.

dist¶

The distribution followed by the StochasticTensor.

Returns:	A `Distribution` instance.

distribution¶

Warning

Deprecated in 0.4, will be removed in 0.4.1.

The distribution followed by the StochasticTensor.

Returns:	A `Distribution` instance.

dtype¶

The sample type of the StochasticTensor.

Returns:	A `DType` instance.

get_shape()¶

Alias of shape.

Returns:	A `TensorShape` instance.

is_observed()¶

Whether the StochasticTensor is observed or not.

Returns:	A bool.

log_prob(given)¶

Warning

Deprecated in 0.4, will be removed in 0.4.1.

Compute the log probability density (mass) function of the underlying distribution at the given value.

Parameters:	given – A Tensor.
Returns:	A Tensor. The log probability value.

name¶

The name of the StochasticTensor.

Returns:	A string.

net¶

Warning

Deprecated in 0.4, will be removed in 0.4.1.

The BayesianNet where the StochasticTensor lives.

Returns:	A `BayesianNet` instance.

prob(given)¶

Warning

Deprecated in 0.4, will be removed in 0.4.1.

Compute the probability density (mass) function of the underlying distribution at the given value.

Parameters:	given – A Tensor.
Returns:	A Tensor. The probability value.

sample(n_samples)¶

Warning

Deprecated in 0.4, will be removed in 0.4.1.

Sample from the underlying distribution.

Parameters:	n_samples – A 0-D int32 Tensor. The number of samples.
Returns:	A Tensor.

shape¶

Return the static shape of this StochasticTensor.

Returns:	A `TensorShape` instance.

tensor¶

The value of this StochasticTensor. If it is observed, then the observation is returned, otherwise samples are returned.

Returns:	A Tensor.

class BayesianNet(observed=None)¶

Bases: zhusuan.framework.bn._BayesianNet, zhusuan.framework.utils.Context

The BayesianNet class provides a convenient way to construct Bayesian networks, i.e., directed graphical models.

To start, we create a BayesianNet instance:

bn = zs.BayesianNet()

A BayesianNet keeps two kinds of nodes

deterministic nodes: they are just Tensors, usually the outputs of Tensorflow operations.
stochastic nodes: they are random variables in graphical models, and can be constructed like

w = bn.normal("w", 0., std=alpha)

Here w is a StochasticTensor that follows the Normal distribution. For any distribution available in zhusuan.distributions, we can find a method of BayesianNet for creating the corresponding stochastic node. If you define your own distribution class, then there is a general method stochastic() for doing this:

dist = CustomizedDistribution()
w = bn.stochastic("w", dist)

To observe any stochastic nodes in the network, pass a dictionary mapping of (name, Tensor) pairs when constructing BayesianNet. This will assign observed values to corresponding StochasticTensor s. For example:

bn = zs.BayesianNet(observed={"w": w_obs})

will set w to be observed.

Note

The observation passed must have the same type and shape as the StochasticTensor.

A useful case is that we often need to pass different observations more than once into the Bayesian network, for which we provide meta_bayesian_net() decorator and another abstract class MetaBayesianNet.

See also

For more details and examples, please refer to Basic Concepts in ZhuSuan.

Parameters:	observed – A dictionary of (string, Tensor) pairs, which maps from names of stochastic nodes to their observed values.

bag_of_categoricals(name, logits, normalize_logits=True, group_ndims=0, dtype=tf.int32, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the UnnormalizedMultinomial distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See UnnormalizedMultinomial for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

bernoulli(name, logits, n_samples=None, group_ndims=0, dtype=tf.int32, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Bernoulli distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Bernoulli for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

beta(name, alpha, beta, n_samples=None, group_ndims=0, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Beta distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Beta for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

bin_concrete(name, temperature, logits, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the BinConcrete distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See BinConcrete for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

bin_gumbel_softmax(name, temperature, logits, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the BinConcrete distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See BinConcrete for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

binomial(name, logits, n_experiments, n_samples=None, group_ndims=0, dtype=tf.int32, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Binomial distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Binomial for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

categorical(name, logits, n_samples=None, group_ndims=0, dtype=tf.int32, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Categorical distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Categorical for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

concrete(name, temperature, logits, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Concrete distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Concrete for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

cond_log_prob(name_or_names)¶

The conditional log probabilities of stochastic nodes, evaluated at their current values (given by StochasticTensor.tensor).

Parameters:	name_or_names – A string or a list of strings. Name(s) of the stochastic nodes.
Returns:	A Tensor or a list of Tensors.

deterministic(name, input_tensor)¶

Add a named deterministic node in this BayesianNet.

Parameters:	name – The name of the deterministic node. Must be unique in a `BayesianNet`. input_tensor – A Tensor. The value of the deterministic node.
Returns:	A Tensor. The same as input_tensor.

dirichlet(name, alpha, n_samples=None, group_ndims=0, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Dirichlet distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Dirichlet for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

discrete(name, logits, n_samples=None, group_ndims=0, dtype=tf.int32, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Categorical distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Categorical for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

exp_concrete(name, temperature, logits, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the ExpConcrete distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See ExpConcrete for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

exp_gumbel_softmax(name, temperature, logits, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the ExpConcrete distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See ExpConcrete for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

fold_normal(name, mean=0.0, _sentinel=None, std=None, logstd=None, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the FoldNormal distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See FoldNormal for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

gamma(name, alpha, beta, n_samples=None, group_ndims=0, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Gamma distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Gamma for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

get(name_or_names)¶

Get one or several nodes by name. For a single node, one can also use dictionary-like bn[name] to get the node.

Parameters:	name_or_names – A string or a tuple(list) of strings.
Returns:	A Tensor/`StochasticTensor` or a list of Tensor/`StochasticTensor` s.

classmethod get_context()¶

classmethod get_contexts()¶

gumbel_softmax(name, temperature, logits, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Concrete distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Concrete for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

inverse_gamma(name, alpha, beta, n_samples=None, group_ndims=0, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the InverseGamma distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See InverseGamma for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

laplace(name, loc, scale, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Laplace distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Laplace for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

local_log_prob(name_or_names)¶: Note

Deprecated in 0.4, will be removed in 0.4.1.

log_joint()¶

The default log joint probability of this BayesianNet. It works by summing over all the conditional log probabilities of stochastic nodes evaluated at their current values (samples or observations).

Returns:	A Tensor.

matrix_variate_normal_cholesky(name, mean, u_tril, v_tril, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the MatrixVariateNormalCholesky distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See MatrixVariateNormalCholesky for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

multinomial(name, logits, n_experiments, normalize_logits=True, n_samples=None, group_ndims=0, dtype=tf.int32, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Multinomial distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Multinomial for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

multivariate_normal_cholesky(name, mean, cov_tril, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the MultivariateNormalCholesky distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See MultivariateNormalCholesky for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

nodes¶

The dictionary of all named nodes in this BayesianNet, including all StochasticTensor s and named deterministic nodes.

Returns:	A dict.

normal(name, mean=0.0, _sentinel=None, std=None, logstd=None, group_ndims=0, n_samples=None, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Normal distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Normal for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

onehot_categorical(name, logits, n_samples=None, group_ndims=0, dtype=tf.int32, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the OnehotCategorical distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See OnehotCategorical for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

onehot_discrete(name, logits, n_samples=None, group_ndims=0, dtype=tf.int32, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the OnehotCategorical distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See OnehotCategorical for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

outputs(name_or_names)¶: Note

Deprecated in 0.4, will be removed in 0.4.1.

poisson(name, rate, n_samples=None, group_ndims=0, dtype=tf.int32, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Poisson distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Poisson for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

query(name_or_names, outputs=False, local_log_prob=False)¶: Note

Deprecated in 0.4, will be removed in 0.4.1.

stochastic(name, dist, **kwargs)¶

Add a stochastic node in this BayesianNet.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`. dist – The followed distribution. kwargs – Optional parameters to specify the sampling behaviors, n_samples: A 0-D int32 Tensor. Number of samples generated.
Returns:	A `StochasticTensor`.

uniform(name, minval=0.0, maxval=1.0, n_samples=None, group_ndims=0, is_reparameterized=True, check_numerics=False, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the Uniform distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See Uniform for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

unnormalized_multinomial(name, logits, normalize_logits=True, group_ndims=0, dtype=tf.int32, **kwargs)¶

Add a stochastic node in this BayesianNet that follows the UnnormalizedMultinomial distribution.

Parameters:	name – The name of the stochastic node. Must be unique in a `BayesianNet`.

See UnnormalizedMultinomial for more information about the other arguments.

Returns:	A `StochasticTensor` instance.

MetaBayesianNet¶

class MetaBayesianNet(f, args=None, kwargs=None, scope=None, reuse_variables=False)¶

Bases: object

A lazy-constructed BayesianNet. Conceptually it’s better to view MetaBayesianNet rather than BayesianNet as the model because it can accept different observations through the observe() method.

The suggested usage is through the meta_bayesian_net() decorator.

See also

For more information, please refer to Basic Concepts in ZhuSuan.

Parameters:	f – A function that constructs and returns a `BayesianNet`. args – A list. Ordered arguments that will be passed into f. kwargs – A dictionary. Named arguments that will be passed into f. scope – A string. The scope name passed to tensorflow variable_scope(). reuse_variables – A bool. Whether to reuse tensorflow Variables in repeated calls of `observe()`.

log_joint¶

The log joint function of this model. Can be overwritten as:

meta_bn = build_model(...)

def log_joint(bn):
    return ...

meta_bn.log_joint = log_joint

observe(**kwargs)¶

Construct a BayesianNet given observations.

Parameters:	kwargs – A dictionary that maps from node names to their observed values.
Returns:	A `BayesianNet` instance.

meta_bayesian_net(scope=None, reuse_variables=False)¶

Transform a function that builds a BayesianNet into returning MetaBayesianNet.

The suggested usage is as a decorator:

@meta_bayesian_net(scope=..., reuse_variables=True)
def build_model(...):
    bn = zs.BayesianNet()
    ...
    return bn

The decorated function will return a MetaBayesianNet instance instead of a BayesianNet instance.

See also

For more details and examples, please refer to Basic Concepts in ZhuSuan.

Parameters:	scope – A string. The scope name passed to tensorflow variable_scope(). reuse_variables – A bool. Whether to reuse tensorflow Variables in repeated calls of `MetaBayesianNet.observe()`.
Returns:	The transformed function.

Utils¶

get_backward_ops(seed_tensors, treat_as_inputs=None)¶

Get backward ops from inputs to seed_tensors by topological order.

Parameters:	seed_tensors – A Tensor or list of Tensors, for which to get all preceding Tensors. treat_as_inputs – None or a list of Tensors that is treated as inputs during the search (where to stop searching the backward graph).
Returns:	A list of tensorflow Operation s in topological order.

reuse_variables(scope)¶

A decorator for transparent reuse of tensorflow Variables in a function. The decorated function will automatically create variables the first time they are called and reuse them thereafter.

Note

This decorator is internally implemented by tensorflow’s make_template() function. See its doc for requirements on the target function.

Parameters:	scope – A string. The scope name passed to tensorflow variable_scope().

reuse(scope)¶: (Deprecated) Alias of reuse_variables().