sn (version 2.1.1)

symm-modulated-distr: Symmetry-modulated distributions

Description

Symmetry-modulated distributions, univariate and multivariate, AKA skew-symmetric distributions

Usage

dSymmModulated(x, xi=0, omega=1, f0, G0, w, par.f0, par.G0, odd="check", 
  log=FALSE, ...)
rSymmModulated(n=1, xi=0, omega=1, f0, G0, w, par.f0, par.G0, odd="check", ...) 
dmSymmModulated(x, xi, Omega, f0, G0, w, par.f0, par.G0, odd="check", 
  log=FALSE, ...) 
rmSymmModulated(n=1, xi, Omega, f0, G0, w, par.f0, par.G0, odd="check", ...)
plot2D.SymmModulated(range, npt=rep(101,2), xi=c(0,0), Omega, f0, G0, w, 
  par.f0, par.G0, odd="check", ...)

Value

For dSymmModulated, rSymmModulated and dmSymmModulated, a numeric vector; for dmSymmModulated a matrix, unless n=1.

For plot2D.SymmModulated an invisible list containing the x

and y coordinates forming the grid over which the density pdf

has been evaluated for plotting.

Arguments

x

a vector of coordinates where the density must be evaluated; for multivariate densities, evaluated by dmSymmModulated, a matrix is also allowed, each row representing a point.

xi

a numeric vector representing the location parameter; if must have length 1 for dSymmModulated and rSymmModulated, length 2 for plot2D.SymmModulated).

omega

a positive value representing the scale parameter.

f0

a character string denoting the symmetric density to be modulated; admissible values for dSymmModulated and dSymmModulated are "beta", "cauchy", "logistic" (or "logis"), "normal" (or "norm"), "t", "uniform"; for the other functions the possible values are "cauchy", "normal" (or "norm"), "t"; the meaning of the names is described in the ‘Details’ section.

G0

a character string denoting the symmetric distribution used in the modulating factor; admissible values are "beta", "cauchy", "logistic" (or "logis"), "normal" (or "norm"), "t", "uniform", with meaning described in the ‘Details’ section.

w

the name (not as a character string) of a user-defined function which satisfies the condition \(w(-z)=-w(z)\) for all \(z\); see the ‘Details’ section for additional specifications.

par.f0, par.G0

parameters required by f0 and G0, when they are of type "beta" or "t", otherwise ignored.

odd

a character string, with possible values "check" (default), "assume", "force", for regulation of the behaviour about the condition that w is an odd function, as explained in the ‘Details’ section.

log

logical (default: FALSE); if TRUE, densities are given as log(densities).

n

an integer value (default: n=1) indicating the number of random numbers.

Omega

a symmetric positive-definite matrix which regulates the dependence structure of f0 and so of the final density.

range

a two-column matrix whose column-wise range is taken as the plotting intervals on the coordinated axes forming a bivariate grid of points over which the density is plotted.

npt

a numeric vector with two elements representing the number of equally-spaced points on each axis spanning the range described above; default value is rep(101,2).

...

optional parameters regulating the function w and, for plot2D.SymmModulated only, graphical parameters to be supplied to function contour.

Background

In the univariate case, start from symmetric density function \(f_0\), such that \(f_0(z)=f_0(-z)\) for all \(z\), and ‘modulate’ it in the form $$f(z) = 2\, f_0(z)\, G_0\{w(z)\}$$ where \(G_0\) is a univariate symmetric (about 0) distribution function and \(w(z)\)is a real-valued odd function, hence satisfying the condition \(w(-z)=-w(z)\); then $f(z)$ is a proper density function wich integrates to 1. A subsequent location and scale transformation applied to \(f(z)\) delivers the final density. Specifically, if \(Z\) denotes a univariate random variable with density \(f(z)\), then the computed density pertains to the transformed variable $$\xi + \omega Z.$$

In the multivariate case, the scheme is similar, with natural adaptation. Density \(f_0\) is now \(d\)-dimensional, while \(G_0\) is still univariate. The conditions \(f_0(z)=f_0(-z)\) and \(w(-z)=-w(z)\) refer to a \(d\)-dimensional vector \(z\). Given a \(d \times d\) symmetric positive-definite matrix \(\Omega\), we extract the the square roots \(\omega\) of the diagonal element of \(\Omega\) and correspondingly obtain the scale-free matrix $$\bar\Omega = \mathrm{diag}(\omega)^{-1}\, \Omega\, \mathrm{diag}(\omega)^{-1} $$ which is used to regulate the dependence structure of \(f_0(z)\) and so of \(f(z)\). If \(Z\) is multivariate random variable with density \(f(z)\), then the final distribution refers to $$\xi + \mathrm{diag}(\omega)\,Z $$ where \(\xi\) is a \(d\)-dimensional vector of location parametes.

This construction was put forward by Azzalini and Capitanio (2003). An essentially equivalent formulation has been presented by Wang et al. (2004). A summary account is available in Section 1.2 of Azzalini and Capitanio (2014); this includes, inter alia, an explanation of why the term ‘symmetry-modulated’ distributions is preferred to ‘skew-symmetric’ distributions.

