Public API

Core types

VineCopulas.AbstractVineStructure Type

AbstractVineStructure{p}

Abstract supertype for structural descriptions of p-dimensional vines. Structure objects store variable ordering and active tree depth without owning the pair-copula families or parameters.

source

VineCopulas.AbstractVineCopula Type

AbstractVineCopula{p} <: Copulas.Copula{p}

Abstract supertype for all p-dimensional vine copula models implemented by VineCopulas.jl. Concrete subtypes include CVineCopula, DVineCopula, and RVineCopula.

source

VineCopulas.VineCopula Type

VineCopula

Alias for AbstractVineCopula.

source

VineCopulas.PairCopula Type

PairCopula

Alias for Copulas.Copula{2}. Pair-copulas are the bivariate building blocks used on vine edges.

source

VineCopulas.CVineStructure Type

Structure-only description of a C-vine order and active truncation level.

source

VineCopulas.DVineStructure Type

Structure-only description of a D-vine path order and active truncation level.

source

VineCopulas.RVineStructure Type

RVineStructure(order, struct_array; trunc=length(order)-1)

Structure representation for a regular vine. It stores the variable order, triangular structure array, and optional exchange matrix. The truncation level is encoded by the type parameter q and by the length of struct_array.

source

VineCopulas.CVineCopula Type

CVineCopula(order, edges; trunc=length(order)-1)
CVineCopula(structure::CVineStructure, edges)

Construct a canonical vine copula from a variable order and a triangular collection of bivariate pair-copulas. The entry edges[k][i] represents the pair-copula between the root order[k] and the child order[k+i], conditional on the previous roots order[1:k-1].

Matrices of observations follow the package convention p × n: rows are dimensions and columns are observations.

Example

C12 = GaussianCopula([1.0 0.5; 0.5 1.0])
C13 = ClaytonCopula(2, 2.0)
C23_1 = FrankCopula(2, 3.0)
cv = CVineCopula([1, 2, 3], [[C12, C13], [C23_1]])

source

VineCopulas.DVineCopula Type

DVineCopula(order, edges; trunc=length(order)-1)
DVineCopula(structure::DVineStructure, edges)

Construct a drawable/path vine copula from a variable order and a triangular collection of bivariate pair-copulas. The entry edges[k][i] represents the pair-copula between order[i] and order[i+k], conditional on the variables between them in the D-vine path.

Example

C12 = GaussianCopula([1.0 0.5; 0.5 1.0])
C23 = ClaytonCopula(2, 2.0)
C13_2 = FrankCopula(2, 3.0)
dv = DVineCopula([1, 2, 3], [[C12, C23], [C13_2]])

source

VineCopulas.RVineCopula Type

RVineCopula(order, struct_array, edges; trunc=length(order)-1)
RVineCopula(matrix, edges)

Construct a regular-vine copula from an explicit structure array or from an R-vine matrix exchange representation. Standard general R-vine structures are validated against the proximity condition at construction time. General R-vine evaluation is covered by the external rvinecopulib correctness campaign.

source

VineCopulas.VineEdge Type

VineEdge

Description of a pair-copula edge in a vine tree, including the conditioned variables, conditioning set, pair-copula, tree level, and within-tree index.

source

Fitting family sets

VineCopulas.DEFAULT_PAIR_FAMILIES Constant

DEFAULT_PAIR_FAMILIES

Stable parametric family set used by automatic pair-copula selection. It intentionally overlaps the common parametric core used in vinecopulib: Gaussian, Student-t, Clayton, Gumbel, Frank, Joe, BB1, BB6, BB7 and BB8. Independence is handled separately by include_independence=true.

source

VineCopulas.ALL_PARAMETRIC_PAIR_FAMILIES Constant

ALL_PARAMETRIC_PAIR_FAMILIES

Broader parametric set exposed by Copulas.jl/VineCopulas.jl. The default set is deliberately smaller because it is the set that should receive the strongest correctness and benchmark coverage first.

source

VineCopulas.select_paircopula Function

