Document that skewnorm 'mean'/'sd' are the location and scale, not the mean and sd

[StefanoMezzini]

Problem

Throughout the skew-normal and skew-lognormal functions, mean/sd (and meanlog/sdlog) are passed to sn as xi and omega — the direct parameters, i.e. location and scale. For the skew-normal these are not the mean and standard deviation unless shape = 0:

• E[X] = xi + omega * delta * sqrt(2 / pi), where delta = shape / sqrt(1 + shape^2)
• SD[X] = omega * sqrt(1 - 2 * delta^2 / pi)

But R/params.R documents them as the moments:

#' @param mean A numeric vector of the means.
#' @param sd A non-negative numeric vector of the standard deviations.

Reproduction

set.seed(1)
x <- rskewnorm(2e6, mean = 0, sd = 1, shape = 5)
mean(x)   #> 0.7826015     (documented as 0)
sd(x)     #> 0.6236343     (documented as 1)

Scope

This is a documentation problem, not a computational one. The internals convert correctly everywhere I checked — that's what the sqrt(2 / pi) terms in dev_skewnorm, res_skewnorm, res_skewlnorm, sens_skewnorm and sens_skewlnorm are doing, and I verified sens_skewnorm/sens_skewlnorm preserve the true mean and scale the true sd by sd_mult to 4 dp.

The risk is entirely user-facing: anyone simulating data with ran_skewnorm(), setting priors, or interpreting fitted mean/sd parameters will be off by sd * delta * sqrt(2 / pi) in location and a factor of sqrt(1 - 2 * delta^2 / pi) in spread.

Suggestion

Keeping the argument names for consistency with the other distribution families in the package seems reasonable. But ?skewnorm and ?skewlnorm should state plainly that these are the location and scale (xi/omega in sn terms), give the two moment formulas above, and note that they coincide with the mean and sd only at shape = 0. The @param entries inherited from params.R should be overridden for these functions rather than describing them as moments.