Merge pull request #13 from sanjaymjoshi/quantile

Documentation update

relistats/binom_fin.py

@@ -1,20 +1,18 @@
 """ Reliability Engineering Statistics for finite population sizes with
-Binomial Distributions
-
-Also known as Bernoulli Trials.
+Binomial Distributions.Also known as Bernoulli Trials.
 
 Reference:
 S.M. Joshi, "Computation of Reliability Statistics for finite samples of
-Success-Failure Experiments," arXiv:2305.16578 [cs.IT], May 2023.
-https://doi.org/10.48550/arXiv.2305.16578
+Success-Failure Experiments,"
+`arXiv:2305.16578 [cs.IT] <https://doi.org/10.48550/arXiv.2305.16578>`_, May 2023.
 """
 
 from relistats import logger
 from relistats.binomial import confidence
 
 
 def conf_fin(n: int, f: int, m: int, d: int) -> tuple:
-    """Confidence [0, 1] in reliability r for finite population size.
+    """Confidence [0, 1] in reliability `r` for finite population size.
     Returns tuple with second value as actual reliability used for computations.
 
     :param n: number of samples tested
@@ -64,7 +62,7 @@ def conf_fin(n: int, f: int, m: int, d: int) -> tuple:
 
 
 def reli_fin(n: int, f: int, c: float, m: int) -> tuple:
-    """Minimum reliability at confidence level c for finite population size.
+    """Minimum reliability at confidence level `c` for finite population size.
     Returns tuple with second value as actual confidence used for computations.
 
     :param n: number of samples
@@ -99,8 +97,8 @@ def reli_fin(n: int, f: int, c: float, m: int) -> tuple:
 
 def assur_fin(n: int, f: int, m: int, tol=0.001) -> tuple:
     """Assurance [0, 1], i.e., confidence = reliability.
-    Returns tuple with other values as reliability and confidence
-    used for computations.
+    Returns tuple of assurance and actual values of reliability
+    and confidence used for computations.
 
     :param n: number of samples
     :type n: int, >=0

relistats/binomial.py

@@ -1,11 +1,10 @@
-""" Reliability Engineering Statistics for Binomial Distributions
-
+""" Reliability Engineering Statistics for Binomial Distributions.
 Also known as Bernoulli Trials.
 
 Reference:
-S.M. Joshi, "Computation of Reliability Statistics for
-Success-Failure Experiments," arXiv:2303.03167 [stat.ME], March 2023.
-https://doi.org/10.48550/arXiv.2303.03167
+S.M. Joshi, "Computation of Reliability Statistics for Success-Failure Experiments,"
+`arXiv:2303.03167 [stat.ME] <https://doi.org/10.48550/arXiv.2303.03167>`_,
+March 2023.
 """
 
 from math import sqrt
@@ -16,14 +15,14 @@
 
 
 def confidence(n: int, f: int, r: float) -> Optional[float]:
-    """Confidence [0, 1] in reliability r using closed-form expression.
+    """Confidence [0, 1] in reliability `r` using closed-form expression.
 
     :param n: number of samples
     :type n: int, >=0
     :param f: number of failures
     :type f: int, >=0
     :param r: reliability level
-    :type r: float, [0, 1]
+    :type r: float, `0 < r < 1`
     :return: Confidence or None if it could not be computed
     :rtype: float, optional
     """
@@ -54,7 +53,7 @@ def _wilson_lower_corrected(p, n, c):
 
 
 def reliability_closed(n: int, f: int, c: float) -> Optional[float]:
-    """Approximate minimum reliability [0, 1] at confidence level c.
+    """Approximate minimum reliability [0, 1] at confidence level `c`.
     The approximation is within about 5% of actual reliability and uses
     closed-form expression for computation called 'Wilson Score Interval
     with Continuity Correction' [Wallis, Sean A. (2013). "Binomial
@@ -67,7 +66,7 @@ def reliability_closed(n: int, f: int, c: float) -> Optional[float]:
     :param f: number of failures
     :type f: int, >=0
     :param c: confidence level
-    :type c: float, [0, 1]
+    :type c: float, `0 < c <1`
     :return: Reliability or None if it could not be computed
     :rtype: float, optional
     """
@@ -84,7 +83,7 @@ def _reliability_fn(x: float, n: int, f: int, c: float) -> float:
 
 
 def reliability_optim(n: int, f: int, c: float, tol=0.001) -> Optional[float]:
