[ANN] VineCopulas.jl: C-vines, D-vines, and experimental R-vines in Julia

Package Announcements
, , , ,
1

Hi everyone,

I’m happy to announce that VineCopulas.jl is now registered in the Julia General registry.

VineCopulas.jl is a pure-Julia package for explicit vine copula models, built on top of Copulas.jl. The current release focuses on constructing vine copulas from bivariate pair-copulas, evaluating densities, simulating observations, and working with Rosenblatt and inverse Rosenblatt transforms.

Package installation:

using Pkg
Pkg.add("VineCopulas")

Documentation:

Repository:

The current version includes:

  • stable CVineCopula and DVineCopula model types;
  • experimental RVineCopula support for explicit structures;
  • pdf, logpdf, rand, numerical cdf, and simulate_qmc;
  • Rosenblatt and inverse Rosenblatt transforms;
  • truncated C-vines and D-vines;
  • pair-copula conditional primitives: hfunc1, hfunc2, hinv1, and hinv2;
  • model summaries such as loglikelihood, npars, aic, and bic;
  • reproducible benchmark and validation scripts against rvinecopulib.

This is an early release, so feedback, bug reports, suggestions, and contributions are very welcome.

One important note: VineCopulas.jl is currently focused on explicit vine construction and simulation/transform workflows. It does not yet provide automatic structure selection, family selection, or parameter estimation. These are planned for future versions.

Thanks to the Julia copula ecosystem, especially Copulas.jl, which made it much easier to build this package in a modular way.

2

What a large effort, GG @Santymax98 !

I will be taking a look as soon as I can :slight_smile:

3

Thank you @lrnv! I really appreciate it.

Any comments, suggestions, or feedback would be very welcome once you have the chance to take a look :grin::grin:

4

This is awesome, i’ve been waiting for something like this to implement synthetic data priors for PortfolioOptimisers.jl

Looks like there are plans to fit parameters and select copula families/dependence structure so I’ll hold off on it until then.

Also, sick logo, what did you use to design it?

5

Thanks a lot! I really appreciate the kind words.

That sounds like a very nice use case. I’m actually already working on the first tests for parameter fitting, family selection, and dependence-structure selection, with quite promising results so far. I’m also trying to optimize things as much as possible, because I’d like VineCopulas.jl to be competitive and genuinely useful in practice.

And thanks about the logo! I made it in Canva :rofl::rofl:

I’m not a great designer but Canva with AI is very util and intuitive…

6

Hi Santy, has there been much progress on this front? I’m chomping at the bit at finally having this functionality, and already thinking of all the other features it would unlock. Especially with the help of a clanker or two.

8

Hi! Yes — there has actually been quite a bit of progress on that front. We now have a much cleaner fitting/selection interface taking shape, and I’m finishing up the first usable version before pushing it to the repository.

The idea is that you’ll be able to go essentially from data to a fitted vine without having to manually specify every pair-copula: parameter estimation, family selection, and eventually the dependence structure itself will be handled by the fitting layer. Once fitted, it will integrate directly with the existing simulation interface, so generating synthetic samples should be straightforward :grinning_face_with_smiling_eyes:

9

I’m having a hard time understanding what vine copulas are and how I can use them. This seems to be a tool only used by statisticians, but since I am already using Copulas.jl in engineering I would like to also explore this. Any reference you can recommend?

11

Thanks for asking! I think this is actually a sign that I should add a more intuitive introduction to the docs :sweat_smile:

The basic idea is that vine copulas let you build a flexible multivariate dependence model from bivariate copulas. Instead of assuming one copula family describes the dependence among all variables, different pairs (including conditional relationships) can use different families. This is particularly useful when dependencies have different asymmetries or tail behavior.

A great starting point is Aas et al. (2009), “Pair-copula constructions of multiple dependence.” For a more complete treatment, I’d recommend Claudia Czado’s Analyzing Dependent Data with Vine Copulas.

