Revision **161411bb86f97e5a8bd89091cd61d03a33c2761a** authored by Martin Maechler on **06 February 2012, 00:00:00 UTC**, committed by Gabor Csardi on **06 February 2012, 00:00:00 UTC**

Tip revision: **161411bb86f97e5a8bd89091cd61d03a33c2761a** authored by ** Martin Maechler ** on **06 February 2012, 00:00:00 UTC**

**version 0.8-0**

Tip revision: **161411b**

copFamilies.Rd

```
\name{copFamilies}
\title{Specific Archimedean Copula Families ("acopula" Objects)}
\concept{Copula Family}
\alias{acopula-families}
\alias{copAMH}
\alias{copClayton}
\alias{copFrank}
\alias{copGumbel}
\alias{copJoe}
\docType{data}
\description{
Specific Archimedean families (\code{"\linkS4class{acopula}"} objects)
implemented in the package \pkg{nacopula}.
These families are \dQuote{classical} as from p. 116 of Nelsen (2007).
More specifially, see Table 1 of Hofert (2011).
}
\usage{
copAMH
copClayton
copFrank
copGumbel
copJoe
}
\value{
A \code{"\linkS4class{acopula}"} object.
}
\details{
All these are objects of the formal class \code{"\linkS4class{acopula}"}.
\describe{
\item{\code{copAMH}:}{Archimedean family of Ali-Mikhail-Haq with
parametric generator
\deqn{\psi(t)=(1-\theta)/(\exp(t)-\theta),\ t\in[0,\infty],
}{psi(t)=(1-theta)/(exp(t)-theta), t in [0,Inf],}
with \eqn{\theta\in[0,1)}{theta in [0,1)}. The range of
admissible Kendall's tau is [0,1/3). Note that the lower and upper
tail-dependence coefficients are both zero, that is, this copula
family does not allow for tail dependence.}
\item{\code{copClayton}:}{Archimedean family of Clayton with
parametric generator
\deqn{\psi(t)=(1+t)^{-1/\theta},\ t\in[0,\infty],}{
psi(t)=(1+t)^{-1/theta}, t in [0,Inf],}
with \eqn{\theta\in(0,\infty)}{theta in (0,Inf)}. The range of
admissible Kendall's tau, as well as that of the lower
tail-dependence coefficient, is (0,1). Note that this copula does
not allow for upper tail dependence.}
\item{\code{copFrank}:}{Archimedean family of Frank with parametric
generator
\deqn{-\log(1-(1-e^{-\theta})\exp(-t))/\theta,\ t\in[0,\infty]}{
-log(1-(1-e^{-theta})exp(-t))/theta, t in [0,Inf],}
with \eqn{\theta\in(0,\infty)}{theta in (0,Inf)}. The range of
admissible Kendall's tau is (0,1). Note that this copula family
does not allow for tail dependence.}
\item{\code{copGumbel}:}{Archimedean family of Gumbel with
parametric generator
\deqn{\exp(-t^{1/\theta}),\ t\in[0,\infty]}{
exp(-t^{1/theta}), t in [0,Inf],}
with
\eqn{\theta\in[1,\infty)}{theta in [1,Inf)}. The range of
admissible Kendall's tau, as well as that of the upper
tail-dependence coefficient, is [0,1). Note that this copula does
not allow for lower tail dependence.}
\item{\code{copJoe}:}{Archimedean family of Joe with parametric
generator
\deqn{1-(1-\exp(-t))^{1/\theta},\ t\in[0,\infty]}{
1-(1-exp(-t))^{1/theta}, t in [0,Inf],}
with \eqn{\theta\in[1,\infty)}{theta in [1,Inf)}. The range of
admissible Kendall's tau, as well as that of the upper
tail-dependence coefficient, is [0,1). Note that this copula does
not allow for lower tail dependence.}
}
Note that staying within one of these Archimedean families, all of
them can be nested if two (generic) generator parameters
\eqn{\theta_0}{theta0}, \eqn{\theta_1}{theta1} satisfy
\eqn{\theta_0\le\theta_1}{theta0 <= theta1}.
}
\seealso{
The class definition, \code{"\linkS4class{acopula}"}.
\cr
\code{\link{getAcop}} accesses these families
\dQuote{programmatically}.
}
\author{Marius Hofert}
\references{
Nelsen, R.B. (2007),
\emph{An Introduction to Copulas} (2nd ed.),
Springer.
Hofert, M. (2010),
\emph{Sampling Nested Archimedean Copulas with Applications to CDO Pricing},
Suedwestdeutscher Verlag fuer Hochschulschriften AG & Co. KG.
Hofert, M. (2011),
Efficiently sampling nested Archimedean copulas,
\emph{Computational Statistics & Data Analysis} \bold{55}, 57--70.
Marius Hofert and Martin \enc{Mächler}{Maechler} (2011),
Nested Archimedean Copulas Meet R: The nacopula Package.,
\emph{Journal of Statistical Software} \bold{39}(9), 1--20.
\url{http://www.jstatsoft.org/v39/i09/}.
}
\examples{
## Print a copAMH object and its structure
copAMH
str(copAMH)
## Show admissible parameters for a Clayton copula
copClayton@paraInterval
## Generate random variates from a Log(p) distribution via V0 of Frank
p <- 1/2
copFrank@V0(100, -log(1-p))
## Plot the upper tail-dependence coefficient as a function in the
## parameter for Gumbel's family
curve(copGumbel@lambdaU(x), xlim = c(1, 10), ylim = c(0,1), col = 4)
## Plot Kendall's tau as a function in the parameter for Joe's family
curve(copJoe@tau(x), xlim = c(1, 10), ylim = c(0,1), col = 4)
## ------- Plot psi() and tau() - and properties of all families ----
## The copula families currently provided:
(famNms <- ls("package:nacopula", patt="^cop[A-Z]"))
op <- par(mfrow= c(length(famNms), 2),
mar = .6+ c(2,1.4,1,1), mgp = c(1.1, 0.4, 0))
for(nm in famNms) { Cf <- get(nm)
thet <- Cf@tauInv(0.3)
curve(Cf@psi(x, theta = thet), 0, 5,
xlab = expression(x), ylab="", ylim=0:1, col = 2,
main = substitute(list(NAM ~~~ psi(x, theta == TH), tau == 0.3),
list(NAM=Cf@name, TH=thet)))
I <- Cf@paraInterval
Iu <- pmin(10, I[2])
curve(Cf@tau(x), I[1], Iu, col = 3,
xlab = bquote(theta \%in\% .(format(I))), ylab = "",
main = substitute(NAM ~~ tau(theta), list(NAM=Cf@name)))
}
par(op)
## Construct a bivariate Clayton copula with parameter theta
theta <- 2
C2 <- onacopula("Clayton", C(theta, 1:2))
C2@copula # is an "acopula" with specific parameter theta
curve(C2@copula@psi(x, C2@copula@theta),
main = quote("Generator" ~~ psi ~~ " of Clayton A.copula"),
xlab = quote(theta1), ylab = quote(psi(theta1)),
xlim = c(0,5), ylim = c(0,1), col = 4)
## What is the corresponding Kendall's tau?
C2@copula@tau(theta) # 0.5
## What are the corresponding tail-dependence coefficients?
C2@copula@lambdaL(theta)
C2@copula@lambdaU(theta)
## Generate n pairs of random variates from this copula
U <- rnacopula(n = 1000, C2)
## and plot the generated pairs of random variates
plot(U, asp=1, main = "n = 1000 from Clayton(theta = 2)")
}
\keyword{datasets}
```

Computing file changes ...