-    """Minimum reliability [0, 1] at confidence level c using numerical
+    """Minimum reliability [0, 1] at confidence level `c` using numerical
     optimization (Brent's method). The approximation is within specified
     tolerance limit.
 
@@ -93,7 +92,7 @@ def reliability_optim(n: int, f: int, c: float, tol=0.001) -> Optional[float]:
     :param f: number of failures
     :type f: int, >=0
     :param c: confidence level
-    :type c: float, [0, 1]
+    :type c: float, `0 < c < 1`
     :param tol: accuracy tolerance
     :type tol: float, optional
 
@@ -115,7 +114,7 @@ def reliability_optim(n: int, f: int, c: float, tol=0.001) -> Optional[float]:
 
 
 def reliability(n: int, f: int, c: float) -> Optional[float]:
-    """Minimum reliability at confidence level c
+    """Minimum reliability at confidence level `c`.
 
     :param n: number of samples
     :type n: int, >=0
@@ -130,14 +129,14 @@ def reliability(n: int, f: int, c: float) -> Optional[float]:
 
 
 def _assurance_fn(x: float, n: int, f: int) -> float:
-    """Function to find roots of x = confidence(n, f, x)"""
+    """Function to find roots of `x = confidence(n, f, x)`"""
     c = confidence(n, f, x) or 0
     return x - c
 
 
 def assurance(n: int, f: int, tol=0.001) -> Optional[float]:
     """Assurance [0, 1], i.e., confidence = reliability. For example,
-    90% assurance means 90% confidence in 90% reliability (at n=22, f=0).
+    90% assurance means 90% confidence in 90% reliability (at `n=22`, `f=0`).
     This method uses numerical approach of Brent's method to compute
     the solution within the specified tolerance.
 

relistats/intervals.py

@@ -1,8 +1,8 @@
 """Statistical methods for confidence and tolerance intervals.
 
 Reference:
-S.M. Joshi, "Confidence and Assurance of Percentiles," arXiv:2402.19109 [stat.ME], Feb 2024.
-https://doi.org/10.48550/arXiv.2402.19109
+S.M. Joshi, "Confidence and Assurance of Percentiles,"
+`arXiv:2402.19109 [stat.ME] <https://doi.org/10.48550/arXiv.2402.19109>`_, Feb 2024.
 """
 
 from typing import Any, Optional
@@ -170,7 +170,7 @@ def tolerance_interval(t: float, c: float, *args) -> Optional[tuple[Any, Any]]:
     :type c: float, `0 < c < 1`
     :param args: array of values
     :type args: array_like of type that supports computation of mean
-    :return: confidence interval
+    :return: tolerance interval
     :rtype: tuple of same type as `args`
     """
     n = len(*args)

relistats/percentile.py

@@ -1,8 +1,9 @@
 """Statistical methods for percentiles or quantiles and tolerance interval.
 
 Reference:
-S.M. Joshi, "Confidence and Assurance of Percentiles," arXiv:2402.19109 [stat.ME], Feb 2024.
-https://doi.org/10.48550/arXiv.2402.19109
+S.M. Joshi, "Confidence and Assurance of Percentiles,"
+`arXiv:2402.19109 [stat.ME] <https://doi.org/10.48550/arXiv.2402.19109>`_, Feb 2024.
+
 """
 
 from typing import Optional
@@ -14,18 +15,27 @@
 
 
 def confidence_in_percentile(j: int, n: int, p: float) -> float:
-    """Returns confidence (probability) that in a population of n samples,
-    pp^th percentile/quantile (0 < p < 1) is greater than j samples, 1 <= j <= n.
+    """Returns confidence (probability) that in a population of `n` samples,
+    `p`'th percentile/quantile is greater than `j` samples.
 
     From https://online.stat.psu.edu/stat415/lesson/19/19.2
 
     .. math::
         c = \sum_{k=0}^{j-1} {n\choose k}  p^k  (1-p)^{n-k}
 
     This is same as cumulative density function for a binomial
-    distribution, evaluated at j-1 out of n samples.
+    distribution, evaluated at `j-1` out of `n` samples.
 
     Note that :math:`j=n+1` will return 1.
+
+    :param j: sample index
+    :type j: int, `1 <= j <= n`
+    :param n: number of samples
+    :type n: int, >=0
+    :param p: percentile/quantile
+    :type p: float `0 < p < 1`
+    :return: Confidence (`0 <= c <= 1`)
+    :rtype: float
     """
     return stats.binom.cdf(j - 1, n, p)
 
@@ -45,17 +55,16 @@ def _assurance_percentile_fn(x: float, j: int, n: int) -> float:
 
 
 def assurance_in_percentile(j: int, n: int, tol=0.001) -> Optional[float]:
-    """Assurance level at j'th index out of n sorted samples. The confidence
-       is at least the percentile/quantile level.
+    """Assurance level at `j`'th index out of `n` sorted samples. The confidence
+    is at least the percentile/quantile level.
 
     :param j: sample index
-    :type j: int, >0
+    :type j: int, `1 <= j <= n`
     :param n: number of samples
     :type n: int, >=0
     :param tol: accuracy tolerance
     :type tol: float, optional
-
-    :return: Assurance or None if it could not be computed
+    :return: Assurance (`0 <= a <= 1`) or None if it could not be computed
     :rtype: float, optional
     """
     if _num_samples_invalid(n):