Title: clarify meaning of xbar and mu in pvariance/variance of statistics module
Type: Stage:
Components: Library (Lib) Versions: Python 3.11, Python 3.10, Python 3.9
Status: open Resolution:
Dependencies: Superseder:
Assigned To: steven.daprano Nosy List: iritkatriel, jtaylor, ncoghlan, oscarbenjamin, steven.daprano
Priority: normal Keywords: easy, patch

Created on 2014-01-25 12:37 by jtaylor, last changed 2021-08-20 10:12 by iritkatriel.

File name Uploaded Description Edit
issue20389_statistics_docs.diff ncoghlan, 2014-02-08 10:03 Module docs patch
Messages (5)
msg209192 - (view) Author: Julian Taylor (jtaylor) Date: 2014-01-25 12:37
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.

- 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.

msg209193 - (view) Author: Julian Taylor (jtaylor) Date: 2014-01-25 12:39
xbar is the *sample* mean of course

maybe with proper docstrings the two functions could also use the same keyword argument?
msg210119 - (view) Author: Oscar Benjamin (oscarbenjamin) * Date: 2014-02-03 12:14
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):
msg210605 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-02-08 10:03
Steven included some draft docs updates in a separate patch for issue 20481 - I have split those out and uploaded them here (since this discussion refers to the docstrings as well).
msg399953 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-08-20 10:12
I've closed issue36099 as a duplicate of this.
Date User Action Args
2021-08-20 10:12:22iritkatriellinkissue36099 superseder
2021-08-20 10:12:17iritkatrielsetnosy: + iritkatriel
messages: + msg399953
2021-08-20 10:04:08iritkatrielsetkeywords: + easy
versions: + Python 3.9, Python 3.10, Python 3.11, - Python 3.4
2014-02-08 10:03:31ncoghlansetfiles: + issue20389_statistics_docs.diff

nosy: + ncoghlan
messages: + msg210605

keywords: + patch
2014-02-03 12:14:29oscarbenjaminsetnosy: + oscarbenjamin
messages: + msg210119
2014-02-02 11:45:51steven.dapranosetassignee: steven.daprano

nosy: + steven.daprano
2014-01-28 21:59:07jtaylorsetcomponents: + Library (Lib)
2014-01-25 12:39:05jtaylorsetmessages: + msg209193
2014-01-25 12:37:20jtaylorcreate