pyscarcopula

A Python library for dynamic copula modelling: bivariate, multivariate, vine, and stochastic copula models for financial time series and risk analytics.

• About
• Install
• Quick start
• Features
• Mathematical background
• Examples and docs
• License

About

pyscarcopula fits bivariate and multivariate dependence models using copulas in Python. Alongside classical constant-parameter copulas, it supports stochastic copula autoregressive (SCAR) models where the copula parameter is driven by a latent Ornstein-Uhlenbeck process or Kendall's tau follows a bounded Jacobi diffusion.

The package is aimed at financial time series, risk modelling, and experiments with dynamic dependence. It provides bivariate copulas, C-vines, R-vines, conditional sampling, prediction, goodness-of-fit diagnostics, and risk metrics.

Supported estimation methods:

Install

pip install pyscarcopula

Official wheels include the compiled numerical extension and do not need a local compiler. Source and editable installs require a C++17 compiler:

• Windows: Microsoft C++ Build Tools / Visual Studio Build Tools, or MinGW-w64 GCC (see below)
• Linux: GCC or Clang with the usual Python development headers
• macOS: Xcode Command Line Tools

On Windows, a MinGW-w64 GCC toolchain (for example the MSYS2 ucrt64 GCC) can be used instead of the Microsoft compiler by opting in explicitly:

PYSCA_CPP_COMPILER=mingw32 pip install .
# or, from the source tree:
python setup.py build_ext --compiler=mingw32 --inplace

The GCC runtime is linked statically, so the resulting extension does not need MSYS2 DLLs at runtime. MSVC remains the default Windows toolchain.

For local development:

git clone https://github.com/AANovokhatskiy/pyscarcopula
cd pyscarcopula
pip install -e ".[test]"

To run the full test suite from the source tree, build the C++ extension in place first:

python setup.py build_ext --inplace
pytest --run-validation

pytest --run-validation enables optional validation tests. A source checkout without a successfully built extension is incomplete for the default bivariate GAS workflow.

The default command uses one pytest worker and runs tests sequentially. To run independent test modules on an explicit number of CPU cores, pass that number to pytest-xdist:

pytest -n 4 --run-validation

The repository configures xdist's loadscope scheduler, so tests within one module remain sequential while separate modules can run concurrently. Use an explicit core count rather than -n auto for reproducible resource usage.

Timing gates compare relative speedups or overhead ratios; absolute seconds are report-only. Opt-in benchmarks may run through xdist like the rest of the suite:

PYSCA_RUN_BENCHMARKS=1 pytest -n 10 -m benchmark

CPU placement remains under operating-system control. Relative alternatives are measured in paired, interleaved rounds so scheduler migration or transient load cannot systematically put the complete baseline and candidate phases on different classes of CPU core.

Validation and optional external groups use the same parallel runner:

pytest -n 10 --run-validation -m validation
pytest -n 10 --run-validation -m external  # requires .[external]

loadscope intentionally keeps cases from one test module sequential. In particular, alternatives inside one relative benchmark must not execute at the same time, and the release/equicorrelation report writers use one shared JSON artifact per module. Their modules still run concurrently with other modules.

Optional benchmark and large validation checks are disabled by default. Enable them explicitly:

PYSCA_RUN_BENCHMARKS=1 \
PYSCA_RUN_LARGE_BENCHMARKS=1 \
PYSCA_RUN_VINE_BENCHMARKS=1 \
pytest tests --run-validation

On Windows PowerShell:

$env:PYSCA_RUN_BENCHMARKS = "1"
$env:PYSCA_RUN_LARGE_BENCHMARKS = "1"
$env:PYSCA_RUN_VINE_BENCHMARKS = "1"
pytest tests --run-validation

Conditional sampling has separate PR, distributional, nightly external/d=50, and manual benchmark layers. See the conditional sampling validation guide for exact marker selections, oracle-only calibration, artifacts, and failure triage.

Core dependencies: numpy, numba, scipy, joblib, tqdm.

Verify the compiled extension with:

python -m pyscarcopula._native_smoke

Quick start

pyscarcopula expects a two-dimensional array with observations in rows and variables in columns. Copula fitting uses pseudo-observations in the open unit interval. Pass existing pseudo-observations directly, as below, or use to_pobs=True to rank-transform raw continuous observations during fitting.

import numpy as np

from pyscarcopula import GumbelCopula

rng = np.random.default_rng(2026)
source = GumbelCopula(rotate=180)
u = source.sample_at_parameter(
    400,
    r=np.full(400, 1.8),
    rng=rng,
)

model = GumbelCopula(rotate=180)
result = model.fit(u, method="mle")
forecast = model.predict(1_000, rng=np.random.default_rng(2027))

print(result.log_likelihood)
print(forecast.shape)  # (1000, 2)

The fitted result is returned by fit and also stored as model.fit_result. sample(...) reproduces the fitted model, while predict(...) draws from its predictive distribution; this distinction matters for dynamic models. See the complete Quick Start and Prediction Semantics.

Choose the model surface before tuning an estimation method:

See Choosing a Model for the corresponding correlation modes, estimation methods, and limitations.

Features

Vine copulas

VineCopula is the primary API for regular vines. Omitting structure selects an R-vine from data; C-vines and D-vines are fixed RVineMatrix structures:

import numpy as np

from pyscarcopula import VineCopula

rng = np.random.default_rng(2028)
vine_data = rng.random((400, 4))

