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 <ilhanpo...@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.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
>> ...
>>
>> 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: ilhanpo...@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: cmkleff...@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
