Vine copula models — vine • rvinecopulib
Description: Automated fitting or creation of custom vine copula models

# Vine copula models

Source: `R/vine.R`
`vine.Rd`

Automated fitting or creation of custom vine copula models

    vine(
      data,
      margins_controls = list(mult = NULL, xmin = NaN, xmax = NaN, bw = NA, deg = 2),
      copula_controls = list(family_set = "all", structure = NA, par_method = "mle",
        nonpar_method = "constant", mult = 1, selcrit = "aic", psi0 = 0.9, presel = TRUE,
        trunc_lvl = Inf, tree_crit = "tau", threshold = 0, keep_data = FALSE, show_trace =
        FALSE, cores = 1),
      weights = numeric(),
      keep_data = FALSE,
      cores = 1
    )

    vine_dist(margins, pair_copulas, structure)

## Arguments

data

  a matrix or data.frame. Discrete variables have to be declared as `ordered()`.

margins_controls

  a list with arguments to be passed to `kde1d::kde1d()`. Currently, there can be

  - `mult` numeric vector of length one or d; all bandwidths for marginal kernel density estimation are multiplied with `mult`. Defaults to `log(1 + d)` where `d` is the number of variables after applying `rvinecopulib:::expand_factors()`.

  - `xmin` numeric vector of length d; see `kde1d::kde1d()`.

  - `xmax` numeric vector of length d; see `kde1d::kde1d()`.

  - `bw` numeric vector of length d; see `kde1d::kde1d()`.

  - `deg` numeric vector of length one or d; `kde1d::kde1d()`.

copula_controls

  a list with arguments to be passed to `vinecop()`.

weights

  optional vector of weights for each observation.

keep_data

  whether the original data should be stored; if you want to store the pseudo-observations used for fitting the copula, use the `copula_controls` argument.

cores

  the number of cores to use for parallel computations.

margins

  A list with with each element containing the specification of a marginal stats::Distributions. Each marginal specification should be a list with containing at least the distribution family (`"distr"`) and optionally the parameters, e.g. `list(list(distr = "norm"), list(distr = "norm", mu = 1), list(distr = "beta", shape1 = 1, shape2 = 1))`. Note that parameters that have no default values have to be provided. Furthermore, if `margins` has length one, it will be recycled for every component.

pair_copulas

  A nested list of 'bicop_dist' objects, where `pair_copulas[[t]][[e]]` corresponds to the pair-copula at edge `e` in tree `t`.

structure

  an `rvine_structure` object, namely a compressed representation of the vine structure, or an object that can be coerced into one (see `rvine_structure()` and `as_rvine_structure()`). The dimension must be `length(pair_copulas[[1]]) + 1`.

## Value

Objects inheriting from `vine_dist` for `vine_dist()`, and `vine` and `vine_dist` for `vine()`.

Objects from the `vine_dist` class are lists containing:

- `margins`, a list of marginals (see below).

- `copula`, an object of the class `vinecop_dist`, see `vinecop_dist()`.

For objects from the `vine` class, `copula` is also an object of the class `vine`, see `vinecop()`. Additionally, objects from the `vine` class contain:

- `margins_controls`, a `list` with the set of fit controls that was passed to `kde1d::kde1d()` when estimating the margins.

- `copula_controls`, a `list` with the set of fit controls that was passed to `vinecop()` when estimating the copula.

- `data` (optionally, if `keep_data = TRUE` was used), the dataset that was passed to `vine()`.

- `nobs`, an `integer` containing the number of observations that was used to fit the model.

Concerning `margins`:

- For objects created with `vine_dist()`, it simply corresponds to the `margins` argument.

- For objects created with `vine()`, it is a list of objects of class `kde1d`, see `kde1d::kde1d()`.

## Details

`vine_dist()` creates a vine copula by specifying the margins, a nested list of `bicop_dist` objects and a quadratic structure matrix.

`vine()` provides automated fitting for vine copula models. `margins_controls` is a list with the same parameters as `kde1d::kde1d()` (except for `x`). `copula_controls` is a list with the same parameters as `vinecop()` (except for `data`).

## Examples

    # specify pair-copulas
    bicop <- bicop_dist("bb1", 90, c(3, 2))
    pcs <- list(
      list(bicop, bicop), # pair-copulas in first tree
      list(bicop) # pair-copulas in second tree
    )

    # specify R-vine matrix
    mat <- matrix(c(1, 2, 3, 1, 2, 0, 1, 0, 0), 3, 3)

    # set up vine copula model with Gaussian margins
    vc <- vine_dist(list(distr = "norm"), pcs, mat)

    # show model
    summary(vc)
    #> $margins
    #> # A data.frame: 3 x 2
    #>  margin distr
    #>       1  norm
    #>       2  norm
    #>       3  norm
    #>
    #> $copula
    #> # A data.frame: 3 x 10
    #>  tree edge conditioned conditioning var_types family rotation parameters df
    #>     1    1        3, 1                    c,c    bb1       90       3, 2  2
    #>     1    2        2, 1                    c,c    bb1       90       3, 2  2
    #>     2    1        3, 2            1       c,c    bb1       90       3, 2  2
    #>   tau
    #>  -0.8
    #>  -0.8
    #>  -0.8
    #>

    # simulate some data
    x <- rvine(50, vc)

    # estimate a vine copula model
    fit <- vine(x, copula_controls = list(family_set = "par"))
    summary(fit)
    #> $margins
    #> # A data.frame: 3 x 6
    #>  margin name nobs  bw loglik d.f.
    #>       1   V1   50 1.6    -81  3.6
    #>       2   V2   50 1.8    -81  5.1
    #>       3   V3   50 1.2    -79  2.3
    #>
    #> $copula
    #> # A data.frame: 3 x 11
    #>  tree edge conditioned conditioning var_types family rotation parameters df
    #>     1    1        2, 1                    c,c gumbel      270          8  1
    #>     1    2        1, 3                    c,c    bb1      270   2.1, 3.7  2
    #>     2    1        2, 3            1       c,c gumbel       90        4.1  1
    #>    tau loglik
    #>  -0.88     83
    #>  -0.87     82
    #>  -0.75     51
    #>

    ## model for discrete data
    x <- as.data.frame(x)
    x[, 1] <- ordered(round(x[, 1]), levels = seq.int(-5, 5))
    fit_disc <- vine(x, copula_controls = list(family_set = "par"))
    summary(fit_disc)
    #> $margins
    #> # A data.frame: 3 x 6
    #>  margin name nobs  bw loglik d.f.
    #>       1   V1   50 1.6    -81  1.3
    #>       2   V2   50 1.8    -81  5.1
    #>       3   V3   50 1.2    -79  2.3
    #>
    #> $copula
    #> # A data.frame: 3 x 11
    #>  tree edge conditioned conditioning var_types family rotation parameters df
    #>     1    1        2, 1                    c,d gumbel      270        8.6  1
    #>     1    2        1, 3                    d,c    bb7      270  5.4, 23.2  2
    #>     2    1        2, 3            1       c,c  frank        0        1.6  1
    #>    tau loglik
    #>  -0.88   59.1
    #>  -0.86   60.0
    #>   0.18    2.4
    #>