COP: The Copula
In copBasic: General Bivariate Copula Theory and Many Utility Functions
COP R Documentation
The Copula
Description
Compute the copula or joint distribution function through a copula as shown by Nelsen (2006, p. 18) is the joint probability
\mathrm{Pr}[U \le u, V \le v] = \mathbf{C}(u,v)\mbox{.}
The copula is an expression of the joint probability that both U \le u and V \le v.
A copula is a type of dependence function that permits straightforward characterization of dependence from independence. Joe (2014, p. 8) comments that “copula families are usually given as cdfs [cumulative distribution functions.]” A radially symmetric or permutation symmetric copula is one such that \mathbf{C}(u,v) = \mathbf{C}(v,u) otherwise the copula is asymmetric.
The copula inversions t = \mathbf{C}(u{=}U, v) or t = \mathbf{C}(u, v{=}V) for a given t and U or V are provided by COPinv and COPinv2, respectively. A copula exists in the domain of the unit square (\mathcal{I}^2 = [0, 1]\times [0,1]) and is a grounded function meaning that
\mathbf{C}(u,0) = 0 = \mathbf{C}(0,v) \mbox{\ and\ thus\ } \mathbf{C}(0,0) = 0\mbox{, }
and other properties of a copula are that
\mathbf{C}(u,1) = u \mbox{\ and\ } \mathbf{C}(1,v) = v\mbox{\ and}
\mathbf{C}(1,1) = 1\mbox{.}
Copulas can be combined with each other (convexCOP, convex2COP, composite1COP,
composite2COP, composite3COP, and glueCOP) to form more complex and sophisticated dependence structures. Also copula multiplication—a special product of two copulas—yields another copula (see prod2COP).
Perhaps the one of the more useful features of this function is that in practical applications it can be used to take a copula formula and reflect or rotated it in fashions to attain association structures that the native definition of the copula can not acquire. The terminal demonstration in the Examples demonstrates this for the Raftery copula (RFcop).
Usage
COP(u, v, cop=NULL, para=NULL,
reflect=c("cop", "surv", "acute", "grave",
"1", "2", "3", "4"), ...)
Arguments
u
Nonexceedance probability u in the X direction;
v
Nonexceedance probability v in the Y direction;
cop
A copula function with vectorization as in asCOP;
para
Vector of parameters or other data structures, if needed, to pass to the copula;
reflect
The reflection of the copula form (see Note) and the default "cop" or "1" is the usual copula definition (also see simCOPmicro). The numbered values correspond, respectively, to the named values; and
...
Additional arguments to pass to the copula.
Value
Value(s) for the copula are returned.
Note
REFLECTIONS OF VARIABLES (ROTATIONS OF THE COPULA)—The copula of (1-U, 1-V) is the survival copula (\hat{\mathbf{C}}(u,v); surCOP) and is defined as
\mathrm{Pr}[\,U > u, V > v\,] = \hat{\mathbf{C}}(u,v) = u + v - 1 + \mathbf{C}(1-u,1-v)\:\rightarrow\mbox{\ \code{"surv"},}
whereas, following the notation of Joe (2014, p. 271), the copula of (1-U, V) is defined as
\mathrm{Pr}[\,U > u, V \le v\,] = \acute{\mathbf{C}}(u,v) = v - \mathbf{C}(1-u,v)\:\rightarrow\mbox{\ \code{"acute"}, and}
the copula of (U, 1-V) is defined as
\mathrm{Pr}[\,U \le u, V > v\,] = \grave{\mathbf{C}}(u,v) = u - \mathbf{C}(u,1-v)\:\rightarrow\mbox{\ \code{"grave"}.}
Here it is useful to stress the probability aspects that change with the reflections, but this section ends with the reflections themselves being graphically highlighted. The Examples stress simple variations on the probability aspects.
To clarify the seemingly clunky nomenclature—Joe (2014) does not provide “names” for \acute{\mathbf{C}}(u,v) or \grave{\mathbf{C}}(u,v)—the following guidance is informative:
\mbox{}\quad\mbox{}(1) "surv" or \hat{\mathbf{C}}(u,v) is a reflection of U and V on the horizontal and vertical axes, respectively,
\mbox{}\quad\mbox{}(2) "acute" or \acute{\mathbf{C}}(u,v) is a reflection of U on the horizontal axis, and
\mbox{}\quad\mbox{}(3) "grave" or \grave{\mathbf{C}}(u,v) is a reflection of V on the verical axis.
The names "acute" and "grave" match those used in the Rd-format math typesetting instructions. Users are directed to the documentation of simCOPmicro for further discussion because the COP function is expected to be an early entry point for new users interested in the copBasic API.
For the copBasic package and in order to keep some logic brief and code accessible for teaching and applied circumstances, reflections of copulas using analogs to the reflect argument are only natively supported in the COP and simCOPmicro functions. The interfaces of copBasic should already be flexible enough for users to adapt and (or) specially name reflections of copulas for deployment. A caveat is that some individual copula implementations might have some self-supporting infrastructure. The reflection can also be set within the para argument when it is a list (see Examples).
An example is warranted. Although the Gumbel–Hougaard copula (GHcop) can be reflected by COP and simCOPmicro and testing is made in the Note section of simCOPmicro, it is suggested that a user generally requiring say a horizontal reflection ru (or vertical reflection rv) of the Gumbel–Hougaard copula write a function named perhaps ruGHcop (or rvGHcop).
Such functions, consistent with the mathematics at the beginning of this Note, can be used throughout functions of copBasic using the cop arguments. The author (Asquith) eschews implementing what is perceived as too much flexibility and overhead for the package to support the three reflection permutations universally across all copula functions of the package. This being said, COP can take an R list for the para argument for rotation/reflection:
set.seed(14)
UV3 <- simCOP(20, cop=COP, pch=16, col=3,
para=list(cop=GLcop, para=pi+1, reflect="3"))
set.seed(14)
UV2 <- simCOP(20, cop=COP, pch=16, col=4, ploton=FALSE,
para=list(cop=GLcop, para=pi+1, reflect="2"))
arrows(x0=UV3[,1], y0=UV3[,2], x=UV2[,1], y=UV2[,2])
and this type of interface is similar to composite1COP as the following rotation and then asymmetric construction shows:
UV <- simCOP(1000, cop=composite1COP,
para=list(cop1=COP,
para1=c(cop=GHcop, para=pi+1, reflect="4"),
alpha=0.1, beta=0.3))
Author(s)
W.H. Asquith
References
Joe, H., 2014, 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
coCOP, duCOP, surCOP, surfuncCOP
Examples
u <- runif(1); v <- runif(1)
COP(cop=W,u,v); COP(cop=P,u,v); COP(cop=M,u,v); COP(cop=PSP,u,v)
FF <- 0.75 # 75th percentile, nonexceedance
GG <- 0.20 # 25th percentile, nonexceedance
bF <- 1 - FF; bG <- 1 - GG # exceedance
# What is the probability that both X and Y are less than
# 75th and 20th percentiles, respectively?
COP(cop=P, FF, GG) # 0.15
# What is the probability that both X and Y are greater than
# 75th and 20th percentiles, respectively?
surCOP(cop=P, bF, bG) # 0.20
# What is the probability that either X or Y are less than
# the 75th and 20th percentiles, respectively?
duCOP(cop=P, FF, GG) # 0.8
# What is the probability that either X or Y are greater than
# the 75th and 20th percentiles, respectively?
coCOP(cop=P, bF, bG) # 0.85
# Repeat for the PSP copula:
# What is the probability that both X and Y are less than
# 75th and 20th percentiles, respectively?
COP(cop=PSP, FF, GG) # 0.1875
# What is the probability that both X and Y are greater than
# 75th and 20th percentiles, respectively?
surCOP(cop=PSP, bF, bG) # 0.2375
# What is the probability that either X or Y are less than
# the 75th and 20th percentiles, respectively?
duCOP(cop=PSP, FF, GG) # 0.7625
# What is the probability that either X or Y are greater than
# the 75th and 20th percentiles, respectively?
coCOP(cop=PSP, bF, bG) # 0.8125
# Both of these summations equal unity
COP(cop=PSP, FF, GG) + coCOP(cop=PSP, bF, bG) # 1
surCOP(cop=PSP, bF, bG) + duCOP(cop=PSP, FF, GG) # 1
FF <- 0.99 # 99th percentile, nonexceedance
GG <- 0.50 # 50th percentile, nonexceedance
bF <- 1 - FF # nonexceedance
bG <- 1 - GG # nonexceedance
# What is the probability that both X and Y are less than
# 99th and 50th percentiles, respectively?
COP(cop=P, FF, GG) # 0.495
# What is the probability that both X and Y are greater than
# 99th and 50th percentiles, respectively?
surCOP(cop=P, bF, bG) # 0.005
# What is the probability that either X or Y are less than
# the 99th and 50th percentiles, respectively?
duCOP(cop=P, FF, GG) # 0.995
# What is the probability that either X or Y are greater than
# the 99th and 50th percentiles, respectively?
coCOP(cop=P, bF, bG) # 0.505
## Not run:
# MAJOR EXAMPLE FOR QUICKLY MODIFYING INHERENT ASSOCIATION STRUCTURES
p <- 0.5 # Reasonable strong positive association for the Raftery copula
"RFcop1" <- function(u,v, para) COP(u,v, cop=RFcop, para=para, reflect="1")
"RFcop2" <- function(u,v, para) COP(u,v, cop=RFcop, para=para, reflect="2")
"RFcop3" <- function(u,v, para) COP(u,v, cop=RFcop, para=para, reflect="3")
"RFcop4" <- function(u,v, para) COP(u,v, cop=RFcop, para=para, reflect="4")
d <- 0.01 # Just to speed up the density plots a bit
densityCOPplot(RFcop1, para=p, contour.col=1, deluv=d) # the Raftery in the literature
densityCOPplot(RFcop2, para=p, contour.col=1, deluv=d, ploton=FALSE)
densityCOPplot(RFcop3, para=p, contour.col=1, deluv=d, ploton=FALSE)
densityCOPplot(RFcop4, para=p, contour.col=1, deluv=d, ploton=FALSE)
# Now some text into the converging tail to show the reflection used.
text(-2,-2, "reflect=1", col=2); text(+2,+2, "reflect=2", col=2)
text(+2,-2, "reflect=3", col=2); text(-2,+2, "reflect=4", col=2)
# To show how the reflection can be alternatively specified and avoid in this case
# making four Raferty functions, pass by a list para argument. Also, demonstrate
# that cop1 --> cop and para1 --> para are the same in use of the function. This
# provides some nomenclature parallel to the other compositing functions.
densityCOPplot(COP, para=list(reflect=1, cop1=RFcop, para=p ), deluv=d,
contour.col=1, drawlabels=FALSE)
densityCOPplot(COP, para=list(reflect=2, cop= RFcop, para1=p), deluv=d,
contour.col=2, drawlabels=FALSE, ploton=FALSE)
densityCOPplot(COP, para=list(reflect=3, cop1=RFcop, para1=p), deluv=d,
contour.col=3, drawlabels=FALSE, ploton=FALSE)
densityCOPplot(COP, para=list(reflect=4, cop= RFcop, para=p ), deluv=d,
contour.col=4, drawlabels=FALSE, ploton=FALSE) #
## End(Not run)
## Not run:
# Similar example to previous, but COP() can handle the reflection within a
# parameter list ,and the reflect, being numeric here, is converted to
# character internally.
T12 <- CLcop(tau=0.67)$para # Kendall Tau of 0.67
T12 <- list(cop=CLcop, para=T12, reflect=2) # reflected to upper tail dependency
UV <- simCOP(n=1000, cop=COP, para=T12) #
## End(Not run)
copBasic documentation built on Oct. 17, 2023, 5:08 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| COP | R Documentation |
The Copula
Description
Compute the copula or joint distribution function through a copula as shown by Nelsen (2006, p. 18) is the joint probability
\mathrm{Pr}[U \le u, V \le v] = \mathbf{C}(u,v)\mbox{.}
The copula is an expression of the joint probability that both U \le u and V \le v.
A copula is a type of dependence function that permits straightforward characterization of dependence from independence. Joe (2014, p. 8) comments that “copula families are usually given as cdfs [cumulative distribution functions.]” A radially symmetric or permutation symmetric copula is one such that \mathbf{C}(u,v) = \mathbf{C}(v,u) otherwise the copula is asymmetric.
The copula inversions t = \mathbf{C}(u{=}U, v) or t = \mathbf{C}(u, v{=}V) for a given t and U or V are provided by COPinv and COPinv2, respectively. A copula exists in the domain of the unit square (\mathcal{I}^2 = [0, 1]\times [0,1]) and is a grounded function meaning that
\mathbf{C}(u,0) = 0 = \mathbf{C}(0,v) \mbox{\ and\ thus\ } \mathbf{C}(0,0) = 0\mbox{, }
and other properties of a copula are that
\mathbf{C}(u,1) = u \mbox{\ and\ } \mathbf{C}(1,v) = v\mbox{\ and}
\mathbf{C}(1,1) = 1\mbox{.}
Copulas can be combined with each other (convexCOP, convex2COP, composite1COP,
composite2COP, composite3COP, and glueCOP) to form more complex and sophisticated dependence structures. Also copula multiplication—a special product of two copulas—yields another copula (see prod2COP).
Perhaps the one of the more useful features of this function is that in practical applications it can be used to take a copula formula and reflect or rotated it in fashions to attain association structures that the native definition of the copula can not acquire. The terminal demonstration in the Examples demonstrates this for the Raftery copula (RFcop).
Usage
COP(u, v, cop=NULL, para=NULL,
reflect=c("cop", "surv", "acute", "grave",
"1", "2", "3", "4"), ...)
Arguments
u |
Nonexceedance probability |
v |
Nonexceedance probability |
cop |
A copula function with vectorization as in |
para |
Vector of parameters or other data structures, if needed, to pass to the copula; |
reflect |
The reflection of the copula form (see Note) and the default |
... |
Additional arguments to pass to the copula. |
Value
Value(s) for the copula are returned.
Note
REFLECTIONS OF VARIABLES (ROTATIONS OF THE COPULA)—The copula of (1-U, 1-V) is the survival copula (\hat{\mathbf{C}}(u,v); surCOP) and is defined as
\mathrm{Pr}[\,U > u, V > v\,] = \hat{\mathbf{C}}(u,v) = u + v - 1 + \mathbf{C}(1-u,1-v)\:\rightarrow\mbox{\ \code{"surv"},}
whereas, following the notation of Joe (2014, p. 271), the copula of (1-U, V) is defined as
\mathrm{Pr}[\,U > u, V \le v\,] = \acute{\mathbf{C}}(u,v) = v - \mathbf{C}(1-u,v)\:\rightarrow\mbox{\ \code{"acute"}, and}
the copula of (U, 1-V) is defined as
\mathrm{Pr}[\,U \le u, V > v\,] = \grave{\mathbf{C}}(u,v) = u - \mathbf{C}(u,1-v)\:\rightarrow\mbox{\ \code{"grave"}.}
Here it is useful to stress the probability aspects that change with the reflections, but this section ends with the reflections themselves being graphically highlighted. The Examples stress simple variations on the probability aspects.
To clarify the seemingly clunky nomenclature—Joe (2014) does not provide “names” for \acute{\mathbf{C}}(u,v) or \grave{\mathbf{C}}(u,v)—the following guidance is informative:
\mbox{}\quad\mbox{}(1) "surv" or \hat{\mathbf{C}}(u,v) is a reflection of U and V on the horizontal and vertical axes, respectively,
\mbox{}\quad\mbox{}(2) "acute" or \acute{\mathbf{C}}(u,v) is a reflection of U on the horizontal axis, and
\mbox{}\quad\mbox{}(3) "grave" or \grave{\mathbf{C}}(u,v) is a reflection of V on the verical axis.
The names "acute" and "grave" match those used in the Rd-format math typesetting instructions. Users are directed to the documentation of simCOPmicro for further discussion because the COP function is expected to be an early entry point for new users interested in the copBasic API.
For the copBasic package and in order to keep some logic brief and code accessible for teaching and applied circumstances, reflections of copulas using analogs to the reflect argument are only natively supported in the COP and simCOPmicro functions. The interfaces of copBasic should already be flexible enough for users to adapt and (or) specially name reflections of copulas for deployment. A caveat is that some individual copula implementations might have some self-supporting infrastructure. The reflection can also be set within the para argument when it is a list (see Examples).
An example is warranted. Although the Gumbel–Hougaard copula (GHcop) can be reflected by COP and simCOPmicro and testing is made in the Note section of simCOPmicro, it is suggested that a user generally requiring say a horizontal reflection ru (or vertical reflection rv) of the Gumbel–Hougaard copula write a function named perhaps ruGHcop (or rvGHcop).
Such functions, consistent with the mathematics at the beginning of this Note, can be used throughout functions of copBasic using the cop arguments. The author (Asquith) eschews implementing what is perceived as too much flexibility and overhead for the package to support the three reflection permutations universally across all copula functions of the package. This being said, COP can take an R list for the para argument for rotation/reflection:
set.seed(14)
UV3 <- simCOP(20, cop=COP, pch=16, col=3,
para=list(cop=GLcop, para=pi+1, reflect="3"))
set.seed(14)
UV2 <- simCOP(20, cop=COP, pch=16, col=4, ploton=FALSE,
para=list(cop=GLcop, para=pi+1, reflect="2"))
arrows(x0=UV3[,1], y0=UV3[,2], x=UV2[,1], y=UV2[,2])
and this type of interface is similar to composite1COP as the following rotation and then asymmetric construction shows:
UV <- simCOP(1000, cop=composite1COP,
para=list(cop1=COP,
para1=c(cop=GHcop, para=pi+1, reflect="4"),
alpha=0.1, beta=0.3))
Author(s)
W.H. Asquith
References
Joe, H., 2014, 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
coCOP, duCOP, surCOP, surfuncCOP
Examples
u <- runif(1); v <- runif(1)
COP(cop=W,u,v); COP(cop=P,u,v); COP(cop=M,u,v); COP(cop=PSP,u,v)
FF <- 0.75 # 75th percentile, nonexceedance
GG <- 0.20 # 25th percentile, nonexceedance
bF <- 1 - FF; bG <- 1 - GG # exceedance
# What is the probability that both X and Y are less than
# 75th and 20th percentiles, respectively?
COP(cop=P, FF, GG) # 0.15
# What is the probability that both X and Y are greater than
# 75th and 20th percentiles, respectively?
surCOP(cop=P, bF, bG) # 0.20
# What is the probability that either X or Y are less than
# the 75th and 20th percentiles, respectively?
duCOP(cop=P, FF, GG) # 0.8
# What is the probability that either X or Y are greater than
# the 75th and 20th percentiles, respectively?
coCOP(cop=P, bF, bG) # 0.85
# Repeat for the PSP copula:
# What is the probability that both X and Y are less than
# 75th and 20th percentiles, respectively?
COP(cop=PSP, FF, GG) # 0.1875
# What is the probability that both X and Y are greater than
# 75th and 20th percentiles, respectively?
surCOP(cop=PSP, bF, bG) # 0.2375
# What is the probability that either X or Y are less than
# the 75th and 20th percentiles, respectively?
duCOP(cop=PSP, FF, GG) # 0.7625
# What is the probability that either X or Y are greater than
# the 75th and 20th percentiles, respectively?
coCOP(cop=PSP, bF, bG) # 0.8125
# Both of these summations equal unity
COP(cop=PSP, FF, GG) + coCOP(cop=PSP, bF, bG) # 1
surCOP(cop=PSP, bF, bG) + duCOP(cop=PSP, FF, GG) # 1
FF <- 0.99 # 99th percentile, nonexceedance
GG <- 0.50 # 50th percentile, nonexceedance
bF <- 1 - FF # nonexceedance
bG <- 1 - GG # nonexceedance
# What is the probability that both X and Y are less than
# 99th and 50th percentiles, respectively?
COP(cop=P, FF, GG) # 0.495
# What is the probability that both X and Y are greater than
# 99th and 50th percentiles, respectively?
surCOP(cop=P, bF, bG) # 0.005
# What is the probability that either X or Y are less than
# the 99th and 50th percentiles, respectively?
duCOP(cop=P, FF, GG) # 0.995
# What is the probability that either X or Y are greater than
# the 99th and 50th percentiles, respectively?
coCOP(cop=P, bF, bG) # 0.505
## Not run:
# MAJOR EXAMPLE FOR QUICKLY MODIFYING INHERENT ASSOCIATION STRUCTURES
p <- 0.5 # Reasonable strong positive association for the Raftery copula
"RFcop1" <- function(u,v, para) COP(u,v, cop=RFcop, para=para, reflect="1")
"RFcop2" <- function(u,v, para) COP(u,v, cop=RFcop, para=para, reflect="2")
"RFcop3" <- function(u,v, para) COP(u,v, cop=RFcop, para=para, reflect="3")
"RFcop4" <- function(u,v, para) COP(u,v, cop=RFcop, para=para, reflect="4")
d <- 0.01 # Just to speed up the density plots a bit
densityCOPplot(RFcop1, para=p, contour.col=1, deluv=d) # the Raftery in the literature
densityCOPplot(RFcop2, para=p, contour.col=1, deluv=d, ploton=FALSE)
densityCOPplot(RFcop3, para=p, contour.col=1, deluv=d, ploton=FALSE)
densityCOPplot(RFcop4, para=p, contour.col=1, deluv=d, ploton=FALSE)
# Now some text into the converging tail to show the reflection used.
text(-2,-2, "reflect=1", col=2); text(+2,+2, "reflect=2", col=2)
text(+2,-2, "reflect=3", col=2); text(-2,+2, "reflect=4", col=2)
# To show how the reflection can be alternatively specified and avoid in this case
# making four Raferty functions, pass by a list para argument. Also, demonstrate
# that cop1 --> cop and para1 --> para are the same in use of the function. This
# provides some nomenclature parallel to the other compositing functions.
densityCOPplot(COP, para=list(reflect=1, cop1=RFcop, para=p ), deluv=d,
contour.col=1, drawlabels=FALSE)
densityCOPplot(COP, para=list(reflect=2, cop= RFcop, para1=p), deluv=d,
contour.col=2, drawlabels=FALSE, ploton=FALSE)
densityCOPplot(COP, para=list(reflect=3, cop1=RFcop, para1=p), deluv=d,
contour.col=3, drawlabels=FALSE, ploton=FALSE)
densityCOPplot(COP, para=list(reflect=4, cop= RFcop, para=p ), deluv=d,
contour.col=4, drawlabels=FALSE, ploton=FALSE) #
## End(Not run)
## Not run:
# Similar example to previous, but COP() can handle the reflection within a
# parameter list ,and the reflect, being numeric here, is converted to
# character internally.
T12 <- CLcop(tau=0.67)$para # Kendall Tau of 0.67
T12 <- list(cop=CLcop, para=T12, reflect=2) # reflected to upper tail dependency
UV <- simCOP(n=1000, cop=COP, para=T12) #
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.