tbr 0.1.4

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

TBR - Time-Based Regression Analysis Package

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

pip install tbr

Optional dependencies:

pip install tbr[dev]       # Development tools
pip install tbr[docs]      # Documentation tools
pip install tbr[examples]  # Example dependencies

Quick Start

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 file for details.

Support

• Issues: GitHub Issues