From 5c4aac16b54284a59bc5af34e731be7299cbb1d1 Mon Sep 17 00:00:00 2001 From: Mike Jarvis Date: Tue, 8 Jun 2021 07:41:59 -0400 Subject: DOC: Adjust polyfit doc to clarify the meaning of w (#18421) * DOC: Adjust polyfit doc to clarify the meaning of w cov='unscaled', in particular, had inconsistently referred to a weight of 1/sigma**2, while the doc for w says it should be equal to 1/sigma. This change clarifies w to comport with more typical meanings of weights in weighted least squares, and makes clear that cov='unscaled' is appropriate when the weight w**2 = 1/sigma**2. See Issue #5261 for more discussion of the errors/confusion in the previous doc string. * Update doc text for w in all polynomial module fit functions Co-authored-by: Stefan van der Walt Co-authored-by: Ross Barnowski --- numpy/lib/polynomial.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'numpy/lib/polynomial.py') diff --git a/numpy/lib/polynomial.py b/numpy/lib/polynomial.py index 56fcce621..23021cafa 100644 --- a/numpy/lib/polynomial.py +++ b/numpy/lib/polynomial.py @@ -489,8 +489,11 @@ def polyfit(x, y, deg, rcond=None, full=False, w=None, cov=False): default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned. w : array_like, shape (M,), optional - Weights to apply to the y-coordinates of the sample points. For - gaussian uncertainties, use 1/sigma (not 1/sigma**2). + Weights. If not None, the weight ``w[i]`` applies to the unsquared + residual ``y[i] - y_hat[i]`` at ``x[i]``. Ideally the weights are + chosen so that the errors of the products ``w[i]*y[i]`` all have the + same variance. When using inverse-variance weighting, use + ``w[i] = 1/sigma(y[i])``. The default value is None. cov : bool or str, optional If given and not `False`, return not just the estimate but also its covariance matrix. By default, the covariance are scaled by @@ -498,7 +501,7 @@ def polyfit(x, y, deg, rcond=None, full=False, w=None, cov=False): to be unreliable except in a relative sense and everything is scaled such that the reduced chi2 is unity. This scaling is omitted if ``cov='unscaled'``, as is relevant for the case that the weights are - 1/sigma**2, with sigma known to be a reliable estimate of the + w = 1/sigma, with sigma known to be a reliable estimate of the uncertainty. Returns -- cgit v1.2.1