copula-core-0.1.0 has been yanked.

copula-core

copula-core is an experimental Rust library for copula modelling, simulation, and statistical dependence analysis.

The project is under active development. Some modules are substantially tested, while others are research-oriented implementations that still need stronger numerical validation before they should be treated as stable statistical software.

Current capability levels

Core, tested surface

The most mature public surface currently includes:

Gaussian and Student-t copulas
Clayton, Gumbel, Frank, Joe, and Ali-Mikhail-Haq copulas
Marshall-Olkin and empirical copulas
CDF/PDF evaluation where a continuous density is defined
random sampling
tail-dependence calculations where implemented by the family
pseudo-observations and rank-based dependence utilities
property-based tests for important copula axioms and numerical invariants

Feature-gated statistical functionality

With the estimation feature enabled, the crate also exposes parameter-estimation and model-selection functionality. These routines are still evolving and should be validated for the intended model, parameter regime, and sample size before being used in inferential work.

Available Cargo features are:

estimation
parallel
serde
full
experimental

Experimental research modules

The crate also contains implementations for advanced constructions including extreme-value, factor, and vine copulas. These modules are useful for research and experimentation but are not yet part of a stable API contract. Several algorithms use numerical differentiation, iterative inversion, Monte Carlo, or simplified constructions whose accuracy and robustness require further validation.

See ROADMAP.md for the current engineering priorities.

Quick start

Add the crate to Cargo.toml:

[dependencies]

copula-core = "0.1.0"

A basic Clayton example:

use copula_core::{ClaytonCopula, Copula};

fn main() -> Result<(), copula_core::CopulaError> {
    let copula = ClaytonCopula::new(2.0)?;

    let c = copula.cdf(&[0.5, 0.5])?;
    println!("C(0.5, 0.5) = {c}");

    let mut rng = rand::thread_rng();
    let samples = copula.sample(1_000, &mut rng)?;
    println!("generated {} observations", samples.nrows());

    Ok(())
}

Mathematical background

For continuous marginals, Sklar's theorem gives

F(x1, ..., xd) = C(F1(x1), ..., Fd(xd)),

where C is the copula and the Fi are marginal distribution functions.

The implementation is therefore concerned not only with producing numbers but with preserving mathematical constraints such as:

values in the unit interval
correct margins
Fréchet-Hoeffding bounds
non-negative densities where a density exists
valid parameter domains
stable behaviour near parameter and probability boundaries

Property-based tests cover a subset of these invariants for the main families.

Development and verification

Clone the repository and use the standard Rust toolchain:

git clone https://github.com/DiogoRibeiro7/copula-core

cd copula-core

cargo test --all-features

cargo clippy --all-targets --all-features -- -D warnings

cargo fmt --all -- --check

cargo doc --no-deps --all-features

To run the Criterion benchmarks:

cargo bench --all-features

Benchmark results are environment-dependent. The repository intentionally does not claim fixed nanosecond or millisecond performance targets without recording compiler, CPU, feature set, sample size, and benchmark protocol.

CI

The permanent CI workflow checks multiple operating systems and Rust toolchains, feature combinations, Clippy, formatting, documentation, coverage, dependency audit, benchmarks on main, and the minimum supported Rust version.

The repository uses a working branch -> develop -> main flow. main is the protected release-facing branch.

Scope and maturity

This crate is pre-1.0 statistical software. API stability is not guaranteed. The immediate priority is numerical and statistical validation of the existing surface rather than adding many more copula families.

The next engineering sequence is:

parameter-domain validation
-> boundary behaviour
-> stable log-density / likelihood evaluation
-> verified estimation
-> validated model comparison
-> only then broader family coverage

License

Licensed under MIT OR Apache-2.0 as declared in Cargo.toml.

References

Nelsen, R. B. (2006). An Introduction to Copulas. Springer.
Joe, H. (2014). Dependence Modeling with Copulas. CRC Press.
Durante, F., & Sempi, C. (2015). Principles of Copula Theory. CRC Press.
Aas, K., Czado, C., Frigessi, A., & Bakken, H. (2009). Pair-copula constructions of multiple dependence. Insurance: Mathematics and Economics, 44(2), 182-198.

copula-core 0.1.0