Skip to contents

Vine copula models

Source: R/vine.R
vine.Rd

Automated fitting or creation of custom vine copula models

Usage

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,
    allow_rotations = TRUE, trunc_lvl = Inf, tree_crit = "tau", threshold = 0, keep_data
    = FALSE, show_trace = FALSE, cores = 1, tree_algorithm = "mst_prim"),
  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().

  • type 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(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 7 
#>  margin name nobs   bw mult loglik d.f.
#>       1   V1   50 0.74  1.4    -62  3.9
#>       2   V2   50 0.67  1.4    -61  2.7
#>       3   V3   50 0.61  1.4    -64  3.2
#> 
#> $copula
#> # A data.frame: 3 x 11 
#>  tree edge conditioned conditioning var_types   family rotation
#>     1    1        2, 1                    c,c     tawn      270
#>     1    2        1, 3                    c,c gaussian        0
#>     2    1        2, 3            1       c,c     tawn       90
#>        parameters df   tau loglik
#>  0.85, 0.93, 6.64  3 -0.70     51
#>             -0.93  1 -0.76     49
#>  0.71, 1.00, 4.54  3 -0.59     36
#> 

## 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 7 
#>  margin name nobs   bw mult loglik d.f.
#>       1   V1   50 0.98  1.4    -85  6.6
#>       2   V2   50 0.67  1.4    -61  2.7
#>       3   V3   50 0.61  1.4    -64  3.2
#> 
#> $copula
#> # A data.frame: 3 x 11 
#>  tree edge conditioned conditioning var_types family rotation    parameters df
#>     1    1        2, 1                    c,d    bb7      270      1.0, 2.9  2
#>     1    2        1, 3                    d,c    bb8      270    3.87, 0.94  2
#>     2    1        2, 3            1       c,c   tawn        0 0.7, 0.3, 3.4  3
#>    tau loglik
#>  -0.60   27.2
#>  -0.56   20.4
#>   0.23    6.6
#>