tlf-regression-engine

Country-agnostic regression modeling — part of TLF ("The Living Facts").

Fits three types of regression models over any pandas DataFrame — linear, polynomial, and binary logistic — and returns each result as a plain dict with coefficients, standard errors, p-values, and a fit-quality metric (R² / adjusted R² / pseudo R²) behind it.

Unlike tlf-census-stats, this package has no dependency on a specific country schema — it works on any DataFrame with numeric predictor and target columns.

Built on statsmodels rather than raw linear algebra, so every result carries proper inferential statistics (standard errors, p-values) — the same level of rigor as the tests in tlf-hypothesis-testing and the correlations in tlf-correlation-engine, not just point estimates.

Install

pip install tlf-regression-engine

Or from source, inside the TLF-Data-Analysis monorepo:

cd tlf-regression-engine
pip install -e ".[dev]"

Usage

import pandas as pd
from tlf_regression_engine import RegressionEngine

df = pd.read_csv("census_data.csv")

# Linear: one or more numeric predictors
engine = RegressionEngine(df, regression="linear_regression")
engine.run(target="literacy_rate", predictors=["households", "avg_household_size"])

# Polynomial: single numeric predictor, curved fit
engine = RegressionEngine(df, regression="polynomial_regression")
engine.run(target="literacy_rate", predictor="households", degree=2)

# Logistic: binary target (exactly 2 distinct values), one or more numeric predictors
engine = RegressionEngine(df, regression="logistic_regression")
engine.run(target="is_urban_majority", predictors=["literacy_rate", "avg_household_size"])

Regression types

Predictor columns must already be numeric — this package does not one-hot encode categorical predictors; encode those upstream (e.g. with pandas.get_dummies) before passing them in.

Every result includes coefficients, std_errors, p_values, and n (observations used, after dropping rows with nulls in any of the selected columns). linear_regression/polynomial_regression also include r2/adj_r2; logistic_regression includes pseudo_r2 (McFadden's pseudo R², via statsmodels).

A minimum of 3 complete observations per fitted parameter (predictors + intercept) is required, or InsufficientDataError is raised. Perfectly (or near-perfectly) collinear predictors — or, for logistic regression, predictors that perfectly separate the two classes — raise SingularMatrixError instead of returning a nonsensical fit.

CLI

tlf-regression-engine --data census.csv --regression linear_regression --target literacy_rate --predictors households,avg_household_size

Run with no flags at all for a fully interactive walkthrough (file path → sheet selection → regression type → target/predictor(s) → export format). Column prompts are dtype-aware: numeric columns are listed first, each annotated with its type and unique-value count (e.g. Literacy Rate (numeric, 8 unique)), though every column stays selectable either way.

tlf-regression-engine

For unattended/scripted runs, --yes disables all prompting and fails loudly (rather than silently guessing) if something required — like --data — is missing:

tlf-regression-engine --data census.csv --yes --regression polynomial_regression --target literacy_rate --predictor households --degree 2 --export json --export-path out.json

CLI flags

License

MIT