Since you’re already using Copulas.jl in engineering, I’d also be very interested to hear about your use case it might actually make a nice practical example for the VineCopulas.jl docs.

12

That all but nullifies most of the work i was planning on doing. It’s essentially gonna be plug and play. That’s sick.

I shall sit here with my mouth shut and wait.

13

Cool! That does seem very useful :slight_smile:

I’m modelling power systems with significant penetration of renewables. In such systems, the output of adjacent wind or solar farms are strongly correlated. One way to describe that correlation is using Copulas.jl :slight_smile: Here’s a transactions paper on the topic: https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=8004519

14

Haha, you can stop waiting now :grinning_face_with_smiling_eyes:

VineCopulas.jl v0.1.2 is now registered and available.

The fitting/selection layer is in: pair-copula parameter estimation, automatic family and rotation selection, and automatic C-vine, D-vine, and R-vine structure selection are now part of the public API.

Fitted vines integrate directly with the existing simulation interface, so the workflow you had in mind for synthetic priors should now be much closer to plug-and-play.

I also spent some time improving the internals before releasing it — in particular reducing allocations, fusing pair-copula evaluation kernels, and speeding up Student-t conditionals.

I’d really like to see how it behaves inside PortfolioOptimisers.jl. If you run into anything awkward in the API or anything missing for that use case, please open an issue — that kind of downstream integration is exactly what I want to support.

15

Thanks, this is actually a really nice use case — and thanks for sharing the paper :slightly_smiling_face:

The multi-site wind/solar setting seems like a very natural application for vine copulas, especially when different pairs may have different dependence or tail behaviour.

With VineCopulas.jl v0.1.2, the workflow could now be roughly:

historical renewable outputs → fitted vine → correlated scenarios → power-system model

If you have a public dataset or a representative example, I’d be very interested in trying to build a small documentation example around it.

16

Quick update: VineCopulas.jl v0.1.2 is now available :tada:

Since the original announcement, the package has grown quite a bit. The public API now includes:

  • pair-copula parameter fitting,
  • automatic family and rotation selection,
  • automatic structure selection for C-vines, D-vines, and general R-vines.

So you can now go from pseudo-observations to a fitted vine model directly, and then reuse that model for simulation and downstream workflows.

For example:

model = fit(
    RVineCopula,
    U;
    family_set = :default,
    selection_criterion = :bic,
    tree_criterion = :tau,
    tree_algorithm = :kruskal,
)

Unew = rand(model, 10_000)

Internally, v0.1.2 also includes a fair amount of performance work:

  • fused pair-copula kernels,
  • reusable work buffers in vine traversals,
  • generic fallback through Copulas.condition,
  • and substantially faster Student-t conditional evaluation.

So this release is not only broader in functionality, but also noticeably better on the performance side.

A few people in this thread mentioned interesting downstream applications — such as portfolio optimisation and renewable-power dependence modelling — and I’d be very happy to hear how the package behaves in those settings.

As always, feedback, issues, and suggestions are very welcome.

17

This is awesome. I was looking at the docs and haven’t seen anything regarding conditional simulation. That’s pretty important for stress testing extreme scenarios. For example once you have a fitted model, produce a simulation where variable (or variables) i \in (a, b), or i \gtreqless a, where a could be a scalar or a vector (thus letting users define disjoint sets with regions without samples for variable i), for an arbitrary number of constraints. This would generate pseudo observations matching the dependence structure under those constraints.

This is probably the best example i’ve seen. It has a high level API, but as long as there is a low level (index based) api that can constrain and define/find variables as central, then a high level wrapper can me made. They also have other interesting additions like extra dependence structures and inference methods.

This extra capability wouldn’t only have portfolio optimisation as potential applications, but any sort of extreme scenario simulation where complex interactions are in place. Disaster modelling comes to mind, “what if rainfall is x times greater than the mean”, or “what if the part’s failure rate is 5 times greater than anticipated” kind of model.

I think having something like this could make VineCopulas.jl the go-to for this type of work.