Bivariate copula distributions

Density, distribution function, random generation and h-functions (with their inverses) for the bivariate copula distribution.

Usage

dbicop(u, family, rotation, parameters, var_types = c("c", "c"))

pbicop(u, family, rotation, parameters, var_types = c("c", "c"))

rbicop(n, family, rotation, parameters, qrng = FALSE)

hbicop(
  u,
  cond_var,
  family,
  rotation,
  parameters,
  inverse = FALSE,
  var_types = c("c", "c")
)

Arguments

u: evaluation points, a matrix with at least two columns, see Details.
family: the copula family, a string containing the family name (see bicop for all possible families).
rotation: the rotation of the copula, one of 0, 90, 180, 270.
parameters: a vector or matrix of copula parameters.
var_types: variable types, a length 2 vector; e.g., c("c", "c") for both continuous (default), or c("c", "d") for first variable continuous and second discrete.
n: number of observations. If `length(n) > 1“, the length is taken to be the number required.
qrng: if TRUE, generates quasi-random numbers using the bivariate Generalized Halton sequence (default qrng = FALSE).
cond_var: either 1 or 2; cond_var = 1 conditions on the first variable, cond_var = 2 on the second.
inverse: whether to compute the h-function or its inverse.

Value

dbicop() gives the density, pbicop() gives the distribution function, rbicop() generates random deviates, and hbicop() gives the h-functions (and their inverses).

The length of the result is determined by n for rbicop(), and the number of rows in u for the other functions.

The numerical arguments other than n are recycled to the length of the result.

Details

See bicop for the various implemented copula families.

The copula density is defined as joint density divided by marginal densities, irrespective of variable types.

H-functions (hbicop()) are conditional distributions derived from a copula. If $C(u, v) = P(U \le u, V \le v)$ is a copula, then $$h_1(u, v) = P(V \le v | U = u) = \partial C(u, v) / \partial u,$$ $$h_2(u, v) = P(U \le u | V = v) = \partial C(u, v) / \partial v.$$ In other words, the H-function number refers to the conditioning variable. When inverting H-functions, the inverse is then taken with respect to the other variable, that is v when cond_var = 1 and u when cond_var = 2.

Discrete variables

When at least one variable is discrete, more than two columns are required for u: the first $n \times 2$ block contains realizations of $F_{X_1}(x_1), F_{X_2}(x_2)$. The second $n \times 2$ block contains realizations of $F_{X_1}(x_1^-), F_{X_2}(x_2^-)$. The minus indicates a left-sided limit of the cdf. For, e.g., an integer-valued variable, it holds $F_{X_1}(x_1^-) = F_{X_1}(x_1 - 1)$. For continuous variables the left limit and the cdf itself coincide. Respective columns can be omitted in the second block.

Note

The functions can optionally be used with a bicop_dist object in place of the family argument, e.g., dbicop(c(0.1, 0.5), bicop_dist("indep")) or hbicop(c(0.1, 0.5), 2, bicop_dist("indep")).

Examples

## evaluate the copula density
dbicop(c(0.1, 0.2), "clay", 90, 3)
#> [1] 0.04843628
dbicop(c(0.1, 0.2), bicop_dist("clay", 90, 3))
#> [1] 0.04843628

## evaluate the copula cdf
pbicop(c(0.1, 0.2), "clay", 90, 3)
#> [1] 0.0001978703

## simulate data
plot(rbicop(500, "clay", 90, 3))


## h-functions
joe_cop <- bicop_dist("joe", 0, 3)
# h_1(0.1, 0.2)
hbicop(c(0.1, 0.2), 1, "bb8", 0, c(2, 0.5))
#> [1] 0.2436951
# h_2^{-1}(0.1, 0.2)
hbicop(c(0.1, 0.2), 2, joe_cop, inverse = TRUE)
#> [1] 0.05221261

## mixed discrete and continuous data
x <- cbind(rpois(10, 1), rnorm(10, 1))
u <- cbind(ppois(x[, 1], 1), pnorm(x[, 2]), ppois(x[, 1] - 1, 1))
pbicop(u, "clay", 90, 3, var_types = c("d", "c"))
#>  [1] 0.726466873 0.001055373 0.502213354 0.180035017 0.716504356 0.253953372
#>  [7] 0.621916144 0.565928213 0.510552135 0.306905371