docs: Truncate floating point docstring examples to 8 decimal places (#…

…1726)

* Truncate all floating point values in docstring examples to 8 decimal
places to harden the docstrings against small changes in backends, operating
systems, and code that could cause fluctuations beyond a reasonable level
of interest for final results. The choice of 8 decimal places is to match
the default number of decimal places for reprs for most array libraries.
   - Use doctest's ELLIPSIS option to truncate floating point numbers
   - c.f. https://docs.python.org/3/library/doctest.html#doctest.ELLIPSIS

README.rst

@@ -49,8 +49,8 @@ This is how you use the ``pyhf`` Python API to build a statistical model and run
    >>> CLs_obs, CLs_exp = pyhf.infer.hypotest(
    ...     test_mu, data, model, test_stat="qtilde", return_expected=True
    ... )
-   >>> print(f"Observed: {CLs_obs:.9f}, Expected: {CLs_exp:.9f}")
-   Observed: 0.052514974, Expected: 0.064453205
+   >>> print(f"Observed: {CLs_obs:.8f}, Expected: {CLs_exp:.8f}")
+   Observed: 0.05251497, Expected: 0.06445321
 
 Alternatively the statistical model and observational data can be read from its serialized JSON representation (see next section).
 
@@ -66,8 +66,8 @@ Alternatively the statistical model and observational data can be read from its
    >>> CLs_obs, CLs_exp = pyhf.infer.hypotest(
    ...     test_mu, data, model, test_stat="qtilde", return_expected=True
    ... )
-   >>> print(f"Observed: {CLs_obs:.9f}, Expected: {CLs_exp:.9f}")
-   Observed: 0.359984092, Expected: 0.359984092
+   >>> print(f"Observed: {CLs_obs:.8f}, Expected: {CLs_exp:.8f}")
+   Observed: 0.35998409, Expected: 0.35998409
 
 
 Finally, you can also use the command line interface that ``pyhf`` provides

src/pyhf/infer/calculators.py

@@ -618,7 +618,7 @@ def expected_value(self, nsigma):
             >>> samples = normal.sample((100,))
             >>> dist = pyhf.infer.calculators.EmpiricalDistribution(samples)
             >>> dist.expected_value(nsigma=1)
-            6.15094381209...
+            6.15094381...
 
             >>> import pyhf
             >>> import numpy.random as random

src/pyhf/probability.py

@@ -170,10 +170,10 @@ def log_prob(self, value):
             >>> independent = pyhf.probability.Independent(poissons)
             >>> values = pyhf.tensorlib.astensor([8.0, 9.0])
             >>> independent.log_prob(values)
-            -4.262483801927939
+            -4.26248380...
             >>> broadcast_value = pyhf.tensorlib.astensor([11.0])
             >>> independent.log_prob(broadcast_value)
-            -4.347743645878765
+            -4.34774364...
 
         Args:
             value (:obj:`tensor` or :obj:`float`): The value at which to evaluate the distribution

src/pyhf/tensor/numpy_backend.py

@@ -414,7 +414,7 @@ def poisson(self, n, lam):
             >>> import pyhf
             >>> pyhf.set_backend("numpy")
             >>> pyhf.tensorlib.poisson(5., 6.)
-            0.16062314104797995
+            0.16062314...
             >>> values = pyhf.tensorlib.astensor([5., 9.])
             >>> rates = pyhf.tensorlib.astensor([6., 8.])
             >>> pyhf.tensorlib.poisson(values, rates)
@@ -457,7 +457,7 @@ def normal(self, x, mu, sigma):
             >>> import pyhf
             >>> pyhf.set_backend("numpy")
             >>> pyhf.tensorlib.normal(0.5, 0., 1.)
-            0.3520653267642995
+            0.35206532...
             >>> values = pyhf.tensorlib.astensor([0.5, 2.0])
             >>> means = pyhf.tensorlib.astensor([0., 2.3])
             >>> sigmas = pyhf.tensorlib.astensor([1., 0.8])
