superstat 0.0.2
A comprehensive statistical test selection and analysis system with advanced assumption checking, Bayesian methods, and automated DataFrame analysis
Requires Python: >=3.8
Keywords: statistics, statistical-tests, data-analysis, bayesian, assumption-checking, dataframe-analysis, pydantic, scipy, pandas

# SuperStat: Comprehensive Statistical Test Selection System

A production-ready hierarchical statistical test selection system that provides comprehensive test coverage, advanced assumption checking, Bayesian methods integration, and modern statistical methods support.

[![PyPI version](https://badge.fury.io/py/superstat.svg)](https://badge.fury.io/py/superstat)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

### From PyPI (Recommended)

```bash
# Minimal installation (core functionality only)
pip install superstat

# Full installation (all features including Bayesian methods)
pip install superstat[full]

# Development installation (includes testing and development tools)
pip install superstat[dev]
```

### From Source

```bash
git clone https://github.com/superstat/superstat.git
cd superstat
pip install -e .
```

## Package Structure

```
superstat/
├── superstat/                    # Main package
│   ├── __init__.py              # Public API
│   ├── core/                    # Core functionality
│   │   ├── statistical_test_selector.py
│   │   ├── statistical_assumption_validator.py
│   │   └── pydantic_models.py
│   ├── analysis/                # Analysis modules
│   │   ├── dataframe_analyzer.py
│   │   ├── bayesian_integration.py
│   │   └── exec/                # Test execution engine
│   ├── utils/                   # Utilities
│   │   ├── validation_utils.py
│   │   └── json_serialization.py
│   ├── data/                    # Registry files
│   │   ├── statistical_tests_registry.json
│   │   └── bayesian_tests_registry.json
│   └── cli.py                   # Command line interface
├── tests/                         # Comprehensive test suite
│   ├── __init__.py
│   ├── conftest.py
│   ├── pytest.ini
│   ├── run_tests.py
│   ├── test_comprehensive_statistical_selector.py
│   ├── test_assumption_checker.py
│   ├── test_bayesian_integration.py
│   ├── test_pydantic_models.py
│   ├── test_validation_utils.py
│   ├── test_integration_demos.py
│   └── test_requirements.txt
├── demos/                         # Interactive demonstrations
│   ├── __init__.py
│   ├── advanced_assumption_demo.py
│   ├── bayesian_demo.py
│   ├── comprehensive_examples.py
│   ├── registry_extension_example.py
│   ├── pydantic_validation_example.py
│   ├── dataframe_analysis_demo.py
│   └── *.ipynb                    # Jupyter notebook versions
├── examples/                      # Simple usage examples
│   └── dataframe_analysis_example.py
├── docs/                          # Comprehensive documentation
│   ├── __init__.py
│   ├── COMPREHENSIVE_SELECTOR_README.md
│   ├── ADVANCED_ASSUMPTION_CHECKING_DOCUMENTATION.md
│   ├── ADVANCED_ASSUMPTION_CHECKING_SUMMARY.md
│   ├── BAYESIAN_INTEGRATION_DOCUMENTATION.md
│   ├── BAYESIAN_INTEGRATION_SUMMARY.md
│   ├── DATAFRAME_ANALYSIS_DOCUMENTATION.md
│   ├── PYDANTIC_IMPLEMENTATION_SUMMARY.md
│   ├── PROOF_OF_CONCEPT_SUMMARY.md
│   ├── REGISTRY_IMPLEMENTATION_SUMMARY.md
│   └── REGISTRY_SYSTEM_DOCUMENTATION.md
├── requirements.txt               # Core dependencies
├── requirements-dev.txt           # Development dependencies
├── requirements-minimal.txt       # Minimal dependencies
├── requirements-optional.txt      # Optional dependencies
└── README.md                      # This file
```

## Quick Start

### Basic Usage

#### Using the Python API

```python
import superstat
from superstat import analyze_dataframe_and_recommend_test
import pandas as pd

# Your DataFrame
df = pd.DataFrame({
    'outcome': [1, 2, 3, 4, 5],  # Your dependent variable
    'group': ['A', 'B', 'A', 'B', 'A'],  # Your independent variable
    'baseline': [10, 12, 11, 13, 10]  # Another independent variable
})

# One function call does everything!
result = analyze_dataframe_and_recommend_test(
    df, 
    dependent_vars=['outcome'], 
    independent_vars=['group', 'baseline'],
    research_goal='inferential'
)

print(f"Recommended Test: {result['test'].name}")
print(f"Reasoning: {result['metadata']['reasoning']}")
print(f"Assumptions: {', '.join(result['test'].assumptions)}")
```

#### Using the Command Line Interface

```bash
# Analyze a CSV file
superstat analyze data.csv --dependent outcome --independent group

# Get help
superstat --help
```

### Basic Usage

#### Manual Context Creation
```python
import sys
import os
sys.path.append('src')

from statistical_test_selector import (
    StatisticalTestSelector,
    create_analysis_context
)

# Initialize selector
selector = StatisticalTestSelector()

# Example 1: Independent samples t-test
context = create_analysis_context(
    research_goal="inferential",
    design_type="experimental",
    dv_type="continuous",
    iv_types=["categorical"],
    num_groups=2,
    repeated_measures=False
)

# Get test recommendation
test, metadata = selector.select_test(context)
print(f"Recommended Test: {test.name}")
print(f"Reasoning: {metadata['reasoning']}")
print(f"Assumptions: {', '.join(test.assumptions)}")
```

#### Automatic DataFrame Analysis (NEW!)
```python
import pandas as pd
import sys
sys.path.append('src')

from simple_dataframe_analyzer import analyze_dataframe_and_recommend_test

# Your DataFrame
df = pd.DataFrame({
    'outcome': [1, 2, 3, 4, 5],  # Your dependent variable
    'group': ['A', 'B', 'A', 'B', 'A'],  # Your independent variable
    'baseline': [10, 12, 11, 13, 10]  # Another independent variable
})

# One function call does everything!
result = analyze_dataframe_and_recommend_test(
    df, 
    dependent_vars=['outcome'], 
    independent_vars=['group', 'baseline'],
    research_goal='inferential'
)

print(f"Recommended Test: {result['test'].name}")
print(f"Reasoning: {result['metadata']['reasoning']}")
print(f"Assumptions: {', '.join(result['test'].assumptions)}")
```

### Advanced Usage Examples

#### Bayesian Analysis
```python
# Bayesian t-test with custom inference method
bayesian_context = create_analysis_context(
    research_goal="inferential",
    design_type="experimental",
    dv_type="continuous",
    iv_types=["categorical"],
    num_groups=2,
    bayesian_preference=True,
    bayesian_inference_method="nuts"
)

bayesian_test, bayesian_metadata = selector.select_test(bayesian_context)
print(f"Bayesian Test: {bayesian_test.name}")
print(f"Model Spec: {bayesian_metadata['bayesian_specific']}")
```

#### Non-parametric Alternative
```python
# Non-parametric test when normality assumptions are violated
nonparametric_context = create_analysis_context(
    research_goal="inferential",
    design_type="experimental",
    dv_type="continuous",
    iv_types=["categorical"],
    num_groups=2,
    distribution_assumptions={"normality": False}
)

test, metadata = selector.select_test(nonparametric_context)
if "alternative_test" in metadata:
    print(f"Primary: {metadata['primary_test'].name}")
    print(f"Alternative: {metadata['alternative_test'].name}")
```

#### Validation and Error Handling
```python
# Validate context before analysis
validation_result = selector.validate_context({
    "research_goal": "inferential",
    "design_type": "experimental",
    "dv_type": "continuous",
    "iv_types": ["categorical"],
    "num_groups": 2
})

if validation_result.is_valid:
    print("Context is valid")
else:
    print("Validation errors:")
    for error in validation_result.errors:
        print(f"- {error['field']}: {error['message']}")
```

## Running Demonstrations

### Interactive Demonstrations

All demonstrations are available as both Python scripts and Jupyter notebooks:

#### Advanced Assumption Checking
```bash
cd demos
python advanced_assumption_demo.py
# Or run the notebook version
jupyter notebook advanced_assumption_demo.ipynb
```

#### Bayesian Methods Integration
```bash
cd demos
python bayesian_demo.py
# Or run the notebook version
jupyter notebook bayesian_demo.ipynb
```

#### Comprehensive Examples
```bash
cd demos
python comprehensive_examples.py
# Or run the notebook version
jupyter notebook comprehensive_examples.ipynb
```

#### Registry Extension
```bash
cd demos
python registry_extension_example.py
# Or run the notebook version
jupyter notebook registry_extension_example.ipynb
```

#### Pydantic Validation
```bash
cd demos
python pydantic_validation_example.py
# Or run the notebook version
jupyter notebook pydantic_validation_example.ipynb
```

#### DataFrame Analysis (NEW!)
```bash
cd demos
python dataframe_analysis_demo.py
# Or run the notebook version
jupyter notebook dataframe_analysis_demo.ipynb
```

### Demo Features

Each demonstration showcases:
- **Real-world scenarios** with practical examples
- **Step-by-step workflows** for different analysis types
- **Error handling** and validation examples
- **Best practices** for statistical test selection
- **Interactive exploration** of the system capabilities

### DataFrame Analysis Features (NEW!)

The DataFrame analysis demos demonstrate:
- **Automatic variable type detection** from your data
- **Distribution analysis** and normality testing
- **Missing data analysis** with recommendations
- **One-click statistical test selection** from DataFrames
- **Bayesian analysis integration** with automatic model specification
- **Real-world data scenarios** with practical examples

## Key Features

### 🎯 Hierarchical Decision Structure
- **Level 1**: Research Goal (descriptive, inferential, predictive, exploratory)
- **Level 2**: Data Structure (variable types, design, sample characteristics)
- **Level 3**: Statistical Assumptions (distribution, independence, sample size)
- **Level 4**: Test Selection (primary test, alternatives, assumption checks)

### 📊 Comprehensive Test Coverage (40+ Tests)
- **Descriptive Analysis**: Central tendency, variability, distribution shape
- **Inferential Analysis**: Parametric and non-parametric tests, mixed-effects models
- **Predictive Analysis**: Linear/logistic regression, machine learning models
- **Exploratory Analysis**: Factor analysis, cluster analysis, PCA
- **Specialized Tests**: Survival analysis, time series, equivalence testing

### 🔍 Advanced Assumption Checking (21 Statistical Tests)
- **Normality Testing**: Shapiro-Wilk, Kolmogorov-Smirnov, Jarque-Bera, Anderson-Darling
- **Homogeneity of Variance**: Levene's, Bartlett's, Fligner-Killeen tests
- **Independence Testing**: Durbin-Watson, Breusch-Godfrey, Ljung-Box tests
- **Linearity Testing**: Pearson/Spearman correlation, polynomial comparison
- **Multicollinearity**: VIF, correlation analysis, condition index
- **Sphericity**: Mauchly's test, Greenhouse-Geisser epsilon
- **Homoscedasticity**: Breusch-Pagan, White, Goldfeld-Quandt tests

### 🧠 Bayesian Methods Integration (15+ Tests)
- **Bayesian Alternatives**: t-tests, ANOVA, regression, correlation, chi-square
- **Advanced Bayesian Methods**: Mixed-effects, survival, factor analysis, mediation
- **Bayesian Inference**: MCMC, variational, NUTS, HMC sampling
- **Model Comparison**: Bayes factors, model averaging, posterior predictive checks
- **Prior Sensitivity**: Multiple prior testing, convergence diagnostics

### 🛡️ Pydantic Validation & Type Safety
- **Comprehensive Validation**: Input validation with detailed error messages
- **Type Safety**: Strong typing with Pydantic models
- **Runtime Validation**: Automatic validation of analysis contexts and test data
- **Error Handling**: Detailed error messages with suggestions for fixes

### 📊 Automatic DataFrame Analysis (NEW!)
- **Variable Type Detection**: Automatically determines continuous, categorical, ordinal, count variables
- **Distribution Analysis**: Tests for normality, uniform, exponential, lognormal distributions
- **Missing Data Analysis**: Identifies patterns and provides handling recommendations
- **Relationship Detection**: Analyzes correlations, group sizes, and variable relationships
- **Context Generation**: Automatically creates analysis contexts from DataFrame structure
- **One-Click Analysis**: Single function call for complete statistical test selection

### 🛠️ Extensible Registry System
- **JSON-based** test definitions with runtime loading
- **Runtime extension** capabilities for adding new tests
- **Domain-specific** test additions and custom registries
- **Version control** for test definitions and updates

## Documentation

### Core Documentation
- **API Reference**: `docs/COMPREHENSIVE_SELECTOR_README.md` - Complete API documentation
- **Assumption Checking**: `docs/ADVANCED_ASSUMPTION_CHECKING_DOCUMENTATION.md` - Advanced assumption validation
- **Bayesian Integration**: `docs/BAYESIAN_INTEGRATION_DOCUMENTATION.md` - Bayesian methods guide
- **DataFrame Analysis**: `docs/DATAFRAME_ANALYSIS_DOCUMENTATION.md` - Automatic DataFrame analysis guide
- **DataFrame Quick Reference**: `docs/DATAFRAME_ANALYSIS_QUICK_REFERENCE.md` - Quick start guide
- **Registry System**: `docs/REGISTRY_SYSTEM_DOCUMENTATION.md` - Extending the system

### Implementation Guides
- **Pydantic Models**: `docs/PYDANTIC_IMPLEMENTATION_SUMMARY.md` - Data validation and type safety
- **Proof of Concept**: `docs/PROOF_OF_CONCEPT_SUMMARY.md` - System design rationale
- **Registry Implementation**: `docs/REGISTRY_IMPLEMENTATION_SUMMARY.md` - Technical implementation details

### Summary Documents
- **Assumption Checking Summary**: `docs/ADVANCED_ASSUMPTION_CHECKING_SUMMARY.md`
- **Bayesian Integration Summary**: `docs/BAYESIAN_INTEGRATION_SUMMARY.md`

## Testing

### Running Tests

```bash
# Run all tests
cd tests
python run_tests.py

# Run specific test modules
pytest test_comprehensive_statistical_selector.py
pytest test_assumption_checker.py
pytest test_bayesian_integration.py
pytest test_pydantic_models.py

# Run with coverage
pytest --cov=src --cov-report=html
```

### Test Structure

- **`test_comprehensive_statistical_selector.py`**: Core selector functionality
- **`test_assumption_checker.py`**: Assumption checking validation
- **`test_bayesian_integration.py`**: Bayesian methods integration
- **`test_pydantic_models.py`**: Data model validation
- **`test_validation_utils.py`**: Validation utilities
- **`test_integration_demos.py`**: Integration with demo scripts

### Test Coverage

The test suite provides comprehensive coverage of:
- All statistical test selection scenarios
- Bayesian method integration
- Pydantic model validation
- Assumption checking workflows
- Error handling and edge cases
- Registry system functionality

## Contributing

### Development Setup

1. **Clone and Install**:
   ```bash
   git clone <repository>
   cd decision_trees/new_decision_tree
   pip install -r requirements-dev.txt
   ```

2. **Run Tests**:
   ```bash
   cd tests
   python run_tests.py
   ```

3. **Code Style**:
   ```bash
   black src/ tests/ demos/
   flake8 src/ tests/ demos/
   mypy src/
   ```

### Contribution Guidelines

1. **Source Code**: Add new features in `src/`
2. **Tests**: Add comprehensive test cases in `tests/`
3. **Demos**: Add demonstration scripts in `demos/`
4. **Documentation**: Update documentation in `docs/`
5. **Registry**: Extend test registries in JSON files

### Adding New Tests

1. **Update Registry**: Add test definition to `statistical_tests_registry.json`
2. **Add Logic**: Implement selection logic in `statistical_test_selector.py`
3. **Write Tests**: Add test cases in appropriate test file
4. **Update Docs**: Document new test in relevant documentation

## License

This implementation is provided as a proof-of-concept for educational and research purposes.