Repository: numpy/numpy

Issue:
DOC: misleading description in https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.linalg.lstsq.html
This starts by saying "Solves the equation a x = b", which (except in special cases) it does not do.  Perhaps better is to start with "Computes a vector x that minimizes the Euclidean 2-norm || b - a x ||^2.  If the minimal 2-norm is zero, then we have ax=b."




Discussion:
The current documentation is here:

https://numpy.org/doc/1.18/reference/generated/numpy.linalg.lstsq.html#numpy.linalg.lstsq

The text is

> Solves the equation a x = b by computing a vector x that minimizes the squared Euclidean 2-norm \| b - a x \|^2_2. The equation may be under-, well-, or over-determined (i.e., the number of linearly independent rows of a can be less than, equal to, or greater than its number of linearly independent columns). If a is square and of full rank, then x (but for round-off error) is the “exact” solution of the equation.

The link that you mention refers to the documentation of an older version of NumPy (1.13.0), which will probably not be updated.

For information, NumPy now publishes the documentation on its own website: numpy.org
Ok, but the newer docs still say "Solves the equation ax=b".    Like most people, I use the docs which google finds.   There is no easy way to know that they are not the latest.

Keith


________________________________
From: Matti Picus <notifications@github.com>
Sent: 31 March 2020 10:11
To: numpy/numpy <numpy@noreply.github.com>
Cc: Briggs,KM,Keith,TUD2 R <keith.briggs@bt.com>; Author <author@noreply.github.com>
Subject: Re: [numpy/numpy] DOC: misleading description in https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.linalg.lstsq.html (#15874)


The newer documentation<https://numpy.org/devdocs/reference/generated/numpy.linalg.lstsq.html> is different. Is there a reason you are using the old, outdated documentation?

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub<https://github.com/numpy/numpy/issues/15874#issuecomment-606499133>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ABHIQEPOCB2Z76QQ5DYOAU3RKGXURANCNFSM4LXLRWOQ>.

I find the current wording careful. It states directly and in the same sentence that "solves" "by computing...".

The google problem is annoying. The NumPy developers have no control on Google's results of course, but should keep this in mind.
I still think my wording is better: "Computes a vector x that minimizes the Euclidean 2-norm || b - a x ||^2. If the minimal 2-norm is zero, then we have ax=b".  The obsolete pages could all have a warning added at the top, maybe with a link to the latest.
For the specific wording, I leave it to the maintainers who ultimately take the decisions.

I agree that we should put a warning on the older documentation.
Not a maintainer, but I agree with @keithbriggs from a mathematical point of view.
Sure, doc improvements are always welcome. Would be good to have a PR with a suggestion. I personally would hope we can find something simpler than "Computes a vector x that minimizes the Euclidean 2-norm || b - a x ||^2. If the minimal 2-norm is zero, then we have ax=b".

Not that it shouldn't mention all of that, but even if it is a bit misleading, saying "solves ax=b", or maybe "Tries to (approximately) solve solve ax=b" seems much simpler to me. Some users may already be confused by "2-norm", although the only solution to that would be mentioning that only after "in the least squares sense" or so.
Proposal: change the docstring of `numpy.linalg.lstsq` from

    Return the least-squares solution to a linear matrix equation.

    Solves the equation :math:`a x = b` by computing a vector `x` that
    minimizes the squared Euclidean 2-norm :math:`\| b - a x \|^2_2`.
    The equation may be under-, well-, or over-determined (i.e., the
    number of linearly independent rows of `a` can be less than, equal
    to, or greater than its number of linearly independent columns).
    If `a` is square and of full rank, then `x` (but for round-off error)
    is the "exact" solution of the equation.

To

    Return the least-squares solution to a linear matrix equation.

    Computes the vector x that approximatively solves the equation
    :math:`a x = b`.
    The equation may be under-, well-, or over-determined (i.e., the
    number of linearly independent rows of `a` can be less than, equal
    to, or greater than its number of linearly independent columns).
    If `a` is square and of full rank, then `x` (but for round-off error)
    is the "exact" solution of the equation. Else, `x` minimizes the
    Euclidean 2-norm :math:`|| b - a x ||^2`.

I removed "If the minimal 2-norm is zero, then we have ax=b." as the before to last sentence of the paragraph provides the same information.
-exp(iπ).
@keithbriggs do you have an interest in preparing a pull request? Else, I'll do it.
You can probably do it quicker than me.
Thanks!


________________________________
From: Pierre de Buyl <notifications@github.com>
Sent: 07 April 2020 09:22
To: numpy/numpy <numpy@noreply.github.com>
Cc: Briggs,KM,Keith,TUD2 R <keith.briggs@bt.com>; Mention <mention@noreply.github.com>
Subject: Re: [numpy/numpy] DOC: misleading description in https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.linalg.lstsq.html (#15874)


@keithbriggs<https://github.com/keithbriggs> do you have an interest in preparing a pull request? Else, I'll do it.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub<https://github.com/numpy/numpy/issues/15874#issuecomment-610248638>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ABHIQEJBZWGI276VYR7TOF3RLLPDZANCNFSM4LXLRWOQ>.


Resolving patch:
diff --git a/numpy/linalg/linalg.py b/numpy/linalg/linalg.py
--- a/numpy/linalg/linalg.py
+++ b/numpy/linalg/linalg.py
@@ -2172,13 +2172,13 @@ def lstsq(a, b, rcond="warn"):
     r"""
     Return the least-squares solution to a linear matrix equation.
 
-    Solves the equation :math:`a x = b` by computing a vector `x` that
-    minimizes the squared Euclidean 2-norm :math:`\| b - a x \|^2_2`.
-    The equation may be under-, well-, or over-determined (i.e., the
-    number of linearly independent rows of `a` can be less than, equal
-    to, or greater than its number of linearly independent columns).
+    Computes the vector x that approximatively solves the equation
+    ``a @ x = b``. The equation may be under-, well-, or over-determined
+    (i.e., the number of linearly independent rows of `a` can be less than,
+    equal to, or greater than its number of linearly independent columns).
     If `a` is square and of full rank, then `x` (but for round-off error)
-    is the "exact" solution of the equation.
+    is the "exact" solution of the equation. Else, `x` minimizes the
+    Euclidean 2-norm :math:`|| b - a x ||`.
 
     Parameters
     ----------


Test patch: