Crate copula_core 

copula-core

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

The crate is pre-1.0. The principal elliptical and Archimedean families have the strongest test coverage; advanced constructions such as extreme-value, factor, and vine copulas should be treated as experimental until their numerical contracts are validated more thoroughly.

Mathematical setting

For continuous marginals, Sklar’s theorem gives

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

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

A statistical implementation must therefore respect mathematical invariants, not merely return finite numbers. The project tests properties such as unit interval bounds, Fréchet-Hoeffding bounds, density non-negativity, and sampling range for a subset of the main families.

Quick start

use copula_core::{ClaytonCopula, Copula};

let copula = ClaytonCopula::new(2.0)?;
let c = copula.cdf(&[0.5, 0.5])?;
assert!((0.0..=1.0).contains(&c));

let mut rng = rand::rng();
let samples = copula.sample(100, &mut rng)?;
assert_eq!(samples.ncols(), 2);

Main families

Elliptical

• GaussianCopula
• StudentTCopula

Archimedean

• ClaytonCopula
• GumbelCopula
• FrankCopula
• JoeCopula
• AMHCopula

Other

• MarshallOlkinCopula
• EmpiricalCopula

Feature flags

No features are enabled by default.

• estimation enables the estimation and model_selection modules and the FittableCopula trait.
• serde implements Serialize and Deserialize for the core copula types, with parameters validated on deserialization, and the SerializableCopula JSON helpers.
• full enables all of the above.

Minimum supported Rust version

Rust 1.89. Raising it is not considered a breaking change before 1.0, but is always listed in the changelog.

Maturity

The immediate project priority is numerical robustness of the existing API: parameter domains, boundary behaviour, stable likelihood evaluation, and verified estimation. See ROADMAP.md in the repository for the current plan.

Re-exports

pub use error::CopulaError;

pub use error::Result;

pub use model_selection::k_fold_cv;estimation

pub use testing::anderson_darling;

pub use testing::cramer_von_mises;

pub use testing::cvm_multiplier_bootstrap;

pub use testing::kolmogorov_smirnov;

pub use traits::FittableCopula;estimation

pub use traits::ArchimedeanCopula;

pub use traits::Copula;

pub use utils::empirical_ranks;

pub use utils::kendall_tau;

pub use utils::spearman_rho;

pub use utils::to_pseudo_observations;

pub use archimedean::AMHCopula;

pub use archimedean::ClaytonCopula;

pub use archimedean::FrankCopula;

pub use archimedean::GumbelCopula;

pub use archimedean::JoeCopula;

pub use elliptical::GaussianCopula;

pub use elliptical::StudentTCopula;

pub use other::EmpiricalCopula;

pub use other::MarshallOlkinCopula;

Modules

archimedean

Archimedean copulas module.

elliptical

Elliptical copulas module.

error

Error types and handling for copula-core.

estimationestimation

Parameter estimation methods for copulas.

extreme_value

Extreme value copulas module.

factor

Factor copulas module.

model_selectionestimation

Model selection utilities such as cross-validation.

numerical

Numerical utilities for copula computations.

other

Other copula families module (placeholder).

prelude

Convenient imports for common copula operations.

sampling

Advanced sampling methods for copulas.

testing

Statistical testing utilities.

traits

Core traits that define the interface for all copula types.

utils

Utility functions for copula modeling and data preprocessing.

vine

Vine copulas module.

Constants

VERSION

Library version information

Type Aliases

DMatrixalloc or std

A dynamically sized column-major matrix.

DVectoralloc or std

A dynamically sized column vector.