R: Symmetry-modulated distributions

symm-modulated-distr {sn} | R Documentation

## 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", ...)

### 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`.

### 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.

### Background

In the univariate case, start from symmetric density function f₀, such that f₀(z)=f₀(-z) for all z, and ‘modulate’ it in the form

f(z) = 2 f₀(z) G₀{w(z)}

where G₀ 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

ξ + ω Z.

In the multivariate case, the scheme is similar, with natural adaptation. Density f₀ is now d-dimensional, while G₀ is still univariate. The conditions f₀(z)=f₀(-z) and w(-z)=-w(z) refer to a d-dimensional vector z. Given a d x d symmetric positive-definite matrix Ω, we extract the the square roots ω of the diagonal element of Ω and correspondingly obtain the scale-free matrix

cov(Ω) = diag(ω)⁻¹ Ω diag(ω)⁻¹

which is used to regulate the dependence structure of f₀(z) and so of f(z). If Z is multivariate random variable with density f(z), then the final distribution refers to

ξ + diag(ω) Z

where ξ 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).

### 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 cor(Ω), implied by Ω. 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.

### Author(s)

Adelchi Azzalini

### 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 http://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.

[Package sn version 1.5-3 Index]