doc string for variational and importance

Author: thjashin

tests/framework/test_base.py

@@ -206,10 +206,10 @@ def build_meta_bn():
             self.assertNear(log_pc_2_out, log_pc_t_out, 1e-6)
 
 
-class TestReuse(tf.test.TestCase):
+class TestReuseVariables(tf.test.TestCase):
 
-    def test_legacy_reuse(self):
-        @reuse("test")
+    def test_reuse_variables(self):
+        @reuse_variables("test")
         def f():
             w = tf.get_variable("w", shape=[])
             return w
@@ -233,7 +233,7 @@ def test_meta_bn(self):
         # the basic usage is tested in TestBayesianNet. corner cases here
         @meta_bayesian_net(scope='scp', reuse_variables=False)
         def build_mbn(var_to_return):
-            return TestReuse._generate_bn(var_to_return)
+            return TestReuseVariables._generate_bn(var_to_return)
 
         with tf.variable_scope('you_might_want_do_this'):
             mbn = build_mbn('a_mean')
@@ -243,21 +243,21 @@ def build_mbn(var_to_return):
             self.assertNotEqual(m1.name, m2.name)
         with tf.variable_scope('when_you_are_perfectly_conscious'):
             _, m2 = build_mbn('a_mean').observe()
-        self.assertNotEquals(m1.name, m2.name)
+        self.assertNotEqual(m1.name, m2.name)
 
         @meta_bayesian_net(scope='scp', reuse_variables=True)
         def build_mbn(var_to_return):
-            return TestReuse._generate_bn(var_to_return)
+            return TestReuseVariables._generate_bn(var_to_return)
 
         meta_bn = build_mbn('a_mean')
         _, m1 = meta_bn.observe()
         _, m2 = meta_bn.observe()
         _, m3 = build_mbn('a_mean').observe()
-        self.assertEquals(m1.name, m2.name)
+        self.assertEqual(m1.name, m2.name)
         self.assertNotEqual(m1.name, m3.name)
 
         with self.assertRaisesRegexp(ValueError, 'Cannot reuse'):
             @meta_bayesian_net(reuse_variables=True)
             def mbn(var_to_return):
-                return TestReuse._generate_bn(var_to_return)
+                return TestReuseVariables._generate_bn(var_to_return)
             mbn('a_mean')

tests/variational/test_inclusive_kl.py

@@ -41,35 +41,35 @@ def log_joint(observed):
             with self.assertRaisesRegexp(NotImplementedError, err_msg):
                 sess.run(lower_bound)
 
-    def test_rws(self):
+    def test_importance(self):
         eps_samples = tf.convert_to_tensor(self._n01_samples)
         mu = tf.constant(2.)
         sigma = tf.constant(3.)
         qx_samples = tf.stop_gradient(eps_samples * sigma + mu)
         q = Normal(mean=mu, std=sigma)
         log_qx = q.log_prob(qx_samples)
 
-        def _check_rws(x_mean, x_std, threshold):
+        def _check_importance(x_mean, x_std, threshold):
             def log_joint(observed):
                 p = Normal(mean=x_mean, std=x_std)
                 return p.log_prob(observed['x'])
 
             klpq_obj = klpq(log_joint, observed={},
                             latent={'x': [qx_samples, log_qx]}, axis=0)
-            cost = klpq_obj.rws()
-            rws_grads = tf.gradients(cost, [mu, sigma])
+            cost = klpq_obj.importance()
+            importance_grads = tf.gradients(cost, [mu, sigma])
             true_cost = _kl_normal_normal(x_mean, x_std, mu, sigma)
             true_grads = tf.gradients(true_cost, [mu, sigma])
 
             with self.session(use_gpu=True) as sess:
-                g1 = sess.run(rws_grads)
+                g1 = sess.run(importance_grads)
                 g2 = sess.run(true_grads)
-                # print('rws_grads:', g1)
+                # print('importance_grads:', g1)
                 # print('true_grads:', g2)
                 self.assertAllClose(g1, g2, threshold, threshold)
 
-        _check_rws(0., 1., 0.01)
-        _check_rws(2., 3., 0.02)
+        _check_importance(0., 1., 0.01)
+        _check_importance(2., 3., 0.02)
 
         single_sample = tf.stop_gradient(tf.random_normal([]) * sigma + mu)
         single_log_q = q.log_prob(single_sample)
@@ -86,7 +86,7 @@ def log_joint(observed):
             # Cause all warnings to always be triggered.
             warnings.simplefilter("always")
             # Trigger a warning.
