Metadata-Version: 2.4
Name: statpilot
Version: 0.1.0
Summary: Automated, transparent statistical analysis for researchers — picks the right test, explains why, and generates a publication-ready report.
Author: StatPilot Contributors
License: MIT
Project-URL: Homepage, https://github.com/your-org/statpilot
Project-URL: Documentation, https://statpilot.readthedocs.io
Project-URL: Repository, https://github.com/your-org/statpilot
Project-URL: Bug Tracker, https://github.com/your-org/statpilot/issues
Project-URL: Changelog, https://github.com/your-org/statpilot/blob/main/CHANGELOG.md
Keywords: statistics,data analysis,hypothesis testing,ANOVA,t-test,automated statistics,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.11
Requires-Dist: numpy>=1.24
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.13
Requires-Dist: rich>=13.0
Requires-Dist: click>=8.1
Requires-Dist: jinja2>=3.1
Requires-Dist: scikit-posthocs>=0.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mkdocs>=1.5; extra == "dev"
Requires-Dist: mkdocs-material>=9.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: nbformat; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Dynamic: license-file

# StatPilot 🧭

**Automated, transparent statistical analysis for researchers.**

StatPilot picks the right statistical test for your data, explains *why* it chose it, and generates a publication-ready report — all from a single function call.

[![CI](https://github.com/your-org/statpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/statpilot/actions)
[![PyPI version](https://badge.fury.io/py/statpilot.svg)](https://badge.fury.io/py/statpilot)
[![Coverage](https://codecov.io/gh/your-org/statpilot/branch/main/graph/badge.svg)](https://codecov.io/gh/your-org/statpilot)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

---

## The problem

Running statistics correctly involves a sequence of decisions most researchers make inconsistently:

1. Check normality — but which test? Shapiro-Wilk? Visual inspection?
2. Check variance homogeneity — but only when normality holds?
3. Pick the right test — but which of t-test, Welch, Mann-Whitney, ANOVA, Kruskal-Wallis?
4. Calculate effect size — but Cohen's d, eta-squared, or rank-biserial?
5. Write it up — in a reproducible, auditable way.

StatPilot automates this entire chain with a transparent decision engine that shows its work.

---

## Quick start

```bash
pip install statpilot
```

```python
import pandas as pd
from statpilot import compare

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

result = compare(df, target="score", group="treatment")

result.summary()  # prints a rich table to the terminal
result.plot()  # shows a boxplot + distribution
result.to_report()  # returns a Markdown string ready to paste into your paper
```

### What the output looks like

```
┌─────────────────────────────────────────────────────┐
│               StatPilot Result                      │
├─────────────────────────────────────────────────────┤
│ Test selected:   Independent samples t-test         │
│ Statistic:       t = 4.21                           │
│ p-value:         0.0003 ***                         │
│ Effect size:     Cohen's d = 0.87 (large)           │
├─────────────────────────────────────────────────────┤
│ Why this test?                                      │
│  • 2 independent groups detected                    │
│  • Normality: passed (Shapiro-Wilk, α=0.05)        │
│  • Variance equality: passed (Levene, α=0.05)      │
│  → Independent samples t-test is appropriate       │
└─────────────────────────────────────────────────────┘
```

---

## CLI usage

```bash
# Compare two groups from a CSV file
statpilot compare --data my_data.csv --target score --group treatment

# Save a Markdown report
statpilot compare --data my_data.csv --target score --group treatment --report report.md

# Paired comparison
statpilot compare --data my_data.csv --target score --group condition --paired
```

---

## Supported tests (v0.1)

| Scenario | Test selected |
|---|---|
| 2 groups, normal, equal variance | Independent t-test |
| 2 groups, normal, unequal variance | Welch's t-test |
| 2 groups, non-normal | Mann-Whitney U |
| 2 groups, paired, normal | Paired t-test |
| 2 groups, paired, non-normal | Wilcoxon signed-rank |
| 3+ groups, normal, equal variance | One-way ANOVA |
| 3+ groups, otherwise | Kruskal-Wallis |

---

## Why not just use pingouin or statsmodels?

[pingouin](https://pingouin-stats.org/) and [statsmodels](https://www.statsmodels.org/) are excellent libraries — StatPilot uses them under the hood. The difference is the **automated decision layer**: with pingouin, you still choose which function to call. StatPilot runs the assumption checks and makes that choice for you, and documents the reasoning in the output.

---

## Installation for development

```bash
git clone https://github.com/your-org/statpilot.git
cd statpilot
pip install -e ".[dev]"
pytest
```

---

## Documentation

Full documentation at **[statpilot.readthedocs.io](https://statpilot.readthedocs.io)** — including the decision engine concept guide, API reference, and example notebooks.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and feature requests welcome via [GitHub Issues](https://github.com/your-org/statpilot/issues).

---

## Citation

If you use StatPilot in your research, please cite it. A DOI is available via [Zenodo](https://zenodo.org) after each tagged release.

---

## License

[MIT](LICENSE) — free to use in academic and commercial projects.