select_paircopula(U; family_set=:default, pair_method=:default,
                  selection_criterion=:bic, allow_rotations=true,
                  preselect=true, include_independence=true,
                  pair_kwargs=NamedTuple(), strict=false, trace=false)

Fit candidate bivariate copula families to U, optionally evaluate their 0/90/180/270-degree rotations, and select the best candidate by :loglik, :aic, or :bic. Returns the selected Copulas.Copula{2}.

The default candidate set is DEFAULT_PAIR_FAMILIES. Use family_set=:all or an explicit collection of Copulas.jl family types to change the candidates.

source

Use select_paircopula(U) for automatic bivariate family selection. Fitting vine models is exposed through Distributions.fit, for example fit(CVineCopula, U), fit(DVineCopula, U), and fit(RVineCopula, U).

Structure accessors

VineCopulas.structure Function

structure(vine)

Return the vine's structural description without the pair-copula array.

source

VineCopulas.order Function

order(vine_or_structure)

Return the variable order used by a vine copula or vine structure.

source

VineCopulas.edges Function

edges(vine)

Return the triangular array of bivariate pair-copulas used by a vine copula. Tree k is stored in edges(vine)[k].

source

edges(vine)

Return the triangular array of bivariate pair-copulas used by a vine copula. Tree k is stored in edges(vine)[k].

source

Return the triangular array of pair-copulas used by an RVineCopula.

source

VineCopulas.struct_array Function

struct_array(vine)

Return the triangular structure array used by an RVineCopula.

source

VineCopulas.truncation Function

truncation(vine_or_structure)

Return the number of active trees in the vine. A full p-dimensional vine has truncation level p - 1.

source

Base.truncate Function

truncate(vine_or_structure, level)

Return a copy of a vine or vine structure retaining only trees 1:level. Truncation cannot restore trees that are absent from the input object.

source

VineCopulas.rvine_matrix Function

rvine_matrix(vc::RVineCopula)

Return an integer matrix representation of an RVineCopula. If the object was constructed from a matrix, a copy of that original matrix is returned; otherwise one is built from the stored structure array and order.

source

Pair conditionals

These functions are public convenience names for pair conditional CDFs and conditional quantiles. Their generic semantics are defined by the Copulas.condition interface; see Pair-copula contract.

VineCopulas.hfunc1 Function

hfunc1(C, u, v)
hfunc1(C, U)

Compute   for a bivariate pair-copula C. For an n × 2 matrix U, return one value per row.

source

VineCopulas.hfunc2 Function

hfunc2(C, u, v)
hfunc2(C, U)

Compute   for a bivariate pair-copula C. For an n × 2 matrix U, return one value per row.

source

VineCopulas.hinv1 Function

hinv1(C, q, v)

Invert hfunc1 in its first coordinate: return u such that hfunc1(C, u, v) ≈ q. Singular copulas may use a generalized inverse.

source

VineCopulas.hinv2 Function

hinv2(C, q, u)

Invert hfunc2 in its second coordinate: return v such that hfunc2(C, u, v) ≈ q. Singular copulas may use a generalized inverse.

source

VineCopulas.h₁ Function

Unicode alias for hfunc1.

source

VineCopulas.h₂ Function

Unicode alias for hfunc2.

source

VineCopulas.h₁⁻¹ Function

Unicode alias for hinv1.

source

VineCopulas.h₂⁻¹ Function

Unicode alias for hinv2.

source

Simulation and transforms

VineCopulas.simulate_qmc Function

simulate_qmc([rng::AbstractRNG,] vine, N; randomized=true, fixed=nothing)

Generate N quasi-Monte Carlo observations from a vine copula using Sobol points followed by the inverse Rosenblatt transform. The returned matrix has size p × N, with rows corresponding to variables and columns to observations.

When randomized=true the Sobol points are Owen-scrambled and rng drives the scramble. Without an rng the scramble uses a fixed internal seed, preserving the deterministic historical behaviour. When randomized=false, rng is ignored.

The fixed keyword has the same meaning as in inverse_rosenblatt: the fixed coordinates are held at their supplied values and the remaining coordinates are drawn conditionally.

source

VineCopulas.set_cdf_nsamples! Function

