bpo-44151: Various grammar, word order, and markup fixes (GH-26344)

diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
index aad505cceadd051d79b549b531ab9dc0560c93c4..bb03a2ce6ee971bb79768bff29d22018bee28edc 100644 (file)
--- a/Doc/library/statistics.rst
+++ b/Doc/library/statistics.rst
@@ -643,7 +643,7 @@ However, for reading convenience, most of the examples show sorted sequences.
 
    .. versionadded:: 3.10
 
-.. function:: linear_regression(independent_variable, dependent_variable)
+.. function:: linear_regression(x, y, /)
 
    Return the slope and intercept of `simple linear regression
    <https://en.wikipedia.org/wiki/Simple_linear_regression>`_
@@ -651,30 +651,30 @@ However, for reading convenience, most of the examples show sorted sequences.
    regression describes the relationship between an independent variable *x* and
    a dependent variable *y* in terms of this linear function:
 
-      *y = intercept + slope \* x + noise*
+      *y = slope \* x + intercept + noise*
 
    where ``slope`` and ``intercept`` are the regression parameters that are
-   estimated, and noise represents the
+   estimated, and ``noise`` represents the
    variability of the data that was not explained by the linear regression
    (it is equal to the difference between predicted and actual values
-   of dependent variable).
+   of the dependent variable).
 
    Both inputs must be of the same length (no less than two), and
-   the independent variable *x* needs not to be constant;
-   otherwise :exc:`StatisticsError` is raised.
+   the independent variable *x* cannot be constant;
+   otherwise a :exc:`StatisticsError` is raised.
 
    For example, we can use the `release dates of the Monty
-   Python films <https://en.wikipedia.org/wiki/Monty_Python#Films>`_, and used
-   it to predict the cumulative number of Monty Python films
+   Python films <https://en.wikipedia.org/wiki/Monty_Python#Films>`_
+   to predict the cumulative number of Monty Python films
    that would have been produced by 2019
-   assuming that they kept the pace.
+   assuming that they had kept the pace.
 
    .. doctest::
 
       >>> year = [1971, 1975, 1979, 1982, 1983]
       >>> films_total = [1, 2, 3, 4, 5]
       >>> slope, intercept = linear_regression(year, films_total)
-      >>> round(intercept + slope * 2019)
+      >>> round(slope * 2019 + intercept)
       16
 
    .. versionadded:: 3.10

diff --git a/Lib/statistics.py b/Lib/statistics.py
index c505a0517923a8e49793dd5079da24b021eb9691..26009b0cbe430d14057eafddd5fee8c8b79c9bab 100644 (file)
--- a/Lib/statistics.py
+++ b/Lib/statistics.py
@@ -936,26 +936,26 @@ LinearRegression = namedtuple('LinearRegression', ('slope', 'intercept'))
 
 
 def linear_regression(x, y, /):
-    """Intercept and slope for simple linear regression
+    """Slope and intercept for simple linear regression.
 
-    Return the intercept and slope of simple linear regression
+    Return the slope and intercept of simple linear regression
     parameters estimated using ordinary least squares. Simple linear
-    regression describes relationship between *x* and
-    *y* in terms of linear function:
+    regression describes relationship between an independent variable
+    *x* and a dependent variable *y* in terms of linear function:
 
-        y = intercept + slope * x + noise
+        y = slope * x + intercept + noise
 
-    where *intercept* and *slope* are the regression parameters that are
+    where *slope* and *intercept* are the regression parameters that are
     estimated, and noise represents the variability of the data that was
     not explained by the linear regression (it is equal to the
-    difference between predicted and actual values of dependent
+    difference between predicted and actual values of the dependent
     variable).
 
     The parameters are returned as a named tuple.
 
     >>> x = [1, 2, 3, 4, 5]
     >>> noise = NormalDist().samples(5, seed=42)
-    >>> y = [2 + 3 * x[i] + noise[i] for i in range(5)]
+    >>> y = [3 * x[i] + 2 + noise[i] for i in range(5)]
     >>> linear_regression(x, y)  #doctest: +ELLIPSIS
     LinearRegression(slope=3.09078914170..., intercept=1.75684970486...)