r-devel / r-dev-day

Repo to organize tasks for R Dev Days
7 stars 2 forks source link

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

Open hturner opened 2 weeks ago

hturner commented 2 weeks ago

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:

In both cases: