solow_formula/lib.rs
1//! # solow-formula
2//!
3//! An R/patsy-style *formula* interface that turns a formula string plus named
4//! data into a numeric design matrix with column names, matching
5//! [patsy](https://patsy.readthedocs.io/) semantics.
6//!
7//! ```
8//! use solow_formula::{DataFrame, build};
9//!
10//! let mut df = DataFrame::new();
11//! df.add_numeric("y", vec![1.0, 2.0, 3.0, 4.0]);
12//! df.add_numeric("x", vec![0.0, 1.0, 2.0, 3.0]);
13//! let out = build("y ~ x", &df).unwrap();
14//! assert_eq!(out.names, vec!["Intercept".to_string(), "x".to_string()]);
15//! assert!(out.y.is_some());
16//! ```
17//!
18//! Supported right-hand-side syntax:
19//!
20//! * `+` add a term, `-` remove a term (`- 1` / `+ 0` drop the intercept),
21//! * `:` interaction, `*` full cross (`a*b == a + b + a:b`),
22//! * `/` nesting (`a/b == a + a:b`), `**` interaction power
23//! (`(a + b + c)**2` = all ≤2-way interactions), and parenthesized groups,
24//! * `C(var)` mark a column categorical, optionally with a contrast coding:
25//! `C(g, Poly)`, `C(g, Sum)`, `C(g, Helmert)`, `C(g, Diff)`
26//! (orthogonal polynomial, deviation/sum-to-zero, Helmert, and
27//! backward-difference coding; the bare `C(g)` is treatment/dummy coding),
28//! * `I(expr)` identity / arithmetic transform (`**`, `*`, `+`, `-`, unary `-`)
29//! over a numeric column and numeric literals.
30//!
31//! Categorical factors are coded with structural avoidance of redundancy: with
32//! an intercept (or a lower-order term) spanning the constant direction the
33//! reduced `k-1`-column contrast is used, and where a full-rank encoding is
34//! needed the full `k`-column matrix (carrying the constant/mean column) is
35//! emitted — matching patsy's `code_without_intercept` / `code_with_intercept`.
36
37mod ast;
38mod contrasts;
39mod data;
40mod design;
41mod eval;
42mod parser;
43mod redundancy;
44mod terms;
45
46pub use data::DataFrame;
47pub use design::{build, DesignOutput};
48
49pub use solow_core::{Error, Result};