https://github.com/moderndive/moderndive-python
https://github.com/moderndive/moderndive-python
Last synced: 10 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/moderndive/moderndive-python
- Owner: moderndive
- License: mit
- Created: 2026-06-18T21:55:05.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-19T01:04:52.000Z (about 1 month ago)
- Last Synced: 2026-06-19T02:17:52.260Z (about 1 month ago)
- Language: Python
- Size: 12.8 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: code-of-conduct.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
# moderndive (Python)
[](https://github.com/moderndive/moderndive-python/actions/workflows/tests.yml) [](https://codecov.io/gh/moderndive/moderndive-python) [](https://moderndive.readthedocs.io/en/latest/) [](LICENSE)
The Python companion package for **ModernDive: Statistical Inference via Data Science** — a faithful port of the R [`moderndive`](https://moderndive.github.io/moderndive/) and [`infer`](https://infer.tidymodels.org) packages to a modern Python data-science stack ([polars](https://pola.rs), [plotly](https://plotly.com/python/), [plotnine](https://plotnine.org), [statsmodels](https://www.statsmodels.org)).
📖 **Documentation (with runnable examples): **
It is intentionally **pure-Python** (no compiled extensions) so it installs under [Pyodide](https://pyodide.org) via `micropip` for in-browser execution.
## Installation
``` bash
pip install moderndive # from PyPI
# or, from source:
pip install git+https://github.com/moderndive/moderndive-python
```
## What’s inside
- **A tidy simulation-inference grammar** mirroring R `infer`: `specify → hypothesize → generate → calculate`, plus `fit()` for multiple regression, `observe()`, and `assume()` (theoretical t/z/F/Chisq). `specify()` is also available as a DataFrame method, so you can write `df.specify(...)` just like R’s `df %>% specify(...)`. `calculate(stat=...)` takes the full infer vocabulary **or any custom callable** test statistic. Summaries via `get_p_value` / `get_confidence_interval` (percentile, SE, bias-corrected); British-spelling and short aliases included.
- **Dual-engine plots**: `visualize` / `shade_p_value` / `shade_confidence_interval` (and every plot helper) take `engine="plotly"` (default, interactive) or `engine="plotnine"` — same code, your choice of output.
- **Theory-based wrapper tests**: `t_test`, `prop_test`, `chisq_test`, `t_stat`, `chisq_stat`, plus the `moderndive.theory` module.
- **Regression & summary helpers** mirroring R `moderndive`: `get_regression_table`, `get_regression_points`, `get_regression_summaries`, `get_correlation`, `pop_sd`, `tidy_summary`, `count_missing` (built on `statsmodels` where relevant, returning `polars` frames), plus the model plots `gg_parallel_slopes` / `geom_parallel_slopes` and `gg_categorical_model` / `geom_categorical_model`, and `pairplot` (the `GGally::ggpairs` analog).
- **Sampling**: `rep_slice_sample` / `rep_sample_n` for sampling-distribution activities.
- **58 datasets**: `load_*()` loaders returning `polars` DataFrames (the `moderndive`/`infer`, `nycflights23`, `gapminder`, ISLR2, and FiveThirtyEight datasets used in the book).
## Quick start
Are tracks more likely to be popular in *metal* than in *deep house*? Compute the observed difference in “popular” rates, then permute the genre labels 1000 times to build a null distribution and read off a p-value.
``` python
import moderndive as md
from moderndive import get_p_value, visualize, shade_p_value
spotify = md.load_spotify_metal_deephouse()
# Observed difference in popularity rates (metal − deep house)
obs = (
spotify
.specify(formula="popular_or_not ~ track_genre", success="popular")
.calculate(stat="diff in props", order=("metal", "deep-house"))
)
obs
```
ObservedStatistic(stat='diff in props', value=0.034)
``` python
# Permutation null distribution + p-value
null = (
spotify
.specify(formula="popular_or_not ~ track_genre", success="popular")
.hypothesize(null="independence")
.generate(reps=1000, type="permute", seed=76)
.calculate(stat="diff in props", order=("metal", "deep-house"))
)
print(get_p_value(null, obs_stat=obs, direction="right"))
```
shape: (1, 1)
┌─────────┐
│ p_value │
│ --- │
│ f64 │
╞═════════╡
│ 0.075 │
└─────────┘
``` python
# Visualize — interactive plotly by default; engine="plotnine" for ggplot-style
visualize(null) + shade_p_value(obs_stat=obs, direction="right")
```
## Development
This repo uses [uv](https://docs.astral.sh/uv/).
``` bash
uv sync --extra dev # create the environment
make test # run the test suite (enforces 100% coverage)
make readme # re-render README.md from README.qmd (needs Quarto)
make build-data # rebuild the bundled Parquet datasets (needs R; see tools/)
make build # build the wheel/sdist
```
The test suite is held at **100% statement coverage** (enforced in CI via `--cov-fail-under=100`). Releases are automated on `v*` tags — see [RELEASING.md](RELEASING.md).
## License
MIT. The ModernDive book *content* is licensed CC-BY-NC-SA 4.0; this *software package* is MIT-licensed.