-            single_sample_obj.rws()
+            single_sample_obj.importance()
             self.assertTrue(issubclass(w[-1].category, UserWarning))
             self.assertTrue("biased and inaccurate when you're using only "
                             "a single sample" in str(w[-1].message))

zhusuan/evaluation.py

@@ -9,7 +9,7 @@
 import tensorflow as tf
 import numpy as np
 
-from zhusuan.utils import log_mean_exp, merge_dicts
+from zhusuan.utils import merge_dicts
 from zhusuan.variational import ImportanceWeightedObjective
 
 
@@ -20,24 +20,29 @@
 
 
 def is_loglikelihood(meta_bn, observed, latent=None, axis=None,
-                     proposal=None, allow_default=False):
+                     proposal=None):
     """
     Marginal log likelihood (:math:`\log p(x)`) estimates using self-normalized
     importance sampling.
 
-    :param log_joint: A function that accepts a dictionary argument of
+    :param meta_bn: A :class:`~zhusuan.framework.meta_bn.MetaBayesianNet`
+        instance or a log joint probability function.
+        For the latter, it must accepts a dictionary argument of
         ``(string, Tensor)`` pairs, which are mappings from all
-        `StochasticTensor` names in the model to their observed values. The
+        node names in the model to their observed values. The
         function should return a Tensor, representing the log joint likelihood
         of the model.
     :param observed: A dictionary of ``(string, Tensor)`` pairs. Mapping from
-        names of observed `StochasticTensor` s to their values
+        names of observed stochastic nodes to their values.
     :param latent: A dictionary of ``(string, (Tensor, Tensor))`` pairs.
-        Mapping from names of latent `StochasticTensor` s to their samples and
-        log probabilities.
+        Mapping from names of latent stochastic nodes to their samples and
+        log probabilities. `latent` and `proposal` are mutually exclusive.
     :param axis: The sample dimension(s) to reduce when computing the
-        outer expectation in the importance sampling estimation. If None, no
-        dimension is reduced.
+        outer expectation in the objective. If ``None``, no dimension is
+        reduced.
+    :param proposal: A :class:`~zhusuan.framework.bn.BayesianNet` instance
+        that defines the proposal distributions of latent nodes.
+        `proposal` and `latent` are mutually exclusive.
 
     :return: A Tensor. The estimated log likelihood of observed data.
     """
@@ -46,8 +51,7 @@ def is_loglikelihood(meta_bn, observed, latent=None, axis=None,
         observed,
         latent=latent,
         axis=axis,
-        variational=proposal,
-        allow_default=allow_default).tensor
+        variational=proposal).tensor
 
 
 class AIS:

zhusuan/framework/utils.py

@@ -5,6 +5,7 @@
 from __future__ import print_function
 from __future__ import division
 from collections import deque, OrderedDict
+import warnings
 
 import tensorflow as tf
 
@@ -109,5 +110,8 @@ def reuse(scope):
     """
     (Deprecated) Alias of :func:`reuse_variables`.
     """
-    # TODO: raise warning
+    warnings.warn(
+        "The `reuse()` function has been renamed to `reuse_variables()`, "
+        "`reuse()` will be removed in the coming version (0.4.1)",
+        DeprecationWarning)
     return reuse_variables(scope)

zhusuan/variational/exclusive_kl.py

@@ -24,7 +24,14 @@ class EvidenceLowerBoundObjective(VariationalObjective):
     calling :func:`elbo`::
 
         # lower_bound is an EvidenceLowerBoundObjective instance
-        lower_bound = zs.variational.elbo(log_joint, observed, latent)
+        lower_bound = zs.variational.elbo(
+            meta_bn, observed, variational=variational, axis=0)
+
+    Here ``meta_bn`` is a :class:`~zhusuan.framework.meta_bn.MetaBayesianNet`
+    instance representing the model to be inferred. ``variational`` is
+    a :class:`~zhusuan.framework.bn.BayesianNet` instance that defines the
+    variational family. ``axis`` is the index of the sample dimension used
+    to estimate the expectation when computing the objective.
 
     Instances of :class:`EvidenceLowerBoundObjective` are Tensor-like. They
     can be automatically or manually cast into Tensors when fed into Tensorflow
@@ -60,8 +67,7 @@ class EvidenceLowerBoundObjective(VariationalObjective):
 
         # optimize the surrogate cost wrt. variational parameters
         optimizer = tf.train.AdamOptimizer(learning_rate)
-        infer_op = optimizer.minimize(cost,
-                                      var_list=variational_parameters)
+        infer_op = optimizer.minimize(cost, var_list=variational_parameters)
         with tf.Session() as sess:
             for _ in range(n_iters):
                 _, lb = sess.run([infer_op, lower_bound], feed_dict=...)
