copBasic (version 1.7.1)

densityCOPplot: Contour Density Plot of a Copula

Description

Generate a contour density plot after the advocation of Joe (2015, pp. 9--15). Such plots are plots of scaled copula densities ($c^\star(u,v)$, bivariate herein) that are copula densities scaled to Standard Normal distribution N(0,1) margins. Joe (2015) repeatedly emphasizes such plots in contrast to Uniform distribution U(0,1) margins. Nelsen (2006) does not discuss such scaling but seemingly Nelsen's objectives for his book were different.

The density of copula $\mathbf{C}(u,v)$ is numerically estimated by $$c(u,v) = [\mathbf{C}(u_2,v_2) - \mathbf{C}(u_2,v_1) - \mathbf{C}(u_1,v_2) + \mathbf{C}(u_1,v_1)]/[\Delta(uv)\times\Delta(uv)]\mbox{,}$$ where $c(u,v) \ge 0$ (see Nelsen (2006, p. 10); densityCOP). Given a numerically estimated quantity $c^\star(u,v) = c(u,v)\phi(\Phi^{(-1)}(u))\phi(\Phi^{(-1)}(v))$ for copula density $c(u,v)$, a grid of the $c^\star(u,v)$ values can be contoured by the contour function of R. The density function of the N(0,1) is $\phi(z)$ for standard normal variate $z$ and the quantile function of the N(0,1) is $\Phi^{(-1)}(t)$ for nonexceedance probability $t$.

A grid (matrix) of $c(u,v)$ or $c^\star(u,v)$ is defined for sequence of $u$ and $v$ probabilities for which the sequence has a step of $\Delta(uv)$. This function has as focus on plotting of the contour lines of $c^\star(u,v)$ but the Rmatrix of either $c(u,v)$ or $c^\star(u,v)$ can be requested on return. For either matrix, the colnames() and rownames() (the Rfunctions) are set equal to the sequence of $u$ and $v$, respectively. Neither the column or row names are set to the standard normal variates for the matrix of $c^\star(u,v)$, the names remain in terms of nonexceedance probability.

For plotting and other uses of normal scores of data, Joe (2015, p. 245) advocates that one should use the plotting position formula $u_i = (i-1/2)/n$ (Hazen plotting position) for normal scores $z_i = \Phi^{-1}(u_i)$ in preference to $i/(n+1)$ (Weibull plotting position) because $n^{-1}\sum_{i=1}^{n} z^2_i$ is closer to unity. Other places of Joe's advocation for the Hazen plotting position are available (Joe, 2015, pp. 9, 17, 245, 247--248).

Usage

densityCOPplot(cop=NULL, para=NULL, deluv=0.002, origins=TRUE,
               getmatrix=c("none", "cdenzz", "cden"), n=0,
               ploton=TRUE, contour.col=1, ...)

Arguments

cop

A copula function;

para

Vector of parameters or other data structure, if needed, to pass to the copula;

deluv

The change in ${u, v} \mapsto \delta, \ldots, 1-\delta; \delta = \Delta(uv)$ probabilities;

origins

A logical to plot the origin lines;

getmatrix

A trigger on whether the density matrix is to be returned. The option cdenzz returns the density scaled by the two standard normal densities ($c^\star(u,v)$), whereas the option cden returns simply the copula density ($c(u,v)$);

ploton

A logical to toggle on the plot;

contour.col

The color of the contour lines, which corresponds to the col argument of the contour function in R;

n

An optional sample size for which simulation of this many values from the copula will be made by simCOP and drawn; and

...

Additional arguments to pass to the copula function and to the contour function of R(e.g., to turn off labeling of contours add drawlabels=FALSE).

Value

• This is a high-level function used for its side effects. An Rmatrix can be triggered as the returned value.

encoding

utf8

References

Joe, H., 2015, Dependence modeling with copulas: Boca Raton, CRC Press, 462 p.

Nelsen, R.B., 2006, An introduction to copulas: New York, Springer, 269 p.

See Also

simCOP, densityCOP

Examples

# Joe (2015, p. 5) names rMTCJ = reflected Mardia-Takahasi-Cook-Johnson copula
"rMTCJ" <- function(u,v,para, ...) {
   u + v - 1 + ((1-u)^(-para) + (1-v)^(-para) - 1)^(-1/para)
 } # Survial Copula ("reflected" in Joe's terms)
densityCOPplot(cop=rMTCJ, para=1.0760, n=9000)
# The density plot matches that shown by Joe (2015, p. 11, fig. 1.2, lower left plot)
# for a Spearman's Rho equaling 0.5.
rhoCOP(cop=rMTCJ, para=1.076075) # 0.4999958

# Now let us get really wild with a composition with TWO modes!
# This example also proves that the orientation of the grid is consistent with
# orientation of the simulations.
para <- list(alpha=0.15, beta=0.90, kappa=0.06, gamma=0.96,
             cop1=GHcop, cop2=PLACKETTcop, para1=5.5, para2=0.07)
densityCOPplot(cop=composite2COP, para=para, n=9000)

# Now let us hack back to a contour density plot with U(0,1) and not N(0,1)
# margins just so show that capability exists, but emphasis of densityCOPplot
# is clearly on Joe's advocation to it does not have a trigger to use U(0,1)
# margins.
set.seed(12)
H <- densityCOPplot(cop=PLACKETTcop, para=41.25, getmatrix="cden", n=1000)
set.seed(12)
UV <- simCOP(cop=PLACKETTcop, para=41.25, n=1000, col=8)
U <- as.numeric(colnames(H)); V <- as.numeric(rownames(H))
contour(x=U, y=V, z=t(H), lwd=1.5, cex=2, add=TRUE, col=2)