Repair the plot of pm.Interpolated and add an example for pm.Deterministic

Makefile

@@ -52,16 +52,18 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(SOURCEDIR)/api/generated
 	rm -rf $(SOURCEDIR)/api/**/generated
 	rm -rf $(SOURCEDIR)/api/**/classmethods
+	rm -rf $(SOURCEDIR)/contributing/private_api/generated
 	rm -rf $(SOURCEDIR)/contributing/private_api/**/generated
 	rm -rf $(SOURCEDIR)/contributing/private_api/**/classmethods
 	rm -rf docs/jupyter_execute
 
 html:
 	$(SPHINXBUILD) $(SOURCEDIR) $(BUILDDIR) -b html
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)."
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -199,4 +201,4 @@ pseudoxml:
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
 
 serve: html
-	cd $(BUILDDIR)/html && python -m http.server
+	python -m http.server --directory $(BUILDDIR)

pymc/distributions/continuous.py

@@ -3711,16 +3711,16 @@ class Interpolated(BoundedContinuous):
         from scipy.stats import gamma
         plt.style.use('arviz-darkgrid')
         rv = gamma(1.99)
-        x = np.linspace(rv.ppf(0.01),rv.ppf(0.99), 1000)
+        x = np.linspace(rv.ppf(0.01), rv.ppf(0.99), 1000)
         points = np.linspace(x[0], x[-1], 50)
         pdf = rv.pdf(points)
         interpolated = pm.Interpolated.dist(points, pdf)
         fig, ax = plt.subplots(1, 1)
-        ax.plot(x, rv.pdf(x), 'C0', linestyle = '--',  label='Original Gamma pdf',alpha=0.8,lw=2)
-        ax.plot(points, pdf, color='black', marker='o', label='Lattice Points',alpha=0.5,linestyle='')
-        ax.plot(x, np.exp(interpolated.logp(x).eval()),'C1',label='Interpolated pdf',alpha=0.8,lw=3)
-        r = interpolated.random(size=1000)
-        ax.hist(r, density=True, alpha=0.4,align ='mid',color='grey')
+        ax.plot(x, rv.pdf(x), 'C0', linestyle = '--',  label='Original Gamma pdf', alpha=0.8, lw=2)
+        ax.plot(points, pdf, color='black', marker='o', label='Lattice Points', alpha=0.5, linestyle='')
+        ax.plot(x, np.exp(pm.logp(interpolated, x).eval()), 'C1', label='Interpolated pdf', alpha=0.8, lw=3)
+        r = pm.draw(interpolated, draws=1000)
+        ax.hist(r, density=True, alpha=0.4, align ='mid', color='grey')
         ax.legend(loc='best', frameon=False)
         plt.show()
 
@@ -4008,6 +4008,7 @@ class PolyaGamma(PositiveContinuous):
     .. math::
 
        f(x \mid h, z) = cosh^h(\frac{z}{2})e^{-\frac{1}{2}xz^2}f(x \mid h, 0),
+
     where :math:`f(x \mid h, 0)` is the pdf of a :math:`PG(h, 0)` variable.
     Notice that the pdf of this distribution is expressed as an alternating-sign
     sum of inverse-Gaussian densities.

pymc/distributions/transforms.py

@@ -194,7 +194,7 @@ class Interval(IntervalTransform):
     lower : int or float, optional
         Lower bound of the interval transform. Must be a constant finite value.
         By default (``lower=None``), the interval is not bounded below.
-    upper : int or float, optinoal
+    upper : int or float, optional
         Upper bound of the interval transform. Must be a constant finite value.
         By default (``upper=None``), the interval is not bounded above.
     bounds_fn : callable, optional

pymc/model.py

@@ -1937,11 +1937,52 @@ def Point(*args, filter_model_vars=False, **kwargs) -> Dict[str, np.ndarray]:
 
 
 def Deterministic(name, var, model=None, dims=None, auto=False):
-    """Create a named deterministic variable
+    """Create a named deterministic variable.
+
+    Deterministic nodes are only deterministic given all of their inputs, i.e.
+    they don't add randomness to the model.  They are generally used to record
+    an intermediary result.
+
+    Indeed, PyMC allows for arbitrary combinations of random variables, for
+    example in the case of a logistic regression
+
+    .. code:: python
+
+        with pm.Model():
+            alpha = pm.Normal("alpha", 0, 1)
+            intercept = pm.Normal("intercept", 0, 1)
+            p = pm.math.invlogit(alpha * x + intercept)
+            outcome = pm.Bernoulli("outcome", p, observed=outcomes)
+
+
+    but doesn't memorize the fact that the expression ``pm.math.invlogit(alpha *
+    x + intercept)`` has been affected to the variable ``p``.  If the quantity
+    ``p`` is important and one would like to track its value in the sampling
+    trace, then one can use a deterministic node:
+
+    .. code:: python
+
+        with pm.Model():
+            alpha = pm.Normal("alpha", 0, 1)
+            intercept = pm.Normal("intercept", 0, 1)
+            p = pm.Deterministic("p", pm.math.invlogit(alpha * x + intercept))
+            outcome = pm.Bernoulli("outcome", p, observed=outcomes)
+
+    These two models are strictly equivalent from a mathematical point of view.
+    However, in the first case, the inference data will only contain values for
+    the variables ``alpha``, ``intercept`` and ``outcome``.  In the second, it
+    will also contain sampled values of ``p`` for each of the observed points.
 
     Notes
     -----
-    Deterministic nodes are ones that given all the inputs are not random variables
+    Even though adding a Deterministic node forces PyMC to compute this
+    expression, which could have been optimized away otherwise, this doesn't come
+    with a performance cost.  Indeed, Deterministic nodes are computed outside
+    the main computation graph, which can be optimized as though there was no
+    Deterministic nodes.  Whereas the optimized graph can be evaluated thousands
+    of times during a NUTS step, the Deterministic quantities are just
+    computeed once at the end of the step, with the final values of the other
+    random variables.
 
     Parameters
     ----------