zhusuan.framework¶
BayesianNet¶
-
class
StochasticTensor
(bn, name, dist, observation=None, **kwargs)¶ Bases:
zhusuan.utils.TensorArithmeticMixin
The
StochasticTensor
class represents the stochastic nodes in aBayesianNet
.We can use any distribution available in
zhusuan.distributions
to construct a stochastic node in aBayesianNet
. For example:bn = zs.BayesianNet() x = bn.normal("x", 0., std=1.)
will build a stochastic node in
bn
with theNormal
distribution. The returnedx
will be aStochasticTensor
. 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 aBayesianNet
. - 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 thetensor
property will return the observation. This argument will overwrite the observation provided inzhusuan.framework.meta_bn.MetaBayesianNet.observe()
. - n_samples – A 0-D int32 Tensor. Number of samples generated by
this
StochasticTensor
.
-
bn
¶ The
BayesianNet
where theStochasticTensor
lives.Returns: A BayesianNet
instance.
-
cond_log_p
¶ The conditional log probability of the
StochasticTensor
, evaluated at its current value (given bytensor
).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.
-
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 theStochasticTensor
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.
- bn – A
-
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 aStochasticTensor
that follows theNormal
distribution. For any distribution available inzhusuan.distributions
, we can find a method ofBayesianNet
for creating the corresponding stochastic node. If you define your own distribution class, then there is a general methodstochastic()
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 constructingBayesianNet
. This will assign observed values to correspondingStochasticTensor
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 classMetaBayesianNet
.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.
- name – The name of the deterministic node. Must be unique in a
-
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 allStochasticTensor
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: - name – The name of the stochastic node. Must be unique in a
-
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 viewMetaBayesianNet
rather thanBayesianNet
as the model because it can accept different observations through theobserve()
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.
- f – A function that constructs and returns a
-
meta_bayesian_net
(scope=None, reuse_variables=False)¶ Transform a function that builds a
BayesianNet
into returningMetaBayesianNet
.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 aBayesianNet
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.
- scope –
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()
.