R: Class "acopula" of Archimedean Copula Families

acopula-class {copula} | R Documentation

## 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 F01 with Laplace-Stieltjes transform psi01 (see `dV01`) and parameters theta0=`theta0`, theta1=`theta1`.

`dV01`:

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

  psi01(t;V0) = exp(-V0*psi0^{-1}(psi1(t))),

  corresponding to the distribution function F01.

  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")

[Package copula version 1.0-1 Index]