clarify meaning of xbar and mu in pvariance/variance of statistics module

[jtaylor]

BPO	20389
Nosy	@ncoghlan, @stevendaprano, @iritkatriel
Files	issue20389_statistics_docs.diff: Module docs patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/stevendaprano'
closed_at = None
created_at = <Date 2014-01-25.12:37:20.207>
labels = ['easy', 'library', '3.9', '3.10', '3.11']
title = 'clarify meaning of xbar and mu in pvariance/variance of statistics module'
updated_at = <Date 2021-08-20.10:12:17.443>
user = 'https://bugs.python.org/jtaylor'

bugs.python.org fields:

activity = <Date 2021-08-20.10:12:17.443>
actor = 'iritkatriel'
assignee = 'steven.daprano'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2014-01-25.12:37:20.207>
creator = 'jtaylor'
dependencies = []
files = ['33990']
hgrepos = []
issue_num = 20389
keywords = ['patch', 'easy']
message_count = 5.0
messages = ['209192', '209193', '210119', '210605', '399953']
nosy_count = 5.0
nosy_names = ['ncoghlan', 'steven.daprano', 'jtaylor', 'oscarbenjamin', 'iritkatriel']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue20389'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

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

[jtaylor]

the pvariance and variance functions take the argument mu and xbar to pass the population and sample mean to avoid some recomputation.

I assume the keyword arguments are different because the two means accepted are different, but the docstring does not indicate this directly.
It just says mu or xbar is the mean of the data. The module documentation is a little clearer but only in the grey box right at the end.

I would propose to change the docstring and module documentation to explicitly state that mu is the population mean and xbar is the population mean.
E.g.

• The optional argument mu, if given, should be the mean of
  the data.
  + The optional argument mu, if given, should be the population mean of
  the data.

etc.

[jtaylor]

xbar is the *sample* mean of course

maybe with proper docstrings the two functions could also use the same keyword argument?

[oscarbenjamin]

I agree that the current wording in the doc-strings is ambiguous. It should be more careful to distinguish between

mu : true/population mean
xbar : estimated/sample mean

I disagree that the keyword arguments should be made the same. There is an important conceptual difference between these two things that the user needs to be aware of and mu, xbar - as symbols rather than ascii characters - are widely used for this. See e.g. this Wikipedia entry (although it uses ybar instead of xbar):
http://en.wikipedia.org/wiki/Variance#Population_variance

[ncoghlan]

Steven included some draft docs updates in a separate patch for bpo-20481 - I have split those out and uploaded them here (since this discussion refers to the docstrings as well).

[iritkatriel]

I've closed bpo-36099 as a duplicate of this.