What happened to the numpy.random documentation?
Hi All, The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation: https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html Now the same page in the API documentation looks like this: https://numpy.org/doc/stable/reference/random/index.html While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference. From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc). Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries. Cheers, Paul Magwene
Hi Paul, Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this? - Melissa On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Cheers, Paul Magwene _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
I second that reinstating such a list would be extremely useful. My issue has been with the polynomial package, but the end result is the same. - Joe On Thu, Oct 14, 2021, 12:45 Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Cheers, Paul Magwene _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: jfoxrabinovitz@gmail.com
On Thursday, October 14, 2021, Joseph Fox-Rabinovitz < jfoxrabinovitz@gmail.com> wrote:
I second that reinstating such a list would be extremely useful. My issue has been with the polynomial package, but the end result is the same.
There's a mostly relevant issue: https://github.com/numpy/numpy/issues/19420 András
- Joe
On Thu, Oct 14, 2021, 12:45 Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Cheers, Paul Magwene _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: jfoxrabinovitz@gmail.com
Hi Melissa, I think that's the right approach. Looking through the current docs, I think the page on the FFT module is exemplary in this regard: https://numpy.org/doc/stable/reference/routines.fft.html It lists all the available functions (with links to details), and then has a section on "Background Information", "Implementation Details", etc. It's easy to get a quick overview of what the available functions are, and then ease into the background info in terms of how it works. Cheers, Paul On Thu, Oct 14, 2021 at 12:44 PM Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Cheers, Paul Magwene _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: pmmagic@gmail.com
I think the issue in random specifically is that a raw list of available functions does not provide suitable guidance for someone looking for random variate generating function. This is because the module-level API is mostly dominated by methods of the singleton RandomState instance. Best practice going forward is to use the methods of a Generator instance, most likely provided by default_rng(). A simple API-list will not be able to provide this guidance. FFT has a very simple API and so a simple list make sense. Similarly, np.random before the generation was revamped, which is hy the old-style was adequate for <=1.16, but not for >=1.17 Kevin On Thu, Oct 14, 2021 at 6:09 PM Paul M. <pmmagic@gmail.com> wrote:
Hi Melissa,
I think that's the right approach. Looking through the current docs, I think the page on the FFT module is exemplary in this regard:
https://numpy.org/doc/stable/reference/routines.fft.html
It lists all the available functions (with links to details), and then has a section on "Background Information", "Implementation Details", etc. It's easy to get a quick overview of what the available functions are, and then ease into the background info in terms of how it works.
Cheers, Paul
On Thu, Oct 14, 2021 at 12:44 PM Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Cheers, Paul Magwene _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: pmmagic@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
Hi Kevin, I'm all for wanting the docs to guide folks to current best practice, but in its current form the documentation for this module is quite opaque. Maybe a table like the old version that maps old functionality to exemplar versions using Generator instances would be a useful compromise? Cheers, Paul On Thu, Oct 14, 2021 at 1:19 PM Kevin Sheppard <kevin.k.sheppard@gmail.com> wrote:
I think the issue in random specifically is that a raw list of available functions does not provide suitable guidance for someone looking for random variate generating function. This is because the module-level API is mostly dominated by methods of the singleton RandomState instance. Best practice going forward is to use the methods of a Generator instance, most likely provided by default_rng(). A simple API-list will not be able to provide this guidance.
FFT has a very simple API and so a simple list make sense. Similarly, np.random before the generation was revamped, which is hy the old-style was adequate for <=1.16, but not for >=1.17
Kevin
On Thu, Oct 14, 2021 at 6:09 PM Paul M. <pmmagic@gmail.com> wrote:
Hi Melissa,
I think that's the right approach. Looking through the current docs, I think the page on the FFT module is exemplary in this regard:
https://numpy.org/doc/stable/reference/routines.fft.html
It lists all the available functions (with links to details), and then has a section on "Background Information", "Implementation Details", etc. It's easy to get a quick overview of what the available functions are, and then ease into the background info in terms of how it works.
Cheers, Paul
On Thu, Oct 14, 2021 at 12:44 PM Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Cheers, Paul Magwene _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: pmmagic@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: pmmagic@gmail.com
On Thu, Oct 14, 2021 at 7:19 PM Kevin Sheppard <kevin.k.sheppard@gmail.com> wrote:
I think the issue in random specifically is that a raw list of available functions does not provide suitable guidance for someone looking for random variate generating function. This is because the module-level API is mostly dominated by methods of the singleton RandomState instance. Best practice going forward is to use the methods of a Generator instance, most likely provided by default_rng(). A simple API-list will not be able to provide this guidance.
The list can be annotated with headings and one-line or one-paragraph descriptions, something like: ``` ## Generator interface This is the recommended interface ... <etc - list methods too> ## Interface for unit testing and legacy code <explain purpose, then list all routines> ``` The complaint is very much valid here, I have made the same one before. The way the page currently is written makes little sense - it addresses a user transitioning from the old to the new interface, or explicitly comparing the two for some reason. To a user just looking for information on NumPy today, that's more confusing than helpful. The page also talks about "The new interface", "What's new and different", "Some long-overdue API cleanup", and "Since Numpy version 1.17.0" - that all belongs in a NEP, and not in the API reference docs. Cheers, Ralf
FFT has a very simple API and so a simple list make sense. Similarly, np.random before the generation was revamped, which is hy the old-style was adequate for <=1.16, but not for >=1.17
Kevin
On Thu, Oct 14, 2021 at 6:09 PM Paul M. <pmmagic@gmail.com> wrote:
Hi Melissa,
I think that's the right approach. Looking through the current docs, I think the page on the FFT module is exemplary in this regard:
https://numpy.org/doc/stable/reference/routines.fft.html
It lists all the available functions (with links to details), and then has a section on "Background Information", "Implementation Details", etc. It's easy to get a quick overview of what the available functions are, and then ease into the background info in terms of how it works.
Cheers, Paul
On Thu, Oct 14, 2021 at 12:44 PM Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Cheers, Paul Magwene _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: pmmagic@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: ralf.gommers@googlemail.com
On Thu, Oct 14, 2021 at 7:22 PM Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Thu, Oct 14, 2021 at 7:19 PM Kevin Sheppard <kevin.k.sheppard@gmail.com> wrote:
I think the issue in random specifically is that a raw list of available functions does not provide suitable guidance for someone looking for random variate generating function. This is because the module-level API is mostly dominated by methods of the singleton RandomState instance. Best practice going forward is to use the methods of a Generator instance, most likely provided by default_rng(). A simple API-list will not be able to provide this guidance.
The list can be annotated with headings and one-line or one-paragraph descriptions, something like:
``` ## Generator interface
This is the recommended interface ... <etc - list methods too>
## Interface for unit testing and legacy code
<explain purpose, then list all routines> ```
The complaint is very much valid here, I have made the same one before. The way the page currently is written makes little sense - it addresses a user transitioning from the old to the new interface, or explicitly comparing the two for some reason. To a user just looking for information on NumPy today, that's more confusing than helpful.
The page also talks about "The new interface", "What's new and different", "Some long-overdue API cleanup", and "Since Numpy version 1.17.0" - that all belongs in a NEP, and not in the API reference docs.
Cheers, Ralf
I don't think the doc style there is ideal. I would still say that a relatively naive dump of `np.random` (something that would be everything in [v for v in dir(np.random) if not v.startswith("_")] would not lead to an idea set of docs because most of the "obvious" functions are methods of the legacy RandomState. A good set would need something like (excluding headers) default_rng Generator Generator.random Generator.integers ... <much lower, or IMO better in a a sperate page> Legacy Methods ============== <short explainer> np.random.random_sample np.random.randint RandmState ... IMO many (likely most) methods exposed in np.random should not be on the default landing page for np.random. Best, Kevin
FFT has a very simple API and so a simple list make sense. Similarly, np.random before the generation was revamped, which is hy the old-style was adequate for <=1.16, but not for >=1.17
Kevin
On Thu, Oct 14, 2021 at 6:09 PM Paul M. <pmmagic@gmail.com> wrote:
Hi Melissa,
I think that's the right approach. Looking through the current docs, I think the page on the FFT module is exemplary in this regard:
https://numpy.org/doc/stable/reference/routines.fft.html
It lists all the available functions (with links to details), and then has a section on "Background Information", "Implementation Details", etc. It's easy to get a quick overview of what the available functions are, and then ease into the background info in terms of how it works.
Cheers, Paul
On Thu, Oct 14, 2021 at 12:44 PM Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Cheers, Paul Magwene _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: pmmagic@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: ralf.gommers@googlemail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
As a cosmic coincidence this happened to me yesterday. My goal: generate n-long arrays of 1s and -1s picked from a uniform distribution to mimic BLAS function ?LARNV. Full disclosure: I know a bit about the subject, but I'm not an expert and too lazy to gather my thoughts about it at the moment because I think I'll need "choice" so I just want to end up there quickly. - So I went to the docs, and picked numpy.random from the left menu. It started with some paragraphs, ok something somehing bitgenerator ok fine interesting. - Started scrolling down, OK old vs new hmm what is RandomState... nevermind replaced with something new; where is the numpy.random.rand stuff? ... nevermind scroll more - OK some more stuff about what's new... then a try except block. None of this seems familiar - Introduction section !? in the middle of the page. OK am I in the correct page? - Things are getting tough now I'm in the PCG64 something something... What is all stuff about? - OK intro is over then a section "What's new or different"... I am not introduced sufficiently yet... - Giving up and scrolling all the way down and up a few more - OK go back to google, search for "numpy choice" end up in numpy.random.choice. - There is a warning ... it says this is old stuff see QuickStart - click and we are back :) This is really not a complaint, I think there is an occupational hazard about random stuff throughout the internet. An insatiable urge to teach people about pseudorandom processes but I don't think it is the right way to go about it. Unless you are knee deep in this area almost none of this matters to an average user. We had this discussion before over SciPy about setting a seed as easy as the good ol' "numpy.random.seed" but all I am getting is extensive details about how the engine works. I appreciate the state-of-art implementation of any method but it can be saved for the interested who wants to geek about it. Otherwise it would be really beneficial if quick start is indeed quick. Currently it is a bit unquick :) Best, ilhan On Fri, Oct 15, 2021 at 12:13 PM Kevin Sheppard <kevin.k.sheppard@gmail.com> wrote:
On Thu, Oct 14, 2021 at 7:22 PM Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Thu, Oct 14, 2021 at 7:19 PM Kevin Sheppard < kevin.k.sheppard@gmail.com> wrote:
I think the issue in random specifically is that a raw list of available functions does not provide suitable guidance for someone looking for random variate generating function. This is because the module-level API is mostly dominated by methods of the singleton RandomState instance. Best practice going forward is to use the methods of a Generator instance, most likely provided by default_rng(). A simple API-list will not be able to provide this guidance.
The list can be annotated with headings and one-line or one-paragraph descriptions, something like:
``` ## Generator interface
This is the recommended interface ... <etc - list methods too>
## Interface for unit testing and legacy code
<explain purpose, then list all routines> ```
The complaint is very much valid here, I have made the same one before. The way the page currently is written makes little sense - it addresses a user transitioning from the old to the new interface, or explicitly comparing the two for some reason. To a user just looking for information on NumPy today, that's more confusing than helpful.
The page also talks about "The new interface", "What's new and different", "Some long-overdue API cleanup", and "Since Numpy version 1.17.0" - that all belongs in a NEP, and not in the API reference docs.
Cheers, Ralf
I don't think the doc style there is ideal. I would still say that a relatively naive dump of `np.random` (something that would be everything in [v for v in dir(np.random) if not v.startswith("_")] would not lead to an idea set of docs because most of the "obvious" functions are methods of the legacy RandomState. A good set would need something like (excluding headers)
default_rng Generator Generator.random Generator.integers ...
<much lower, or IMO better in a a sperate page> Legacy Methods ============== <short explainer> np.random.random_sample np.random.randint RandmState ...
IMO many (likely most) methods exposed in np.random should not be on the default landing page for np.random.
Best, Kevin
FFT has a very simple API and so a simple list make sense. Similarly, np.random before the generation was revamped, which is hy the old-style was adequate for <=1.16, but not for >=1.17
Kevin
On Thu, Oct 14, 2021 at 6:09 PM Paul M. <pmmagic@gmail.com> wrote:
Hi Melissa,
I think that's the right approach. Looking through the current docs, I think the page on the FFT module is exemplary in this regard:
https://numpy.org/doc/stable/reference/routines.fft.html
It lists all the available functions (with links to details), and then has a section on "Background Information", "Implementation Details", etc. It's easy to get a quick overview of what the available functions are, and then ease into the background info in terms of how it works.
Cheers, Paul
On Thu, Oct 14, 2021 at 12:44 PM Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Cheers, Paul Magwene _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: pmmagic@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: ralf.gommers@googlemail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: ilhanpolat@gmail.com
Hi, Maybe a short introduction like this one: https://albertcthomas.github.io/good-practices-random-number-generators/ could help to get the idea. Cheers Carl Am Fr., 15. Okt. 2021 um 13:51 Uhr schrieb Ilhan Polat <ilhanpolat@gmail.com
:
As a cosmic coincidence this happened to me yesterday. My goal: generate n-long arrays of 1s and -1s picked from a uniform distribution to mimic BLAS function ?LARNV.
Full disclosure: I know a bit about the subject, but I'm not an expert and too lazy to gather my thoughts about it at the moment because I think I'll need "choice" so I just want to end up there quickly.
- So I went to the docs, and picked numpy.random from the left menu. It started with some paragraphs, ok something somehing bitgenerator ok fine interesting. - Started scrolling down, OK old vs new hmm what is RandomState... nevermind replaced with something new; where is the numpy.random.rand stuff? ... nevermind scroll more - OK some more stuff about what's new... then a try except block. None of this seems familiar - Introduction section !? in the middle of the page. OK am I in the correct page? - Things are getting tough now I'm in the PCG64 something something... What is all stuff about? - OK intro is over then a section "What's new or different"... I am not introduced sufficiently yet... - Giving up and scrolling all the way down and up a few more
- OK go back to google, search for "numpy choice" end up in numpy.random.choice. - There is a warning ... it says this is old stuff see QuickStart - click and we are back :)
This is really not a complaint, I think there is an occupational hazard about random stuff throughout the internet. An insatiable urge to teach people about pseudorandom processes but I don't think it is the right way to go about it. Unless you are knee deep in this area almost none of this matters to an average user. We had this discussion before over SciPy about setting a seed as easy as the good ol' "numpy.random.seed" but all I am getting is extensive details about how the engine works. I appreciate the state-of-art implementation of any method but it can be saved for the interested who wants to geek about it. Otherwise it would be really beneficial if quick start is indeed quick. Currently it is a bit unquick :)
Best, ilhan
On Fri, Oct 15, 2021 at 12:13 PM Kevin Sheppard < kevin.k.sheppard@gmail.com> wrote:
On Thu, Oct 14, 2021 at 7:22 PM Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Thu, Oct 14, 2021 at 7:19 PM Kevin Sheppard < kevin.k.sheppard@gmail.com> wrote:
I think the issue in random specifically is that a raw list of available functions does not provide suitable guidance for someone looking for random variate generating function. This is because the module-level API is mostly dominated by methods of the singleton RandomState instance. Best practice going forward is to use the methods of a Generator instance, most likely provided by default_rng(). A simple API-list will not be able to provide this guidance.
The list can be annotated with headings and one-line or one-paragraph descriptions, something like:
``` ## Generator interface
This is the recommended interface ... <etc - list methods too>
## Interface for unit testing and legacy code
<explain purpose, then list all routines> ```
The complaint is very much valid here, I have made the same one before. The way the page currently is written makes little sense - it addresses a user transitioning from the old to the new interface, or explicitly comparing the two for some reason. To a user just looking for information on NumPy today, that's more confusing than helpful.
The page also talks about "The new interface", "What's new and different", "Some long-overdue API cleanup", and "Since Numpy version 1.17.0" - that all belongs in a NEP, and not in the API reference docs.
Cheers, Ralf
I don't think the doc style there is ideal. I would still say that a relatively naive dump of `np.random` (something that would be everything in [v for v in dir(np.random) if not v.startswith("_")] would not lead to an idea set of docs because most of the "obvious" functions are methods of the legacy RandomState. A good set would need something like (excluding headers)
default_rng Generator Generator.random Generator.integers ...
<much lower, or IMO better in a a sperate page> Legacy Methods ============== <short explainer> np.random.random_sample np.random.randint RandmState ...
IMO many (likely most) methods exposed in np.random should not be on the default landing page for np.random.
Best, Kevin
FFT has a very simple API and so a simple list make sense. Similarly, np.random before the generation was revamped, which is hy the old-style was adequate for <=1.16, but not for >=1.17
Kevin
On Thu, Oct 14, 2021 at 6:09 PM Paul M. <pmmagic@gmail.com> wrote:
Hi Melissa,
I think that's the right approach. Looking through the current docs, I think the page on the FFT module is exemplary in this regard:
https://numpy.org/doc/stable/reference/routines.fft.html
It lists all the available functions (with links to details), and then has a section on "Background Information", "Implementation Details", etc. It's easy to get a quick overview of what the available functions are, and then ease into the background info in terms of how it works.
Cheers, Paul
On Thu, Oct 14, 2021 at 12:44 PM Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
> Hi All, > > The documentation of Numpy's submodules used to have a fairly > standard structure as shown here in the 1.16 documentation: > > > https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html > > Now the same page in the API documentation looks like this: > > https://numpy.org/doc/stable/reference/random/index.html > > While I appreciate the expository text in the new documentation > about how the generators work, this new version is much less useful as a > reference to the API. It seems like it might fit better in the user manual > rather than the API reference. > > From my perspective it seems like the new version of the > documentation is harder to navigate in terms of finding information quickly > (more scrolling, harder to get a bird's eye view of functions in various > submodules, etc). > > Has anyone else had a similar reaction to the changes? I teach a > couple of courses in scientific computing and bioinformatics and my > students seem to also struggle to get a sense of what the different modules > offer based on the new version of the documentation. For now, I'm referring > them to the old (1.70) reference manuals as a better way to get acquainted > with the libraries. > > Cheers, > Paul Magwene > _______________________________________________ > NumPy-Discussion mailing list -- numpy-discussion@python.org > To unsubscribe send an email to numpy-discussion-leave@python.org > https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ > Member address: melissawm@gmail.com > _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: pmmagic@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: ralf.gommers@googlemail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: ilhanpolat@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: cmkleffner@gmail.com
On Fri, Oct 15, 2021 at 12:11 PM Kevin Sheppard <kevin.k.sheppard@gmail.com> wrote:
On Thu, Oct 14, 2021 at 7:22 PM Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Thu, Oct 14, 2021 at 7:19 PM Kevin Sheppard < kevin.k.sheppard@gmail.com> wrote:
I think the issue in random specifically is that a raw list of available functions does not provide suitable guidance for someone looking for random variate generating function. This is because the module-level API is mostly dominated by methods of the singleton RandomState instance. Best practice going forward is to use the methods of a Generator instance, most likely provided by default_rng(). A simple API-list will not be able to provide this guidance.
The list can be annotated with headings and one-line or one-paragraph descriptions, something like:
``` ## Generator interface
This is the recommended interface ... <etc - list methods too>
## Interface for unit testing and legacy code
<explain purpose, then list all routines> ```
The complaint is very much valid here, I have made the same one before. The way the page currently is written makes little sense - it addresses a user transitioning from the old to the new interface, or explicitly comparing the two for some reason. To a user just looking for information on NumPy today, that's more confusing than helpful.
The page also talks about "The new interface", "What's new and different", "Some long-overdue API cleanup", and "Since Numpy version 1.17.0" - that all belongs in a NEP, and not in the API reference docs.
Cheers, Ralf
I don't think the doc style there is ideal. I would still say that a relatively naive dump of `np.random` (something that would be everything in [v for v in dir(np.random) if not v.startswith("_")] would not lead to an idea set of docs because most of the "obvious" functions are methods of the legacy RandomState. A good set would need something like (excluding headers)
default_rng Generator Generator.random Generator.integers ...
<much lower, or IMO better in a a sperate page> Legacy Methods ============== <short explainer> np.random.random_sample np.random.randint RandmState ...
I don't think we're disagreeing, this is very close to what I was suggesting. IMO many (likely most) methods exposed in np.random should not be on the
default landing page for np.random.
They should stay on that page, if they're marked as legacy with a brief explanation that'll guide people to the recommended API just fine. Every public object should be in the docs, and these are heavily used functions. Cheers, Ralf Best,
Kevin
FFT has a very simple API and so a simple list make sense. Similarly, np.random before the generation was revamped, which is hy the old-style was adequate for <=1.16, but not for >=1.17
Kevin
On Thu, Oct 14, 2021 at 6:09 PM Paul M. <pmmagic@gmail.com> wrote:
Hi Melissa,
I think that's the right approach. Looking through the current docs, I think the page on the FFT module is exemplary in this regard:
https://numpy.org/doc/stable/reference/routines.fft.html
It lists all the available functions (with links to details), and then has a section on "Background Information", "Implementation Details", etc. It's easy to get a quick overview of what the available functions are, and then ease into the background info in terms of how it works.
Cheers, Paul
On Thu, Oct 14, 2021 at 12:44 PM Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Cheers, Paul Magwene _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: pmmagic@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: ralf.gommers@googlemail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: ralf.gommers@googlemail.com
Moved this discussion to an issue: https://github.com/numpy/numpy/issues/20121 Feel free to add your own thoughts and suggestions there. On Fri, Oct 15, 2021 at 9:11 AM Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Fri, Oct 15, 2021 at 12:11 PM Kevin Sheppard < kevin.k.sheppard@gmail.com> wrote:
On Thu, Oct 14, 2021 at 7:22 PM Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Thu, Oct 14, 2021 at 7:19 PM Kevin Sheppard < kevin.k.sheppard@gmail.com> wrote:
I think the issue in random specifically is that a raw list of available functions does not provide suitable guidance for someone looking for random variate generating function. This is because the module-level API is mostly dominated by methods of the singleton RandomState instance. Best practice going forward is to use the methods of a Generator instance, most likely provided by default_rng(). A simple API-list will not be able to provide this guidance.
The list can be annotated with headings and one-line or one-paragraph descriptions, something like:
``` ## Generator interface
This is the recommended interface ... <etc - list methods too>
## Interface for unit testing and legacy code
<explain purpose, then list all routines> ```
The complaint is very much valid here, I have made the same one before. The way the page currently is written makes little sense - it addresses a user transitioning from the old to the new interface, or explicitly comparing the two for some reason. To a user just looking for information on NumPy today, that's more confusing than helpful.
The page also talks about "The new interface", "What's new and different", "Some long-overdue API cleanup", and "Since Numpy version 1.17.0" - that all belongs in a NEP, and not in the API reference docs.
Cheers, Ralf
I don't think the doc style there is ideal. I would still say that a relatively naive dump of `np.random` (something that would be everything in [v for v in dir(np.random) if not v.startswith("_")] would not lead to an idea set of docs because most of the "obvious" functions are methods of the legacy RandomState. A good set would need something like (excluding headers)
default_rng Generator Generator.random Generator.integers ...
<much lower, or IMO better in a a sperate page> Legacy Methods ============== <short explainer> np.random.random_sample np.random.randint RandmState ...
I don't think we're disagreeing, this is very close to what I was suggesting.
IMO many (likely most) methods exposed in np.random should not be on the
default landing page for np.random.
They should stay on that page, if they're marked as legacy with a brief explanation that'll guide people to the recommended API just fine. Every public object should be in the docs, and these are heavily used functions.
Cheers, Ralf
Best,
Kevin
FFT has a very simple API and so a simple list make sense. Similarly, np.random before the generation was revamped, which is hy the old-style was adequate for <=1.16, but not for >=1.17
Kevin
On Thu, Oct 14, 2021 at 6:09 PM Paul M. <pmmagic@gmail.com> wrote:
Hi Melissa,
I think that's the right approach. Looking through the current docs, I think the page on the FFT module is exemplary in this regard:
https://numpy.org/doc/stable/reference/routines.fft.html
It lists all the available functions (with links to details), and then has a section on "Background Information", "Implementation Details", etc. It's easy to get a quick overview of what the available functions are, and then ease into the background info in terms of how it works.
Cheers, Paul
On Thu, Oct 14, 2021 at 12:44 PM Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,
Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?
- Melissa
On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
> Hi All, > > The documentation of Numpy's submodules used to have a fairly > standard structure as shown here in the 1.16 documentation: > > > https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html > > Now the same page in the API documentation looks like this: > > https://numpy.org/doc/stable/reference/random/index.html > > While I appreciate the expository text in the new documentation > about how the generators work, this new version is much less useful as a > reference to the API. It seems like it might fit better in the user manual > rather than the API reference. > > From my perspective it seems like the new version of the > documentation is harder to navigate in terms of finding information quickly > (more scrolling, harder to get a bird's eye view of functions in various > submodules, etc). > > Has anyone else had a similar reaction to the changes? I teach a > couple of courses in scientific computing and bioinformatics and my > students seem to also struggle to get a sense of what the different modules > offer based on the new version of the documentation. For now, I'm referring > them to the old (1.70) reference manuals as a better way to get acquainted > with the libraries. > > Cheers, > Paul Magwene > _______________________________________________ > NumPy-Discussion mailing list -- numpy-discussion@python.org > To unsubscribe send an email to numpy-discussion-leave@python.org > https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ > Member address: melissawm@gmail.com > _______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: pmmagic@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: ralf.gommers@googlemail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: kevin.k.sheppard@gmail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: ralf.gommers@googlemail.com
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-leave@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: melissawm@gmail.com
On Thu, Oct 14, 2021 at 10:36 AM Paul M. <pmmagic@gmail.com> wrote:
Hi All,
The documentation of Numpy's submodules used to have a fairly standard structure as shown here in the 1.16 documentation:
https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
Now the same page in the API documentation looks like this:
https://numpy.org/doc/stable/reference/random/index.html
While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API. It seems like it might fit better in the user manual rather than the API reference.
From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc).
Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.
Agree. As a knowledgeable user, I like short and sweet for reference purposes. Ideally, there would be an easy way to get to the basic facts, and then access extra explanatory material if needed. Chuck
participants (9)
-
Andras Deak -
Carl Kleffner -
Charles R Harris -
Ilhan Polat -
Joseph Fox-Rabinovitz -
Kevin Sheppard -
Melissa Mendonça -
Paul M. -
Ralf Gommers