[3.12] gh-64588: Clarify the difference between mu and xbar in statistics docs (GH...

gh-64588: Clarify the difference between mu and xbar in statistics docs (GH-117333)

Thanks Davin Potts for the clarification idea.
(cherry picked from commit fefd5d97111364afa027ae580c3244f427dda59d)

Co-authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>

diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
index d0274e8b20f74e6493ef6446304acb5d5326156d..4a3a896ccd30b6b52ce14d942c531b96b5f35feb 100644 (file)
--- a/Doc/library/statistics.rst
+++ b/Doc/library/statistics.rst
@@ -449,9 +449,9 @@ However, for reading convenience, most of the examples show sorted sequences.
    variance indicates that the data is spread out; a small variance indicates
    it is clustered closely around the mean.
 
-   If the optional second argument *mu* is given, it is typically the mean of
-   the *data*.  It can also be used to compute the second moment around a
-   point that is not the mean.  If it is missing or ``None`` (the default),
+   If the optional second argument *mu* is given, it should be the *population*
+   mean of the *data*.  It can also be used to compute the second moment around
+   a point that is not the mean.  If it is missing or ``None`` (the default),
    the arithmetic mean is automatically calculated.
 
    Use this function to calculate the variance from the entire population.  To
@@ -521,8 +521,8 @@ However, for reading convenience, most of the examples show sorted sequences.
    the data is spread out; a small variance indicates it is clustered closely
    around the mean.
 
-   If the optional second argument *xbar* is given, it should be the mean of
-   *data*.  If it is missing or ``None`` (the default), the mean is
+   If the optional second argument *xbar* is given, it should be the *sample*
+   mean of *data*.  If it is missing or ``None`` (the default), the mean is
    automatically calculated.
 
    Use this function when your data is a sample from a population. To calculate
@@ -538,8 +538,8 @@ However, for reading convenience, most of the examples show sorted sequences.
       >>> variance(data)
       1.3720238095238095
 
-   If you have already calculated the mean of your data, you can pass it as the
-   optional second argument *xbar* to avoid recalculation:
+   If you have already calculated the sample mean of your data, you can pass it
+   as the optional second argument *xbar* to avoid recalculation:
 
    .. doctest::