pyvinecopulib

pyvinecopulib

Introduction

What are vine copulas?

Vine copulas are a flexible class of dependence models consisting of bivariate building blocks (see e.g., Aas et al., 2009). You can find a comprehensive list of publications and other materials 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 sleaker and more modern API,
• shorter runtimes and lower memory consumption, especially in high dimensions,
• nonparametric and multi-parameter families.

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 [e-mail].

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

The main build time prerequisites are:

• scikit-build-core (>=0.4.3),
• nanobind (>=2.5.0),
• a compiler with C++17 support.

To install from source, Eigen and Boost also need to be available, and CMake will try to find suitable versions automatically. A reproducible environment, also including requirements for the pyvinecopulib's development and documentation, can be created using:

mamba create -n pyvinecopulib eigen boost nanobind scikit-build-core numpy pydot networkx matplotlib mypy ruff pytest sphinx-rtd-theme sphinx-autodoc-typehints nbsphinx myst-parser python=3.11
mamba activate pyvinecopulib

You can also specify the location if Eigen and Boost manually 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

Then, just clone this repository and do pip install. Note the --recursive option which is needed for the vinecopulib and wdm submodules:

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

Building the documentation

Documentation for the example project is generated using Sphinx and the "Read the Docs" theme. The following command generates HTML-based reference documentation; for other formats please refer to the Sphinx manual:

• pip install sphinx-rtd-theme sphinx-autodoc-typehints nbsphinx recommonmark
• cd pyvinecopulib/docs
• python serve_sphinx.py