Metadata-Version: 2.4
Name: tlf-hypothesis-testing
Version: 0.1.0
Summary: Country-agnostic statistical hypothesis testing (t-test, Welch's t-test, paired t-test, Mann-Whitney, ANOVA, Kruskal-Wallis, chi-square) 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: 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-hypothesis-testing

Country-agnostic statistical hypothesis testing — part of **TLF** ("The
Living Facts").

Runs seven hypothesis tests over any pandas DataFrame — two-sample,
paired, multi-group, and categorical-association tests — and returns
each result as a plain dict with the test statistic, p-value, and the
sample-size info behind it.

Unlike `tlf-census-stats`, this package has no dependency on a specific
country schema — it works on any DataFrame with the right column shape
for the test you choose.

---

## Install

```bash
pip install tlf-hypothesis-testing
```

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

```bash
cd tlf-hypothesis-testing
pip install -e ".[dev]"
```

---

## Usage

```python
import pandas as pd
from tlf_hypothesis_testing import HypothesisTestEngine

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

# Two-sample: compare literacy rate between exactly 2 groups
engine = HypothesisTestEngine(df, test="t_test")  # or "welch_t_test" / "mann_whitney"
engine.run(value_col="literacy_rate", group_col="area_type")

# Paired: compare two matched/before-after numeric columns
engine = HypothesisTestEngine(df, test="paired_t_test")
engine.run(col1="literacy_rate_2011", col2="literacy_rate_2021")

# Multi-group: compare literacy rate across 2+ groups
engine = HypothesisTestEngine(df, test="anova")  # or "kruskal_wallis"
engine.run(value_col="literacy_rate", group_col="province")

# Categorical association between two columns
engine = HypothesisTestEngine(df, test="chi_square")
engine.run(col1="province", col2="area_type")
```

### Tests

| Test | Column shape | Use for |
|---|---|---|
| `t_test` | `value_col` + `group_col` (exactly 2 groups) | Independent samples, assumes equal variance |
| `welch_t_test` | `value_col` + `group_col` (exactly 2 groups) | Independent samples, does not assume equal variance |
| `paired_t_test` | `col1` + `col2` | Matched/before-after samples, same length |
| `mann_whitney` | `value_col` + `group_col` (exactly 2 groups) | Non-parametric alternative to the t-test |
| `anova` | `value_col` + `group_col` (2+ groups) | Compare means across 3+ groups |
| `kruskal_wallis` | `value_col` + `group_col` (2+ groups) | Non-parametric alternative to ANOVA |
| `chi_square` | `col1` + `col2` (both categorical) | Association between two categorical columns |

A group with fewer than 2 non-null observations is dropped automatically
before `anova`/`kruskal_wallis` run; `t_test`/`welch_t_test`/`mann_whitney`
require `group_col` to split the data into *exactly* 2 groups, or they
raise `InvalidGroupCountError`.

---

## CLI

```bash
tlf-hypothesis-testing --data census.csv --test anova --value-col literacy_rate --group-col province
```

Run with no flags at all for a fully interactive walkthrough (file path
→ sheet selection → test → columns → export format). Column prompts are
dtype-aware: numeric columns are listed first when picking a value
column, and categorical/low-cardinality columns are listed first when
picking a group column — each annotated with its type and unique-value
count (e.g. `Province  (categorical, 3 unique)`) so it's clear which
columns actually make sense for the role, though every column stays
selectable either way:

```bash
tlf-hypothesis-testing
```

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

```bash
tlf-hypothesis-testing --data census.csv --yes --test chi_square --col1 province --col2 area_type
```

### CLI flags

| Flag | Description |
|---|---|
| `--data` | Path to a CSV, Excel, or JSON file |
| `--sheet` | Excel sheet name (default: first sheet) |
| `--test` | `t_test` \| `welch_t_test` \| `paired_t_test` \| `mann_whitney` \| `anova` \| `kruskal_wallis` \| `chi_square` |
| `--value-col` | Value column (two-sample / multi-group tests) |
| `--group-col` | Group column (two-sample / multi-group tests) |
| `--col1` | First column (`paired_t_test` / `chi_square`) |
| `--col2` | Second column (`paired_t_test` / `chi_square`) |
| `--export` | `csv` \| `json` |
| `--export-path` | Export file path. If it doesn't already end in `.csv`/`.json` (matching `--export`), the right extension is appended automatically. |
| `--yes` | Non-interactive mode: never prompt, error on missing required values |

---

## Errors

- `InvalidTestError` — unsupported `test` value
- `InsufficientDataError` — a sample/group has too few non-null observations for the test
- `InvalidGroupCountError` — `group_col` doesn't split the data into exactly 2 groups for a two-sample test
- `ColumnNotFoundError` — a required column isn't present in the DataFrame

---

## License

MIT — see `LICENSE`.
