Add check and warning for staggered adoption in EventStudy

Added a warning in the EventStudy class and documentation that the implementation only supports simultaneous treatment timing and does not support staggered adoption. Introduced a validation to raise a DataException if treated units have different treatment times. Added a corresponding test to ensure staggered adoption raises an error, and updated the notebook to clarify estimator limitations.

Author: drbenvincent

causalpy/experiments/event_study.py

@@ -55,6 +55,14 @@ class EventStudy(BaseExperiment):
     - :math:`\\beta_k` are the dynamic treatment effects at event time k
     - :math:`k_0` is the reference (omitted) event time
 
+    .. warning::
+
+        This implementation uses a standard two-way fixed effects (TWFE) estimator,
+        which requires **simultaneous treatment timing** (all treated units receive
+        treatment at the same time). Staggered adoption designs, where different units
+        are treated at different times, can produce biased estimates when treatment
+        effects vary across cohorts. See Sun & Abraham (2021) for details.
+
     Parameters
     ----------
     data : pd.DataFrame
@@ -197,6 +205,19 @@ def input_validation(self) -> None:
                 "Each unit should have at most one observation per time period."
             )
 
+        # Check that all treated units have the same treatment time
+        # (staggered adoption is not currently supported)
+        treated_times = self.data.loc[
+            ~self.data[self.treat_time_col].isna(), self.treat_time_col
+        ].unique()
+        if len(treated_times) > 1:
+            raise DataException(
+                f"All treated units must have the same treatment time. "
+                f"Found {len(treated_times)} different treatment times: "
+                f"{sorted(treated_times)}. "
+                f"Staggered adoption designs are not currently supported."
+            )
+
     def _compute_event_time(self) -> None:
         """Compute event time (time relative to treatment) for each observation."""
         self.data["_event_time"] = np.nan

causalpy/tests/test_event_study.py

@@ -176,6 +176,35 @@ def test_event_study_duplicate_observations():
         )
 
 
+def test_event_study_staggered_adoption_not_supported():
+    """Test that staggered adoption (different treatment times) raises DataException."""
+    df = pd.DataFrame(
+        {
+            "unit": [0, 0, 1, 1, 2, 2],
+            "time": [0, 1, 0, 1, 0, 1],
+            "y": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
+            "treat_time": [
+                5.0,
+                5.0,
+                10.0,
+                10.0,
+                np.nan,
+                np.nan,
+            ],  # Different treat times
+        }
+    )
+
+    with pytest.raises(DataException, match="same treatment time"):
+        cp.EventStudy(
+            df,
+            formula="y ~ C(unit) + C(time)",
+            unit_col="unit",
+            time_col="time",
+            treat_time_col="treat_time",
+            model=cp.pymc_models.LinearRegression(sample_kwargs=sample_kwargs),
+        )
+
+
 # ============================================================================
 # Integration Tests with PyMC
 # ============================================================================

docs/source/notebooks/event_study_pymc.ipynb

@@ -6,14 +6,10 @@
    "source": [
     "# Event Study (Dynamic DiD) with `pymc` models\n",
     "\n",
-    "This notebook demonstrates how to use CausalPy's `EventStudy` class to estimate **dynamic treatment effects** over event time. This is also known as a \"dynamic {term}`difference in differences`\" analysis.\n",
-    "\n",
-    ":::{note}\n",
-    "{term}`Event study` is a powerful tool for:\n",
+    "This notebook demonstrates how to use CausalPy's `EventStudy` class to estimate **dynamic treatment effects** over event time. This is also known as a \"dynamic {term}`difference in differences`\" analysis. The {term}`event study` is a powerful tool for:\n",
     "1. Examining **pre-treatment trends** (placebo checks for {term}`parallel trends assumption`)\n",
     "2. Estimating how **treatment effects evolve over time** after treatment\n",
-    "3. Visualizing the full **time path of causal effects**\n",
-    ":::"
+    "3. Visualizing the full **time path of causal effects**"
    ]
   },
   {
@@ -42,7 +38,11 @@
     "\n",
     "**Interpretation:**\n",
     "- $\\beta_k$ for $k < 0$ (pre-treatment): Should be near zero if parallel trends hold\n",
-    "- $\\beta_k$ for $k \\geq 0$ (post-treatment): Measure the causal effect at each period after treatment\n"
+    "- $\\beta_k$ for $k \\geq 0$ (post-treatment): Measure the causal effect at each period after treatment\n",
+    "\n",
+    ":::{warning}\n",
+    "This implementation uses a standard two-way fixed effects (TWFE) estimator, which requires **simultaneous treatment timing** - all treated units must receive treatment at the same time. Staggered adoption designs (where different units are treated at different times) can produce biased estimates when treatment effects vary across cohorts {footcite:t}`sun2021estimating`.\n",
+    ":::\n"
    ]
   },
   {