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:

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/:

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyscarcopula-0.22.0.tar.gz (1.5 MB view details)

Uploaded Sep 6, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pyscarcopula-0.22.0-cp314-cp314-win_amd64.whl (1.3 MB view details)

Uploaded Sep 6, 2026 CPython 3.14Windows x86-64

pyscarcopula-0.22.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.0 MB view details)

Uploaded Sep 6, 2026 CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

pyscarcopula-0.22.0-cp314-cp314-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded Sep 6, 2026 CPython 3.14macOS 11.0+ ARM64

pyscarcopula-0.22.0-cp314-cp314-macosx_10_15_x86_64.whl (1.7 MB view details)

Uploaded Sep 6, 2026 CPython 3.14macOS 10.15+ x86-64

pyscarcopula-0.22.0-cp313-cp313-win_amd64.whl (1.3 MB view details)

Uploaded Sep 6, 2026 CPython 3.13Windows x86-64

pyscarcopula-0.22.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.0 MB view details)

Uploaded Sep 6, 2026 CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

pyscarcopula-0.22.0-cp313-cp313-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded Sep 6, 2026 CPython 3.13macOS 11.0+ ARM64

pyscarcopula-0.22.0-cp313-cp313-macosx_10_13_x86_64.whl (1.7 MB view details)

Uploaded Sep 6, 2026 CPython 3.13macOS 10.13+ x86-64

pyscarcopula-0.22.0-cp312-cp312-win_amd64.whl (1.3 MB view details)

Uploaded Sep 6, 2026 CPython 3.12Windows x86-64

pyscarcopula-0.22.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.0 MB view details)

Uploaded Sep 6, 2026 CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

pyscarcopula-0.22.0-cp312-cp312-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded Sep 6, 2026 CPython 3.12macOS 11.0+ ARM64

pyscarcopula-0.22.0-cp312-cp312-macosx_10_13_x86_64.whl (1.7 MB view details)

Uploaded Sep 6, 2026 CPython 3.12macOS 10.13+ x86-64

pyscarcopula-0.22.0-cp311-cp311-win_amd64.whl (1.3 MB view details)

Uploaded Sep 6, 2026 CPython 3.11Windows x86-64

pyscarcopula-0.22.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.0 MB view details)

Uploaded Sep 6, 2026 CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

pyscarcopula-0.22.0-cp311-cp311-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded Sep 6, 2026 CPython 3.11macOS 11.0+ ARM64

pyscarcopula-0.22.0-cp311-cp311-macosx_10_9_x86_64.whl (1.6 MB view details)

Uploaded Sep 6, 2026 CPython 3.11macOS 10.9+ x86-64

pyscarcopula-0.22.0-cp310-cp310-win_amd64.whl (1.3 MB view details)

Uploaded Sep 6, 2026 CPython 3.10Windows x86-64

pyscarcopula-0.22.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.0 MB view details)

Uploaded Sep 6, 2026 CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

pyscarcopula-0.22.0-cp310-cp310-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded Sep 6, 2026 CPython 3.10macOS 11.0+ ARM64

pyscarcopula-0.22.0-cp310-cp310-macosx_10_9_x86_64.whl (1.6 MB view details)

Uploaded Sep 6, 2026 CPython 3.10macOS 10.9+ x86-64

File details

Details for the file pyscarcopula-0.22.0.tar.gz.

File metadata

Download URL: pyscarcopula-0.22.0.tar.gz
Upload date: Sep 6, 2026
Size: 1.5 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.6

File hashes

Hashes for pyscarcopula-0.22.0.tar.gz
Algorithm	Hash digest
SHA256	`2555b8f4d79216be1d0b9cb79a00a8142085d36317d90cd3c390901f39a0d809`
MD5	`ce6c49ce11e870aa3b2eddd35efd0a8d`
BLAKE2b-256	`63ecccc6f774965a190736a5feec3c6f9fa31ebefe12d14a740597689888ca26`

Algorithm	Hash digest
SHA256	`dded669c225049b7211352c7b44a6eef2727142591f6927037a7c5200b83ce3e`
MD5	`96d2d69546e430dc5984f109ac4a0354`
BLAKE2b-256	`18009d1c04f611581e1d40a8b188f6c3e95499370e3fe3e9c35a38005680471f`

Algorithm	Hash digest
SHA256	`012819f99d738e26525dd8781a462210fe4afd9cfea9187d7e72535aee0f7ec3`
MD5	`9f633758fdd2d2c3157141d8cd8353bc`
BLAKE2b-256	`f2140c723584d30a5054a1199990ec0df732552537f0a550fe3fa46cdd62b6c4`

Algorithm	Hash digest
SHA256	`de529c7ef2b9847afa1eb578651b4ec6ca1453bd40d2d3d870bfffa547266a1d`
MD5	`e687327f7b40941887bced00849a777a`
BLAKE2b-256	`11fc800b6efdeef3e8ee3aea85905566d3a84acf4a7a0ecf84ee843dae7d6840`

Algorithm	Hash digest
SHA256	`3058fc5453422672982a858945bee9a310937560e71c5b9e3b3c02b4cb05ef2e`
MD5	`2b0848de7e38db140fa3918458c36be5`
BLAKE2b-256	`26556a19411bb8e4a958d61e6cd2b700097f93f4885717a4e8ad16b11669fff0`

Algorithm	Hash digest
SHA256	`f8f84f4059a72c96269ccf84955b44020ab82194e088d59783f23c097de7ef7c`
MD5	`4388fe1d37aabe740216e155f6509345`
BLAKE2b-256	`c46dcdbfba97e34c8f6356c31e89bebbbfe31e30d5ccfa85f0bcd717e603d146`

