tbr 0.1.0a1

A comprehensive, domain-agnostic Python package for Time-Based Regression (TBR) analysis

TBR - Time-Based Regression Analysis Package

⚠️ ALPHA RELEASE v0.1.0a1 ⚠️ This package is under active development. The API may change in future versions. For production use, please wait for the stable 1.0.0 release. Current release is primarily for name reservation and early community feedback.

A comprehensive, domain-agnostic Python package for Time-Based Regression (TBR) analysis. Perform rigorous statistical analysis of treatment/control group time series data across any industry - marketing, medical research, economics, and more.

🚧 Alpha Release Status

What's Available Now (v0.1.0a1):

• ✅ Core TBR functionality with 22 professional functions
• ✅ Domain-agnostic API for any treatment/control experiment
• ✅ Complete mathematical implementation with statistical rigor
• ✅ Professional code quality (type hints, documentation, testing)
• ✅ PyPI installation and basic usage examples

What's Coming in Future Releases:

• 🚧 High-level API classes (TBRAnalysis wrapper)
• 🚧 Comprehensive visualization tools
• 🚧 Extended documentation and tutorials
• 🚧 Performance optimizations
• 🚧 Additional statistical diagnostics

Roadmap to v1.0.0: See our Project Plan

🚀 Features

• Domain-Agnostic: Works with any treatment/control group time series data
• Comprehensive Analysis: Lift calculation, counterfactual predictions, statistical inference
• Statistical Rigor: Credible intervals, significance tests, posterior probability assessments
• Flexible: Daily and cumulative analysis, subinterval analysis, incremental analysis
• Production-Ready: Type hints, comprehensive testing, professional documentation
• PyPI Compatible: Easy installation and distribution

📦 Installation

Quick Install (PyPI)

# Basic installation (runtime dependencies only)
pip install tbr

# With development tools
pip install tbr[dev]

# With documentation tools
pip install tbr[docs]

# With example/tutorial dependencies
pip install tbr[examples]

# With everything
pip install tbr[dev,docs,examples]

Development Installation

Option 1: Automated Setup (Recommended)

# Clone the repository
git clone https://github.com/idohi/tbr.git
cd tbr

# If you have an existing virtual environment, deactivate it first
deactivate  # (optional, but recommended)

# Run the automated setup script - handles everything!
./scripts/setup.sh

What the setup script does:

• ✅ Checks and installs Python 3.11.9 (via pyenv)
• ✅ Creates/resets virtual environment (removes existing if found)
• ✅ Installs package with all optional dependencies (pip install -e ".[dev,docs,examples]")
• ✅ Sets up pre-commit hooks
• ✅ Verifies everything works correctly

Requirements:

• pyenv installed (installation guide)

First-time setup example:

# 1. Install pyenv (if not already installed)
# macOS: brew install pyenv
# Linux: curl https://pyenv.run | bash

# 2. Clone and setup
git clone https://github.com/idohi/tbr.git
cd tbr
./scripts/setup.sh

# 3. Activate environment and start developing
source .venv/bin/activate
make test  # Run tests to verify everything works

Option 2: Manual Setup

# Clone the repository
git clone https://github.com/idohi/tbr.git
cd tbr

# Install Python 3.11.9 (if using pyenv)
pyenv install 3.11.9
pyenv local 3.11.9

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Upgrade pip and install package with all dependencies
pip install --upgrade pip
pip install -e ".[dev,docs,examples]"

🛠️ Development Workflow

This project uses a comprehensive development workflow with automated tools:

Quick Commands

make help          # Show all available commands
make setup         # Complete environment setup
make test          # Run tests
make lint          # Run linting
make format        # Format code
make build         # Build package
make all           # Run complete pipeline

Development Tools

• Testing: pytest with coverage reporting
• Code Quality: black, isort, ruff, mypy
• Pre-commit: Automated code quality checks
• Documentation: sphinx with RTD theme
• Build: build system for PyPI distribution

Environment Management

• Python Version: 3.11.9 (managed with pyenv)
• Dependencies: pip-tools for locked requirements
• Virtual Environment: .venv for isolation

🔧 Troubleshooting Setup

Reset Environment

If you need to reset your development environment:

