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

pip install tlf-hypothesis-testing

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

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

Usage

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

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

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:

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:

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

CLI flags

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.