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

Created on 2014-01-25 12:37 by jtaylor, last changed 2014-02-08 10:03 by ncoghlan.

Files
File name Uploaded Description Edit
issue20389_statistics_docs.diff ncoghlan, 2014-02-08 10:03 Module docs patch
Messages (4)
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.
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.
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):
http://en.wikipedia.org/wiki/Variance#Population_variance
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).
History
Date User Action Args
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