pyvinecopulib

Introduction

What are vine copulas?

Sklar’s theorem factorises every joint distribution into one-dimensional marginals and a copula that carries the dependence between variables. A vine copula decomposes that copula into bivariate building blocks — pair copulas — arranged on a sequence of trees called an R-vine (Bedford & Cooke, 2002; Aas et al., 2009). The decomposition makes pair-by-pair estimation scale gracefully into high dimensions and gives a natural place to drop in non-parametric pair-copula estimators like Transformed Local Likelihood (TLL).

A short primer is available on the concepts page; a comprehensive list of publications lives on vine-copula.org.

What is pyvinecopulib?

pyvinecopulib is the Python interface to vinecopulib, a header-only C++ library for vine copula models based on Eigen. It provides high-performance implementations of the core features of the popular VineCopula R library, in particular inference algorithms for both vine copula and bivariate copula models. Advantages over VineCopula are

a stand-alone C++ library with interfaces to both R and Python,
a sleeker and more modern API,
shorter runtimes and lower memory consumption, especially in high dimensions,
nonparametric and multi-parameter families.

Optional backends

Two opt-in subpackages extend the core library:

pyvinecopulib.sklearn — scikit-learn-compatible estimators (VineDensity, VineRegressor, plus forest variants). Drop a vine into any sklearn pipeline:
```
from pyvinecopulib.sklearn import VineDensity
density = VineDensity().fit(X)             # default backend (C++)
density.score_samples(X[:3]); density.cdf(X[:3])
```
Install with pip install pyvinecopulib[sklearn].

pyvinecopulib.torch — pure-PyTorch evaluators (TorchBicop, TorchVinecop) for GPU placement and autograd:

from pyvinecopulib.sklearn import VineDensity
from pyvinecopulib.sklearn.backends import TorchVinecopBackend
from pyvinecopulib.torch import FitControlsTorchVinecop
controls = FitControlsTorchVinecop(device="cuda")
density_gpu = VineDensity(backend=TorchVinecopBackend(controls=controls)).fit(X)

Install with pip install pyvinecopulib[torch].

Custom and conditional pair copulas

The core evaluators (Bicop / Vinecop, and their torch counterparts) implement two backend-neutral contracts, BicopLike and VinecopLike. Subclass the canonical, pure-Python BicopBase / VinecopBase (NumPy or PyTorch) to plug your own pair copula into a vine — including non-simplified vines where each pair copula conditions on its conditioning set. See the concepts page and the examples/11_extending_pyvinecopulib.ipynb notebook.

License

pyvinecopulib is provided under an MIT license that can be found in the LICENSE file. By using, distributing, or contributing to this project, you agree to the terms and conditions of this license.

Contact

If you have any questions regarding the library, feel free to open an issue or send a mail to info@vinecopulib.org.

Installation

With pip

The latest release can be installed using pip:

pip install pyvinecopulib

With conda

Similarly, it can be installed with conda:

conda install conda-forge::pyvinecopulib

Or with mamba:

mamba install conda-forge::pyvinecopulib

From source

Start by cloning this repository, noting the --recursive option which is needed for the vinecopulib, wdm, and kde1d submodules:

git clone --recursive https://github.com/vinecopulib/pyvinecopulib.git
cd pyvinecopulib

The main build time prerequisites are:

scikit-build-core (>=0.5.0),
nanobind (>=2.7.0),
libclang (>=18) — used to regenerate src/include/docstr.hpp from the C++ headers as a step of the build,
numpy / matplotlib / networkx — imported by the post-build stub-generation step,
a compiler with C++17 support.

When installing via pip install . (the default), all of these are pulled into an isolated build environment automatically via [build-system] requires in pyproject.toml; you don’t need to install them yourself.

To install from source, Eigen and Boost also need to be available, and CMake will try to find suitable versions automatically.

The recommended way to install pyvinecopulib from source is to use conda/mamba for the native build prerequisites and uv for the Python side:

mamba create -n pyvinecopulib python=3.11 boost eigen 'python-clang=18.*' uv
mamba activate pyvinecopulib
make sync

See the contributing guide for the full developer workflow.

Alternatively, you can specify manually the location of Eigen and Boost using the environment variables EIGEN3_INCLUDE_DIR and Boost_INCLUDE_DIR respectively. On Linux, you can install the required packages and set the environment variables as follows:

sudo apt-get install libeigen3-dev libboost-all-dev
export Boost_INCLUDE_DIR=/usr/include
export EIGEN3_INCLUDE_DIR=/usr/include/eigen3

Finally, you can build and install pyvinecopulib using pip:

pip install .

The build automatically regenerates src/include/docstr.hpp (from the C++ headers via libclang) and src/pyvinecopulib/__init__.pyi (from the freshly built extension). Both files are gitignored — they’re pure build artifacts.

For an editable install (recommended for development), use --no-build-isolation so the conda env’s libclang is reused and editable.rebuild = true regenerates everything on each import:

pip install -e . --no-build-isolation

Documentation

Stable docs are published at https://pyvinecopulib.readthedocs.io. They are rebuilt automatically by Read the Docs whenever a new release is tagged on main and published to PyPI.

To build the documentation locally:

make docs           # one-shot HTML build → docs/_build/html/
make docs-serve     # live-reload dev server (sphinx-autobuild)

Contributing

Development setup, the build pipeline, the Makefile + pre-commit conventions, the CI workflow, and the release flow are all documented in the contributing guide.