[SciPy-Dev] scipy stats, doc string

[josef.pktd at gmail.com]

On Tue, May 8, 2012 at 4:13 PM, nicky van foreest <vanforeest at gmail.com> wrote:
> Hi,
>
> As Josef pointed out earlier, the Erlang distribution causes some
> further problems wrt the documentation too. The automatically
> generated documentation uses n = 0.9 as a shape parameter, but the
> documentation says that n should be an int. This is a bit silly of
> course. There are two ways to repair this IMO.
>
> 1) As Josef suggested: port Erlang to the gamma distribution and refer
> in the erlang doc string to the gamma distribution. I admit that I
> favor this.
>
> 2) Ensure that Erlang only accepts an int as a shape, implement an
> extra _arg_check (as is currently done), and change
> the string in distributions.py to automatically set the shape
> parameter. Specifically:
>
> https://github.com/scipy/scipy/blob/master/scipy/stats/distributions.py#L222
>
> Would it be possible to change this line to something like
>
>>>> [ %(shapes)s ] = [%(shape_value)f,] * numargs

I think so, in general,
http://projects.scipy.org/scipy/ticket/1581

However it wouldn't work as in your example, since shape_value might
be empty or a list_like (several shape parameters)

each distribution would need a new attribute, example_shape_values (?)
 (or maybe default inherited is empty)

I'm not sure what to do about Erlang anymore.

Josef

>
> Then it would be possible to pass a distribution dependent shape value.
>
> All in all option 1 seems the easiest, and from a user's point of view
> (I still regard myself a user of scipy.stats) sufficiently clear.
> Given this, I propose the following docstring for erlang:
>
>
>    """An Erlang continuous random variable.
>
>    %(before_notes)s
>
>    See Also
>    --------
>    gamma
>
>    Notes
>    -----
>    The Erlang distribution is a special case of the Gamma
>    distribution, with the shape parameter ``a`` an integer. Refer to
>    the ``gamma`` distribution for further examples.
>
>    """
>
> Note that I also remove the examples. In the gamma docsting, on the
> other hand, I include some extra info. I'll do a pull request this
> evening, including this change.
>
>
>
>
> Nicky
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev