On Fri, Oct 15, 2021 at 12:11 PM Kevin Sheppard <[email protected]> wrote:
> > > On Thu, Oct 14, 2021 at 7:22 PM Ralf Gommers <[email protected]> > wrote: > >> >> >> On Thu, Oct 14, 2021 at 7:19 PM Kevin Sheppard < >> [email protected]> 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. <[email protected]> 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 <[email protected]> >>>> 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. <[email protected]> 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 -- [email protected] >>>>>> To unsubscribe send an email to [email protected] >>>>>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ >>>>>> Member address: [email protected] >>>>>> >>>>> _______________________________________________ >>>>> NumPy-Discussion mailing list -- [email protected] >>>>> To unsubscribe send an email to [email protected] >>>>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ >>>>> Member address: [email protected] >>>>> >>>> _______________________________________________ >>>> NumPy-Discussion mailing list -- [email protected] >>>> To unsubscribe send an email to [email protected] >>>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ >>>> Member address: [email protected] >>>> >>> _______________________________________________ >>> NumPy-Discussion mailing list -- [email protected] >>> To unsubscribe send an email to [email protected] >>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ >>> Member address: [email protected] >>> >> _______________________________________________ >> NumPy-Discussion mailing list -- [email protected] >> To unsubscribe send an email to [email protected] >> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ >> Member address: [email protected] >> > _______________________________________________ > NumPy-Discussion mailing list -- [email protected] > To unsubscribe send an email to [email protected] > https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ > Member address: [email protected] >
_______________________________________________ NumPy-Discussion mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: [email protected]
