Getting started with svines

Model layers

An S-vine model combines marginal distributions with a stationary vine copula. The package exposes these two layers separately:

• svine() fits a complete distribution model to observed data. It estimates the marginal distributions, transforms the observations to the unit hypercube, and fits the copula.
• svinecop() fits only the copula and therefore expects approximately uniform pseudo-observations.
• svine_dist() and svinecop_dist() construct models from specified margins, pair copulas, and an S-vine structure.

The argument p is the Markov order. An order-one model relates the current observation to the previous observation, while larger values include additional lags.

Fitting a continuous model

The returns data contain daily log returns of 20 companies. We use two series and restrict the candidate families to keep this example short.

data(returns)
x <- returns[1:200, 1:2]

fit <- svine(
  x,
  p = 1,
  margin_families = c("norm", "std"),
  family_set = c("gaussian", "t")
)
fit
#> 2-dimensional S-vine distribution model of order p = 1 ('svine_dist')
summary(fit)
#> $margins
#> # A data.frame: 2 x 5 
#>  margin    name     model             parameters loglik
#>       1 Allianz    Normal       0.00034, 0.01536    551
#>       2     AXA Student-t 0.0019, 0.0197, 4.0004    522
#> 
#> $copula
#> # A data.frame: 5 x 10 
#>  tree edge conditioned conditioning var_types   family rotation    parameters
#>     1    1        3, 1                    c,c        t        0 -0.084, 4.781
#>     1    2        2, 1                    c,c        t        0    0.84, 4.87
#>     2    1        4, 1            3       c,c gaussian        0        -0.064
#>     2    2        3, 2            1       c,c gaussian        0         0.074
#>     3    1        4, 2         1, 3       c,c gaussian        0        -0.072
#>  df    tau
#>   2 -0.054
#>   2  0.637
#>   1 -0.041
#>   1  0.047
#>   1 -0.046

The fitted object contains the marginal models in fit$margins and the copula model in fit$copula. Standard rvinecopulib methods can be applied to the copula component.

Simulation and diagnostics

Without a conditioning history, svine_sim() generates a new stationary time series. Supplying past instead generates paths conditional on the observed history.

sim <- svine_sim(n = 100, rep = 1, model = fit)
dim(sim)
#> [1] 100   2

next_obs <- svine_sim(n = 1, rep = 100, model = fit, past = x)
dim(next_obs)
#>     dim     
#>   1   2 100

Pseudo-residuals are conditional Rosenblatt transforms. For a fitted model of order p, the result has NROW(x) - p rows.

residuals <- svine_pseudo_residuals(x, fit)
dim(residuals)
#> [1] 199   2

Discrete variables

For discrete variables, specify var_types = "d" and restrict margin_families to suitable discrete families. The following model uses two Poisson margins.

counts <- cbind(
  claims = rpois(250, lambda = 2),
  events = rpois(250, lambda = 4)
)

fit_discrete <- svine(
  counts,
  p = 1,
  var_types = c("d", "d"),
  margin_families = "pois",
  family_set = "gaussian"
)
fit_discrete
#> 2-dimensional S-vine distribution model of order p = 1 ('svine_dist')
svine_sim(5, rep = 1, model = fit_discrete)
#>      claims events
#> [1,]      2      5
#> [2,]      0      1
#> [3,]      5      5
#> [4,]      6      7
#> [5,]      2      3

svine() evaluates both the CDF, F(x), and its left limit, F(x-), and constructs the copula data automatically. When calling svinecop() directly, supply the regular CDF columns first, followed by one left-limit column for each discrete variable.

Copula-only models

When the marginal transformation is handled separately, fit the copula layer directly.

u <- pseudo_obs(x)
copula_fit <- svinecop(
  u,
  p = 1,
  family_set = c("gaussian", "t")
)
copula_fit
#> 2-dimensional S-vine copula model of order p = 1 ('svinecop_dist')

Use svinecop_loglik(), svinecop_scores(), and svinecop_hessian() for copula-level inference. The corresponding svine_* functions include the marginal parameters.