@@ -483,7 +483,7 @@ def normal_cdf(self, x, mu=0, sigma=1):
             >>> import pyhf
             >>> pyhf.set_backend("numpy")
             >>> pyhf.tensorlib.normal_cdf(0.8)
-            0.7881446014166034
+            0.78814460...
             >>> values = pyhf.tensorlib.astensor([0.8, 2.0])
             >>> pyhf.tensorlib.normal_cdf(values)
             array([0.7881446 , 0.97724987])

src/pyhf/tensor/tensorflow_backend.py

@@ -451,7 +451,7 @@ def poisson_logpdf(self, n, lam):
             >>> pyhf.set_backend("tensorflow")
             >>> t = pyhf.tensorlib.poisson_logpdf(5., 6.)
             >>> print(t) # doctest:+ELLIPSIS
-            tf.Tensor(-1.8286943966417..., shape=(), dtype=float64)
+            tf.Tensor(-1.82869439..., shape=(), dtype=float64)
             >>> values = pyhf.tensorlib.astensor([5., 9.])
             >>> rates = pyhf.tensorlib.astensor([6., 8.])
             >>> t = pyhf.tensorlib.poisson_logpdf(values, rates)
@@ -495,7 +495,7 @@ def poisson(self, n, lam):
             >>> pyhf.set_backend("tensorflow")
             >>> t = pyhf.tensorlib.poisson(5., 6.)
             >>> print(t) # doctest:+ELLIPSIS
-            tf.Tensor(0.1606231410479..., shape=(), dtype=float64)
+            tf.Tensor(0.16062314..., shape=(), dtype=float64)
             >>> values = pyhf.tensorlib.astensor([5., 9.])
             >>> rates = pyhf.tensorlib.astensor([6., 8.])
             >>> t = pyhf.tensorlib.poisson(values, rates)
@@ -524,8 +524,8 @@ def normal_logpdf(self, x, mu, sigma):
             >>> import pyhf
             >>> pyhf.set_backend("tensorflow")
             >>> t = pyhf.tensorlib.normal_logpdf(0.5, 0., 1.)
-            >>> print(t)
-            tf.Tensor(-1.0439385332046727, shape=(), dtype=float64)
+            >>> print(t) # doctest:+ELLIPSIS
+            tf.Tensor(-1.04393853..., shape=(), dtype=float64)
             >>> values = pyhf.tensorlib.astensor([0.5, 2.0])
             >>> means = pyhf.tensorlib.astensor([0., 2.3])
             >>> sigmas = pyhf.tensorlib.astensor([1., 0.8])
@@ -556,8 +556,8 @@ def normal(self, x, mu, sigma):
             >>> import pyhf
             >>> pyhf.set_backend("tensorflow")
             >>> t = pyhf.tensorlib.normal(0.5, 0., 1.)
-            >>> print(t)
-            tf.Tensor(0.3520653267642995, shape=(), dtype=float64)
+            >>> print(t) # doctest:+ELLIPSIS
+            tf.Tensor(0.35206532..., shape=(), dtype=float64)
             >>> values = pyhf.tensorlib.astensor([0.5, 2.0])
             >>> means = pyhf.tensorlib.astensor([0., 2.3])
             >>> sigmas = pyhf.tensorlib.astensor([1., 0.8])
@@ -586,8 +586,8 @@ def normal_cdf(self, x, mu=0.0, sigma=1):
             >>> import pyhf
             >>> pyhf.set_backend("tensorflow")
             >>> t = pyhf.tensorlib.normal_cdf(0.8)
-            >>> print(t)
-            tf.Tensor(0.7881446014166034, shape=(), dtype=float64)
+            >>> print(t) # doctest:+ELLIPSIS
+            tf.Tensor(0.78814460..., shape=(), dtype=float64)
             >>> values = pyhf.tensorlib.astensor([0.8, 2.0])
             >>> t = pyhf.tensorlib.normal_cdf(values)
             >>> print(t)