copula_core/lib.rs
1//! # copula-core
2//!
3//! `copula-core` is an experimental Rust library for copula modelling,
4//! simulation, and statistical dependence analysis.
5//!
6//! The crate is pre-1.0. The principal elliptical and Archimedean families have
7//! the strongest test coverage; advanced constructions such as extreme-value,
8//! factor, and vine copulas should be treated as experimental until their
9//! numerical contracts are validated more thoroughly.
10//!
11//! ## Mathematical setting
12//!
13//! For continuous marginals, Sklar's theorem gives
14//!
15//! ```text
16//! F(x1, ..., xd) = C(F1(x1), ..., Fd(xd)),
17//! ```
18//!
19//! where `C` is a copula and the `Fi` are marginal cumulative distribution
20//! functions.
21//!
22//! A statistical implementation must therefore respect mathematical invariants,
23//! not merely return finite numbers. The project tests properties such as unit
24//! interval bounds, Fréchet-Hoeffding bounds, density non-negativity, and sampling
25//! range for a subset of the main families.
26//!
27//! ## Quick start
28//!
29//! ```rust
30//! use copula_core::{ClaytonCopula, Copula};
31//!
32//! let copula = ClaytonCopula::new(2.0)?;
33//! let c = copula.cdf(&[0.5, 0.5])?;
34//! assert!((0.0..=1.0).contains(&c));
35//!
36//! let mut rng = rand::rng();
37//! let samples = copula.sample(100, &mut rng)?;
38//! assert_eq!(samples.ncols(), 2);
39//!
40//! # Ok::<(), copula_core::CopulaError>(())
41//! ```
42//!
43//! ## Main families
44//!
45//! ### Elliptical
46//!
47//! - [`GaussianCopula`]
48//! - [`StudentTCopula`]
49//!
50//! ### Archimedean
51//!
52//! - [`ClaytonCopula`]
53//! - [`GumbelCopula`]
54//! - [`FrankCopula`]
55//! - [`JoeCopula`]
56//! - [`AMHCopula`]
57//!
58//! ### Other
59//!
60//! - [`MarshallOlkinCopula`]
61//! - [`EmpiricalCopula`]
62//!
63//! ## Feature flags
64//!
65//! No features are enabled by default.
66//!
67//! - `estimation` enables the `estimation` and `model_selection` modules and
68//! the `FittableCopula` trait.
69//! - `serde` implements `Serialize` and `Deserialize` for the core copula
70//! types, with parameters validated on deserialization, and the
71//! `SerializableCopula` JSON helpers.
72//! - `full` enables all of the above.
73//!
74//! ## Minimum supported Rust version
75//!
76//! Rust 1.89. Raising it is not considered a breaking change before 1.0, but
77//! is always listed in the changelog.
78//!
79//! ## Maturity
80//!
81//! The immediate project priority is numerical robustness of the existing API:
82//! parameter domains, boundary behaviour, stable likelihood evaluation, and
83//! verified estimation. See `ROADMAP.md` in the repository for the current plan.
84
85#![cfg_attr(docsrs, feature(doc_cfg))]
86#![forbid(unsafe_code)]
87#![warn(missing_docs, rust_2018_idioms)]
88#![allow(clippy::many_single_char_names)] // Mathematical notation uses single chars
89
90#[macro_use]
91mod macros;
92
93// Core modules
94pub mod error;
95pub mod traits;
96pub mod utils;
97
98// Copula family modules
99pub mod archimedean;
100pub mod elliptical;
101pub mod extreme_value;
102pub mod other;
103
104// Advanced constructions
105pub mod factor;
106pub mod vine;
107
108// Statistical methods
109#[cfg(feature = "estimation")]
110#[cfg_attr(docsrs, doc(cfg(feature = "estimation")))]
111pub mod estimation;
112
113#[cfg(feature = "estimation")]
114#[cfg_attr(docsrs, doc(cfg(feature = "estimation")))]
115pub mod model_selection;
116pub mod numerical;
117pub mod sampling;
118pub mod testing;
119
120// Convenience module for common imports
121pub mod prelude;
122
123// Re-export core types and traits
124pub use error::{CopulaError, Result};
125#[cfg(feature = "estimation")]
126pub use model_selection::k_fold_cv;
127pub use testing::{
128 anderson_darling, cramer_von_mises, cvm_multiplier_bootstrap, kolmogorov_smirnov,
129};
130#[cfg(feature = "estimation")]
131pub use traits::FittableCopula;
132pub use traits::{ArchimedeanCopula, Copula};
133pub use utils::{empirical_ranks, kendall_tau, spearman_rho, to_pseudo_observations};
134
135// Re-export main copula types
136pub use archimedean::{AMHCopula, ClaytonCopula, FrankCopula, GumbelCopula, JoeCopula};
137pub use elliptical::{GaussianCopula, StudentTCopula};
138pub use other::{EmpiricalCopula, MarshallOlkinCopula};
139
140// Re-export commonly used external types
141pub use nalgebra::{DMatrix, DVector};
142
143/// Library version information
144pub const VERSION: &str = env!("CARGO_PKG_VERSION");
145
146#[cfg(test)]
147mod tests {
148 use super::*;
149
150 #[test]
151 #[allow(clippy::assertions_on_constants)]
152 fn test_library_version() {
153 assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
154 }
155}