[SciPy-Dev] Design of scipy.stats

[josef.pktd at gmail.com]

On Tue, May 25, 2010 at 3:52 PM, David Goldsmith
<d.l.goldsmith at gmail.com> wrote:
> On Tue, May 25, 2010 at 11:04 AM, Robert Kern <robert.kern at gmail.com> wrote:
>>
>> On Tue, May 25, 2010 at 12:47, David Goldsmith <d.l.goldsmith at gmail.com>
>> wrote:
>> > On Tue, May 25, 2010 at 8:54 AM, Ralf Gommers
>> > <ralf.gommers at googlemail.com>
>> > wrote:
>>
>> >>>  Plus they're not really unimportant.
>> >>>
>> >>> Why not?  They're not returned by Python's help system.  (See earlier
>> >>> this same thread.)
>> >>
>> >> Compare "help(alpha)" with "print alpha.__doc__" - help() is broken
>> >> imho.
>> >
>> > Care to elaborate? ("Where I come from" help is the proper idiom - I've
>> > never heard of anyone using, nor being told to use, print .__doc__; your
>> > "ho" - that help is broken - strikes me as pretty strange).
>>
>> help() is broken in this case because it does not display the .__doc__
>> attribute that is present. Yes, help() is idiomatic. That doesn't mean
>> its behavior in this case is not broken. Nor does it mean that the
>> text in the .__doc__ attributes are Unimportant for the docstring
>> editing workflow. They just happen to be unavailable to the web
>> docstring editor for technical reasons.
>
> Perhaps the origin of this thread has been forgotten:
>
> help(alpha) returns:
>
>>>> help(alpha)
> Help on alpha_gen in module scipy.stats.distributions object:
>
> class alpha_gen(rv_continuous)
>  |  ## Alpha distribution
> :
> :
>
> help(alpha_gen) returns:
>
>>>> help(alpha_gen)
> Traceback (most recent call last):
>   File "<stdin>", line 1, in <module>
> NameError: name 'alpha_gen' is not defined

do you have alpha_gen in your namespace?
>>> from scipy import stats
>>> help(stats.distributions.alpha_gen)

>
> But (in the Wiki) scipy.stats.distributions.alpha is "full," whereas
> scipy.stats.distributions.alpha_gen is empty (but for automatically
> generated content): help and the doc Wiki appear to exhibit the "transpose"
> of one another - I don't know "which one" is "broken" in this situation, but
> obviously something is.

Most _gen don't have docstrings in the source, but are fully
automatically generated docs
An example for the new template based docstring is
http://docs.scipy.org/scipy/docs/scipy.stats.distributions.maxwell_gen/

I'd rather not have wholesale editing of distribution docstrings,
because it is too much to maintain, until we have established that any
new pattern really works. The recipe how distributions work, can be
explained generically without repeating variations on it in 90
different ways.

The pdf, cdf, ... formulas are attached to the scipy.stats tutorial,
based on the original documentation by Travis.

Josef


>
> At what level is help broken: the scipy level or the Python level?  If help
> is simply an alias for print .__doc__, why precisely is this happening?  Is
> this an undiagnosed breakage (in the sense that only the symptom(s), but
> neither the cause(s) nor the cure(s) are known)?
>
> Looking back on this thread, since <X> is the thing users are intended to
> use, it sounds like the docstring _should_ be associated with <X>, not
> <X>_gen, so I guess the Wiki is showing the docstring in the "right" place,
> but why does help associate the docstring with <X>_gen?  And if the
> docstring for <X> is consequently important, is the docstring for <X>_gen
> Unimportant (since its object "should" never be used explicitly)?  If its
> docstring is also important, please explain why.
>
> Thanks.
>
> DG
>
>>
>> If you want to mark them
>> Unimportant just as a workaround, that's fine. But if you are keeping
>> track of items to work on this summer, these are important things to
>> do. You will just have to do it manually.
>>
>> --
>> Robert Kern
>>
>> "I have come to believe that the whole world is an enigma, a harmless
>> enigma that is made terrible by our own mad attempt to interpret it as
>> though it had an underlying truth."
>>  -- Umberto Eco
>> _______________________________________________
>> SciPy-Dev mailing list
>> SciPy-Dev at scipy.org
>> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
>
> --
> Mathematician: noun, someone who disavows certainty when their uncertainty
> set is non-empty, even if that set has measure zero.
>
> Hope: noun, that delusive spirit which escaped Pandora's jar and, with her
> lies, prevents mankind from committing a general suicide.  (As interpreted
> by Robert Graves)
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>