Skip to content

Commit 9cd04b4

Browse files
committed
Replace flag with a "method" keyword argument for future proofing.
1 parent f0db81e commit 9cd04b4

File tree

3 files changed

+15
-10
lines changed

3 files changed

+15
-10
lines changed

Doc/library/statistics.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -648,15 +648,15 @@ However, for reading convenience, most of the examples show sorted sequences.
648648

649649
.. versionadded:: 3.10
650650

651-
.. function:: correlation(x, y, /, *, by_rank=False)
651+
.. function:: correlation(x, y, /, *, method='linear')
652652

653653
Return the `Pearson's correlation coefficient
654654
<https://en.wikipedia.org/wiki/Pearson_correlation_coefficient>`_
655655
for two inputs. Pearson's correlation coefficient *r* takes values
656656
between -1 and +1. It measures the strength and direction of a linear
657657
relationship.
658658

659-
If *by_rank* is true, computes `Spearman's rank correlation coefficient
659+
If *method* is "ranked", computes `Spearman's rank correlation coefficient
660660
<https://en.wikipedia.org/wiki/Spearman%27s_rank_correlation_coefficient>`_
661661
for two inputs. The data is replaced by ranks. Ties are averaged so that
662662
equal values receive the same rank. The resulting coefficient measures the
@@ -679,7 +679,7 @@ However, for reading convenience, most of the examples show sorted sequences.
679679
>>> dist_from_sun = [58, 108, 150, 228, 778, 1_400, 2_900, 4_500] # million km
680680

681681
>>> # Show that a perfect monotonic relationship exists
682-
>>> correlation(orbital_period, dist_from_sun, by_rank=True)
682+
>>> correlation(orbital_period, dist_from_sun, method='ranked')
683683
1.0
684684

685685
>>> # Observe that a linear relationship is imperfect
@@ -688,7 +688,7 @@ However, for reading convenience, most of the examples show sorted sequences.
688688

689689
>>> # Demonstrate Kepler's third law: There is a linear correlation
690690
>>> # between the square of the orbital period and the cube of the
691-
>>> # distance from the sun
691+
>>> # distance from the sun.
692692
>>> period_squared = [p * p for p in orbital_period]
693693
>>> dist_cubed = [d * d * d for d in dist_from_sun]
694694
>>> round(correlation(period_squared, dist_cubed), 4)

Lib/statistics.py

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1032,7 +1032,7 @@ def covariance(x, y, /):
10321032
return sxy / (n - 1)
10331033

10341034

1035-
def correlation(x, y, /, *, by_rank=False):
1035+
def correlation(x, y, /, *, method='linear'):
10361036
"""Pearson's correlation coefficient
10371037
10381038
Return the Pearson's correlation coefficient for two inputs. Pearson's
@@ -1046,10 +1046,10 @@ def correlation(x, y, /, *, by_rank=False):
10461046
>>> correlation(x, y)
10471047
-1.0
10481048
1049-
If *by_rank* is true, computes Spearman's rank correlation coefficient
1049+
If *method* is "ranked", computes Spearman's rank correlation coefficient
10501050
for two inputs. The data is replaced by ranks. Ties are averaged
1051-
so that equal values receive the same rank. The resulting coefficient measures
1052-
the strength of a monotonic relationship.
1051+
so that equal values receive the same rank. The resulting coefficient
1052+
measures the strength of a monotonic relationship.
10531053
10541054
Spearman's rank correlation coefficient is appropriate for ordinal
10551055
data or for continuous data that doesn't meet the linear proportion
@@ -1060,7 +1060,9 @@ def correlation(x, y, /, *, by_rank=False):
10601060
raise StatisticsError('correlation requires that both inputs have same number of data points')
10611061
if n < 2:
10621062
raise StatisticsError('correlation requires at least two data points')
1063-
if by_rank:
1063+
if method not in {'linear', 'ranked'}:
1064+
raise ValueError(f'Unknown method: {method!r}')
1065+
if method == 'ranked':
10641066
x = _rank(x)
10651067
y = _rank(y)
10661068
xbar = fsum(x) / n

Lib/test/test_statistics.py

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2575,9 +2575,12 @@ def test_correlation_spearman(self):
25752575
# https://www.wolframalpha.com/input?i=SpearmanRho%5B%7B56%2C+75%2C+45%2C+71%2C+61%2C+64%2C+58%2C+80%2C+76%2C+61%7D%2C+%7B66%2C+70%2C+40%2C+60%2C+65%2C+56%2C+59%2C+77%2C+67%2C+63%7D%5D
25762576
reading = [56, 75, 45, 71, 61, 64, 58, 80, 76, 61]
25772577
mathematics = [66, 70, 40, 60, 65, 56, 59, 77, 67, 63]
2578-
self.assertAlmostEqual(statistics.correlation(reading, mathematics, by_rank=True),
2578+
self.assertAlmostEqual(statistics.correlation(reading, mathematics, method='ranked'),
25792579
0.6686960980480712)
25802580

2581+
with self.assertRaises(ValueError):
2582+
statistics.correlation(reading, mathematics, method='bad_method')
2583+
25812584
class TestLinearRegression(unittest.TestCase):
25822585

25832586
def test_constant_input_error(self):

0 commit comments

Comments
 (0)