rvinecopulib (version 1.0.0.1.0)

vinecop_distributions: Vine copula distributions

Description

Density, distribution function and random generation for the vine copula distribution.

Usage

dvinecop(
  u,
  vinecop,
  cores = 1,
  keep_all = FALSE,
  parameters = NULL,
  log = FALSE
)
scores(u, vinecop, ...)
# S3 method for vinecop_dist
scores(u, vinecop, step_wise = TRUE, cores = 1, parameters = NULL, ...)
hessian(u, vinecop, ...)
# S3 method for vinecop_dist
hessian(u, vinecop, step_wise = TRUE, cores = 1, parameters = NULL, ...)
pvinecop(u, vinecop, n_mc = 10^4, cores = 1)
rvinecop(
  n,
  vinecop,
  qrng = FALSE,
  cores = 1,
  u_cond = NULL,
  conditioning_set = NULL
)

Value

dvinecop() gives the density, pvinecop() gives the distribution function, rvinecop() generates unconditional or conditional random deviates, scores() gives the observation-wise score matrix, and hessian() gives the average Hessian matrix.

If keep_all = TRUE, dvinecop() returns a list with entries pdf, logpdf, pdf_edges, hfunc1, hfunc2, hfunc1_sub, and hfunc2_sub. The _sub

entries contain h-functions evaluated at left-sided limits when the model contains discrete variables; they are empty for fully continuous models.

The length of the result is determined by n for rvinecop(), and the number of rows in u for the other functions.

The vinecop object is recycled to the length of the result.

Arguments

u

matrix of evaluation points; must contain at least d columns, where d is the number of variables in the vine. More columns are required for discrete models, see Details.

vinecop

an object of class "vinecop_dist".

cores

number of cores to use; if larger than one, computations are done in parallel on cores batches .

keep_all

if TRUE, dvinecop() returns additional intermediate quantities computed during density evaluation.

parameters

optional observation-specific parameters for dvinecop(), scores(), and hessian(). For a model with one parameter, this may be a vector with one entry per observation. Otherwise, it must be a matrix with one row per observation and one column per model parameter. For vine copulas, columns follow the (tree, edge, parameter) order of scores(). Parameters are not recycled. Only continuous parametric models are supported.

log

if TRUE, dvinecop() returns the log-density instead of the density. A vine density is a product of one factor per edge, so it underflows to 0 in high dimensions or under strong dependence while its logarithm is still an ordinary double; log = TRUE accumulates in log space and is the accurate way to obtain it. Ignored when keep_all = TRUE, which reports both.

...

unused.

step_wise

if FALSE, the score/Hessian is computed for the full likelihood; if TRUE, gradients are computed per pair-copula as in step-wise estimation.

n_mc

number of samples used for quasi Monte Carlo integration.

n

number of observations.

qrng

if TRUE, generates quasi-random numbers using the multivariate Generalized Halton sequence up to dimension 300 and the Generalized Sobol sequence in higher dimensions (default qrng = FALSE).

u_cond

optional conditioning values for rvinecop(). A vector or one-row matrix is repeated n times; alternatively, supply an n-row matrix for observation-specific conditioning values. The first block holds the copula-scale values \(F(x)\). The expanded layout appends one left-limit column \(F(x^-)\) per conditioning variable in the same order; columns for continuous variables equal their value columns. In the compact layout, the redundant columns for continuous variables are omitted. If NULL, rvinecop() performs unconditional simulation.

conditioning_set

variable indices or names corresponding to the first block of u_cond. When NULL, the columns of u_cond correspond to the last variables of the current vine order. When supplied, the model is transiently reoriented and is not modified.

Details

See vinecop() for the estimation and construction of vine copula models.

The copula density is defined as joint density divided by marginal densities, irrespective of variable types.

Discrete variables

When at least one variable is discrete, two types of "observations" are required in u: the first \(n \; x \; d\) block contains realizations of \(F_{X_j}(X_j)\). The second \(n \; x \; d\) block contains realizations of \(F_{X_j}(X_j^-)\). The minus indicates a left-sided limit of the cdf. For, e.g., an integer-valued variable, it holds \(F_{X_j}(X_j^-) = F_{X_j}(X_j - 1)\). For continuous variables the left limit and the cdf itself coincide. Respective columns can be omitted in the second block.

See Also

vinecop_dist(), vinecop(), plot.vinecop(), contour.vinecop()

Examples

## simulate dummy data
x <- rnorm(30) * matrix(1, 30, 5) + 0.5 * matrix(rnorm(30 * 5), 30, 5)
u <- pseudo_obs(x)

## fit a model
vc <- vinecop(u, family_set = "clayton")

# simulate from the model
u <- rvinecop(100, vc)
pairs(u)

# evaluate the density and cdf
dvinecop(u[1, ], vc)
pvinecop(u[1, ], vc)

# evaluate derivatives of the log-likelihood
scores(u, vc)
hessian(u, vc)

# derivatives can also be computed for the full likelihood
scores(u, vc, step_wise = FALSE)
hessian(u, vc, step_wise = FALSE)

## Discrete models
vc$var_types <- rep("d", 5)  # convert model to discrete

# with discrete data we need two types of observations (see Details)
x <- qpois(u, 1)  # transform to Poisson margins
u_disc <- cbind(ppois(x, 1), ppois(x - 1, 1))

dvinecop(u_disc[1:5, ], vc)
pvinecop(u_disc[1:5, ], vc)

# simulated data always has uniform margins
pairs(rvinecop(200, vc))

## Conditional simulation
vc_cond <- vinecop(
  u,
  family_set = "gaussian",
  conditioning_set = c(2, 4)
)
u_cond <- c(0.25, 0.75)
uc <- rvinecop(
  100,
  vc_cond,
  u_cond = u_cond,
  conditioning_set = c(2, 4)
)
stopifnot(
  isTRUE(all.equal(uc[, 2], rep(0.25, 100))),
  isTRUE(all.equal(uc[, 4], rep(0.75, 100)))
)