[SciPy-Dev] Working on the docstring for stats.distributions.rv_continuous.fit

[Skipper Seabold]

On Tue, Jun 15, 2010 at 8:38 PM, David Goldsmith
<d.l.goldsmith at gmail.com> wrote:
> Hi!  IMHO, the descriptions of the *args & **kwds parameters of the
> Subject-referenced method are not very clear, so let me see if I understand
> correctly:
>

I agree and was having a look at this last week.  Here's my take.  I
would err on the side of verbose in these docs, as the stats docs seem
to be a general source of confusion from comments I've received off
list, though obviously Josef, Travis, and others would know the
details better than I.

> *args : float(s), optional
>     If the distribution in question depends on n parameters, _excluding
> location and scale_, then *args may contain 0 to n floats, which are
> starting estimates for the corresponding parameters.  No default value(s).
>

I would add a note that n can be found in the numargs attribute of the
distribution.

> **kwds _may_ contain the following:
>
> loc : float, optional
>     Starting estimate for the location parameter, no default.
>
> scale : float, optional
>     Starting estimate for the scale parameter, no default.

If the extra args *and* loc *and* scale are not specified, then the
default starting estimates for loc, scale, and args are taken from the
distribution's _fitstart(data) method.  I think it would make more
sense to take the defaults for ones that are not provided by the user
only, but this is not how the code reads at the moment as far as I can
tell.

> floc : bool, optional
>     Hold the location parameter constant; default: False.
>

floc : float, optional
    Hold the location parameter constant at the given value.  Default:
Fit this parameter using the data.

> fscale : bool, optional
>     Hold the scale parameter constant; default: False
>

See above.

> fi : bool, optional
>     Hold the i-th scale parameter constant; there may be up to len(args) of
> these; default: False
>

I would keep it as something like

f1...fn : float, optional
   Hold shape parameter fi constant at the given value, where i may be
1 to numargs of the distribution.


Skipper