DOC: docstrings in robust.norms, improve, reorganize #9402

maxkuttner · 2024-10-19T07:09:12Z

closes DOC: docstrings in robust.norms, improve, reorganize #8807
tests added / passed.
code/documentation is well formatted.
properly formatted commit message. See
NumPy's guide.

This PR rebases #8975 to the current main branch with some minor additions and corrections.

Notes:

It is essential that you add a test when making code changes. Tests are not
needed for doc changes.
When adding a new function, test values should usually be verified in another package (e.g., R/SAS/Stata).
When fixing a bug, you must add a test that would produce the bug in main and
then show that it is fixed with the new code.
New code additions must be well formatted. Changes should pass flake8. If on Linux or OSX, you can
verify you changes are well formatted by running
```
git diff upstream/main -u -- "*.py" | flake8 --diff --isolated
```
assuming flake8 is installed. This command is also available on Windows
using the Windows System for Linux once flake8 is installed in the
local Linux environment. While passing this test is not required, it is good practice and it help
improve code quality in statsmodels.
Docstring additions must render correctly, including escapes and LaTeX.

maxkuttner · 2024-10-23T09:45:41Z

Hello @josef-pkt, is this PR ready to be merged?

bashtage · 2024-10-23T10:06:08Z

Could you address the review comments please?

maxkuttner · 2024-10-23T10:18:05Z

Could you address the review comments please?

It seems there are no review comments yet. Or am I not seeing them for some reason?

bashtage · 2024-10-20T15:10:32Z

statsmodels/robust/norms.py

+
+            \psi: \mathbb{R}^n \to \mathbb{R}^n
+
+            \psi(z) = z


Doesn't seem to match the formula below. Can you check?

bashtage · 2024-10-20T15:11:56Z

statsmodels/robust/norms.py

+
+            \text{weights}(z) = \begin{cases}
+                        \left(1 - \left(\frac{z}{
+                        c}\right)^4\right)^2, & \text{if }


Formula has k not 4.

bashtage · 2024-10-20T15:12:23Z

statsmodels/robust/norms.py

+            \psi: \mathbb{R}^n \to \mathbb{R}^n
+
+            \psi(z) = \begin{cases}
+                       z \left(1 - \frac{z}{c}^4\right)^2, & \text{if }


Same k in formula, not 4.

bashtage · 2024-10-23T11:12:11Z

Sorry, forgot to finish my review by requesting changes.

pep8speaks · 2024-10-23T18:21:35Z

Hello @maxkuttner! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2024-11-03 16:09:13 UTC

bashtage

Needs some more work. Some are not correct. The big issus is that many now have two mathematical details pages. Shoudl only have one, so need to replace existing if necessary.

bashtage · 2024-10-25T08:49:50Z

statsmodels/robust/norms.py

+
+            \text{weights}: \mathbb{R}^n \to \mathbb{R}^n
+
+            \text{weights}(z) = \frac{\psi(z)}{z}


This one doesn't seem to match the answer. Looks like weights(z) = 1

bashtage · 2024-10-25T08:51:39Z

statsmodels/robust/norms.py

+
+            \rho(z) = \begin{cases}
+                          \frac{z^2}{2}, & \text{if } \lvert z \rvert \le t \\
+                          \lvert z \rvert \ t - \frac{z^2}{2}, & \text{if }


Second case here seems to be wrong asn well. -0.5 t^2, not -0.5 z^2.

bashtage · 2024-10-25T08:56:39Z

statsmodels/robust/norms.py

+                          \lvert z \rvert \le a\pi \\
+                          2a, & \text{if } \lvert z \rvert > a\pi
+                      \end{cases}
+


This feel redundant given then math below. We should consolidate these definitions with the formula explanation contained in each, so that there aren't two explanations. Sometimes the formula is python math, sometimes it is LaTeX. I'm happy if you put your latex in place of the which ever is there.

Ok. Thank you for the feedback @bashtage. I understand - so ideally there would always be one formula (either latex or python math). I would therefore refactor all docstrings in this file to have the LaTex formulas in the "Returns" statement to consolidate the information of what the function does in there.

This would look like this:

def rho(self, z): r""" The robust criterion function for Andrew's wave. Parameters ---------- z : array_like 1d array Returns ------- rho : ndarray The elements of rho are defined as: .. math:: \rho: \mathbb{R}^n \to \mathbb{R}^n \rho(z) = \begin{cases} a^2 (1 - \cos(\frac{z}{a})), & \text{if } \lvert z \rvert \le a\pi \\ 2a, & \text{if } \lvert z \rvert > a\pi \end{cases} """

This way there would be one single place to look for this information. Is this how you imagined it?

bashtage · 2024-10-27T17:17:26Z

See this example. I think a good format would be

Parameters
----------
blah : ...

Returns
-------

Notes
------
rho is defined as 

   .. math::

      rho(z) & = a^2 *(1-cos(z/a)), |z| \leq a\pi \\
      rho(z) & = 2a, |z|>q\pi

Either this or skip the Notes section header and simply include the math as part of the returns.

Replace python formulas with LaTex. Move formulas to Notes section of docstring. Co-authored-by: Ca7Ac1 <Ca7Ac1@gmail.com>

maxkuttner · 2024-11-03T16:18:11Z

Hello @bashtage. I replaced the python math in the "Returns" section with LaTex math. Any chance you could have a quick look at it again?

josef-pkt · 2025-07-19T09:27:52Z

One disadvantage of the heavy LATEX is that it is difficult to read in the code editor.
I often rely on being able to read the formulas/equations when checking the code.

Maybe there is a compromise (or formula duplication) to have (also) a version with readable code

maxkuttner marked this pull request as ready for review October 19, 2024 07:10

josef-pkt added comp-docs comp-robust labels Oct 21, 2024

josef-pkt added this to the 0.15 milestone Oct 21, 2024

bashtage requested changes Oct 23, 2024

View reviewed changes

maxkuttner force-pushed the DocUpdates branch from bb69352 to 8a55450 Compare October 23, 2024 18:25

maxkuttner requested a review from bashtage October 23, 2024 18:30

bashtage requested changes Oct 25, 2024

View reviewed changes

maxkuttner force-pushed the DocUpdates branch 2 times, most recently from ed0b59f to 82933ea Compare November 3, 2024 15:49

DOC: docstrings in robust.norms, improve, reorganize

696d970

Replace python formulas with LaTex. Move formulas to Notes section of docstring. Co-authored-by: Ca7Ac1 <Ca7Ac1@gmail.com>

maxkuttner force-pushed the DocUpdates branch from 82933ea to 696d970 Compare November 3, 2024 16:09

maxkuttner requested a review from bashtage November 3, 2024 16:18

josef-pkt added the prio-elev label Jul 19, 2025


		\text{weights}: \mathbb{R}^n \to \mathbb{R}^n

		\text{weights}(z) = \frac{\psi(z)}{z}

DOC: docstrings in robust.norms, improve, reorganize #9402

Are you sure you want to change the base?

DOC: docstrings in robust.norms, improve, reorganize #9402

Uh oh!

Conversation

maxkuttner commented Oct 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maxkuttner commented Oct 23, 2024

Uh oh!

bashtage commented Oct 23, 2024

Uh oh!

maxkuttner commented Oct 23, 2024

Uh oh!

bashtage Oct 20, 2024

Choose a reason for hiding this comment

Uh oh!

bashtage Oct 20, 2024

Choose a reason for hiding this comment

Uh oh!

bashtage Oct 20, 2024

Choose a reason for hiding this comment

Uh oh!

bashtage commented Oct 23, 2024

Uh oh!

pep8speaks commented Oct 23, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Comment last updated at 2024-11-03 16:09:13 UTC

Uh oh!

bashtage left a comment

Choose a reason for hiding this comment

Uh oh!

bashtage Oct 25, 2024

Choose a reason for hiding this comment

Uh oh!

bashtage Oct 25, 2024

Choose a reason for hiding this comment

Uh oh!

bashtage Oct 25, 2024

Choose a reason for hiding this comment

Uh oh!

maxkuttner Oct 27, 2024

Choose a reason for hiding this comment

Uh oh!

bashtage commented Oct 27, 2024

Uh oh!

maxkuttner commented Nov 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

josef-pkt commented Jul 19, 2025

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

maxkuttner commented Oct 19, 2024 •

edited

Loading

pep8speaks commented Oct 23, 2024 •

edited

Loading

maxkuttner commented Nov 3, 2024 •

edited

Loading