Repository: scipy/scipy

Issue:
DOC: rvalue description is missing in stats.probplot
The description of `rvalue` in `stats.probplot()` is missing.

```
def probplot(x, sparams=(), dist='norm', fit=True, plot=None, rvalue=False):
...
Parameters
    ----------
    x : array_like
        Sample/response data from which `probplot` creates the plot.
    sparams : tuple, optional
        Distribution-specific shape parameters (shape parameters plus location
        and scale).
    dist : str or stats.distributions instance, optional
        Distribution or distribution function name. The default is 'norm' for a
        normal probability plot.  Objects that look enough like a
        stats.distributions instance (i.e. they have a ``ppf`` method) are also
        accepted.
    fit : bool, optional
        Fit a least-squares regression (best-fit) line to the sample data if
        True (default).
    plot : object, optional
        If given, plots the quantiles.
        If given and `fit` is True, also plots the least squares fit.
        `plot` is an object that has to have methods "plot" and "text".
        The `matplotlib.pyplot` module or a Matplotlib Axes object can be used,
        or a custom object with the same methods.
        Default is None, which means that no plot is created.
    Returns
    -------
```
DOC: rvalue description is missing in stats.probplot
The description of `rvalue` in `stats.probplot()` is missing.

```
def probplot(x, sparams=(), dist='norm', fit=True, plot=None, rvalue=False):
...
Parameters
    ----------
    x : array_like
        Sample/response data from which `probplot` creates the plot.
    sparams : tuple, optional
        Distribution-specific shape parameters (shape parameters plus location
        and scale).
    dist : str or stats.distributions instance, optional
        Distribution or distribution function name. The default is 'norm' for a
        normal probability plot.  Objects that look enough like a
        stats.distributions instance (i.e. they have a ``ppf`` method) are also
        accepted.
    fit : bool, optional
        Fit a least-squares regression (best-fit) line to the sample data if
        True (default).
    plot : object, optional
        If given, plots the quantiles.
        If given and `fit` is True, also plots the least squares fit.
        `plot` is an object that has to have methods "plot" and "text".
        The `matplotlib.pyplot` module or a Matplotlib Axes object can be used,
        or a custom object with the same methods.
        Default is None, which means that no plot is created.
    Returns
    -------
```


Discussion:
Hi @msat59, thank you for reporting. Would you like to make a PR?
@tupui Can I contribute to this issue?
Hi @harivamsi9, yes of course since @msat59 did not reply. Thank you in advance 😃
Thank you @tupui ,  I am getting mixed answers online on the rvalue.
Would you be able give me some info, or pointers, regarding it? so I can refer and PR this quick?
@harivamsi9, The function prints `r**2` which corresponds to the coefficient of determination. https://en.wikipedia.org/wiki/Coefficient_of_determination

>  The function prints `r**2` which corresponds to the coefficient of determination.

@harivamsi9 the way you can tell is here:
https://github.com/scipy/scipy/blob/4cf21e753cf937d1c6c2d2a0e372fbc1dbbeea81/scipy/stats/_morestats.py#L616-L623

Above, `r` is returned by `linregress`.
https://github.com/scipy/scipy/blob/4cf21e753cf937d1c6c2d2a0e372fbc1dbbeea81/scipy/stats/_morestats.py#L603-L605

And you can read about `r` in the [`linregress` documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.linregress.html).

