Address PR #208 review: remove TWFE from registry, add lo-sufficient short-circuit

- Remove TwoWayFixedEffects from power analysis registry (time="period"
  produces treated*period_number, not standard ATT)
- Add early return in simulate_sample_size() when lower bound already
  achieves target power (both explicit n_range and auto-bracket paths)
- Narrow docstring from "All" to "Most" built-in estimators
- Add regression tests for TWFE exclusion and lo-sufficient scenarios

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: igerber

diff_diff/power.py

@@ -136,15 +136,6 @@ def _basic_fit_kwargs(
     return dict(outcome="outcome", treatment="treated", time="post")
 
 
-def _twfe_fit_kwargs(
-    data: pd.DataFrame,
-    n_units: int,
-    n_periods: int,
-    treatment_period: int,
-) -> Dict[str, Any]:
-    return dict(outcome="outcome", treatment="treated", time="period", unit="unit")
-
-
 def _multiperiod_fit_kwargs(
     data: pd.DataFrame,
     n_units: int,
@@ -264,13 +255,6 @@ def _get_registry() -> Dict[str, _EstimatorProfile]:
             result_extractor=_extract_simple,
             min_n=20,
         ),
-        "TwoWayFixedEffects": _EstimatorProfile(
-            default_dgp=generate_did_data,
-            dgp_kwargs_builder=_basic_dgp_kwargs,
-            fit_kwargs_builder=_twfe_fit_kwargs,
-            result_extractor=_extract_simple,
-            min_n=20,
-        ),
         "MultiPeriodDiD": _EstimatorProfile(
             default_dgp=generate_did_data,
             dgp_kwargs_builder=_basic_dgp_kwargs,
@@ -1221,7 +1205,7 @@ def simulate_power(
 
     This function simulates datasets with known treatment effects and estimates
     power as the fraction of simulations where the null hypothesis is rejected.
-    All built-in estimators are supported via an internal registry that selects
+    Most built-in estimators are supported via an internal registry that selects
     the appropriate data-generating process and fit signature automatically.
 
     Parameters
@@ -1987,7 +1971,24 @@ def _power_at_n(n: int) -> float:
     # --- Bracket ---
     if n_range is not None:
         lo, hi = n_range
-        _power_at_n(lo)  # evaluate lo to populate search_path
+        power_lo = _power_at_n(lo)
+        if power_lo >= power:
+            warnings.warn(
+                f"Power at n={lo} is {power_lo:.2f} >= target {power}. "
+                f"Lower bound already achieves target power. Returning lo.",
+                UserWarning,
+            )
+            return SimulationSampleSizeResults(
+                required_n=lo,
+                power_at_n=power_lo,
+                target_power=power,
+                alpha=alpha,
+                effect_size=treatment_effect,
+                n_simulations_per_step=n_simulations,
+                n_steps=len(search_path),
+                search_path=search_path,
+                estimator_name=estimator_name,
+            )
         power_hi = _power_at_n(hi)
         if power_hi < power:
             warnings.warn(
@@ -1997,6 +1998,19 @@ def _power_at_n(n: int) -> float:
             )
     else:
         lo = min_n
+        power_lo = _power_at_n(lo)
+        if power_lo >= power:
+            return SimulationSampleSizeResults(
+                required_n=lo,
+                power_at_n=power_lo,
+                target_power=power,
+                alpha=alpha,
+                effect_size=treatment_effect,
+                n_simulations_per_step=n_simulations,
+                n_steps=len(search_path),
+                search_path=search_path,
+                estimator_name=estimator_name,
+            )
         hi = max(100, 2 * min_n)
         for _ in range(10):
             if _power_at_n(hi) >= power:

tests/test_power.py

@@ -43,7 +43,6 @@
     _staggered_dgp_kwargs,
     _staggered_fit_kwargs,
     _trop_fit_kwargs,
-    _twfe_fit_kwargs,
 )
 
 
@@ -671,7 +670,6 @@ class TestEstimatorRegistry:
 
     EXPECTED_ESTIMATORS = [
         "DifferenceInDifferences",
-        "TwoWayFixedEffects",
         "MultiPeriodDiD",
         "CallawaySantAnna",
         "SunAbraham",
@@ -720,7 +718,6 @@ def test_fit_kwargs_builders_return_dicts(self):
         dummy_df = pd.DataFrame({"period": [0, 1, 2, 3]})
         for builder in [
             _basic_fit_kwargs,
-            _twfe_fit_kwargs,
             _staggered_fit_kwargs,
             _ddd_fit_kwargs,
             _trop_fit_kwargs,
@@ -803,6 +800,18 @@ def test_continuous_did_not_in_registry(self):
                 progress=False,
             )
 
+    def test_twfe_not_in_registry(self):
+        """TwoWayFixedEffects is not in registry and raises without custom data_generator."""
+        registry = _get_registry()
+        assert "TwoWayFixedEffects" not in registry
+
+        with pytest.raises(ValueError, match="not in registry"):
+            simulate_power(
+                TwoWayFixedEffects(),
+                n_simulations=5,
+                progress=False,
+            )
+
     def test_unknown_estimator_raises_without_data_generator(self):
         """Unknown estimator without data_generator raises ValueError."""
 
@@ -841,15 +850,6 @@ def test_did(self):
         )
         self._assert_valid_result(result, "DifferenceInDifferences")
 
-    def test_twfe(self):
-        result = simulate_power(
-            TwoWayFixedEffects(),
-            n_simulations=10,
-            seed=42,
-            progress=False,
-        )
-        self._assert_valid_result(result, "TwoWayFixedEffects")
-
     def test_multiperiod(self):
         result = simulate_power(
             MultiPeriodDiD(),
@@ -1225,3 +1225,32 @@ def test_unbracketed_n_range_warns(self):
                 seed=42,
                 progress=False,
             )
+
+    def test_lo_already_sufficient_explicit(self):
+        """When lo already meets power, return lo immediately with warning."""
+        with pytest.warns(UserWarning, match="Lower bound already achieves"):
+            result = simulate_sample_size(
+                DifferenceInDifferences(),
+                treatment_effect=50.0,
+                sigma=0.1,
+                n_simulations=50,
+                n_range=(20, 200),
+                seed=42,
+                progress=False,
+            )
+        assert result.required_n == 20
+        assert result.power_at_n >= 0.80
+
+    def test_lo_already_sufficient_auto(self):
+        """Auto-bracket returns min_n when effect overwhelmingly large."""
+        result = simulate_sample_size(
+            DifferenceInDifferences(),
+            treatment_effect=50.0,
+            sigma=0.1,
+            n_simulations=50,
+            seed=42,
+            progress=False,
+        )
+        # min_n for DifferenceInDifferences is 20
+        assert result.required_n == 20
+        assert result.power_at_n >= 0.80