On Thu, Oct 14, 2021 at 7:22 PM Ralf Gommers <ralf.gomm...@gmail.com> wrote:
>
>
> On Thu, Oct 14, 2021 at 7:19 PM Kevin Sheppard <kevin.k.shepp...@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. <pmma...@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 <meliss...@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. <pmma...@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-le...@python.org
>>>>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
>>>>> Member address: meliss...@gmail.com
>>>>>
>>>> _______________________________________________
>>>> NumPy-Discussion mailing list -- numpy-discussion@python.org
>>>> To unsubscribe send an email to numpy-discussion-le...@python.org
>>>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
>>>> Member address: pmma...@gmail.com
>>>>
>>> _______________________________________________
>>> NumPy-Discussion mailing list -- numpy-discussion@python.org
>>> To unsubscribe send an email to numpy-discussion-le...@python.org
>>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
>>> Member address: kevin.k.shepp...@gmail.com
>>>
>> _______________________________________________
>> NumPy-Discussion mailing list -- numpy-discussion@python.org
>> To unsubscribe send an email to numpy-discussion-le...@python.org
>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
>> Member address: ralf.gomm...@googlemail.com
>>
> _______________________________________________
> NumPy-Discussion mailing list -- numpy-discussion@python.org
> To unsubscribe send an email to numpy-discussion-le...@python.org
> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
> Member address: kevin.k.shepp...@gmail.com
>
_______________________________________________
NumPy-Discussion mailing list -- numpy-discussion@python.org
To unsubscribe send an email to numpy-discussion-le...@python.org
https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
Member address: arch...@mail-archive.com
