solow_cv/lib.rs
1//! # solow-cv
2//!
3//! Cross-validation, resampling, and bootstrap for the Solow statistical
4//! stack.
5//!
6//! The crate provides three composable layers:
7//!
8//! 1. **Splitters** — [`KFold`], [`StratifiedKFold`], [`TimeSeriesSplit`],
9//! [`LeaveOneOut`], and [`ShuffleSplit`] behind the shared [`Splitter`]
10//! trait. Every splitter emits validated `Vec<Split>` fold lists that a
11//! caller can iterate, index, or run in parallel.
12//!
13//! 2. **Cross-validated scoring** — [`cross_val_score`] runs a
14//! `fit_and_score` callback across every fold and returns the per-fold
15//! scores with mean, unbiased standard deviation, and standard error.
16//!
17//! 3. **Bootstrap confidence intervals** — [`bootstrap_ci`] resamples with
18//! replacement and returns a percentile, reverse-percentile ("basic"), or
19//! Efron BCa confidence interval for any scalar statistic of a sample.
20//!
21//! ```
22//! use ndarray::array;
23//! use solow_cv::{KFold, Splitter};
24//!
25//! let y = array![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0];
26//! let kf = KFold::new(5)?.shuffle(false);
27//! for split in kf.split(y.len())? {
28//! let (train, test) = (split.train, split.test);
29//! assert_eq!(train.len() + test.len(), y.len());
30//! // Fit on `y.select(Axis(0), &train)`; score on the test rows.
31//! }
32//! # Ok::<_, solow_core::Error>(())
33//! ```
34//!
35//! ## Determinism
36//!
37//! Random splits and bootstrap resamples use a well-tested 64-bit
38//! linear-congruential generator (Numerical Recipes' MMIX constants),
39//! seeded by the caller. The stream is bit-for-bit portable across
40//! platforms; a fixed seed always produces the same folds and replicates.
41
42#![forbid(unsafe_code)]
43#![warn(missing_docs)]
44
45mod block_bootstrap;
46mod bootstrap;
47mod extras;
48mod group_splitters;
49mod scoring;
50mod shuffle;
51mod splitters;
52
53pub use block_bootstrap::{
54 circular_block_bootstrap_indices, moving_block_bootstrap_indices,
55 stationary_bootstrap_indices,
56};
57pub use bootstrap::{bootstrap_ci, BootstrapCi, BootstrapMethod};
58pub use extras::{
59 learning_curve, permutation_test_score, validation_curve, LeavePOut, RepeatedKFold,
60 RepeatedStratifiedKFold,
61};
62pub use group_splitters::{
63 CombinatorialPurgedKFold, GroupKFold, PurgedKFold, StratifiedGroupKFold,
64};
65pub use shuffle::{GroupShuffleSplit, StratifiedShuffleSplit};
66#[cfg(feature = "parallel")]
67pub use scoring::cross_val_score_parallel;
68pub use scoring::{cross_val_score, cross_val_score_from_folds, CrossValScores};
69pub use splitters::{
70 KFold, LeaveOneOut, ShuffleSplit, Split, Splitter, StratifiedKFold, TimeSeriesSplit,
71};
72
73/// Commonly used imports.
74pub mod prelude {
75 pub use crate::{
76 bootstrap_ci, cross_val_score, cross_val_score_from_folds, learning_curve,
77 permutation_test_score, validation_curve, BootstrapCi, BootstrapMethod,
78 CombinatorialPurgedKFold, CrossValScores, GroupKFold, GroupShuffleSplit, KFold,
79 LeaveOneOut, LeavePOut, PurgedKFold, RepeatedKFold, RepeatedStratifiedKFold, ShuffleSplit,
80 Split, Splitter, StratifiedGroupKFold, StratifiedKFold, StratifiedShuffleSplit,
81 TimeSeriesSplit,
82 };
83}