@@ -81,11 +87,9 @@ class EvidenceLowerBoundObjective(VariationalObjective):
     optimize the class instance::
 
         # optimize wrt. model parameters
-        learn_op = optimizer.minimize(-lower_bound,
-                                      var_list=model_parameters)
+        learn_op = optimizer.minimize(-lower_bound, var_list=model_parameters)
         # or
-        # learn_op = optimizer.minimize(cost,
-        #                               var_list=model_parameters)
+        # learn_op = optimizer.minimize(cost, var_list=model_parameters)
         # both ways are correct
 
     Or we can do inference and learning jointly by optimize over both
@@ -95,30 +99,34 @@ class EvidenceLowerBoundObjective(VariationalObjective):
         infer_and_learn_op = optimizer.minimize(
             cost, var_list=model_and_variational_parameters)
 
-    :param log_joint: A function that accepts a dictionary argument of
+    :param meta_bn: A :class:`~zhusuan.framework.meta_bn.MetaBayesianNet`
+        instance or a log joint probability function.
+        For the latter, it must accepts a dictionary argument of
         ``(string, Tensor)`` pairs, which are mappings from all
-        `StochasticTensor` names in the model to their observed values. The
+        node names in the model to their observed values. The
         function should return a Tensor, representing the log joint likelihood
         of the model.
     :param observed: A dictionary of ``(string, Tensor)`` pairs. Mapping from
-        names of observed `StochasticTensor` s to their values.
+        names of observed stochastic nodes to their values.
     :param latent: A dictionary of ``(string, (Tensor, Tensor))`` pairs.
-        Mapping from names of latent `StochasticTensor` s to their samples and
-        log probabilities.
+        Mapping from names of latent stochastic nodes to their samples and
+        log probabilities. `latent` and `variational` are mutually exclusive.
     :param axis: The sample dimension(s) to reduce when computing the
         outer expectation in the objective. If ``None``, no dimension is
         reduced.
+    :param variational: A :class:`~zhusuan.framework.bn.BayesianNet` instance
+        that defines the variational family.
+        `variational` and `latent` are mutually exclusive.
     """
 
     def __init__(self, meta_bn, observed, latent=None, axis=None,
-                 variational=None, allow_default=False):
+                 variational=None):
         self._axis = axis
         super(EvidenceLowerBoundObjective, self).__init__(
             meta_bn,
             observed,
             latent=latent,
-            variational=variational,
-            allow_default=allow_default)
+            variational=variational)
 
     def _objective(self):
         lower_bound = self._log_joint_term()
@@ -223,27 +231,31 @@ def reinforce(self,
             return cost
 
 
-def elbo(meta_bn, observed, latent=None, axis=None, variational=None,
-         allow_default=False):
+def elbo(meta_bn, observed, latent=None, axis=None, variational=None):
     """
     The evidence lower bound (ELBO) objective for variational inference. The
     returned value is a :class:`EvidenceLowerBoundObjective` instance.
 
     See :class:`EvidenceLowerBoundObjective` for examples of usage.
 
-    :param log_joint: A function that accepts a dictionary argument of
+    :param meta_bn: A :class:`~zhusuan.framework.meta_bn.MetaBayesianNet`
+        instance or a log joint probability function.
+        For the latter, it must accepts a dictionary argument of
         ``(string, Tensor)`` pairs, which are mappings from all
-        `StochasticTensor` names in the model to their observed values. The
+        node names in the model to their observed values. The
         function should return a Tensor, representing the log joint likelihood
         of the model.
     :param observed: A dictionary of ``(string, Tensor)`` pairs. Mapping from
-        names of observed `StochasticTensor` s to their values.
+        names of observed stochastic nodes to their values.
     :param latent: A dictionary of ``(string, (Tensor, Tensor))`` pairs.
-        Mapping from names of latent `StochasticTensor` s to their samples and
-        log probabilities.
+        Mapping from names of latent stochastic nodes to their samples and
+        log probabilities. `latent` and `variational` are mutually exclusive.
     :param axis: The sample dimension(s) to reduce when computing the
         outer expectation in the objective. If ``None``, no dimension is
         reduced.
+    :param variational: A :class:`~zhusuan.framework.bn.BayesianNet` instance
+        that defines the variational family.
+        `variational` and `latent` are mutually exclusive.
 
     :return: An :class:`EvidenceLowerBoundObjective` instance.
     """
@@ -252,5 +264,4 @@ def elbo(meta_bn, observed, latent=None, axis=None, variational=None,
         observed,
         latent=latent,
         axis=axis,
-        variational=variational,
-        allow_default=allow_default)
+        variational=variational)