Better docs for mini-batch and total_size (#3221)

Author: ferrine

docs/source/notebooks/variational_api_quickstart.ipynb

@@ -1451,7 +1451,9 @@
     "\n",
     "Now let's use minibatches. At every iteration, we will draw 500 random values:\n",
     "\n",
-    "> Remember to set `total_size` in observed"
+    "> Remember to set `total_size` in observed\n",
+    "\n",
+    "**total_size** is an important parameter that allows pymc3 to infer the right way of rescaling densities. If it is not set, you are likely to get completely wrong results. For more information please refer to the comprehensive documentation of `pm.Minibatch`."
    ]
   },
   {
@@ -1684,7 +1686,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.0b4"
+   "version": "3.6.3"
   }
  },
  "nbformat": 4,

pymc3/data.py

@@ -124,6 +124,14 @@ class Minibatch(tt.TensorVariable):
     minibatch : minibatch tensor
         Used for training
 
+    Notes
+    -----
+    Below is a common use case of Minibatch within the variational inference.
+    Importantly, we need to make PyMC3 "aware" of minibatch being used in inference.
+    Otherwise, we will get the wrong :math:`logp` for the model.
+    To do so, we need to pass the `total_size` parameter to the observed node, which correctly scales
+    the density of the model logp that is affected by Minibatch. See more in examples below.
+
     Examples
     --------
     Consider we have data