Metadata-Version: 2.4
Name: tlf-regression-engine
Version: 0.1.0
Summary: Country-agnostic linear, polynomial, and logistic regression over pandas DataFrames — part of The Living Facts (TLF).
Author-email: Sanchita Karki <karkisanchu06@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ctpl-git/TLF-Data-Analysis
Project-URL: Repository, https://github.com/ctpl-git/TLF-Data-Analysis
Project-URL: Issues, https://github.com/ctpl-git/TLF-Data-Analysis/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: statsmodels>=0.14
Requires-Dist: scipy>=1.9
Requires-Dist: openpyxl>=3.1
Requires-Dist: questionary>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install tlf-regression-engine
```

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

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

---

## Usage

```python
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

| Type | Column shape | Use for |
|---|---|---|
| `linear_regression` | `target` + `predictors` (1+ numeric columns) | Ordinary least squares over one or more predictors |
| `polynomial_regression` | `target` + `predictor` (1 numeric column) + `degree` | Curved (non-linear) fit against a single predictor |
| `logistic_regression` | `target` (exactly 2 distinct values) + `predictors` (1+ numeric columns) | Binary classification / probability modeling |

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

```bash
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.

```bash
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:

```bash
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

| Flag | Applies to | Notes |
|---|---|---|
| `--data` | all | CSV, Excel, or JSON path |
| `--sheet` | all | Excel sheet name (default: first sheet) |
| `--regression` | all | `linear_regression` / `polynomial_regression` / `logistic_regression` |
| `--target` | all | Target (dependent) column |
| `--predictors` | linear, logistic | Comma-separated column names, e.g. `households,avg_household_size` |
| `--predictor` | polynomial | Single column name |
| `--degree` | polynomial | Default: 2 |
| `--export` / `--export-path` | all | `csv` or `json`; extension auto-appended if omitted |
| `--yes` | all | Non-interactive mode |

---

## License

MIT