Random number generation is based on expression (1.11a) of Azzalini and Capitanio (2014).

Author

Adelchi Azzalini

Details

Functions dSymmModulated and rSymmModulated deal with univariate distributions, for computing densities and generating random rumbers, respectively; dmSymmModulated and rmSymmModulated act similarly for multivariate distributions. For the bivariate case only, plot2D.SymmModulated computes a density over a grid of coordinates and produces a contour plot.

The distribution names used in f0 and G0 have, in the univariate case, the same meaning as described in the Distributions page, with the following exceptions, to achive symmetry about 0: "uniform" denotes a uniform distribution over the interval \((-1, 1)\); "beta" denotes the a symmetric Beta distribution with support over the interval \((-1, 1)\) and a common value of the shape parameters.

In the multivariate case, the available options "normal" and "t" for f0 refer to densities computed by dmnorm and dmt with 0 location and correlation matrix \(\bar\Omega\), implied by \(\Omega\). Argument G0 has the same meaning as in the univariate case.

Options "beta" and "t" for f0 and G0 require the specification of a shape parameter, via the arguments par.f0 and par.G0, respectively. For "beta" the parameter represents the common value of the shape parameters of Beta; for "t", it represents df of TDist and dmt.

Function w most be of the form w <- function(z, ...) where ... are optional additional parameters and z represents valued of the standardized form of the density; in the univariate case, x and z are related by z=(x-xi)/omega and an analogous fact holds in the multivariate setting. The function must satisfy the condition \(w(-z)=-w(z)\). It is assumed that the function is vectorized and, in the multivariate case, it will be called with z representing a matrix with d columns, if d denotes the dimensionality of the random variable.

Argument odd regulates the behaviour with respect to the condition \(w(-z)=-w(z)\). If its value is "assume", the condition is just assumed to hold, and no action is taken. If the value is "check" (deafult), a limited check is performed; namely, in case of densities, the check is at 0 and the supplied x points, while for random numbers the check is at 0 and the generated points. The value "force" ensures that the condition is satisfied by actually constructing a modified version of the user-supplied function w, such that the required condition is enforced.

References

Arellano-Valle, R. B., Gómez, H. W. and Quintana, F. A. (2004). A new class of skew-normal distributions. Comm. Stat., Theory & Methods, 58, 111-121.

Azzalini, A. and Capitanio, A. (2003). Distributions generated by perturbation of symmetry with emphasis on a multivariate skew-t distribution. J.Roy. Statist. Soc. B 65, 367--389. Full version of the paper at https://arXiv.org/abs/0911.2342

Azzalini, A. with the collaboration of Capitanio, A. (2014). The Skew-Normal and Related Families. Cambridge University Press, IMS Monographs series.

Wang, J., Boyer, J. and Genton, M. G. (2004). A skew-symmetric representation of multivariate distributions. Statistica Sinica, 14, 1259-1270.

See Also

Distributions, Beta, TDist, dmnorm, dmt, contour

Examples

x <- seq(2, 13, length=45)
wLinear <- function(z, lambda) lambda*z
y <- dSymmModulated(x, 5, 2, f0="normal", G0="normal", w=wLinear, lambda=3)
# the same of dsn(x, 5, 2, 3), up to negligible numerical differences
#
wSGN <- function(z, lambda) z*lambda[1]/sqrt(1 + lambda[2]*z^2) 
y <- dSymmModulated(x, 5, 2, f0="normal", G0="normal", w=wSGN, lambda=c(3,5))
# SGN distribution of Arellano-Valle et al. (2004)
#
wST <- function(z, lambda, nu) lambda*z*sqrt((nu+1)/(nu+z^2))
y <- rSymmModulated(n=100, 5, 2, f0="t", G0="t", w=wST, par.f0=8, par.G0=9, 
        lambda=3, nu=8)
# equivalent to rst(n=100, 5, 2, 3, 8) 
#
wTrigs <- function(z, p, q) sin(z * p)/(1 + cos(z * q))
x <- seq(-1, 1, length=51)
y <- dSymmModulated(x, 0, 1, f0="beta", G0="logistic", w=wTrigs, par.f0=2,
        par.G0=NULL, p=5, q=0.5)   
plot(x, y, type="l")        
# univariate analogue of the bivariate distribution on pp.372-3 of
# Azzalini & Capitanio (2003)           
#
range <- cbind(c(-3,3), c(-3,3))
wMvTrigs <- function(z, p, q) sin(z %*% p)/(1 + cos(z %*% q))
plot2D.SymmModulated(range, xi=c(0,0), Omega=diag(2), f0="normal", G0="normal",
    w=wMvTrigs, par.f0=NULL, par.G0=NULL, p=c(2,3), q=c(1,1), col=4)
# w(.) as in (1.6) of Azzalini & Capitanio (2014, p.4) and plot as in 
# bottom-right panel of their Figure 1.1.