rvinecopulib (version 0.3.2.1.1)

vinecop: Vine copula models

Description

Automated fitting or creation of custom vine copula models

Usage

vinecop(data, family_set = "all", structure = NA, par_method = "mle",
  nonpar_method = "constant", mult = 1, selcrit = "bic",
  weights = numeric(), psi0 = 0.9, presel = TRUE, trunc_lvl = Inf,
  tree_crit = "tau", threshold = 0, keep_data = FALSE,
  show_trace = FALSE, cores = 1)
vinecop_dist(pair_copulas, structure)

Arguments

data

a matrix or data.frame (copula data should have approximately uniform margins).

family_set

a character vector of families; see bicop() for additional options.

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; for vinecop(), structure = NA performs automatic structure selection.

par_method

the estimation method for parametric models, either "mle" for maximum likelihood or "itau" for inversion of Kendall's tau (only available for one-parameter families and "t".

nonpar_method

the estimation method for nonparametric models, either "constant" for the standard transformation estimator, or "linear"/"quadratic" for the local-likelihood approximations of order one/two.

mult

multiplier for the smoothing parameters of nonparametric families. Values larger than 1 make the estimate more smooth, values less than 1 less smooth.

selcrit

criterion for family selection, either "loglik", "aic", "bic", "mbic". For vinecop() there is the additional option "mbicv".

weights

optional vector of weights for each observation.

psi0

prior probability of a non-independence copula (only used for selcrit = "mbic" and selcrit = "mbicv").

presel

whether the family set should be thinned out according to symmetry characteristics of the data.

trunc_lvl

the truncation level of the vine copula; Inf means no truncation, NA indicates that the truncation level should be selected automatically by mBICV().

tree_crit

the criterion for tree selection, one of "tau", "rho", "hoeffd", or "mcor" for Kendall's \(\tau\), Spearman's \(\rho\), Hoeffding's \(D\), and maximum correlation, respectively.

threshold

for thresholded vine copulas; NA indicates that the threshold should be selected automatically by mBICV().

keep_data

whether the data should be stored (necessary for using fitted()).

show_trace

logical; whether a trace of the fitting progress should be printed.

cores

number of cores to use; if more than 1, estimation of pair copulas within a tree is done in parallel.

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.

Value

Objects inheriting from vinecop_dist for vinecop_dist(), and vinecop and vinecop_dist for vinecop().

Object from the vinecop_dist class are lists containing:

• pair_copulas, a list of lists. Each element of pair_copulas corresponds to a tree, which is itself a list of bicop_dist objects, see bicop_dist().

• 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()).

• npars, a numeric with the number of (effective) parameters.

For objects from the vinecop class, elements of the sublists in pair_copulas are also bicop objects, see bicop(). Additionally, objects from the vinecop class contain:

• threshold, the (set or estimated) threshold used for thresholding the vine.

• data (optionally, if keep_data = TRUE was used), the dataset that was passed to vinecop().

• controls, a list with the set of fit controls that was passed to vinecop().

• nobs, an integer with the number of observations that was used to fit the model.

Details

vinecop_dist() creates a vine copula by specifying a nested list of bicop_dist() objects and a quadratic structure matrix.

vinecop() provides automated fitting for vine copula models. The function inherits the parameters of bicop(). Optionally, an rvine_structure() or rvine_matrix() can be used as input to specify the vine structure. tree_crit describes the criterion for tree selection, one of "tau", "rho", "hoeffd" for Kendall's tau, Spearman's rho, and Hoeffding's D, respectively. Additionally, threshold allows to threshold the tree_crit and trunc_lvl to truncate the vine copula, with threshold_sel and trunc_lvl_sel to automatically select both parameters.

Examples

# NOT RUN {
# 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
vc <- vinecop_dist(pcs, mat)

# show model
summary(vc)

# simulate some data
u <- rvinecop(50, vc)

# estimate a vine copula model
fit <- vinecop(u, "par")
fit
summary(fit)
str(fit, 3)
# }