deactivate              # Exit current virtual environment
./scripts/setup.sh      # Script automatically removes old .venv and creates fresh one

Manual Environment Reset

deactivate              # Exit current virtual environment
rm -rf .venv           # Remove virtual environment
./scripts/setup.sh      # Run setup script

Common Issues

• pyenv: command not found: Install pyenv first (guide)
• Permission denied: Make script executable with chmod +x scripts/setup.sh
• Python version issues: The script will install Python 3.11.9 automatically
• Dependency conflicts: The setup script creates a clean environment each time

📚 Quick Start (Alpha API)

Note: The high-level TBRAnalysis class is coming in future releases. Currently available: functional API.

import pandas as pd
import numpy as np
from tbr.functional import perform_tbr_analysis

# Example: Create time series data (date, control, test columns)
np.random.seed(42)
dates = pd.date_range('2023-01-01', periods=100, freq='D')
data = pd.DataFrame({
    'date': dates,
    'control': np.random.normal(100, 10, 100),  # Control group metric
    'test': np.random.normal(105, 10, 100)      # Treatment group metric
})

# Run TBR analysis
tbr_results, summary_results = perform_tbr_analysis(
    data=data,
    date_col='date',
    control_col='control',
    test_col='test',
    pretest_start='2023-01-01',  # Start of baseline period
    test_start='2023-02-15',     # Start of treatment period
    test_end='2023-04-10',       # End of analysis period
    level=0.80,                  # Confidence level for intervals
    threshold=0.0                # Threshold for significance testing
)

# View results
print("TBR Analysis Results:")
print(summary_results)

# The results contain:
# - Incremental lift estimates with credible intervals
# - Cumulative effects over time
# - Statistical significance tests
# - Posterior probability assessments

What the Analysis Provides

• Counterfactual Predictions: What would have happened without treatment
• Lift Calculations: Treatment effect with statistical uncertainty
• Credible Intervals: Bayesian confidence bounds using t-distribution
• Significance Testing: Posterior probability of positive/negative effects
• Time Series Output: Daily and cumulative analysis over treatment period

📖 Documentation

• API Reference: Full documentation
• Examples: See examples/ directory
• Notebooks: Interactive tutorials in notebooks/
• Mathematical Details: See references/tbr_parameter_derivations.md

🧪 Testing

# Run all tests
make test

# Run with coverage
make test-cov

# Run specific test file
pytest tests/unit/test_core.py -v

# Run mathematical validation tests
pytest tests/mathematical/ -v

🔧 Project Structure

tbr/
├── src/tbr/                 # Main package
│   ├── core/               # Core TBR functionality
│   ├── functional/         # Functional implementation
│   ├── analysis/           # Analysis tools
│   ├── utils/              # Utilities
│   └── visualization/      # Plotting tools
├── tests/                  # Test suite
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   ├── mathematical/      # Mathematical validation
│   └── performance/       # Performance tests
├── docs/                   # Documentation
├── examples/              # Usage examples
├── notebooks/             # Jupyter tutorials
├── scripts/               # Development scripts
└── references/            # Mathematical references

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Run ./scripts/setup.sh for complete environment setup
3. Create a feature branch
4. Make your changes with tests
5. Run make all to validate
6. Submit a pull request

Code Quality

• All code must pass make check (linting, type checking, formatting)
• Tests required for new features
• Documentation for public APIs
• Follow existing code style

📊 Mathematical Foundation

TBR analysis is based on rigorous statistical methods:

• Ordinary Least Squares (OLS) regression
• Counterfactual prediction with uncertainty quantification
• Bayesian inference for credible intervals
• Variance decomposition (model uncertainty + residual noise)
• Statistical significance testing

For detailed mathematical derivations, see references/tbr_parameter_derivations.md.

🔄 Version Compatibility

• Python: 3.8+ (tested on 3.8, 3.9, 3.10, 3.11, 3.12)
• pandas: 2.0+
• numpy: 1.24+
• scipy: 1.10+
• statsmodels: 0.14+

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by Google's GeoexperimentsResearch R package
• Built with modern Python best practices
• Designed for the data science community

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Read the Docs

---

Made with ❤️ for the data science community