Re: [boost] Review Request: Statistical Distributions and Mathematical Special Functions

From: John Maddock (john_at_[hidden])
Date: 2007-01-08 12:19:57

Markus Werle wrote:
> John Maddock <john <at> johnmaddock.co.uk> writes:
>
>>
>> The "Math Toolkit" has now matured to the point where Paul Bristow
>> and I would like to ask for a formal review.
>
> Some comments before the review begins (If you allow):

No problem at all: the more feedback the better.

> In the docs sometimes you have formulations like e.g.
> "Returns the cubed root of x.". For native speakers this may be no
> problem,
> but sqrt(x)^3 may be easier to catch for the rest of us.

That would be x^(1/3) :-)

I've just added that.

> Also I dislike: "The definition used here is that used by Wolfram
> MathWorld" since by this the docs are neither self-contained nor
> robust against

Hmmm, that section could be better phrased,

Looks like we need a concise definition of "kertosis", but there are limits 
to how much we can rewrite what's already very well explained elsewhere.

> Citing papers is OK, but it takes a few thousand dollars to get them
> all I guess. So adding an outline of the algorithm would be nice for
> all functions (though saying what you use is GoodStuff(TM), too).

The special functions all have an "implementation" section that should 
provide that (or at least a formula).  However, there are some papers that 
are just too complex to summarise (the methods used to obtain the initial 
approximations for the inverse incomplete gamma and beta functions are good 
examples of this).

The aim is that someone should be able to get the jist of the code, by 
refering to the implementation section and the formulae.  They may still 
need to do a bit of pencil and paper math to get their head round some of 
the formulae, but that's not necessarily a bad thing :-)

> Since I got really excited about gamma functions (I need them and had
> hard times evaluating exact solutions from continuum mechanics):
> The Definition section needs some rework and the warnings about the
> different definitions will not help much in this form (at least for
> me, the stupid one)
>
> I see no connection between \Int R(t, s) dt and the definitions F, E
> and \Pi so here again the docs are a little bit confusing and the
> information about gamma function definitions and what Legendre found
> out will not enter my brain without further information from other
> sources which I find odd.

Now I'm confused: the functions F, E and Pi relate to the exponential 
integrals, the incomplete gamma functions are traditionally denoted P and Q 
(for the regularized forms) and with upper and lower case gamma's for 
full-non-regularized versions.  They are fully defined by the definitions 
given (the integrals), and those definitions are completely standard, so 
giving information beyond that is the job of the textbooks: like A&S etc.

Which functions were you looking for?

> OTOH given these function on a silver tablet I'd like to say:
> Thank You!
>
>
> What I also dislike is the existence of default typedefs for double
> (students_t et al.). This is unnecessary and makes double a special
> type
> which it is not.
> I'd vote for removing those from the boost version of this due to the
> asymmetry it produces.

I'd be interested in other views on this: my gut feeling is that hardly any 
users of the statistics code will be using anything except double precision. 
The convenience of being able to write:

quantile(students_t(10), .95);  // 95% quantile for 10 degrees freedom

is well worth it IMO.  The alternative:

quantile(students_t_distribution<double>(10), .95);

is unnecessarily verbose in comparison.  It's like writing:

std::string

rather than:

std::basic_string<char>

all the time.

Thanks for the feedback,

John.