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//! **Beta.** The API may still change. Constant (zero-variance) columns are
38//! rejected explicitly by the scalers rather than silently producing a zero
39//! column — see [`MattenMlprepError::ZeroVariance`]. Dynamic tensors are
40//! rejected at every public entry point unconditionally — the guard does not
41//! depend on the companion `dynamic` feature (RFC-031).
42//!
43//! # Feature flags
44//!
45//! - `dynamic` — Compatibility forwarding feature. No longer required for
46//! dynamic rejection as of v0.19.1. Dynamic tensors are rejected at companion
47//! boundaries regardless of whether this feature is enabled. Reconsider
48//! removal no earlier than v0.20.0.
49
50#![forbid(unsafe_code)]
51
52mod bias;
53mod error;
54mod scale;
55mod split;
56mod util;
57
58pub use crate::bias::add_bias_column;
59pub use crate::error::MattenMlprepError;
60pub use crate::scale::{minmax_scale_columns, standardize_columns};
61pub use crate::split::train_test_split;