Transfer-Function ITS: Graded Interventions with Saturation & Adstock Transforms

[drbenvincent]

This PR introduces Transfer-Function Interrupted Time Series (TF-ITS), a powerful new experiment class that extends CausalPy's causal inference capabilities to handle graded (non-binary) interventions in single-market time series data.

🎯 What This Adds

• Unlike traditional ITS methods that focus on binary on/off treatments, TF-ITS enables practitioners to:
• Model interventions with varying intensity (e.g., advertising spend, policy intensity, promotional campaigns)
• Account for diminishing returns through saturation transforms (Hill, logistic, Michaelis-Menten)
• Capture carryover effects using adstock transforms (geometric decay with configurable half-life)
• Estimate window-level causal lift by constructing counterfactuals with scaled or zeroed interventions

This makes TF-ITS particularly valuable for marketing mix modeling, policy evaluation, and any scenario where treatment intensity varies over time.

🔧 Implementation Details

MVP Scope (Non-Bayesian):

• Estimation: OLS regression with HAC standard errors (via statsmodels)
• Transforms: Leverages pymc-marketing transform library for saturation and adstock functions
• Counterfactuals: Flexible engine for computing treatment effects by scaling exposures in specified time windows
• Diagnostics: Residual ACF/PACF plots and Ljung-Box tests
• Visualization: Model fit plots and impulse response functions (IRF)

Architecture:

• Designed for future Bayesian extension following CausalPy conventions
• Modular transform system with dataclasses (Saturation, Adstock, Lag, Treatment)
• Clean separation between transform specification and application logic

📦 What's Included

• Core Implementation
  • causalpy/experiments/transfer_function_its.py: New TransferFunctionITS experiment class
  • causalpy/transforms.py: Transform dataclasses and application logic
• Testing
  • causalpy/tests/test_transfer_function_its.py: Comprehensive unit and integration tests
• Documentation
  • docs/source/notebooks/tfits_single_channel.ipynb: Tutorial notebook with simulated advertising example
  • Updated glossary with TF-ITS definition and key concepts
  • Citations to Box & Tiao (1975) intervention analysis literature
• Dependencies
  • Added pymc-marketing>=0.7.0 for transform functions

🎓 Example Use Case

The tutorial notebook demonstrates estimating the causal lift of a TV advertising flight campaign by:

1. Fitting a model with baseline controls (trend, seasonality) + transformed TV spend
2. Applying Hill saturation (diminishing returns) and geometric adstock (3-week half-life)
3. Computing counterfactual sales if TV spend had been zeroed during the flight window
4. Quantifying total and mean weekly lift with proper diagnostics

🚀 Why This Matters

This addition positions CausalPy as a comprehensive toolkit for time-series causal inference, complementing existing methods:

• RDD/IV: Cross-sectional causal inference
• DiD/Synthetic Control: Panel data methods
• ITS: Binary treatment time series
• TF-ITS (NEW): Graded treatment time series with realistic dose-response modeling

The non-Bayesian MVP enables fast prototyping and production deployment, while the architecture is ready for future Bayesian implementations that will provide full uncertainty quantification and hierarchical modeling capabilities.

---

Dependencies: Adds pymc-marketing>=0.7.0
Breaking Changes: None
Future Work: Bayesian estimation, parameter grid search, multi-channel attribution

---

📚 Documentation preview 📚: https://causalpy--548.org.readthedocs.build/en/548/

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[williambdean]

We avoided this intentionally with pymc-marketing. Is this the only way to implement this?

Reference:
https://williambdean.github.io/blog/posts/2024/pymc-marketing-strategy-pattern/

[drbenvincent]

Thanks for flagging this. Very early days on this PR, will look into changing it

[drbenvincent]

Hopefully resolved in 659b502

[codecov]

Codecov Report

❌ Patch coverage is 89.96898% with 97 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.10%. Comparing base (757d150) to head (4ebd026).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
causalpy/experiments/graded_intervention_its.py	84.04%	56 Missing ⚠️
causalpy/transform_optimization.py	80.43%	27 Missing ⚠️
causalpy/transforms.py	89.15%	9 Missing ⚠️
causalpy/skl_models.py	91.80%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #548      +/-   ##
==========================================
- Coverage   95.59%   94.10%   -1.50%     
==========================================
  Files          29       33       +4     
  Lines        2681     3648     +967     
==========================================
+ Hits         2563     3433     +870     
- Misses        118      215      +97     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.