Algorithm	Hash digest
SHA256	`8cbe9de624324194be732295861ef6e90f47bc44e927110fd0c107f834a590a3`
MD5	`a7f662d041b73408e507988594fbff57`
BLAKE2b-256	`9e2dc6e90f1692423e22b2037d16b2561d78c5aaf62faeace26e39eae7ee45f8`

Algorithm	Hash digest
SHA256	`7303b93a9b13bdbd3a60f5b95d6b4a6fbe58e84959172883573776887430a1b8`
MD5	`da16188bcfef25e61303a16627cb3368`
BLAKE2b-256	`1fc88f44045481478eec0ac28c11cc28f20039c602ffc7c34846de26a1d3deaf`

Algorithm	Hash digest
SHA256	`eca38e023cef24c7e71ba771190f054113896f5ab8fc474ae9adcb278580b33e`
MD5	`75d675c85bd29c0d03331d59ad15560d`
BLAKE2b-256	`5caeff9982856863edbe4e90ab3278b19d99e0ba65fa1c6574a091d58a5236e3`

Algorithm	Hash digest
SHA256	`713104547ef0965cb3d13bc26287eb71a09d33eab2cbb19a9de2b8c12f3093d9`
MD5	`5b8ba590fd4217ef8b3bfbe379a2a905`
BLAKE2b-256	`d1288f94d6e190815bb72976d5888ff5ce4db7330385f6bac96005dfe341b0a4`

Algorithm	Hash digest
SHA256	`802dfed4fc59b8dcdc88a1400de1a76e2e4767d3c7d629b0cb520c9b7e100f86`
MD5	`a3af12c6fc027e805c81bf1be3a034a7`
BLAKE2b-256	`a9fd895f259abe1b17f1fd103ec3a5a80db4d2163b5bbace0ed39e2a01ca78e6`

Algorithm	Hash digest
SHA256	`a3cd88c7d73f97e95e547f5a75b3c79f8eb30a48de7dbe97f803acb3144b1ff0`
MD5	`410cfc7bb0d4801de10753bfb08f77ec`
BLAKE2b-256	`445d124848345cdad2f8b0821a35037212700a18b51d8051b5ebf8efc1380608`

Algorithm	Hash digest
SHA256	`ab4616320a07dc51f4ab6277c7f6b4a4e47ddc18943ec57d0b3d57bb0c0ad96f`
MD5	`dc41eda23dd0052f13eb8f7ef16e787a`
BLAKE2b-256	`d680715400bf13fc9141fbdf78a1c97f2fb1bb75d9a5c99192e29e31480a838e`

Algorithm	Hash digest
SHA256	`f874c651331c8dd52d91ef66116bed4cf4a4720b894761660a510d00f9928320`
MD5	`dabdb41115a66e1c805ca549fef70b88`
BLAKE2b-256	`816db065f1c834510012ef4a5509cd5d4f57abb5c4bb28ddffe5e013c97fd336`

Algorithm	Hash digest
SHA256	`0c8200f84d737f2c46d7d71284be36d4e5bcb2201264de31ec35d8a90837c304`
MD5	`54206465fcbb00d932401f12b35a9465`
BLAKE2b-256	`0110fdb7dead4400eabf0bfa7f160759e964f44ceab62c5c5454c181a1b5738d`

Algorithm	Hash digest
SHA256	`0c50fec67dd30ee700255f6b95ab9845d16e120da8ed651ffd39d1462b806f68`
MD5	`0fb4a40371394b4f530aeea3fd10a61f`
BLAKE2b-256	`4e40611c88967ba4bc60a9b05cfa75ba965a201438a1224bd3564ecf031f5faf`

Algorithm	Hash digest
SHA256	`3da3da8244cf1c9140334a4308f84ebcf23baf3fa1453e2a19d1a7367dfa57d3`
MD5	`88f07992f201c0a039f65c8f8b0547ed`
BLAKE2b-256	`e6606abe49da0ac0b2f8a05ef1ee57f36d265aaf2dd2469a28c91c6ce312cb1f`

Algorithm	Hash digest
SHA256	`218a3fd7766c016f24476dd14e0b1706081096859919481c8a6d41b6fb15048f`
MD5	`fd2e98146f880a4184e7d21a338f04b0`
BLAKE2b-256	`a008ff81ba2c80be2e9c82ee1f4ca9e73290bee298a2f8c80034cc0fbd38ffe0`

Algorithm	Hash digest
SHA256	`f487258c39ad276ac248acfb619c78b1373d53627e36eaaa935114a22983fae6`
MD5	`4c2f299b49aa4c195aba2486c586a0a7`
BLAKE2b-256	`b20f6cb2b61abb206678ad3f66c5023b37631b4f2adde9af5f747869b0b098d7`

Algorithm	Hash digest
SHA256	`a0c074b703406476ef657fe18e58ff597f0367b1c3d94d4f57889a9b5164a682`
MD5	`1eb420a2a8bed2164c905919d8e455c6`
BLAKE2b-256	`5333cc88d5582d503f6de484127f2af37a07777a7ba3074a30e0120675f6dee9`

Algorithm	Hash digest
SHA256	`292c655d3176daf6b3cf6f833870981d6a749522d4c51602c08c4a9f3f819ac8`
MD5	`2e72cf65245b92d0e4a0d96578567133`
BLAKE2b-256	`cd2c5f8beda3c6e73264713c4690de588eedd8101fd46c7d0027e4747eeee340`

pyscarcopula 0.22.0

pyscarcopula

About

Install

Quick start

Features

Mathematical background

Examples and docs

License

Contacts

Project links

Key dates

1 maintainer

Credits

License expression

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details