Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 714c60d

Browse files
rhettingerrhettinger
authored
bpo-36324: Add inv_cdf() to statistics.NormalDist() (GH-12377)
1 parent faddaed commit 714c60d

4 files changed

Lines changed: 182 additions & 0 deletions

File tree

‎Doc/library/statistics.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -569,6 +569,18 @@ of applications in statistics.
569569
compute the probability that a random variable *X* will be less than or
570570
equal to *x*. Mathematically, it is written ``P(X <= x)``.
571571

572+
.. method:: NormalDist.inv_cdf(p)
573+
574+
Compute the inverse cumulative distribution function, also known as the
575+
`quantile function <https://en.wikipedia.org/wiki/Quantile_function>`_
576+
or the `percent-point
577+
<https://www.statisticshowto.datasciencecentral.com/inverse-distribution-function/>`_
578+
function. Mathematically, it is written ``x : P(X <= x) = p``.
579+
580+
Finds the value *x* of the random variable *X* such that the
581+
probability of the variable being less than or equal to that value
582+
equals the given probability *p*.
583+
572584
.. method:: NormalDist.overlap(other)
573585

574586
Compute the `overlapping coefficient (OVL)
@@ -628,6 +640,16 @@ rounding to the nearest whole number:
628640
>>> round(fraction * 100.0, 1)
629641
18.4
630642

643+
Find the `quartiles <https://en.wikipedia.org/wiki/Quartile>`_ and `deciles
644+
<https://en.wikipedia.org/wiki/Decile>`_ for the SAT scores:
645+
646+
.. doctest::
647+
648+
>>> [round(sat.inv_cdf(p)) for p in (0.25, 0.50, 0.75)]
649+
[928, 1060, 1192]
650+
>>> [round(sat.inv_cdf(p / 10)) for p in range(1, 10)]
651+
[810, 896, 958, 1011, 1060, 1109, 1162, 1224, 1310]
652+
631653
What percentage of men and women will have the same height in `two normally
632654
distributed populations with known means and standard deviations
633655
<http://www.usablestats.com/lessons/normal>`_?

‎Lib/statistics.py‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -745,6 +745,101 @@ def cdf(self, x):
745745
raise StatisticsError('cdf() not defined when sigma is zero')
746746
return 0.5 * (1.0 + erf((x - self.mu) / (self.sigma * sqrt(2.0))))
747747

