Bivariate copula distributions — bicop_distributions • rvinecopulib
Description: Density, distribution function, random generation and h-functions (with their inverses) for the bivariate copula distribution.

# Bivariate copula distributions

Source: `R/bicop_methods.R`
`bicop_methods.Rd`

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

    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_1}(x_1^-)\). 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, e.g., `dbicop(c(0.1, 0.5), bicop_dist("indep"))`.

## See also

`bicop_dist()`, `bicop()`

## 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.2656806 0.5530300 0.3588555 0.9798320 0.3616805 0.2016459 0.6836471
    #>  [8] 0.2367264 0.8360947 0.5256395