# Data-driven regular vine
auto = VineCopula().fit(vine_data, method="mle")

# Fixed standard structures
c_vine = VineCopula.cvine(d=4).fit(vine_data, method="mle")
d_vine = VineCopula.dvine(d=4).fit(vine_data, method="mle")

For an arbitrary valid regular-vine tree sequence, construct RVineMatrix.from_trees(...) and pass it as VineCopula(structure=...). The Vine guide defines the decoded tree format and explains family selection, truncation, and conditional sampling.

Use vine.structure for the RVineMatrix and vine.natural_order_matrix when an integration specifically needs the natural-order runtime matrix. vine.matrix is a compatibility property. The raw pyvinecopulib matrix uses one-based labels and the opposite tree-level order above each anti-diagonal entry, so it is not obtained by simply adding one. See the matrix-layout conversion.

Copula families

• Archimedean: Gumbel, Frank, Clayton, Joe, including rotations where supported
• Elliptical: Gaussian and Student-t
• Independence copula for null models and vine pruning
• Multivariate Gaussian, Student-t, equicorrelation, and stochastic Student models
• Shared APIs for bivariate, multivariate, and vine models

Vine copulas

• One VineCopula runtime for auto-selected and fixed regular vines
• Fixed C-vine and D-vine factories backed by RVineMatrix
• Arbitrary valid structures built from decoded tree edges
• Automatic family and rotation selection per edge using AIC/BIC
• Tree-level and edge-level truncation
• Mixed MLE, SCAR, GAS, and independence edges within one vine

Sampling and prediction

• Unconditional sampling from fitted bivariate, multivariate, and vine models
• Conditional sampling for static and dynamic multivariate models and R-vines
• Exact and approximate conditional modes for R-vines
• PredictConfig for explicit prediction options
• Reproducible random generation via rng
• JSON persistence through model.save() and ModelClass.load() (include_data=False can omit stored training data)

Diagnostics and risk

• Rosenblatt-transform based goodness-of-fit tests
• Mixture Rosenblatt transform for stochastic models
• Predictive time-varying copula parameter paths
• VaR and CVaR utilities in pyscarcopula.contrib

CPU parallelism

• Explicit native threading for eligible multivariate row, emission, conditional-sampling, static-likelihood, and Monte Carlo kernels
• Process-level fit_independent and rolling risk_metrics execution
• Absolute one-thread default: omitted n_threads always means 1, regardless of environment variables
• Dependency-free C++17 linear algebra without hidden BLAS or OpenMP pools

Mathematical background

By Sklar's theorem, a joint distribution can be represented as

F(x_1, \ldots, x_d) = C(F_1(x_1), \ldots, F_d(x_d)),

where C is a copula and F_i are marginal distributions. This separates marginal modelling from dependence modelling.

For a one-parameter Archimedean copula with generator phi,

C(u_1, \ldots, u_d; \theta)
  = \phi^{-1}(\phi(u_1; \theta) + \cdots + \phi(u_d; \theta)).

In SCAR models the copula parameter is time-varying:

\theta_t = \Psi(x_t),
\qquad
dx_t = \kappa(\mu - x_t)dt + \nu dW_t,

where x_t is a latent Ornstein-Uhlenbeck process and Psi maps the latent state to the valid parameter domain. scar-tm-jacobi instead evolves Kendall's tau directly with a bounded Jacobi diffusion and maps tau back to the copula parameter for families that implement tau_to_param.

The transfer matrix method evaluates the latent-state likelihood by exploiting the Markov structure of the latent process. The path integral is computed as a sequence of matrix-vector products on a discretized grid or spectral basis, avoiding Monte Carlo variance at the cost of numerical approximation.

For SCAR-TM-OU, transition_method='auto' uses a hybrid deterministic strategy: Hermite spectral evaluation where it is reliable, matrix-based transition evaluation for regimes better handled on a grid, and local Gauss-Hermite in narrow-kernel OU cases. In broad terms, this keeps the latent path integral as repeated deterministic linear-algebra updates while choosing the most suitable transition representation automatically. See docs/guide/performance.md for the details and the available transition_method values.

result = fit(copula, u, method="scar-tm-ou")

result = fit(copula, u, method="gas")

Use the default scaling="unit" for production. scaling="fisher" remains an experimental, numerically sensitive mode.

See docs/guide/performance.md for supported families and numerical options.

Vine copulas decompose a d-dimensional dependence model into bivariate copulas arranged in a sequence of trees. VineCopula() selects a regular-vine structure from data subject to the proximity condition. VineCopula.cvine(...) and VineCopula.dvine(...) use fixed standard structures, while VineCopula(structure=RVineMatrix.from_trees(...)) accepts an arbitrary valid decoded tree sequence.

Examples and docs

Worked notebooks are available in examples/:

• 01_basic_api.ipynb
• 02_bivariate.ipynb
• 03_multivariate.ipynb
• 04_vine.ipynb
• 05_risk_metrics.ipynb
• 06_pyvinecopulib_comparison.ipynb

Additional documentation is in docs/. Estimation methods are described in docs/guide/estimation-methods.md, and performance-related details are kept in docs/guide/performance.md. CPU threading, process workers, thread safety, and scaling limits are documented in docs/guide/parallelism.md. Release history is in CHANGELOG.md.

License

MIT License. See LICENSE.txt.

Contacts

Contact me for any questions or discussion aanovokhatskiy@gmail.com