[R] Incomplete Gamma function

[Robin Hankin]

Hello Ted


thanks for the comments below.

You point out below some less-than-perfect aspects of
some of my documentation (bizarrely, this is not the first time that  
this
has happened.  The real problem is  that *other people* insist on
reading the docs, when as everyone knows, the real purpose
of documentation is to remind the *developer* what he's done ;-).

The issue with the gsl_sf_ prefix is interesting.  I decided that
having an R function named "gsl_sf_gamma_inc()" would be
a bit long-winded, so I removed the prefix.  I did this elsewhere
too, notably Bessel.Rd, because I felt that the GSL naming scheme
was sufficiently distinct from R's in the case of Bessel functions to
obviate typing "gsl_sf_" every single time.

But as you point out, this is potentially confusing to a user; as a
developer, one tends to see the Rd file as one of a number of files
that one must edit, and in the case of  the gsl library, the R and C
code is very regimented and has adequate inline comments.  But
I'd lost sight of the fact that many users' sole source of documentation
is the Rd files.  And in the  case of gsl, the documentation is just a
pointer to ams-55 via gsl-ref [the GSL reference manual].  I now
suspect that my short function definitions have unnecessarily
obscured that audit trail.

What I think I'll do  (read "will add to my to-do-list")
is to (eg) define R function gsl_sf_gamma_inc()
and then define gamma_inc <- gsl_sf_gamma_inc
and add appropriate aliases to the docs.

Then I could deprecate gsl_inc(); and then possibly defunct them.

Anyone got any comments on this?  Do other package developers
have any experiences of making functions defunct that would be  
interesting?
How long do folk leave functions deprecated before defuncting them?

best wishes

Robin


On 1 Sep 2007, at 15:50, (Ted Harding) wrote:


[snip]

>
> In the documenation for the Gamma functions in the gsl package,
> it is simply stated
>
>   All functions [including gamma_inc()] as documented in the
>   GSL reference manual section 7.19.
>
> There is no function named "gamma_inc" in the GSL reference
> manual. See:
>
> http://www.gnu.org/software/gsl/manual/html_node/Function-Index.html
>
> All functions are named like "gsl_sf_gamma_inc", so
> presumably this is what is intended; in which case it computes
> "the unnormalized incomplete Gamma Function
>  \Gamma(a,x) = \int_x^\infty dt t^{a-1} \exp(-t)
>  for a real and x >= 0."
>
> And again that is clear enough -- once you track it down!
>
> In many places in the R documentation (including the "?" pages)
> people have taken the trouble to spell out mathematical definitions
> (where these can be given in reasonable space). Especially in cases
> like the Incomplete Gamma and Beta functions, where there can be
> dispute over what is meant (see above), it is surely wise to spell
> it out!
>
> Best wishes to all,
> Ted.
>
>>> On 31 Aug 2007, at 00:29, poolloopus at yahoo.com wrote:
>>>
>>>> Hello
>>>>
>>>> I am trying to evaluate an Incomplete gamma function
>>>> in R. Library Zipfr gives the Igamma function. From
>>>> Mathematica, I have:
>>>>
>>>> "Gamma[a, z] is the incomplete gamma function."
>>>>
>>>> In[16]: Gamma[9,11.1]
>>>> Out[16]: 9000.5
>>>>
>>>> Trying the same in R, I get
>>>>
>>>>> Igamma(9,11.1)
>>>> [1] 31319.5
>>>> OR
>>>>> Igamma(11.1,9)
>>>> [1] 1300998
>>>>
>>>> I know I have to understand the theory and the math
>>>> behind it rather than just ask for help, but while I
>>>> am trying to do that (and only taking baby steps, I
>>>> must admit), I was hoping someone could help me out.
>>>>
>>>> Regard
>>>>
>>>> Kris.
>
> --------------------------------------------------------------------
> E-Mail: (Ted Harding) <Ted.Harding at manchester.ac.uk>
> Fax-to-email: +44 (0)870 094 0861
> Date: 01-Sep-07                                       Time: 15:49:57
> ------------------------------ XFMail ------------------------------
>
> ______________________________________________
> R-help at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/posting- 
> guide.html
> and provide commented, minimal, self-contained, reproducible code.

--
Robin Hankin
Uncertainty Analyst
National Oceanography Centre, Southampton
European Way, Southampton SO14 3ZH, UK
  tel  023-8059-7743