![image](https://user-images.githubusercontent.com/6570539/172383200-ca212c85-feff-4f31-9be4-73dd3e5a5555.png)

So a reasonable addition to the docstring would be:
```
    rvalue : bool, optional
        If `plot` is provided and `fit` is True, setting `rvalue` to True
        includes the coefficient of determination on the plot. 
        Default is False.
```
(My preference would be for the `True`s and `False`s to be enclosed in double-backticks throughout to render them in teletype because they refer to literals. But that is inconsistent in SciPy documentation, so I wouldn't ask for it to be changed in this function.)

---
Something else we should fix while we're at it is:
```
res = stats.probplot(x, plot=plt, fit=False, rvalue=True)
Traceback (most recent call last):

  File "C:\Users\matth\AppData\Local\Temp\ipykernel_19556\1053949826.py", line 1, in <module>
    res = stats.probplot(x, plot=plt, fit=False, rvalue=True)

  File "C:\Users\matth\Desktop\scipy\scipy\stats\_morestats.py", line 632, in probplot
    plot.text(posx, posy, "$R^2=%1.4f$" % r**2)

UnboundLocalError: local variable 'r' referenced before assignment
```
So I would change:
https://github.com/scipy/scipy/blob/4cf21e753cf937d1c6c2d2a0e372fbc1dbbeea81/scipy/stats/_morestats.py#L616
to 
```python
if fit and rvalue:
```
since it doesn't make much sense to show the coefficient of determination without the fit line.

Hey @tupui would it be okay if I contribute to this issue? I'm working on testing but will be finished soon
Hey @boatwrong, mine is done. 
@boatwrong we don't want people to compete and @harivamsi9 is still involved with this issue. There are plenty of other easy issues to tackle.
@tupui @harivamsi9  Sorry about that, thanks for the replies!
Hey @tupui , I made the required changes.
To perform all the unitests, and checks before raising a PR, I need the dev-env setup locally.

However, I facing issues with setting up the dev environment with conda (followed https://scipy.github.io/devdocs/dev/dev_quickstart.html) and when i execute 

> conda env create -f environment.yml

It is running for a while checking all the packages and examining conflicts.
However, after this, when i try to 

> conda activate scipy-dev

It says that the environment is not present. 
Could you be able to help me out?



What is the output of `conda env create -f environment.yml`?

On which system are you? If Windows, I suggest you use WSL. In general developing Python tools on Windows is a lot harder.
[output.txt](https://github.com/scipy/scipy/files/8861829/output.txt)

i am using windows 10
Yes we've seen this issue. There are some dependencies conflicts on windows. I don't know how to fix this yet and don't have a windows machine to investigate.

Meanwhile, I suggest you either use WSL, another system, docker or gitpod. See our guides.
Note that for this particular PR, since there is mostly doc changes you could send a PR without locally testing.
Hi @msat59, thank you for reporting. Would you like to make a PR?
@tupui Can I contribute to this issue?
Hi @harivamsi9, yes of course since @msat59 did not reply. Thank you in advance 😃
Thank you @tupui ,  I am getting mixed answers online on the rvalue.
Would you be able give me some info, or pointers, regarding it? so I can refer and PR this quick?
@harivamsi9, The function prints `r**2` which corresponds to the coefficient of determination. https://en.wikipedia.org/wiki/Coefficient_of_determination

>  The function prints `r**2` which corresponds to the coefficient of determination.

@harivamsi9 the way you can tell is here:
https://github.com/scipy/scipy/blob/4cf21e753cf937d1c6c2d2a0e372fbc1dbbeea81/scipy/stats/_morestats.py#L616-L623

Above, `r` is returned by `linregress`.
https://github.com/scipy/scipy/blob/4cf21e753cf937d1c6c2d2a0e372fbc1dbbeea81/scipy/stats/_morestats.py#L603-L605

And you can read about `r` in the [`linregress` documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.linregress.html).

![image](https://user-images.githubusercontent.com/6570539/172383200-ca212c85-feff-4f31-9be4-73dd3e5a5555.png)

So a reasonable addition to the docstring would be:
```
    rvalue : bool, optional
        If `plot` is provided and `fit` is True, setting `rvalue` to True
        includes the coefficient of determination on the plot. 
        Default is False.
```
(My preference would be for the `True`s and `False`s to be enclosed in double-backticks throughout to render them in teletype because they refer to literals. But that is inconsistent in SciPy documentation, so I wouldn't ask for it to be changed in this function.)

---
Something else we should fix while we're at it is:
```
res = stats.probplot(x, plot=plt, fit=False, rvalue=True)
Traceback (most recent call last):

  File "C:\Users\matth\AppData\Local\Temp\ipykernel_19556\1053949826.py", line 1, in <module>
    res = stats.probplot(x, plot=plt, fit=False, rvalue=True)

  File "C:\Users\matth\Desktop\scipy\scipy\stats\_morestats.py", line 632, in probplot
    plot.text(posx, posy, "$R^2=%1.4f$" % r**2)

UnboundLocalError: local variable 'r' referenced before assignment
```
So I would change:
https://github.com/scipy/scipy/blob/4cf21e753cf937d1c6c2d2a0e372fbc1dbbeea81/scipy/stats/_morestats.py#L616
to 
```python
if fit and rvalue:
```
since it doesn't make much sense to show the coefficient of determination without the fit line.

Hey @tupui would it be okay if I contribute to this issue? I'm working on testing but will be finished soon
Hey @boatwrong, mine is done. 
@boatwrong we don't want people to compete and @harivamsi9 is still involved with this issue. There are plenty of other easy issues to tackle.
@tupui @harivamsi9  Sorry about that, thanks for the replies!
Hey @tupui , I made the required changes.
To perform all the unitests, and checks before raising a PR, I need the dev-env setup locally.

However, I facing issues with setting up the dev environment with conda (followed https://scipy.github.io/devdocs/dev/dev_quickstart.html) and when i execute 

> conda env create -f environment.yml

It is running for a while checking all the packages and examining conflicts.
However, after this, when i try to 

> conda activate scipy-dev

It says that the environment is not present. 
Could you be able to help me out?



What is the output of `conda env create -f environment.yml`?

On which system are you? If Windows, I suggest you use WSL. In general developing Python tools on Windows is a lot harder.
[output.txt](https://github.com/scipy/scipy/files/8861829/output.txt)

i am using windows 10
Yes we've seen this issue. There are some dependencies conflicts on windows. I don't know how to fix this yet and don't have a windows machine to investigate.

Meanwhile, I suggest you either use WSL, another system, docker or gitpod. See our guides.
Note that for this particular PR, since there is mostly doc changes you could send a PR without locally testing.

Resolving patch:
diff --git a/scipy/stats/_morestats.py b/scipy/stats/_morestats.py
--- a/scipy/stats/_morestats.py
+++ b/scipy/stats/_morestats.py
@@ -510,6 +510,10 @@ def probplot(x, sparams=(), dist='norm', fit=True, plot=None, rvalue=False):
         The `matplotlib.pyplot` module or a Matplotlib Axes object can be used,
         or a custom object with the same methods.
         Default is None, which means that no plot is created.
+    rvalue : bool, optional
+        If `plot` is provided and `fit` is True, setting `rvalue` to True
+        includes the coefficient of determination on the plot.
+        Default is False.
 
     Returns
     -------
@@ -622,7 +626,7 @@ def probplot(x, sparams=(), dist='norm', fit=True, plot=None, rvalue=False):
                                title='Probability Plot')
 
         # Add R^2 value to the plot as text
-        if rvalue:
+        if fit and rvalue:
             xmin = amin(osm)
             xmax = amax(osm)
             ymin = amin(x)


Test patch: