Metadata-Version: 2.4
Name: tbr
Version: 0.1.3
Summary: A comprehensive, domain-agnostic Python package for Time-Based Regression (TBR) analysis
Author-email: Ido Hirsh <idohirsh@users.noreply.github.com>
Maintainer-email: Ido Hirsh <idohirsh@users.noreply.github.com>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/idohi/tbr
Project-URL: Repository, https://github.com/idohi/tbr
Project-URL: Documentation, https://tbr.readthedocs.io/
Project-URL: Bug Tracker, https://github.com/idohi/tbr/issues
Project-URL: Changelog, https://github.com/idohi/tbr/blob/main/CHANGELOG.md
Keywords: time-based-regression,tbr,causal-inference,statistics,data-science,regression-analysis,treatment-control,time-series
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas<2.0.0,>=1.5.0; python_version < "3.9"
Requires-Dist: pandas~=2.0.0; python_version >= "3.9"
Requires-Dist: numpy<1.25.0,>=1.21.0; python_version < "3.9"
Requires-Dist: numpy~=1.24.0; python_version >= "3.9"
Requires-Dist: scipy<1.11.0,>=1.9.0; python_version < "3.9"
Requires-Dist: scipy~=1.10.0; python_version >= "3.9"
Requires-Dist: statsmodels<0.15.0,>=0.13.0; python_version < "3.9"
Requires-Dist: statsmodels~=0.14.0; python_version >= "3.9"
Requires-Dist: lazy_loader>=0.1
Requires-Dist: psutil>=5.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: tox>=4.0.0; extra == "dev"
Requires-Dist: pydocstyle[toml]>=6.3.0; extra == "dev"
Requires-Dist: interrogate>=1.5.0; extra == "dev"
Requires-Dist: vulture>=2.7; extra == "dev"
Requires-Dist: psutil>=5.9.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Provides-Extra: examples
Requires-Dist: jupyter>=1.0.0; extra == "examples"
Requires-Dist: matplotlib~=3.7.0; extra == "examples"
Requires-Dist: seaborn~=0.12.0; extra == "examples"
Dynamic: license-file

# TBR - Time-Based Regression Analysis Package

[![PyPI version](https://badge.fury.io/py/tbr.svg)](https://badge.fury.io/py/tbr)
[![Build Status](https://github.com/idohi/tbr/workflows/CI/badge.svg)](https://github.com/idohi/tbr/actions)
[![Coverage Status](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/idohi/tbr/actions)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Development Status](https://img.shields.io/badge/status-beta-yellow.svg)](https://pypi.org/project/tbr/)

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.

## Status: Beta

**TBR** is feature-complete and ready for production use with:
- Complete TBR functionality (functional + OOP APIs)
- 1,200+ tests with 100% code coverage
- Intuitive, type-safe API interfaces
- Export utilities (JSON, CSV)
- Performance validated (linear O(n) scalability)
- Cross-platform support (Python 3.8-3.12)

**Why Beta?** While comprehensively tested, we're gathering real-world feedback before declaring v1.0 stable. We encourage production use and welcome your feedback!

## 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**: Temporal and cumulative analysis, subinterval analysis, incremental analysis
- **Well-Tested**: Type hints, 100% code coverage, comprehensive test suite
- **Easy to Use**: Simple, intuitive API for both quick analysis and advanced workflows

## Installation

```bash
pip install tbr
```

Optional dependencies:
```bash
pip install tbr[dev]       # Development tools
pip install tbr[docs]      # Documentation tools
pip install tbr[examples]  # Example dependencies
```

## Quick Start

```python
import pandas as pd
import numpy as np
from tbr import TBRAnalysis

# Create example time series data
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),
    'test': np.random.normal(105, 10, 100)
})

# Initialize and fit model
model = TBRAnalysis(level=0.90)
model.fit(
    data=data,
    time_col='date',
    control_col='control',
    test_col='test',
    pretest_start='2023-01-01',
    test_start='2023-02-15',
    test_end='2023-04-10'
)

# Get results
summary = model.summarize()
print(f"Treatment Effect: {summary.estimate:.2f}")
print(f"95% CI: [{summary.ci_lower:.2f}, {summary.ci_upper:.2f}]")
print(f"Significant: {summary.is_significant()}")

# Additional capabilities
predictions = model.predict()
subinterval = model.analyze_subinterval(start_day=1, end_day=10)
incremental = model.summarize_incremental()
summary.to_json('results.json')
```

## Key Capabilities

- **Counterfactual Predictions**: Estimates what would have happened without treatment
- **Lift Calculations**: Treatment effect with statistical uncertainty quantification
- **Credible Intervals**: Bayesian confidence bounds using t-distribution
- **Significance Testing**: Posterior probability of positive/negative effects
- **Flexible Analysis**: Subinterval analysis, incremental tracking, custom confidence levels

## Mathematical Foundation

TBR analysis implements rigorous statistical methods based on Ordinary Least Squares (OLS) regression, counterfactual prediction with uncertainty quantification, Bayesian inference for credible intervals, and variance decomposition.

## Documentation

- **Examples**: See `examples/` directory in the repository
- **Full Documentation**: Coming in v0.2.0

## 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 BSD-3-Clause License - see the [LICENSE](https://github.com/idohi/tbr/blob/main/LICENSE) file for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/idohi/tbr/issues)
