Crate polars_formula 

polars-formula

A parsing and materialization library for Rust that brings R-style and Python Patsy/Formulaic formula syntax to the Polars DataFrame ecosystem.

Overview

This library provides a simple, focused API for parsing statistical model formulas and materializing them into design matrices. It seamlessly integrates with Polars DataFrames and provides efficient conversion to faer matrices for linear algebra operations.

Simple API

The library exposes just 4 main functions for a clean, focused experience:

use polars::prelude::*;
use polars_formula::{canonicalize, materialize, print_formula, print_modelspec};

// 1. Parse and canonicalize a formula
let spec = canonicalize("y ~ x1 + x2")?;

// 2. Print the canonical formula with colors
print_formula(&spec);

// 3. Materialize against your data
let (y, x, z) = materialize(&spec, &df)?;

// 4. Inspect the full model specification
print_modelspec(&spec);

Supported Syntax

Syntax	Description
y ~ x1 + x2	Linear regression
y ~ x1 * x2	Product terms (expands to x1 + x2 + x1:x2)
y ~ x1:x2	Interaction terms
y ~ poly(x1, 2)	Polynomial terms (x, x², x³, …)
y ~ (1|group)	Random intercepts
y ~ (x|group)	Random slopes
y ~ (x||group)	Uncorrelated random effects
y ~ I(x)	Identity function (literal interpretation)
y ~ x^2	Power terms
y ~ (a+b)^3	Polynomial expansion
y ~ a/b	Nesting (a + a:b)
y ~ b %in% a	Nesting (b within a)
y | weights(w) ~ x	Auxiliary terms (weights, se, trials, etc.)
Surv(time, event) ~ x	Survival analysis
cbind(success, failure) ~ x	Multivariate responses
s(x, k=10, bs="tp")	Smooth terms (s, t2, te, ti)
family=gaussian() y ~ x	Distribution families
y ~ x + sigma ~ z	Distributional parameters
y ~ x + ar(p=1)	Autocorrelation terms

Enums

Error

Functions

canonicalize

Parse and canonicalize a formula string into a ModelSpec.

materialize

Materialize a ModelSpec against a DataFrame to produce design matrices.

print_formula

Print the canonical formula with syntax highlighting.

print_modelspec

Pretty print the full ModelSpec structure.