Merge pull request #3389 from jmloyola/add_data_container

Add data container and pm.set_data

Author: twiecki

RELEASE-NOTES.md

@@ -4,6 +4,8 @@
 
 ### New features
 
+- Add data container class (`Data`) that wraps the theano SharedVariable class and let the model be aware of its inputs and outputs.
+- Add function `set_data` to update variables defined as `Data`.
 - `Mixture` now supports mixtures of multidimensional probability distributions, not just lists of 1D distributions.
 - `GLM.from_formula` and `LinearComponent.from_formula` can extract variables from the calling scope. Customizable via the new `eval_env` argument. Fixing #3382.
 

docs/source/notebooks/bayesian_neural_network_advi.ipynb

@@ -4,6 +4,7 @@ Gallery.contents = {
     "PyMC3_and_Theano.rst": "Basics",
     "Probability_Distributions.rst": "Basics",
     "Gaussian_Processes.rst": "Basics",
+    "data_container": "Basics",
     "sampling_compound_step": "Deep dives",
     "sampler-stats": "Deep dives",
     "Diagnosing_biased_Inference_with_Divergences": "Deep dives",

docs/source/notebooks/data_container.ipynb

@@ -12,7 +12,8 @@
     'get_data',
     'GeneratorAdapter',
     'Minibatch',
-    'align_minibatches'
+    'align_minibatches',
+    'Data',
 ]
 
 
@@ -385,3 +386,67 @@ def align_minibatches(batches=None):
                 raise TypeError('{b} is not a Minibatch')
             for rng in Minibatch.RNG[id(b)]:
                 rng.seed()
+
+
+class Data:
+    """Data container class that wraps the theano SharedVariable class
+    and let the model be aware of its inputs and outputs.
+
+    Parameters
+    ----------
+    name : str
+        The name for this variable
+    value
+        A value to associate with this variable
+
+    Examples
+    --------
+
+    .. code:: ipython
+
+        >>> import pymc3 as pm
+        >>> import numpy as np
+        >>> # We generate 10 datasets
+        >>> true_mu = [np.random.randn() for _ in range(10)]
+        >>> observed_data = [mu + np.random.randn(20) for mu in true_mu]
+
+        >>> with pm.Model() as model:
+        ...     data = pm.Data('data', observed_data[0])
+        ...     mu = pm.Normal('mu', 0, 10)
+        ...     pm.Normal('y', mu=mu, sigma=1, observed=data)
+
+    .. code:: ipython
+
+        >>> # Generate one trace for each dataset
+        >>> traces = []
+        >>> for data_vals in observed_data:
+        ...     with model:
+        ...         # Switch out the observed dataset
+        ...         pm.set_data({'data': data_vals})
+        ...         traces.append(pm.sample())
+
+    To set the value of the data container variable, check out
+    :func:`pm.set_data()`.
+
+    For more information, take a look at this example notebook
+    https://docs.pymc.io/notebooks/data_container.html
+    """
+    def __new__(self, name, value):
+        # `pm.model.pandas_to_array` takes care of parameter `value` and
+        # transforms it to something digestible for pymc3
+        shared_object = theano.shared(pm.model.pandas_to_array(value), name)
+
+        # To draw the node for this variable in the graphviz Digraph we need
+        # its shape.
+        shared_object.dshape = tuple(shared_object.shape.eval())
+
+        # Add data container to the named variables of the model.
+        try:
+            model = pm.Model.get_context()
+        except TypeError:
+            raise TypeError("No model on context stack, which is needed to "
+                            "instantiate a data container. Add variable "
+                            "inside a 'with model:' block.")
+        model.add_random_variable(shared_object)
+
+        return shared_object