Draft (new feature) : Model to estimate when a intervention had effect

[JeanVanDyk]

New Feature: InterventionTimeEstimator for Unknown Treatment Timing

This PR introduces a new model, InterventionTimeEstimator, designed to estimate when an intervention has an effect in a time series — especially in cases where the exact treatment time is unknown.

---

Use Case

• Enhances the Interrupted Time Series (ITS) feature by providing a way to infer the likely time of intervention
• Supports scenarios where the treatment onset is uncertain or delayed
• Helps identify lagged effects between intervention and observable outcomes

This addition gives users a flexible, Bayesian approach to model treatment timing uncertainty directly within the CausalPy framework.

---

Notes / Open Questions

• Where should this model fit into the CausalPy workflow?
  I’m unsure whether InterventionTimeEstimator should be integrated within the InterruptedTimeSeries (ITS) feature, or used as a standalone tool.
  This affects how a user-defined model could be supported.
  Depending on the intended usage, I can propose a solution to allow users to inject their own custom models.

• Custom model usage — base vs. intervention
  Should users be able to:

  • Provide a custom model to represent the base time series (e.g. intercept, trend, seasonality)?
  • Provide a custom model to capture the intervention effect (e.g. shape or dynamics of the post-switch impact)?
  • Or support both?

• Covariates
  I considered adding time-varying covariates to improve the fit. Would that be useful or out of scope?

• Multivariate Time Series
  It's relatively easy to extend the model for multivariate input. Let me know if this is something you'd like to see.

---

Model Summary

• Inputs:

  • t: 1D array of time points
  • y: 1D array of observed values
  • Optional span: restricts the window for switchpoint detection
  • Optional coords: can include seasons for modeling periodic effects
  • effect: list of components, e.g. "trend", "level", "impulse"
  • grain_season: number of time steps per season

• Model Components:

  • Time series is modeled as:
    intercept + trend + seasonal
  • A Uniform prior is used to place a switchpoint
  • A sigmoid curve models the onset of the effect after the switchpoint, applied to the selected effect components

---

Feel free to share any feedback or suggestions! I'm happy to refine the model or explore extensions based on your input.

---

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