Bug 18677 - Documentation of base::gamma & base::is.numeric could be Improved

[hturner]

This issue is good for someone with a mathematical/statistical background, who is comfortable with basic LaTex-style math markup.

In Bug 18677, Jorgen Harmse (JH) proposes improvements to the documentation files. This issue will iterate on these suggestions and create a patch file for the proposed changes.

Changes to ?gamma

1. Suggestion to clarify definition of $\Gamma(x)$ for negative x. This is a fair point - the definition taken from Abramowitz and Stegun applies to complex numbers with positive real part (note the R function only takes real numbers). The definition for negative values is obtained by analytic continuation, see e.g. Julia docs and further detail in A First Course in Differential Equations for Scientists and Engineers (Herman).
2. Suggestion to replace $\ln \Gamma$ with lgamma in the formula for digamma (where lgamma computes the natural logarithm of the absolute value of the gamma function). I think this change can be skipped - the definition with $\ln \Gamma$ is used widely (e.g. several refs on Wikipedia, including Abramowitz and Stegun) and as $\ln \Gamma$ is defined for negative values (via complex numbers) I don't see an issue here (see e.g. this discussion on mathematics Stack Exchange).

Changes to ?is.numeric

The issue here is some surprise that is.numeric returns FALSE for complex numbers. This is as documented, e.g.

Methods for is.numeric should only return true if the base type of the class is double or integer

I suggest extending the part

there are methods for classes "Date", "POSIXt" and "difftime" (all of which return false)

to include "complex".

How to make the changes

I suggest editing the help files (src/library/stats/man/GammaDist.Rd and src/library/base/man/numeric.Rd in one of two ways:

• Using the R Dev Container, following the R Contribution Workflow to edit the help files and then create a patch file.
• Using the GitHub mirror, as documented in the R Dev Guide of the R sources. Rather than editing the file in the GitHub browser interface, I would make local copies of the files and edit there. When you have final versions, then you can follow the workflow given in the R Dev Guide to create a patch.

In both cases:

• Refer to Writing R Extensions to ensure you are using correct markup (it is LaTeX-like not markdown-like!)
• Check your draft with tools::checkRd()

[ajinkya-k]

I can take a crack at this with some help

[hturner]

@ajinkya-k that's great, a patch would be welcome. I've invited you to this repo so I can assign you to the issue.

Please have a go at editing the documentation files as described above. If you want feedback/help you can come to the office hours (the next ones are tomorrow!) or post on the R Contributors Slack - use the #core-documentation if it is a general question about contributing to documentation or the #work-out-loud channel to discuss this particular case.

[ajinkya-k]

Thanks!

[ajinkya-k]

Just a note: the Gamma function (as opposed to the distributed) documentation is in base/man/Special.Rd. So changes would have to be made there .

[ajinkya-k]

EDIT: Sorry I was wrong about the x < -10 case
Looking at the C in src/nmath/gamma.c its clear that the gamma function is NOT defined for any real number < -10. I think the documentation should reflect that. I also confirmed this by playing around with the gamma function in R and found that gamma(-10+4.000000000000001*eps) is the smallest number (that i could find) that produces a numeric result. eps here is just a variable that stores the machine epsilon i.e. eps = .Machine$double.eps

[MichaelChirico]

Just want to be sure we're not missing the |y| > 10 case just below the line you shared:

https://github.com/r-devel/r-svn/blob/82fc32ede271782223e298053d655726a584c28d/src/nmath/gamma.c#L179

[ajinkya-k]

i think you are right. I dont know why but I got a few NaNs for numbers less than 10 and i thought it didnt work. I restarted R and it seems to work okay now . Maybe I supplied numbers too close to integers

[ajinkya-k]

@hturner I have a patch ready. I sent an email to get access to BugZilla.