copula-core 0.2.0

Copula modelling, simulation, and dependence analysis (experimental, pre-1.0)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

//! # 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
//!
//! ```text
//! 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
//!
//! ```rust
//! 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);
//!
//! # Ok::<(), copula_core::CopulaError>(())
//! ```
//!
//! ## 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.

#![cfg_attr(docsrs, feature(doc_cfg))]
#![forbid(unsafe_code)]
#![warn(missing_docs, rust_2018_idioms)]
#![allow(clippy::many_single_char_names)] // Mathematical notation uses single chars

#[macro_use]
mod macros;

// Core modules
pub mod error;
pub mod traits;
pub mod utils;

// Copula family modules
pub mod archimedean;
pub mod elliptical;
pub mod extreme_value;
pub mod other;

// Advanced constructions
pub mod factor;
pub mod vine;

// Statistical methods
#[cfg(feature = "estimation")]
#[cfg_attr(docsrs, doc(cfg(feature = "estimation")))]
pub mod estimation;

#[cfg(feature = "estimation")]
#[cfg_attr(docsrs, doc(cfg(feature = "estimation")))]
pub mod model_selection;
pub mod numerical;
pub mod sampling;
pub mod testing;

// Convenience module for common imports
pub mod prelude;

// Re-export core types and traits
pub use error::{CopulaError, Result};
#[cfg(feature = "estimation")]
pub use model_selection::k_fold_cv;
pub use testing::{
    anderson_darling, cramer_von_mises, cvm_multiplier_bootstrap, kolmogorov_smirnov,
};
#[cfg(feature = "estimation")]
pub use traits::FittableCopula;
pub use traits::{ArchimedeanCopula, Copula};
pub use utils::{empirical_ranks, kendall_tau, spearman_rho, to_pseudo_observations};

// Re-export main copula types
pub use archimedean::{AMHCopula, ClaytonCopula, FrankCopula, GumbelCopula, JoeCopula};
pub use elliptical::{GaussianCopula, StudentTCopula};
pub use other::{EmpiricalCopula, MarshallOlkinCopula};

// Re-export commonly used external types
pub use nalgebra::{DMatrix, DVector};

/// Library version information
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    #[allow(clippy::assertions_on_constants)]
    fn test_library_version() {
        assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
    }
}