diff --git a/relistats/binom_fin.py b/relistats/binom_fin.py index 34211b0..06df2a2 100644 --- a/relistats/binom_fin.py +++ b/relistats/binom_fin.py @@ -1,12 +1,10 @@ """ 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] `_, May 2023. """ from relistats import logger @@ -14,7 +12,7 @@ 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 diff --git a/relistats/binomial.py b/relistats/binomial.py index 140446a..a11bc74 100644 --- a/relistats/binomial.py +++ b/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] `_, +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. diff --git a/relistats/intervals.py b/relistats/intervals.py index 63b8eb6..a8b1b1c 100644 --- a/relistats/intervals.py +++ b/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] `_, 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) diff --git a/relistats/percentile.py b/relistats/percentile.py index a87f96b..57aa1a1 100644 --- a/relistats/percentile.py +++ b/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] `_, Feb 2024. + """ from typing import Optional @@ -14,8 +15,8 @@ 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 @@ -23,9 +24,18 @@ def confidence_in_percentile(j: int, n: int, p: float) -> float: 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):