Transfer-Function ITS: Graded Interventions with Saturation & Adstock Transforms #548
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
williambdean
reviewed
Nov 3, 2025
causalpy/transforms.py
Outdated
|
|
||
|
|
||
| @dataclass | ||
| class Saturation: |
Contributor
There was a problem hiding this comment.
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/
Collaborator
Author
There was a problem hiding this comment.
Thanks for flagging this. Very early days on this PR, will look into changing it
Refactored transform classes to use a strategy pattern with explicit Adstock, Saturation, and Lag implementations. Added transform_optimization.py for grid search and optimization of transform parameters. Updated TransferFunctionITS to support transform parameter estimation and metadata. Revised tests to use new transform classes and parameter estimation workflows.
Expanded and clarified docstrings in transfer_function_its.py to document the nested parameter estimation approach for saturation and adstock transforms. Updated the example and usage instructions to reflect the new estimation workflow. Revised the notebook to demonstrate transform parameter estimation via grid search, show parameter recovery, and clarify the distinction between grid search and continuous optimization. Removed the outdated and redundant test class for TransferFunctionITS in test_transfer_function_its.py.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #548 +/- ##
==========================================
+ Coverage 95.59% 95.73% +0.13%
==========================================
Files 29 34 +5
Lines 2681 5108 +2427
==========================================
+ Hits 2563 4890 +2327
- Misses 118 218 +100 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Expanded documentation and code comments to better explain HAC (Newey-West) standard errors, their purpose, and the hac_maxlags parameter. Added a detailed explanation and citation in the notebook, and improved docstrings and print output in transfer_function_its.py. Added the Newey-West reference to references.bib.
Expanded the TF-ITS notebook with a detailed explanation of autocorrelation in time series, its impact on causal inference, and the motivation for using HAC (Newey-West) standard errors. Updated the simulation to generate autocorrelated errors using an AR(1) process, and clarified the importance of robust inference in the context of time series interventions.
Extended TransferFunctionITS and transform optimization to support ARIMAX (ARIMA with exogenous variables) error models in addition to HAC standard errors. Updated model fitting, parameter estimation, and documentation to allow users to specify error_model ('hac' or 'arimax') and ARIMA order. Added comprehensive tests for ARIMAX functionality and updated the notebook to demonstrate ARIMAX usage and comparison with HAC.
Refactors GradedInterventionTimeSeries and TransferFunctionOLS to follow the standard CausalPy pattern: the experiment class now takes an unfitted model and handles transform parameter estimation, fitting, and result extraction. Removes the with_estimated_transforms factory method, updates all docstrings, and adapts tests and documentation to the new workflow. This enables more flexible and consistent usage for multi-treatment and advanced modeling scenarios.
Introduces new plotting methods to GradedInterventionTimeSeries, including plot_effect and plot_transforms, and renames diagnostics() to plot_diagnostics(). Updates tests to cover new plotting features. Enhances documentation and notebook explanations for model fitting and parameter estimation, and updates the interrogate badge.
Renamed 'tfits_single_channel.ipynb' to 'graded_intervention_time_series_single_channel_ols.ipynb' and updated the notebook title and references in both the notebook and the index.md file to reflect the new name and description.
Refactored transfer function parameter estimation and plotting to allow models with only adstock or only saturation transforms (or both). Updated validation logic, grid/optimize routines, and plotting to handle optional transforms. Added comprehensive tests for all transform configurations and clarified documentation and notebook to demonstrate adstock-only use case.
Added detailed documentation explaining challenges of AR error modeling in PyMC, why standard approaches fail, and the rationale for using quasi-differencing in TransferFunctionARRegression. Also clarified alternative latent AR component modeling and why it is not used, providing guidance on when to use each model.
Introduces a separate 'ar_sample_kwargs' dictionary for Bayesian AR(1) model sampling in the transfer function test. Updates assertions to reference the new parameters, clarifying the need for increased sampling due to model complexity.
Added a citation for pymc-marketing to references.bib and updated the graded intervention time series notebook to explain the use of transformation functions from pymc-marketing for modeling temporal and intensity dynamics.
Clarified the rationale for HAC standard errors, improved the explanation of autocorrelation and heteroskedasticity, and streamlined the discussion of advantages and tradeoffs. Updated ARIMAX section reference for consistency.
drbenvincent
requested review from
NathanielF,
cetagostini,
juanitorduz and
williambdean
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
One reason why it's exciting is that it starts to create a bridge between CausalPy and pymc-marketing.
🎯 What This Adds
Unlike traditional ITS methods that focus on binary on/off treatments, TF-ITS enables practitioners to:
This makes TF-ITS particularly valuable for marketing mix modeling, policy evaluation, and any scenario where treatment intensity varies over time.
🔧 Implementation Details
Architecture:
Dependencies: Adds pymc-marketing>=0.7.0
Breaking Changes: None
Future Work: Multiple intervention channels (this may be close to working, but just not worked through an example). Add another notebook directly focussing on a marketing-based case study.
📚 Documentation preview 📚: https://causalpy--548.org.readthedocs.build/en/548/