set_cdf_nsamples!(N::Integer)

Set the global number of Monte Carlo or quasi-Monte Carlo samples used by the numerical cdf approximation for vine copulas. This does not affect pdf, logpdf, rand, or Rosenblatt transforms.

source

VineCopulas.enable_deterministic_cdf! Function

enable_deterministic_cdf!(Npow::Integer=15)

Use 2^Npow quasi-Monte Carlo points for the numerical cdf approximation. This helper is intended for reproducible examples and tests.

source

Copulas.rosenblatt Function

rosenblatt(vine, u)
rosenblatt(vine, U)

Compute the Rosenblatt transform of a point or matrix under a vine copula. A matrix input is interpreted as p × n: rows are dimensions and columns are observations. The output has the same shape as the input.

source

VineCopulas.rosenblatt! Function

rosenblatt!(out, vine, U)

In-place Rosenblatt transform. out and U must have the same p × n shape.

source

Copulas.inverse_rosenblatt Function

inverse_rosenblatt(vine, z; fixed=nothing)
inverse_rosenblatt(vine, Z; fixed=nothing)

Apply the inverse Rosenblatt transform. This maps independent uniforms on the unit hypercube into observations from the vine copula. Matrix inputs and outputs use the p × n convention.

With fixed = (js, Ujs) the coordinates js are not generated from Z: their raw uniforms are taken from Ujs (a length(js) × n matrix, or a tuple or vector of length(js) scalars broadcast over every column) and only the remaining coordinates are generated, each conditionally on the fixed block and on the coordinates generated before it. Every value of Ujs must lie in [0, 1], or an ArgumentError is thrown, and it is validated before any numerical helper sees it. The rows js of the result hold the supplied values exactly; a boundary value 0 or 1 conditions the recursion at the nearest interior floating-point number, which is the limit of the conditional law at that edge. The rows Z[js, :] are ignored, so an unconditional Z can be passed unchanged. The result is an exact draw from the conditional copula   whenever admits_conditioning(vine, js) is true, which is the case when js heads a sampling order of the vine. Otherwise an ArgumentError names the fit-side option that makes the predicate true. A js => Ujs pair is accepted in place of the tuple.

source

VineCopulas.inverse_rosenblatt! Function

inverse_rosenblatt!(out, vine, Z; fixed=nothing)

In-place inverse Rosenblatt transform. out and Z must have the same p × n shape. fixed has the same meaning as in inverse_rosenblatt.

source

VineCopulas.admits_conditioning Function

admits_conditioning(vine, js) -> Bool

Whether fixing the coordinates js admits an exact conditional draw of the remaining coordinates through the vine's own sampling recursion, that is, whether js heads a sampling order of vine.

The inverse Rosenblatt transform generates the coordinates one at a time, each conditionally on the ones generated before it. When the fixed set is exactly the first length(js) coordinates that recursion generates, seeding them with known values and generating the rest gives an exact sample from   at the cost of an unconditional rand. For a DVineCopula this holds when js sits at either end of the path order(vine); for a CVineCopula when js is the first length(js) roots of order(vine); for a standard RVineCopula when js is the tail of order(vine), which fit(RVineCopula, U; sampling_tail=js) arranges whenever the selected trees allow it. The order of the labels inside js does not matter.

When the predicate is false, rand(vine, n; fixed=(js, Ujs)) refuses with an ArgumentError rather than returning an approximate draw.

source

Model summaries

VineCopulas.loglikelihood Function

loglikelihood(vine, u)
loglikelihood(vine, U)

Return the log-density at a single point or the summed log-likelihood over a p × n matrix of observations.

source

VineCopulas.npars Function

npars(C)
npars(vine)

Return a lightweight structural parameter count. For pair-copulas this uses Distributions.params when available. For vines it sums over all active edges.

source

VineCopulas.aic Function

aic(vine, U)

Compute Akaike's information criterion for an explicit vine and a p × n data matrix on the copula scale.

source

VineCopulas.bic Function

bic(vine, U)

Compute the classical Bayesian information criterion for an explicit vine and a p × n data matrix on the copula scale.

source