https://github.com/cran/sn
Tip revision: bc33612e6cc33fcf28f50655cab5f1931985ccde authored by Adelchi Azzalini on 04 April 2023, 17:10:02 UTC
version 2.1.1
version 2.1.1
Tip revision: bc33612
makeSECdistr.Rd
% file sn/man/makeSECdistr.Rd
% This file is a component of the package 'sn' for R
% copyright (C) 2013-2014 Adelchi Azzalini
%---------------------
\name{makeSECdistr}
\encoding{UTF-8}
\alias{makeSECdistr}
\concept{skew-elliptical distribution}
\title{Build a skew-elliptically contoured distribution}
\description{Build an object which identifies a skew-elliptically contoured
distribution (\acronym{SEC}), in the univariate and in the multivariate case.
The term \sQuote{skew-elliptical distribution} is a synonym of \acronym{SEC}
distribution.}
\usage{makeSECdistr(dp, family, name, compNames)}
\arguments{
\item{dp}{a numeric vector (in the univariate case) or a list (in the
multivariate case) of parameters which identify the specific distribution
within the named \code{family}. See \sQuote{Details} for their expected
structure.}
\item{family}{a character string which identifies the parametric
family; currently, possible values are: \kbd{"SN"}, \kbd{"ESN"},
\kbd{"ST"}, \kbd{"SC"}.
See \sQuote{Details} for additional information.}
\item{name}{an optional character string with the name of the distribution.
If missing, one is created.}
\item{compNames}{in the multivariate case, an optional vector of character
strings with the names of the component variables; its length must be
equal to the dimensionality of the distribution being generated.
If missing and the first component of \code{dp} is a named vector,
its names are used as \code{compNames}; otherwise
the components are named \code{"V1"}, \code{"V2"}, \dots}
}
\details{If \code{dp} is a numeric vector, a univariate distribution is built.
Alternatively, if \code{dp} is a list, a multivariate distribution is
built. In both cases, the required number of components of \code{dp}
depends on \code{family}: it must be \code{3} for \kbd{"SN"} and
\kbd{"SC"}; it must be \code{4} for \kbd{"ESN"} and \kbd{"ST"}.
In the univariate case, the first three components of \code{dp} represent
what for the specific distributions are denoted \code{xi} (location),
\code{omega} (scale, positive) and \code{alpha} (slant); see functions
\code{\link{dsn}}, \code{\link{dst}}, \code{\link{dsc}} for their
description.
The fourth component, when it exists, represents either \code{tau}
(hidden variable mean) for \kbd{"ESN"} or \code{nu} (degrees of freedom)
for \kbd{"ST"}. The names of the individual parameters are attached
to the components of \code{dp} in the returned object.
In the multivariate case, \code{dp} is a list with components having
similar role as in the univariate case, but \code{xi=dp[[1]]} and
\code{alpha=dp[[3]]} are now vectors and the scale parameter
\code{Omega=dp[[2]]} is a symmetric positive-definite matrix.
For a multivariate distribution of dimension 1 (which can be created,
although a warning message is issued), \code{Omega} corresponds to the
square of \code{omega} in the univariate case.
Vectors \code{xi} and \code{alpha} must be of length \code{ncol(Omega)}.
See also functions \code{\link{dmsn}}, \code{\link{dmst}} and
\code{\link{dmsc}}.
The fourth component, when it exists, is a scalar with the same role as
in the univariate case.
In the univariate case \code{alpha=Inf} is allowed, but in the multivariate
case all components of the vector \code{alpha} must be finite.
An object built by this function operates according to the S4 protocol.
}
\section{Background}{
For background information, see Azzalini and Capitanio (2014), specifically
Chapters 2 and 4 for univariate cases, Chapters 5 and 6 for multivariate
cases; Section 6.1 provides a general formulation of \acronym{SEC}
distributions.
If the slant parameter \code{alpha} is \code{0} (or a vector of \code{0}'s,
in the multivariate case), the distribution is of classical elliptical
type.
The \acronym{ESN} distribution is included here as a members of the
\acronym{SEC} class, with a very slight extension of the original definition
of this class, since the only difference is the non-zero truncation point
of the unobserved component of the \code{(d+1)}-dimensional \acronym{EC}
variable.
}
\value{In the univariate case, an object of class \code{SECdistrUv};
in the multivariate case, an object of class \code{SECdistrMv}.
See \code{\link{SECdistrUv-class}} and \code{\link{SECdistrMv-class}}
for their description.
}
\references{
Azzalini, A. with the collaboration of Capitanio, A. (2014).
\emph{The Skew-Normal and Related Families}.
Cambridge University Press, IMS Monographs series.
}
\author{Adelchi Azzalini}
\seealso{
The description of classes \code{\link{SECdistrUv-class}} and
\code{\link{SECdistrMv-class}}
\code{\link{plot.SECdistr}} for plotting and
\code{\link{summary.SECdistr}} for summaries
Related functions \code{\link{dsn}}, \code{\link{dst}}, \code{\link{dsc}},
\code{\link{dmsn}}, \code{\link{dmst}}, \code{\link{dp2cp}}
Functions \code{\link{affineTransSECdistr}} and
\code{\link{conditionalSECdistr}} to manipulate objects of class
\code{\link{SECdistrMv-class}}
Function \code{\link{extractSECdistr}} to extract objects of class
\code{\link{SECdistrMv-class}} and \code{\link{SECdistrUv-class}}
representing the \acronym{SEC} distribution of a \code{\link{selm}} fit
}
\examples{
f1 <- makeSECdistr(dp=c(3,2,5), family="SN", name="First-SN")
show(f1)
summary(f1)
plot(f1)
plot(f1, probs=c(0.1, 0.9))
#
f2 <- makeSECdistr(dp=c(3, 5, -4, 8), family="ST", name="First-ST")
f9 <- makeSECdistr(dp=c(5, 1, Inf, 0.5), family="ESN", name="ESN,alpha=Inf")
#
dp0 <- list(xi=1:2, Omega=diag(3:4), alpha=c(3, -5))
f10 <- makeSECdistr(dp=dp0, family="SN", name="SN-2d", compNames=c("u1", "u2"))
#
dp1 <- list(xi=1:2, Omega=diag(1:2)+outer(c(3,3),c(2,2)), alpha=c(-3, 5), nu=6)
f11 <- makeSECdistr(dp=dp1, family="ST", name="ST-2d", compNames=c("t1", "t2"))
}
\keyword{distribution}
\keyword{multivariate}