StatPilot 🧭

Automated, transparent statistical analysis for researchers.

Developed by AuthBrain • Created & Maintained by Md Mehedi Hassan

---

🌟 Overview

StatPilot simplifies statistical workflows for data scientists and academic researchers by automating group comparisons.

Instead of manually checking assumptions across multiple statistical software tools, StatPilot evaluates your dataset's distribution, runs assumption diagnostics (Shapiro-Wilk normality and Levene's test for variance homogeneity), selects the appropriate parametric or non-parametric test, computes effect sizes, and outputs a transparent, audit-ready report.

Key Features

• 🧠 Automated Decision Engine: Picks the right test based on group count, pairing, normality, and variance.
• 🔍 Transparent Diagnostics: Documents why a test was chosen with step-by-step reasoning.
• 📊 Rich Terminal Summaries & Plots: Clean terminal tables via Rich, and publication-ready distribution plots via Seaborn.
• 📄 Publication-Ready Markdown Reports: Export full statistical write-ups directly for academic manuscripts.
• 🛠️ CLI & Python API: Use StatPilot seamlessly in Python scripts, Jupyter notebooks, or directly from the terminal.

---

🔗 Quick Links

• 📦 PyPI Package: https://pypi.org/project/statpilot/
• 💻 GitHub Repository: https://github.com/mhashiq/statpilot
• 🐛 Issue Tracker: https://github.com/mhashiq/statpilot/issues
• 📖 Documentation: https://statpilot.readthedocs.io
• 🏢 Developer Site: https://www.authbrain.io

---

🚀 Quick Start

Installation

Install StatPilot via pip:

pip install statpilot

---

💻 Python API Usage

import pandas as pd
from statpilot import compare

# 1. Load your tabular data
df = pd.read_csv("my_experimental_data.csv")

# 2. Run automated statistical comparison
result = compare(df, target="response_time", group="treatment_group")

# 3. View terminal summary table with reasoning
result.summary()

# 4. Display distribution and boxplot graphics
result.plot()

# 5. Generate Markdown report for manuscript submission
report_md = result.to_report()
print(report_md)

Working with Built-in Datasets

StatPilot comes with standard benchmark datasets for immediate testing:

from statpilot.datasets import load_penguins, load_iris
from statpilot import compare

# Load penguins dataset
df = load_penguins()

# Compare flipper length across species
result = compare(df, target="flipper_length_mm", group="species")
result.summary()

---

🖥️ Command Line Interface (CLI)

StatPilot provides a full-featured CLI tool:

# Compare two groups from a CSV file
statpilot compare --data research_data.csv --target score --group condition

# Save an automated Markdown report to disk
statpilot compare --data research_data.csv --target score --group condition --report report.md

# Paired analysis for repeated measurements
statpilot compare --data pre_post_data.csv --target value --group timepoint --paired

---

📊 Decision Matrix

StatPilot automates assumption testing and selects tests according to standard statistical decision trees:

Group Count	Paired / Repeated	Normality (Shapiro-Wilk)	Equal Variance (Levene's)	Test Selected	Effect Size Metric
2 Groups	No	Normal ($\alpha=0.05$)	Equal ($\alpha=0.05$)	Independent Samples t-test	Cohen's d
2 Groups	No	Normal ($\alpha=0.05$)	Unequal ($\alpha<0.05$)	Welch's t-test	Cohen's d
2 Groups	No	Non-Normal ($\alpha<0.05$)	N/A	Mann-Whitney U	Rank-Biserial r
2 Groups	Yes	Normal ($\alpha=0.05$)	N/A	Paired Samples t-test	Cohen's d
2 Groups	Yes	Non-Normal ($\alpha<0.05$)	N/A	Wilcoxon Signed-Rank	Rank-Biserial r
3+ Groups	No	Normal ($\alpha=0.05$)	Equal ($\alpha=0.05$)	One-Way ANOVA	Eta-squared ($\eta^2$)
3+ Groups	No	Non-Normal / Heterogeneous	N/A	Kruskal-Wallis H	Epsilon-squared ($\epsilon^2$)

---

🤝 How to Contribute

Contributions are warmly welcomed! You can contribute code, documentation, bug fixes, or new statistical methods.

Step-by-Step Contribution Guide

1. Fork the GitHub Repository: Navigate to https://github.com/mhashiq/statpilot and click Fork.

2. Clone your fork locally:

   git clone https://github.com/mhashiq/statpilot.git
   cd statpilot

3. Set up a development environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e ".[dev]"

4. Make changes and run tests:

   pytest
   ruff check .
   ruff format .

5. Submit a Pull Request: Push your changes to a feature branch on your fork and open a Pull Request against main.

For more details, check out our full CONTRIBUTING.md guide.

---

👥 Authors & Organization Credits

• Author & Maintainer: Md Mehedi Hassan (GitHub: @mhashiq)
• Developed by: AuthBrain

---

📄 License

StatPilot is open-source software licensed under the MIT License.