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()