On Fri, Oct 15, 2021 at 12:11 PM Kevin Sheppard <kevin.k.shepp...@gmail.com>
wrote:
>
>
> 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
> ...
>
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. <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: 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: arch...@mail-archive.com
