subtr_actor/collector/ndarray/mod.rs
1//! Dense numeric feature extraction: build an [`ndarray::Array2`] of replay
2//! features for ML/analytics.
3//!
4//! # What feature adders are
5//!
6//! A [`NDArrayCollector`] runs the replay frame by frame and, for each sampled
7//! frame, asks a list of *feature adders* to append their numbers to that
8//! frame's row. Each adder owns a fixed set of named columns and knows how to
9//! compute them from the current [`ProcessorView`](crate::ProcessorView) (and,
10//! for analysis-backed adders, from analysis-graph state). The collector
11//! concatenates every adder's columns into one wide matrix plus a header list,
12//! so the set of adders you choose *is* your feature schema.
13//!
14//! There are two flavours, each in a global and a per-player form:
15//!
16//! - [`FeatureAdder`] / [`PlayerFeatureAdder`] — compute directly from frame and
17//! processor state.
18//! - [`AnalysisFeatureAdder`] / [`AnalysisPlayerFeatureAdder`] — additionally
19//! read [`AnalysisGraph`](crate::stats::analysis_graph::AnalysisGraph) state,
20//! declaring their node dependencies so the collector wires up the graph.
21//!
22//! The `LengthChecked*` trait variants let an adder fix its column count at
23//! compile time. Player adders emit their columns once per player.
24//!
25//! # Registering adders
26//!
27//! - **Explicitly:** construct adders and pass them to the collector (see the
28//! builder methods on [`NDArrayCollector`]).
29//! - **By name:** [`NDArrayCollector::from_strings`] /
30//! [`from_strings_typed`](NDArrayCollector::from_strings_typed) look up adders
31//! in a built-in string registry — convenient for the Python/JS bindings.
32//!
33//! Recognized global (ball / game) names include `BallRigidBody`,
34//! `BallRigidBodyNoVelocities`, `BallRigidBodyQuaternions`,
35//! `BallRigidBodyBasis`, `InterpolatedBallRigidBodyNoVelocities`,
36//! `CurrentTime`, `FrameTime`, `SecondsRemaining`, and `BallHasBeenHit`.
37//! Recognized per-player names include `PlayerRigidBody`,
38//! `PlayerRigidBodyNoVelocities`, `PlayerRelativeBallPosition`,
39//! `PlayerLocalRelativeBallVelocity`, `PlayerBoost`, `PlayerJump`,
40//! `PlayerAnyJump`, `PlayerDodgeRefreshed`, `PlayerDemolishedBy`, and
41//! `PlayerBallDistance`. Analysis-backed per-player event features are also
42//! addressable by mechanic name (e.g. `touch`, `flick`, `whiff`, `bump`,
43//! `pass`, `rotation`, `movement`, `positioning`). The matching arms in
44//! `collector.rs` and `analysis_builtins.rs` are the authoritative list.
45
46mod analysis_builtins;
47mod builtins;
48mod collector;
49mod traits;
50
51pub use self::analysis_builtins::*;
52pub use self::builtins::*;
53pub use self::collector::*;
54pub use self::traits::*;