Repository: numpy/numpy

Issue:
Possible wrong polyfit documentation 
<!-- Please describe the issue in detail here, and fill in the fields below -->

Hi! I think that the documentation of numpy polyfit could be misleading/wrong when describing the scaling factor for the covariance matrix. 

Indeed with the option ``cov=True``,  the covariance matrix is scaled so to return a unit value for reduced chi2 of the fit.
I, therefore, expect that the scaling factor should be chi2/(M-N) = chi2/dof, where M is the number of data points and N the parameters of the fit. 

However, the documentation reports that the scaling factor is chi2/sqrt(N-dof), where I guess N is the number of data points.

I did a test and actually the scaling factor I found is consistent with chi2/dof, rather than the expression reported in the documentation.

### Reproducing code example:

<!-- A short code example that reproduces the problem/missing feature. It should be
self-contained, i.e., possible to run as-is via 'python myproblem.py' -->

```python
# Generate synthetically the data
# True parameters
import numpy as np

true_slope = 3
true_intercept = 7

x_data = np.linspace(-5, 5, 30)

# The y-data will have a noise term, to simulate imperfect observations
sigma = 1
y_data = true_slope * np.linspace(-5, 5, 30) + true_intercept
y_obs = y_data + np.random.normal(loc=0.0, scale=sigma, size=x_data.size)

# Here I generate artificially some unequal uncertainties 
# (even if there is no reason for them to be so)
y_uncertainties = sigma * np.random.normal(loc=1.0, scale=0.5*sigma, size=x_data.size)

# Make the fit
popt, pcov = np.polyfit(x_data, y_obs, 1, w=1/y_uncertainties, cov='unscaled')
popt, pcov_scaled = np.polyfit(x_data, y_obs, 1, w=1/y_uncertainties, cov=True)

my_scale_factor = np.sum((y_obs - popt[0] * x_data  - popt[1])**2 / y_uncertainties**2)\
                         / (len(y_obs)-2)

scale_factor =  pcov_scaled[0,0] / pcov[0,0]
```

As you can see the real scaling factor is equal to "my_scale_factor", i.e. chi2/dof.

### Numpy/Python version information:

<!-- Output from 'import sys, numpy; print(numpy.__version__, sys.version)' -->
1.18.5 3.7.7 (default, May  6 2020, 11:45:54) [MSC v.1916 64 bit (AMD64)]



Discussion:
Hello @davidedalbosco , thanks for bringing this up. Looks like that comment was added in [this PR](https://github.com/numpy/numpy/pull/11197) and from what I understand your observation is correct. [This is when that comment was added](https://github.com/numpy/numpy/commit/1837df75469d908c15434d97c15d9af4424ca897#diff-1f06e7d647d0b4e503d67faa546c6a7a); note that in the code the scaling factor is `fac = resids / (len(x) - order)`, where `order=deg+1`. Unless I'm missing something, I'm not sure what was meant with that comment. Maybe @mhvk could help here?
I'm coming here from the stackoverflow question. I confirm that the present implementation is reasonable and that just the docstring needs to be updated. I don't know enough about Bayesian statistics.
Indeed, the documentation seems to have not been updated quite right. Sorry! Would be wonderful if someone could make a quite PR...

Resolving patch:
diff --git a/numpy/lib/polynomial.py b/numpy/lib/polynomial.py
--- a/numpy/lib/polynomial.py
+++ b/numpy/lib/polynomial.py
@@ -494,11 +494,12 @@ def polyfit(x, y, deg, rcond=None, full=False, w=None, cov=False):
     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
-        chi2/sqrt(N-dof), i.e., the weights are presumed 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 uncertainty.
+        chi2/dof, where dof = M - (deg + 1), i.e., the weights are presumed 
+        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 
+        uncertainty.
 
     Returns
     -------


Test patch: