Formula Syntax¶

Formula-based regression using R-style syntax. Supports polynomial and interaction effects that are computed per-group with group_by/over.

Note: Unlike R, the intercept is controlled via the with_intercept parameter, not in the formula. R's y ~ x - 1 or y ~ 0 + x syntax for removing the intercept is not supported. Use with_intercept=False instead.

Supported Formula Syntax¶

Pattern	Example	Expansion
Main effects	`y ~ x1 + x2`	Two variables
Interaction only	`y ~ x1:x2`	Product term
Full crossing	`y ~ x1 * x2`	`x1 + x2 + x1:x2`
Polynomial (centered)	`y ~ poly(x, 2)`	Centered x, x^2
Polynomial (raw)	`y ~ poly(x, 2, raw=True)`	x, x^2
Explicit transform	`y ~ I(x^2)`	x squared

Formula Functions¶

All regression models have a *_formula variant:

Linear Models¶

ps.ols_formula(formula: str, with_intercept: bool = True, alias_tolerance: float = 1e-7) -> pl.Expr
ps.ridge_formula(formula: str, lambda_: float = 1.0, with_intercept: bool = True) -> pl.Expr
ps.elastic_net_formula(formula: str, lambda_: float = 1.0, alpha: float = 0.5, with_intercept: bool = True) -> pl.Expr
ps.wls_formula(formula: str, weights: Union[pl.Expr, str], with_intercept: bool = True, alias_tolerance: float = 1e-7) -> pl.Expr
ps.rls_formula(formula: str, forgetting_factor: float = 0.99, with_intercept: bool = True) -> pl.Expr
ps.bls_formula(formula: str, lower_bound: float | None = None, upper_bound: float | None = None, with_intercept: bool = True) -> pl.Expr
ps.nnls_formula(formula: str, with_intercept: bool = True) -> pl.Expr

ols_formula/wls_formula also accept alias_tolerance (default 1e-7) — forwarded to the underlying ols/wls rank-deficiency tolerance; see Linear Models.

GLM Models¶

ps.logistic_formula(formula: str, with_intercept: bool = True) -> pl.Expr
ps.poisson_formula(formula: str, with_intercept: bool = True) -> pl.Expr
ps.negative_binomial_formula(formula: str, theta: float | None = None, with_intercept: bool = True) -> pl.Expr
ps.tweedie_formula(formula: str, var_power: float = 1.5, with_intercept: bool = True) -> pl.Expr
ps.probit_formula(formula: str, with_intercept: bool = True) -> pl.Expr
ps.cloglog_formula(formula: str, with_intercept: bool = True) -> pl.Expr

ALM¶

ps.alm_formula(formula: str, distribution: str = "normal", with_intercept: bool = True) -> pl.Expr

Penalized GLM¶

ps.penalized_glm_formula(formula: str, family: str = "poisson", offset=None, ...) -> pl.Expr

See Penalized GLM. R's formula offset() term is not parsed — pass offset as a column/expression directly.

Survival (AFT)¶

ps.aft_formula(formula: str, event: Union[pl.Expr, str], distribution: str = "weibull", ...) -> pl.Expr

The formula's left-hand side is the time column; event is not part of the formula syntax and is passed separately. See Survival Regression (AFT).

Examples¶

Polynomial Regression¶

# Quadratic regression per group
df.group_by("group").agg(
    ps.ols_formula("y ~ poly(x, 2)").alias("model")
)

Interaction Effects¶

# Full interaction model
df.group_by("group").agg(
    ps.ols_formula("y ~ x1 * x2").alias("model")
)

# Equivalent to:
df.group_by("group").agg(
    ps.ols_formula("y ~ x1 + x2 + x1:x2").alias("model")
)

Explicit Transformations¶

# Square term
df.group_by("group").agg(
    ps.ols_formula("y ~ x + I(x^2)").alias("model")
)

Summary and Prediction Formula Variants¶

Summary functions:

ps.ols_formula_summary(formula, with_intercept=True, alias_tolerance=1e-7)
ps.ridge_formula_summary(formula, lambda_=1.0, with_intercept=True)
ps.penalized_glm_formula_summary(formula, family="poisson", vcov_type="laplace", conf_level=0.95, ...)
ps.aft_formula_summary(formula, event, distribution="weibull", vcov_type="laplace", conf_level=0.95, ...)
# ... etc.

Prediction functions:

ps.ols_formula_predict(formula, interval=None, level=0.95, with_intercept=True, alias_tolerance=1e-7)
ps.ridge_formula_predict(formula, lambda_=1.0, interval=None, level=0.95, with_intercept=True)
ps.penalized_glm_formula_predict(formula, family="poisson", predict_type="response", null_policy="drop", ...)
# ... etc.

Note: only ols_formula/wls_formula have alias_tolerance; there is no wls_formula_summary/wls_formula_predict — use ps.wls_summary/ps.wls_predict's column-based interface (both accept alias_tolerance) for a WLS summary/prediction after a formula fit.