rvinecopulib (version 0.2.8.1.0)

vinecop: Vine copula models

Description

Automated fitting or creation of custom vine copula models

Usage

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

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.

matrix

a quadratic matrix specifying the structure matrix (see check_rvine_matrix()); for vinecop_dist(), the dimension must be length(pair_copulas)-1; for vinecop(), matrix = 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".

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 computing fit statistics and 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().

• matrix, an R-vine matrix, namely a compressed representation of the vine structure, see check_rvine_matrix().

• 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, a quadratic matrix can be used as input to pre-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)

# }