add docs, add limits for adding distributions

Author: geraintpalmer

ciw/dists/distributions.py

@@ -150,6 +150,18 @@ def variance(self):
                 return float('nan')
             return (v1 / (m2 ** 2)) + ((m1 ** 2) * v2) / (m2 ** 4)
 
+    @property
+    def upper_limit(self):
+        if self.operator == add:
+            return self.d1.upper_limit + self.d2.upper_limit
+        return float('nan')
+
+    @property
+    def lower_limit(self):
+        if self.operator == add:
+            return self.d1.lower_limit + self.d2.lower_limit
+        return float('nan')
+
 
 class Uniform(Distribution):
     """

docs/Guides/Distributions/index.rst

@@ -9,4 +9,5 @@ Contents:
    set_distributions.rst
    phasetype.rst
    combining_distributions.rst
+   summary_stats.rst
    time_dependent.rst

docs/Guides/Distributions/summary_stats.rst

@@ -0,0 +1,75 @@
+.. _set-dists:
+
+===============================================
+How to Access Distributions' Summary Statistics
+===============================================
+
+Every distribution object in Ciw has attributes giving summary statisics for the distributions. These are:
+
++ Mean
++ Median
++ Variance
++ Standard deviation
++ Upper limit
++ Lower limit
+
+They can be accessed as follows::
+
+    >>> import ciw
+    >>> D = ciw.dists.Exponential(rate=5)
+    >>> D.mean
+    0.2
+    >>> D.median
+    0.1386294361...
+    >>> D.variance
+    0.04
+    >>> D.sd
+    0.2
+    >>> D.upper_limit
+    inf
+    >>> D.lower_limit
+    0
+
+
+In some cases where a closed from expression does not exist, the attribute will return :code:`nan`. For example::
+
+    >>> G = ciw.dists.Gamma(shape=0.6, scale=1.2)
+    >>> G.median
+    nan
+
+
+And where possible, summary statistics are calculated for :ref:`combined distributions <combine-dists>`. For example::
+
+
+    >>> D1 = ciw.dists.Uniform(lower=2, upper=6)
+    >>> D2 = ciw.dists.Uniform(lower=3, upper=9)
+    >>> D = D1 + D2
+    >>> D1.mean, D2.mean, D.mean
+    (4.0, 6.0, 10.0)
+    >>> D1.sd, D2.sd, D.sd
+    (1.154..., 1.732..., 2.081...)
+    >>> D1.lower_limit, D2.lower_limit, D.lower_limit
+    (2, 3, 5)
+    >>> D1.upper_limit, D2.upper_limit, D.upper_limit
+    (6, 9, 15)
+
+and :ref:`mixture distributions <combine-dists>`::
+
+    >>> D1 = ciw.dists.Uniform(lower=2, upper=6)
+    >>> D2 = ciw.dists.Uniform(lower=3, upper=9)
+    >>> D = ciw.dists.MixtureDistribution(
+    ...     dists=[D1, D2],
+    ...     probs=[0.5, 0.5]
+    ... )
+    >>> D.mean
+    5.0
+    >>> D.sd
+    1.7795...
+    >>> D.upper_limit
+    9
+    >>> D.lower_limit
+    2
+
+
+
+

tests/test_sampling.py

@@ -1205,6 +1205,8 @@ def test_combined_add_summary_stats(self):
         expected_var  = A.variance + B.variance             # 1 + 0.25 = 1.25
         self.assertEqual(C.mean, expected_mean)
         self.assertEqual(C.variance, expected_var)
+        self.assertEqual(C.upper_limit, float('inf'))
+        self.assertEqual(C.lower_limit, 0)
 
     def test_combined_sub_summary_stats(self):
         A = ciw.dists.Normal(5.0, 1.0)
@@ -1215,6 +1217,8 @@ def test_combined_sub_summary_stats(self):
         expected_var  = A.variance + B.variance             # 1 + 0.25 = 1.25
         self.assertEqual(C.mean, expected_mean)
         self.assertEqual(C.variance, expected_var)
+        self.assertTrue(math.isnan(C.upper_limit))
+        self.assertTrue(math.isnan(C.lower_limit))
 
     def test_combined_mul_summary_stats(self):
         # Product moments (independent):