Metadata-Version: 2.4
Name: statpilot
Version: 1.1.0
Summary: Automated, transparent statistical analysis for researchers — picks the right test, explains why, and generates a publication-ready report.
Author: Md Mehedi Hassan
License: MIT
Project-URL: Homepage, https://github.com/mhashiq/statpilot
Project-URL: Documentation, https://statpilot.readthedocs.io
Project-URL: Repository, https://github.com/mhashiq/statpilot
Project-URL: Bug Tracker, https://github.com/mhashiq/statpilot/issues
Project-URL: Changelog, https://github.com/mhashiq/statpilot/blob/main/CHANGELOG.md
Project-URL: AuthBrain, https://www.authbrain.io
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.**

[![PyPI Version](https://img.shields.io/pypi/v/statpilot.svg?color=blue)](https://pypi.org/project/statpilot/)
[![Python Version](https://img.shields.io/pypi/pyversions/statpilot.svg)](https://pypi.org/project/statpilot/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Developed by AuthBrain](https://img.shields.io/badge/Developed%20by-AuthBrain-indigo.svg)](https://www.authbrain.io)
[![GitHub Repo](https://img.shields.io/badge/GitHub-mhashiq%2Fstatpilot-black?logo=github)](https://github.com/mhashiq/statpilot)
[![CI Build](https://github.com/mhashiq/statpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/mhashiq/statpilot/actions)

Developed by **[AuthBrain](https://www.authbrain.io)** • 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/](https://pypi.org/project/statpilot/)
- 💻 **GitHub Repository**: [https://github.com/mhashiq/statpilot](https://github.com/mhashiq/statpilot)
- 🐛 **Issue Tracker**: [https://github.com/mhashiq/statpilot/issues](https://github.com/mhashiq/statpilot/issues)
- 📖 **Documentation**: [https://statpilot.readthedocs.io](https://statpilot.readthedocs.io)
- 🏢 **Developer Site**: [https://www.authbrain.io](https://www.authbrain.io)

---

## 🚀 Quick Start

### Installation

Install StatPilot via `pip`:

```bash
pip install statpilot
```

---

## 💻 Python API Usage

```python
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:

```python
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:

```bash
# 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](https://github.com/mhashiq/statpilot) and click **Fork**.

2. **Clone your fork locally**:
   ```bash
   git clone https://github.com/mhashiq/statpilot.git
   cd statpilot
   ```

3. **Set up a development environment**:
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e ".[dev]"
   ```

4. **Make changes and run tests**:
   ```bash
   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](https://github.com/mhashiq/statpilot/blob/main/CONTRIBUTING.md) guide.

---

## 👥 Authors & Organization Credits

- **Author & Maintainer**: **Md Mehedi Hassan** ([GitHub: @mhashiq](https://github.com/mhashiq))
- **Developed by**: **[AuthBrain](https://www.authbrain.io)**

---

## 📄 License

StatPilot is open-source software licensed under the **[MIT License](https://github.com/mhashiq/statpilot/blob/main/LICENSE)**.
