Address PR #97 review: fix base_period fallback and add validation

- Remove fallback to non-consecutive base periods in varying mode
- Add base_period parameter to CallawaySantAnna docstring
- Add validation and warning for empty post-treatment effect sets
- Add tests for no-fallback behavior and NaN result with warning

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: igerber

diff_diff/staggered.py

@@ -209,6 +209,15 @@ class CallawaySantAnna(
         - "warn": Issue warning and drop linearly dependent columns (default)
         - "error": Raise ValueError
         - "silent": Drop columns silently without warning
+    base_period : str, default="varying"
+        Method for selecting the base (reference) period for computing
+        ATT(g,t). Options:
+        - "varying": For pre-treatment periods (t < g - anticipation), use
+          t-1 as base (consecutive comparisons). For post-treatment, use
+          g-1-anticipation. Requires t-1 to exist in data.
+        - "universal": Always use g-1-anticipation as base period.
+        Both produce identical post-treatment effects. Matches R's
+        did::att_gt() base_period parameter.
 
     Attributes
     ----------
@@ -462,11 +471,8 @@ def _compute_att_gt_fast(
                 base_period_val = g - 1 - self.anticipation
 
         if base_period_val not in period_to_col:
-            # Find closest earlier period
-            earlier = [p for p in time_periods if p < base_period_val]
-            if not earlier:
-                return None, 0.0, 0, 0, None
-            base_period_val = max(earlier)
+            # Base period must exist; no fallback to maintain methodological consistency
+            return None, 0.0, 0, 0, None
 
         # Check if periods exist in the data
         if base_period_val not in period_to_col or t not in period_to_col:

diff_diff/staggered_aggregation.py

@@ -72,6 +72,17 @@ def _aggregate_simple(
             gt_pairs.append((g, t))
             groups_for_gt.append(g)
 
+        # Guard against empty post-treatment set
+        if len(effects) == 0:
+            import warnings
+            warnings.warn(
+                "No post-treatment effects available for overall ATT aggregation. "
+                "This can occur when cohorts lack post-treatment periods in the data.",
+                UserWarning,
+                stacklevel=2
+            )
+            return np.nan, np.nan
+
         effects = np.array(effects)
         weights = np.array(weights_list, dtype=float)
         groups_for_gt = np.array(groups_for_gt)

diff_diff/staggered_bootstrap.py

@@ -323,6 +323,16 @@ def _run_multiplier_bootstrap(
             group_time_effects[gt]['n_treated'] for gt in gt_pairs
         ], dtype=float)
         post_n_treated = all_n_treated[post_treatment_mask]
+
+        # Guard against empty post-treatment set
+        if len(post_treatment_indices) == 0:
+            warnings.warn(
+                "No post-treatment effects for bootstrap aggregation.",
+                UserWarning,
+                stacklevel=2
+            )
+            # Return results with NaN for overall ATT - will be handled by caller
+
         overall_weights_post = post_n_treated / np.sum(post_n_treated)
 
         # Original point estimates

tests/test_staggered.py

@@ -2205,3 +2205,89 @@ def test_default_base_period_is_varying(self):
         cs = CallawaySantAnna()
         assert cs.base_period == "varying"
         assert cs.get_params()["base_period"] == "varying"
+
+    def test_varying_mode_no_fallback_to_nonconsecutive(self):
+        """Varying mode skips pre-treatment effects where t-1 doesn't exist."""
+        # Create data where first period (e.g., period 1) has no t-1 predecessor
+        data = generate_staggered_data(
+            n_units=100,
+            n_periods=6,  # periods 1-6
+            n_cohorts=2,
+            treatment_effect=2.0,
+            seed=42
+        )
+
+        # Identify the earliest time period in data
+        min_period = data['time'].min()
+
+        cs = CallawaySantAnna(base_period="varying")
+        results = cs.fit(
+            data,
+            outcome='outcome',
+            unit='unit',
+            time='time',
+            first_treat='first_treat'
+        )
+
+        # In varying mode, ATT(g, min_period) should NOT be computed for
+        # any cohort g because t-1 (period 0) doesn't exist
+        for (g, t) in results.group_time_effects.keys():
+            if t == min_period:
+                # This should not happen - the (g, min_period) pair should be skipped
+                pytest.fail(
+                    f"ATT({g}, {t}) should not exist because t-1 doesn't exist. "
+                    "Fallback to non-consecutive base period was incorrectly applied."
+                )
+
+    def test_no_post_treatment_effects_returns_nan_with_warning(self):
+        """Warn and return NaN when no post-treatment effects exist."""
+        import warnings
+
+        # Create data where the treatment cohort treats AFTER the last observed period
+        # so there are no post-treatment periods (t >= g never holds)
+        n_units = 50
+        n_periods = 5
+        np.random.seed(42)
+
+        data = []
+        for unit in range(n_units):
+            for t in range(1, n_periods + 1):
+                # Treated units get treated at period 6 (beyond data range)
+                # Data only goes to period 5, so no post-treatment periods exist
+                first_treat = n_periods + 1 if unit < n_units // 2 else 0
+                outcome = np.random.randn()
+                data.append({
+                    'unit': unit,
+                    'time': t,
+                    'outcome': outcome,
+                    'first_treat': first_treat
+                })
+
+        df = pd.DataFrame(data)
+
+        cs = CallawaySantAnna(base_period="varying")
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            results = cs.fit(
+                df,
+                outcome='outcome',
+                unit='unit',
+                time='time',
+                first_treat='first_treat'
+            )
+
+            # Should have emitted a warning about no post-treatment effects
+            warning_messages = [str(warning.message) for warning in w]
+            has_warning = any(
+                "No post-treatment effects" in msg for msg in warning_messages
+            )
+            assert has_warning, (
+                f"Expected warning about no post-treatment effects, got: {warning_messages}"
+            )
+
+        # Overall ATT should be NaN
+        assert np.isnan(results.overall_att), (
+            f"Expected NaN for overall_att when no post-treatment effects exist, "
+            f"got {results.overall_att}"
+        )