acopula-class {copula}

Class "acopula" of Archimedean Copula Families

Description

This class "acopula" of Archimedean Copula Families is mainly used for providing objects of known Archimedean families with all related functions.

Objects from the Class

Objects can be created by calls of the form new("acopula", ...). For several well-known Archimedean copula families, the package copula already provides such family objects.

Slots

name:

A string (class "character") describing the copula family, for example, "AMH" (or simply "A"), "Clayton" ("C"), "Frank" ("F"), "Gumbel" ("G"), or "Joe" ("J").

theta:

Parameter value, a numeric, where NA means “unspecified”.

psi, iPsi:

The (Archimedean) generator \psi (with \psi(t)=\exp(-t) being the generator of the independence copula) and its inverse (function). iPsi has an optional argument log which, if TRUE returns the logarithm of inverse of the generator.

absdPsi:

A function which computes the absolute value of the derivative of the generator \psi for the given parameter theta and of the given degree (defaults to 1). Note that there is no informational loss by computing the absolute value since the derivatives alternate in sign (the generator derivative is simply (-1)^degree*absdPsi). The number n.MC denotes the sample size for a Monte Carlo evaluation approach. If n.MC is zero (the default), the generator derivatives are evaluated with their exact formulas. The optional parameter log (defaults to FALSE) indicates whether or not the logarithmic value is returned.

absdiPsi:

a function computing the absolute value of the derivative of the generator inverse (iPsi()) for the given parameter theta. The optional parameter log (defaults to FALSE) indicates whether the logarithm of the absolute value of the first derivative of iPsi() is returned.

dDiag:

a function computing the density of the diagonal of the Archimedean copula at u with parameter theta. The parameter log is as described before.

dacopula:

a function computing the density of the Archimedean copula at u with parameter theta. The meanings of the parameters n.MC and log are as described before.

score:

a function computing the derivative of the density with respect to the parameter \theta.

uscore:

a function computing the derivative of the density with respect to the each of the arguments.

paraInterval:

Either NULL or an object of class "interval", which is typically obtained from a call such as interval("[a,b)").

paraConstr:

A function of theta returning TRUE if and only if theta is a valid parameter value. Note that paraConstr is built automatically from the interval, whenever the paraInterval slot is valid. "interval".

nestConstr:

A function, which returns TRUE if and only if the two provided parameters theta0 and theta1 satisfy the sufficient nesting condition for this family.

V0:

A function which samples n random variates from the distribution F with Laplace-Stieltjes transform \psi and parameter theta.

dV0:

A function which computes either the probability mass function or the probability density function (depending on the Archimedean family) of the distribution function whose Laplace-Stieltjes transform equals the generator \psi at the argument x (possibly a vector) for the given parameter theta. An optional argument log indicates whether the logarithm of the mass or density is computed (defaults to FALSE).

V01:

A function which gets a vector of realizations of V0, two parameters theta0 and theta1 which satisfy the sufficient nesting condition, and which returns a vector of the same length as V0 with random variates from the distribution function F_{01} with Laplace-Stieltjes transform \psi_{01} (see dV01) and parameters \theta_0=\,theta0, \theta_1=\,theta1.

dV01:

Similar to dV0 with the difference being that this function computes the probability mass or density function for the Laplace-Stieltjes transform

\psi_{01}(t;V_0) = \exp(-V_0\psi_0^{-1}(\psi_1(t))),

corresponding to the distribution function F_{01}.

Arguments are the evaluation point(s) x, the value(s) V0, and the parameters theta0 and theta1. As for dV0, the optional argument log can be specified (defaults to FALSE). Note that if x is a vector, V0 must either have length one (in which case V0 is the same for every component of x) or V0 must be of the same length as x (in which case the components of V0 correspond to the ones of x).

tau, iTau:

Compute Kendall's tau of the bivariate Archimedean copula with generator \psi as a function of theta, respectively, theta as a function of Kendall's tau.

lambdaL, lambdaU, lambdaLInv, lambdaUInv:

Compute the lower (upper) tail-dependence coefficient of the bivariate Archimedean copula with generator \psi as a function of theta, respectively, theta as a function of the lower (upper) tail-dependence coefficient.

For more details about Archimedean families, corresponding distributions and properties, see the references.

Methods

initialize

signature(.Object = "acopula"): is used to automatically construct the function slot paraConstr, when the paraInterval is provided (typically via interval()).

show

signature("acopula"): compact overview of the copula.

References

See those of the families, for example, copGumbel.

See Also

Specific provided copula family objects, for example, copAMH, copClayton, copFrank, copGumbel, copJoe.
To access these, you may also use getAcop.

A nested Archimedean copula without child copulas (see class "nacopula") is a proper Archimedean copula, and hence, onacopula() can be used to construct a specific parametrized Archimedean copula; see the example below.

Alternatively, setTheta also returns such a (parametrized) Archimedean copula.

Examples

## acopula class information
showClass("acopula")

## Information and structure of Clayton copulas
copClayton
str(copClayton)

## What are admissible parameters for Clayton copulas?
copClayton@paraInterval

## A Clayton "acopula" with Kendall's tau = 0.8 :
(cCl.2 <- setTheta(copClayton, iTau(copClayton, 0.8)))

## Can two Clayton copulas with parameters theta0 and theta1 be nested?
## Case 1: theta0 = 3, theta1 = 2
copClayton@nestConstr(theta0 = 3, theta1 = 2)
## -> FALSE as the sufficient nesting criterion is not fulfilled
## Case 2: theta0 = 2, theta1 = 3
copClayton@nestConstr(theta0 = 2, theta1 = 3) # TRUE

## For more examples, see  help("acopula-families")