pyscarcopula
A Python library for dynamic copula modelling: bivariate, multivariate, vine, and stochastic copula models for financial time series and risk analytics.
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:
| Method | Key | Description |
|---|---|---|
| Maximum likelihood | mle |
Static/constant model parameters |
| SCAR transfer matrix | scar-tm-ou |
Deterministic OU latent-state likelihood |
| SCAR Jacobi transfer matrix | scar-tm-jacobi |
Deterministic Kendall-tau diffusion likelihood |
| GAS | gas |
Observation-driven score model |
Install
pip install pyscarcopula
For source and editable builds, compiler selection, testing, benchmarks, and documentation builds, see the installation guide.
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:
| Task | Start with |
|---|---|
| Two-variable dependence | GumbelCopula, ClaytonCopula, FrankCopula, JoeCopula, or BivariateGaussianCopula |
| Static unrestricted multivariate dependence | GaussianCopula or StudentCopula |
| Scalar dynamic multivariate dependence | EquicorrGaussianCopula or StochasticStudentCopula |
| Flexible high-dimensional pair decomposition | VineCopula |
See Choosing a Model for the corresponding correlation modes, estimation methods, and limitations.
Features
The library covers bivariate, multivariate, factor, and vine copulas. See the documentation for estimation methods, sampling and prediction, diagnostics, and CPU parallelism.
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 and 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 it to the
valid parameter domain. The Jacobi variant models Kendall's tau with a bounded
diffusion. Deterministic likelihood evaluation uses grid, spectral, or local
quadrature backends.
For derivations and parameter mappings, see Mathematical Contracts. Implementation and grid details are covered by Numerical Backends, with practical choices summarized in Performance Tuning.
Examples and docs
Worked notebooks are available in examples/:
01_basic_api.ipynb02_bivariate.ipynb03_multivariate.ipynb04_vine.ipynb05_risk_metrics.ipynb06_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
1 maintainer
Metadata
1 maintainer
Release files for pyscarcopula 0.22.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pyscarcopula-0.22.1.tar.gz | 1.6 MB | Details |
Built distributions (wheels)
Total release size: 34.6 MB
Release files / pyscarcopula-0.22.1.tar.gz
| Download URL | pyscarcopula-0.22.1.tar.gz |
|---|---|
| Size | 1.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
22c664465713ea5e9fe1fe8f5c6ac9edcf7831398f875d2009ba8de85575f8df
|
|
BLAKE2b-256 checksum How to use checksums |
4c8efa3388998db17c4480ac416ccb005833e2c70aa6d872e368fd10bd7d3a9c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp314-cp314-win_amd64.whl
| Download URL | pyscarcopula-0.22.1-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
c52012acfafaf7c0ecf7a9e87827361cf2f7bec44418e3968a9278d77dbccc14
|
|
BLAKE2b-256 checksum How to use checksums |
b27dc957dda76171b181fc80c9f40f57d02ba28d058c472a269475af7ba8dee9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pyscarcopula-0.22.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.14 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
0d405879cd3c7bda22e7ba6a59ebc0d1b5d2908ab822e5b1625f65324283295b
|
|
BLAKE2b-256 checksum How to use checksums |
862a06bb739497ae68f3039cade56e43b5c686eb2a94520fc0f7b5deb516678a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | pyscarcopula-0.22.1-cp314-cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.14 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
bf473cefc6dc6d6f9a8b4708692ee6d42bddf6d380c218d6ffdf66f77591b7f8
|
|
BLAKE2b-256 checksum How to use checksums |
1073903ed7722521fe7b483dc675bce07cb01df5611429d909aa080b3d3e9ed1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp314-cp314-macosx_10_15_x86_64.whl
| Download URL | pyscarcopula-0.22.1-cp314-cp314-macosx_10_15_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.14 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
a9b20a324f3f6a89dabcaa9ce18ddb265c9106d7c070db6e56c7dcf76e57f414
|
|
BLAKE2b-256 checksum How to use checksums |
788493ff8725f6b07a791e8dd9a1568866b7cb231bdcc2b80c71982a68ba5555
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp313-cp313-win_amd64.whl
| Download URL | pyscarcopula-0.22.1-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.3 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
4051fc54c7ab146dbe5bd2486081b140d53eacfbff358444c1d4d22410cb4d83
|
|
BLAKE2b-256 checksum How to use checksums |
3580b6c364d1cc26687ef0e6d5ea85591fdaee83b67145064112d5f2a91d4efd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pyscarcopula-0.22.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
ded877b8c077d07c53ee20a839b8423ccc23ecb7e99f1d9470899ead98200f9c
|
|
BLAKE2b-256 checksum How to use checksums |
a40b31704626cb7d20e5e48ab2dda8ba1b0859c2b68f233e88e0b26b6a192622
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | pyscarcopula-0.22.1-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
95cfaefadd87dfa6d427d6a774efc8780f07f039ad9af84cb5dc849ba8aebd75
|
|
BLAKE2b-256 checksum How to use checksums |
6e508852b10ce9327886751089d263270ced2b704c7bd344a3c798cd1354ed83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp313-cp313-macosx_10_13_x86_64.whl
| Download URL | pyscarcopula-0.22.1-cp313-cp313-macosx_10_13_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
2b8a81703d3dd7873c1728a95c2ce9bba5d957d4d4796d0fd05acc97a09df180
|
|
BLAKE2b-256 checksum How to use checksums |
35c5f9906ee8ef82d461723b5925c5bfdbe5b27197c5f2b4720d9c713681f203
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp312-cp312-win_amd64.whl
| Download URL | pyscarcopula-0.22.1-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.3 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
e45da74a9c2b7a9dd4c011240008764d7c8f20315bfd004e0116749534b5e305
|
|
BLAKE2b-256 checksum How to use checksums |
c0573498fd26bcb89350c5df7d8f0d3db90d4e3573ec355c0dd31c63d28cffdd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pyscarcopula-0.22.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
9db23b2da7e8ba7d0c054aa9bb44f61cd4d5eb4a492f2d12746fa267b4246ede
|
|
BLAKE2b-256 checksum How to use checksums |
63b978cbd3cb59965b7f61cf6f2c302de5e4e9ea1070f58b19f3eff803a2835f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | pyscarcopula-0.22.1-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ce5f9e9267acf22939d4699bb7c6a3e047f06f2f487e3657ced547221bf861a3
|
|
BLAKE2b-256 checksum How to use checksums |
19674089d5c51768647e406ff0aa8591b1eee55b38ba91271ed5ee039b77a8a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp312-cp312-macosx_10_13_x86_64.whl
| Download URL | pyscarcopula-0.22.1-cp312-cp312-macosx_10_13_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
ed169aff915e6f249dcb49585390768a1bc33f5d6e4f87bda272dd6e96e95305
|
|
BLAKE2b-256 checksum How to use checksums |
87ba95f9956566aa6c4aa928bde046615a67526d2cc7551cb90ec071c3e02a9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp311-cp311-win_amd64.whl
| Download URL | pyscarcopula-0.22.1-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.3 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
484273eab5defc962f2a17c7d4b93ae4b237a200ab85e380abfed1a5e4486ee2
|
|
BLAKE2b-256 checksum How to use checksums |
cc5309c7ce0d3a3802d7b74fbed1f95b086c97578905ccfa5a296df878e7cab2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pyscarcopula-0.22.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
a4a879e23bff7cc7638c3c02738cb61d85f03e0051066eaa048269f149422cf7
|
|
BLAKE2b-256 checksum How to use checksums |
9dee8ddf65dc72dbc325c3ec1ea61fe5f161b61693e74a1ed67aeddbd4dabb3e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | pyscarcopula-0.22.1-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
61a6aba14c82ef69de2d63f2962709be9677444dcc118803d67c538427014c19
|
|
BLAKE2b-256 checksum How to use checksums |
39e3e785f689cfd1f6d84b08ceb10a49f49d3ce6a3d5d176c3f93865b20f1305
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp311-cp311-macosx_10_9_x86_64.whl
| Download URL | pyscarcopula-0.22.1-cp311-cp311-macosx_10_9_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
3c3d91f37b54e2598012f6f7ed2a429b33e5822d9ba15a9885619dde1ce01181
|
|
BLAKE2b-256 checksum How to use checksums |
a5e38721ff62b1c61a02a3beced316519a868db357eb90676517c9a873b50461
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp310-cp310-win_amd64.whl
| Download URL | pyscarcopula-0.22.1-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.3 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
66205e27dd5ae6fb8b1e0e13fbaf73e10b045e9a2dd92da306b5a6293771494e
|
|
BLAKE2b-256 checksum How to use checksums |
f9752f40fd6af61c9c8a51d20c250b252fc920d6413228ac0ecf41c0de7e4c32
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pyscarcopula-0.22.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
86c20544c3129156e5f2a9e0ac0504e16355ee61d3fca98f2fad83caeb81c045
|
|
BLAKE2b-256 checksum How to use checksums |
d0c830ec4f97e42240e5cf1cf3d127704b9a489ccb75c908e5a328742455fcd7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | pyscarcopula-0.22.1-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
46ddf05e2b655f3952749dc79c7feb0e94cfce32a389203d7eb3ae21ae83bc34
|
|
BLAKE2b-256 checksum How to use checksums |
9acfedfb1e92174a567bba1df9838f5cd60ba78266535bf1835255edd93636c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscarcopula-0.22.1-cp310-cp310-macosx_10_9_x86_64.whl
| Download URL | pyscarcopula-0.22.1-cp310-cp310-macosx_10_9_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
29bca924f54032451f7bec1c3fc4ce61f75601206fcae4025fb4f5cf52e353ae
|
|
BLAKE2b-256 checksum How to use checksums |
88c56f1a2961c22d9ee3bccc93614d5fe39615be8a626c4809f5f38b6bd078f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