748+
def inv_cdf(self, p):
749+
''' Inverse cumulative distribution function: x : P(X <= x) = p
750+
751+
Finds the value of the random variable such that the probability of the
752+
variable being less than or equal to that value equals the given probability.
753+
754+
This function is also called the percent-point function or quantile function.
755+
756+
'''
757+
if (p <= 0.0 or p >= 1.0):
758+
raise StatisticsError('p must be in the range 0.0 < p < 1.0')
759+
if self.sigma <= 0.0:
760+
raise StatisticsError('cdf() not defined when sigma at or below zero')
761+
762+
# There is no closed-form solution to the inverse CDF for the normal
763+
# distribution, so we use a rational approximation instead:
764+
# Wichura, M.J. (1988). "Algorithm AS241: The Percentage Points of the
765+
# Normal Distribution". Applied Statistics. Blackwell Publishing. 37
766+
# (3): 477–484. doi:10.2307/2347330. JSTOR 2347330.
767+
768+
q = p - 0.5
769+
if fabs(q) <= 0.425:
770+
a0 = 3.38713_28727_96366_6080e+0
771+
a1 = 1.33141_66789_17843_7745e+2
772+
a2 = 1.97159_09503_06551_4427e+3
773+
a3 = 1.37316_93765_50946_1125e+4
774+
a4 = 4.59219_53931_54987_1457e+4
775+
a5 = 6.72657_70927_00870_0853e+4
776+
a6 = 3.34305_75583_58812_8105e+4
777+
a7 = 2.50908_09287_30122_6727e+3
778+
b1 = 4.23133_30701_60091_1252e+1
779+
b2 = 6.87187_00749_20579_0830e+2
780+
b3 = 5.39419_60214_24751_1077e+3
781+
b4 = 2.12137_94301_58659_5867e+4
782+
b5 = 3.93078_95800_09271_0610e+4
783+
b6 = 2.87290_85735_72194_2674e+4
784+
b7 = 5.22649_52788_52854_5610e+3
785+
r = 0.180625 - q * q
786+
num = (q * (((((((a7 * r + a6) * r + a5) * r + a4) * r + a3)
787+
* r + a2) * r + a1) * r + a0))
788+
den = ((((((((b7 * r + b6) * r + b5) * r + b4) * r + b3)
789+
* r + b2) * r + b1) * r + 1.0))
790+
x = num / den
791+
return self.mu + (x * self.sigma)
792+
793+
r = p if q <= 0.0 else 1.0 - p
794+
r = sqrt(-log(r))
795+
if r <= 5.0:
796+
c0 = 1.42343_71107_49683_57734e+0
797+
c1 = 4.63033_78461_56545_29590e+0
798+
c2 = 5.76949_72214_60691_40550e+0
799+
c3 = 3.64784_83247_63204_60504e+0
800+
c4 = 1.27045_82524_52368_38258e+0
801+
c5 = 2.41780_72517_74506_11770e-1
802+
c6 = 2.27238_44989_26918_45833e-2
803+
c7 = 7.74545_01427_83414_07640e-4
804+
d1 = 2.05319_16266_37758_82187e+0
805+
d2 = 1.67638_48301_83803_84940e+0
806+
d3 = 6.89767_33498_51000_04550e-1
807+
d4 = 1.48103_97642_74800_74590e-1
808+
d5 = 1.51986_66563_61645_71966e-2
809+
d6 = 5.47593_80849_95344_94600e-4
810+
d7 = 1.05075_00716_44416_84324e-9
811+
r = r - 1.6
812+
num = ((((((((c7 * r + c6) * r + c5) * r + c4) * r + c3)
813+
* r + c2) * r + c1) * r + c0))
814+
den = ((((((((d7 * r + d6) * r + d5) * r + d4) * r + d3)
815+
* r + d2) * r + d1) * r + 1.0))
816+
else:
817+
e0 = 6.65790_46435_01103_77720e+0
818+
e1 = 5.46378_49111_64114_36990e+0
819+
e2 = 1.78482_65399_17291_33580e+0
820+
e3 = 2.96560_57182_85048_91230e-1
821+
e4 = 2.65321_89526_57612_30930e-2
822+
e5 = 1.24266_09473_88078_43860e-3
823+
e6 = 2.71155_55687_43487_57815e-5
824+
e7 = 2.01033_43992_92288_13265e-7
825+
f1 = 5.99832_20655_58879_37690e-1
826+
f2 = 1.36929_88092_27358_05310e-1
827+
f3 = 1.48753_61290_85061_48525e-2
828+
f4 = 7.86869_13114_56132_59100e-4
829+
f5 = 1.84631_83175_10054_68180e-5
830+
f6 = 1.42151_17583_16445_88870e-7
831+
f7 = 2.04426_31033_89939_78564e-15
832+
r = r - 5.0
833+
num = ((((((((e7 * r + e6) * r + e5) * r + e4) * r + e3)
834+
* r + e2) * r + e1) * r + e0))
835+
den = ((((((((f7 * r + f6) * r + f5) * r + f4) * r + f3)
836+
* r + f2) * r + f1) * r + 1.0))
837+
838+
x = num / den
839+
if q < 0.0:
840+
x = -x
841+
return self.mu + (x * self.sigma)
842+
748843
def overlap(self, other):
749844
'''Compute the overlapping coefficient (OVL) between two normal distributions.
750845

‎Lib/test/test_statistics.py‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2174,6 +2174,69 @@ def test_cdf(self):
21742174
self.assertEqual(X.cdf(float('Inf')), 1.0)
21752175
self.assertTrue(math.isnan(X.cdf(float('NaN'))))
21762176

2177+
def test_inv_cdf(self):
2178+
NormalDist = statistics.NormalDist
2179+
2180+
# Center case should be exact.
2181+
iq = NormalDist(100, 15)
2182+
self.assertEqual(iq.inv_cdf(0.50), iq.mean)
2183+
2184+
# Test versus a published table of known percentage points.
2185+
# See the second table at the bottom of the page here:
2186+
# http://people.bath.ac.uk/masss/tables/normaltable.pdf
2187+
Z = NormalDist()
2188+
pp = {5.0: (0.000, 1.645, 2.576, 3.291, 3.891,
2189+
4.417, 4.892, 5.327, 5.731, 6.109),
2190+
2.5: (0.674, 1.960, 2.807, 3.481, 4.056,
2191+
4.565, 5.026, 5.451, 5.847, 6.219),
2192+
1.0: (1.282, 2.326, 3.090, 3.719, 4.265,
2193+
4.753, 5.199, 5.612, 5.998, 6.361)}
2194+
for base, row in pp.items():
2195+
for exp, x in enumerate(row, start=1):
2196+
p = base * 10.0 ** (-exp)
2197+
self.assertAlmostEqual(-Z.inv_cdf(p), x, places=3)
2198+
p = 1.0 - p
2199+
self.assertAlmostEqual(Z.inv_cdf(p), x, places=3)
2200+
2201+
# Match published example for MS Excel
2202+
# https://support.office.com/en-us/article/norm-inv-function-54b30935-fee7-493c-bedb-2278a9db7e13
2203+
self.assertAlmostEqual(NormalDist(40, 1.5).inv_cdf(0.908789), 42.000002)
2204+
2205+
# One million equally spaced probabilities
2206+
n = 2**20
2207+
for p in range(1, n):
2208+
p /= n
2209+
self.assertAlmostEqual(iq.cdf(iq.inv_cdf(p)), p)
2210+
2211+
# One hundred ever smaller probabilities to test tails out to
2212+
# extreme probabilities: 1 / 2**50 and (2**50-1) / 2 ** 50
2213+
for e in range(1, 51):
2214+
p = 2.0 ** (-e)
2215+
self.assertAlmostEqual(iq.cdf(iq.inv_cdf(p)), p)
2216+
p = 1.0 - p
2217+
self.assertAlmostEqual(iq.cdf(iq.inv_cdf(p)), p)
2218+
2219+
# Now apply cdf() first. At six sigmas, the round-trip
2220+
# loses a lot of precision, so only check to 6 places.
2221+
for x in range(10, 190):
2222+
self.assertAlmostEqual(iq.inv_cdf(iq.cdf(x)), x, places=6)
2223+
2224+
# Error cases:
2225+
with self.assertRaises(statistics.StatisticsError):
2226+
iq.inv_cdf(0.0) # p is zero
2227+
with self.assertRaises(statistics.StatisticsError):
2228+
iq.inv_cdf(-0.1) # p under zero
2229+
with self.assertRaises(statistics.StatisticsError):
2230+
iq.inv_cdf(1.0) # p is one
2231+
with self.assertRaises(statistics.StatisticsError):
2232+
iq.inv_cdf(1.1) # p over one
2233+
with self.assertRaises(statistics.StatisticsError):
2234+
iq.sigma = 0.0 # sigma is zero
2235+
iq.inv_cdf(0.5)
2236+
with self.assertRaises(statistics.StatisticsError):
2237+
iq.sigma = -0.1 # sigma under zero
2238+
iq.inv_cdf(0.5)
2239+
21772240
def test_overlap(self):
21782241
NormalDist = statistics.NormalDist
21792242

‎Misc/NEWS.d/next/Library/2019-03-17-01-17-45.bpo-36324.dvNrRe.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Add method to statistics.NormalDist for computing the inverse cumulative
2+
normal distribution.

0 commit comments

Comments
 (0)