copula_core/
lib.rs

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

copula_core/
lib.rs
