matten_mlprep/lib.rs
1//! `matten-mlprep` — small, transparent, deterministic preprocessing helpers for
2//! [`matten::Tensor`].
3//!
4//! This companion crate (RFC-024, RFC-028) prepares numeric tensors for use with
5//! external tools. It is **not** an ML framework: there is no model training, no
6//! autograd, no optimizer, and no hidden randomness. Every function is a pure,
7//! deterministic transform you can reason about. It depends only on core
8//! `matten` (no default features) — no `ndarray`, no `candle`, no `rand`.
9//!
10//! # Convention
11//!
12//! All functions operate on **rank-2** tensors with `rows = samples` and
13//! `columns = features`. A non-2D tensor is rejected; there is no silent
14//! transposition.
15//!
16//! # Functions
17//!
18//! - [`standardize_columns`] — per-column z-score (population std).
19//! - [`minmax_scale_columns`] — per-column scaling to `[0, 1]`.
20//! - [`add_bias_column`] — prepend a constant `1.0` intercept column.
21//! - [`train_test_split`] — ordered, deterministic row split.
22//!
23//! ```
24//! use matten::Tensor;
25//! use matten_mlprep::{add_bias_column, standardize_columns, train_test_split};
26//!
27//! let x = Tensor::new(vec![1.0, 3.0, 5.0, 7.0], &[4, 1]);
28//! let z = standardize_columns(&x).unwrap(); // zero mean, unit std
29//! let z = add_bias_column(&z).unwrap(); // [4, 2], column 0 = 1.0
30//! let (train, test) = train_test_split(&z, 0.75).unwrap();
31//! assert_eq!(train.shape(), &[3, 2]);
32//! assert_eq!(test.shape(), &[1, 2]);
33//! ```
34//!
35//! # Status
36//!
37//! **Production-ready candidate.** The small surface is stable; usable seriously
38//! if the documented limits are acceptable. Note that [`train_test_split`] is
39//! ordered-only (no shuffle). Constant (zero-variance) columns are rejected
40//! explicitly by the scalers rather than silently producing a zero column — see
41//! [`MattenMlprepError::ZeroVariance`]. Dynamic tensors are rejected at every
42//! public entry point unconditionally — the guard does not depend on the
43//! companion `dynamic` feature (RFC-031).
44//!
45//! # Feature flags
46//!
47//! - `dynamic` — Compatibility forwarding feature. No longer required for
48//! dynamic rejection as of v0.19.1. Dynamic tensors are rejected at companion
49//! boundaries regardless of whether this feature is enabled. Reconsider
50//! removal no earlier than v0.20.0.
51
52#![forbid(unsafe_code)]
53
54mod bias;
55mod error;
56mod scale;
57mod split;
58mod util;
59
60pub use crate::bias::add_bias_column;
61pub use crate::error::MattenMlprepError;
62pub use crate::scale::{minmax_scale_columns, standardize_columns};
63pub use crate::split::train_test_split;