TBR Quick Start Guide#

Welcome to the Time-Based Regression (TBR) Python package! This guide will help you get started with analyzing treatment effects in time series data.

Installation#

pip install tbr

Basic Usage#

1. Import and Prepare Data#

import pandas as pd
from tbr import TBRAnalysis

# Create or load your time series data
# Required columns: time, control group metric, test group metric
data = pd.DataFrame({
    'date': pd.date_range('2024-01-01', periods=90),
    'control': [1000, 1020, 980, ...],  # Control group values
    'test': [1010, 1035, 995, ...]      # Test group values
})

2. Initialize the Model#

# Create a TBR analysis instance
model = TBRAnalysis(
    level=0.80,        # 80% credibility level
    threshold=0.0      # Test if effect > 0
)

3. Fit the Model#

# Fit the model to your data
model.fit(
    data=data,
    time_col='date',
    control_col='control',
    test_col='test',
    pretest_start='2024-01-01',  # Start of pretest period
    test_start='2024-02-15',     # Start of test period
    test_end='2024-03-31'        # End of test period
)

4. Get Results#

# Get final summary
summary = model.summarize()
print(f"Treatment Effect: {summary.estimate:.2f}")
print(f"80% CI: [{summary.lower:.2f}, {summary.upper:.2f}]")
print(f"Significant: {summary.is_significant()}")

# Access detailed results
results_df = model.results_
predictions = model.predict()

Complete Example#

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

# Generate sample data
np.random.seed(42)
dates = pd.date_range('2024-01-01', periods=90)
control = np.random.normal(1000, 50, 90)
test = control * 1.02 + np.random.normal(0, 5, 90)  # 2% treatment effect

data = pd.DataFrame({
    'date': dates,
    'control': control,
    'test': test
})

# Run TBR analysis
model = TBRAnalysis(level=0.80, threshold=0.0)
model.fit(
    data=data,
    time_col='date',
    control_col='control',
    test_col='test',
    pretest_start='2024-01-01',
    test_start='2024-02-15',
    test_end='2024-03-31'
)

# Get results
summary = model.summarize()
print(f"Effect: {summary.estimate:.2f}")
print(f"CI: [{summary.lower:.2f}, {summary.upper:.2f}]")
print(f"P(effect > 0): {summary.prob:.3f}")

One-Liner Analysis#

# Quick analysis without storing model
summary = TBRAnalysis().fit_summarize(
    data, 'date', 'control', 'test',
    pretest_start='2024-01-01',
    test_start='2024-02-15',
    test_end='2024-03-31'
)
print(f"Effect: {summary.estimate:.2f}")

Next Steps#

Key Concepts#

Time Periods#

  • Pretest Period: Historical data used to learn the relationship between control and test

  • Test Period: Period where treatment is applied

  • Counterfactual: What the test would have been without treatment

Configuration Parameters#

  • level: Credibility level for confidence intervals (0 < level < 1)

  • threshold: Minimum effect size for probability calculations

  • test_end_inclusive: Whether to include the end date in analysis

Result Components#

  • estimate: Cumulative treatment effect

  • lower/upper: Credible interval bounds

  • prob: Posterior probability that effect exceeds threshold

  • precision: Inverse of variance (higher = more certain)

Common Use Cases#

Marketing Campaign Analysis#

Measure the incremental impact of a marketing campaign on sales or conversions.

A/B Testing#

Analyze treatment effects in controlled experiments with time series data.

Medical Trials#

Evaluate treatment effects in clinical studies with temporal components.

Economic Policy Analysis#

Assess the impact of policy interventions on economic indicators.

Feature Rollouts#

Measure the impact of new product features on user metrics.

Tips#

  1. Sufficient Pretest Data: Use at least 2x the test period length for pretest

  2. Stable Relationships: Ensure control-test relationship is stable in pretest

  3. Check Diagnostics: Use model diagnostics to validate assumptions

  4. Domain-Agnostic: Works with any time series where you have control and test groups

  5. Multiple Analyses: Re-fit the same model with different periods for comparisons

Getting Help#