# Symmetry-modulated distributions Symmetry-modulated distributions, univariate and multivariate, AKA skew-symmetric distributions UTF-8 ```r 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`. ## 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_0(z)\, G_0\{w(z)\}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 $$ \xi + \omega 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 $\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}cov(\Omega) = diag(\omega)⁻¹ \Omega diag(\omega)⁻¹ $$ 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 $$ \xi + \mathrm{diag}(\omega)\,Z\xi + 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). ## 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(\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. ## Returns 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. ## 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 [https://arXiv.org/abs/0911.2342](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 ```r 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. ```

symm-modulated-distr function