Propagate rank_deficient_action to all estimators (P2)

Complete parameter propagation for rank_deficient_action across all
estimators that use OLS internally:

- TwoWayFixedEffects: Pass to LinearRegression, conditional warning
  suppression based on setting
- CallawaySantAnna: Add parameter to __init__, pass to _linear_regression
  helper in _outcome_regression and _doubly_robust methods
- SunAbraham: Add parameter to __init__, pass to LinearRegression in
  _fit_saturated_regression
- TripleDifference: Add parameter to __init__, pass to solve_ols and
  LinearRegression in regression methods, also update convenience function

All estimators now support:
- "warn" (default): Issue warning and drop linearly dependent columns
- "error": Raise ValueError on rank deficiency
- "silent": Drop columns silently without warning

Tests added for each estimator verifying error/silent behavior.

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

Author: igerber

diff_diff/staggered.py

@@ -109,6 +109,7 @@ def gradient(beta: np.ndarray) -> np.ndarray:
 def _linear_regression(
     X: np.ndarray,
     y: np.ndarray,
+    rank_deficient_action: str = "warn",
 ) -> Tuple[np.ndarray, np.ndarray]:
     """
     Fit OLS regression.
@@ -119,6 +120,11 @@ def _linear_regression(
         Feature matrix (n_samples, n_features). Intercept added automatically.
     y : np.ndarray
         Outcome variable.
+    rank_deficient_action : str, default "warn"
+        Action when design matrix is rank-deficient:
+        - "warn": Issue warning and drop linearly dependent columns (default)
+        - "error": Raise ValueError
+        - "silent": Drop columns silently without warning
 
     Returns
     -------
@@ -132,7 +138,10 @@ def _linear_regression(
     X_with_intercept = np.column_stack([np.ones(n), X])
 
     # Use unified OLS backend (no vcov needed)
-    beta, residuals, _ = solve_ols(X_with_intercept, y, return_vcov=False)
+    beta, residuals, _ = solve_ols(
+        X_with_intercept, y, return_vcov=False,
+        rank_deficient_action=rank_deficient_action,
+    )
 
     return beta, residuals
 
@@ -195,6 +204,11 @@ class CallawaySantAnna(
             Use ``bootstrap_weights`` instead. Will be removed in v2.0.
     seed : int, optional
         Random seed for reproducibility.
+    rank_deficient_action : str, default="warn"
+        Action when design matrix is rank-deficient (linearly dependent columns):
+        - "warn": Issue warning and drop linearly dependent columns (default)
+        - "error": Raise ValueError
+        - "silent": Drop columns silently without warning
 
     Attributes
     ----------
@@ -277,6 +291,7 @@ def __init__(
         bootstrap_weights: Optional[str] = None,
         bootstrap_weight_type: Optional[str] = None,
         seed: Optional[int] = None,
+        rank_deficient_action: str = "warn",
     ):
         import warnings
 
@@ -312,6 +327,12 @@ def __init__(
                 f"got '{bootstrap_weights}'"
             )
 
+        if rank_deficient_action not in ["warn", "error", "silent"]:
+            raise ValueError(
+                f"rank_deficient_action must be 'warn', 'error', or 'silent', "
+                f"got '{rank_deficient_action}'"
+            )
+
         self.control_group = control_group
         self.anticipation = anticipation
         self.estimation_method = estimation_method
@@ -322,6 +343,7 @@ def __init__(
         # Keep bootstrap_weight_type for backward compatibility
         self.bootstrap_weight_type = bootstrap_weights
         self.seed = seed
+        self.rank_deficient_action = rank_deficient_action
 
         self.is_fitted_ = False
         self.results_: Optional[CallawaySantAnnaResults] = None
@@ -778,7 +800,10 @@ def _outcome_regression(
         if X_treated is not None and X_control is not None and X_treated.shape[1] > 0:
             # Covariate-adjusted outcome regression
             # Fit regression on control units: E[Delta Y | X, D=0]
-            beta, residuals = _linear_regression(X_control, control_change)
+            beta, residuals = _linear_regression(
+                X_control, control_change,
+                rank_deficient_action=self.rank_deficient_action,
+            )
 
             # Predict counterfactual for treated units
             X_treated_with_intercept = np.column_stack([np.ones(n_t), X_treated])
@@ -938,7 +963,10 @@ def _doubly_robust(
         if X_treated is not None and X_control is not None and X_treated.shape[1] > 0:
             # Doubly robust estimation with covariates
             # Step 1: Outcome regression - fit E[Delta Y | X] on control
-            beta, _ = _linear_regression(X_control, control_change)
+            beta, _ = _linear_regression(
+                X_control, control_change,
+                rank_deficient_action=self.rank_deficient_action,
+            )
 
             # Predict counterfactual for both treated and control
             X_treated_with_intercept = np.column_stack([np.ones(n_t), X_treated])
@@ -1014,6 +1042,7 @@ def get_params(self) -> Dict[str, Any]:
             # Deprecated but kept for backward compatibility
             "bootstrap_weight_type": self.bootstrap_weight_type,
             "seed": self.seed,
+            "rank_deficient_action": self.rank_deficient_action,
         }
 
     def set_params(self, **params) -> "CallawaySantAnna":

diff_diff/sun_abraham.py

@@ -319,6 +319,11 @@ class SunAbraham:
         If 0, uses analytical cluster-robust standard errors.
     seed : int, optional
         Random seed for reproducibility.
+    rank_deficient_action : str, default="warn"
+        Action when design matrix is rank-deficient (linearly dependent columns):
+        - "warn": Issue warning and drop linearly dependent columns (default)
+        - "error": Raise ValueError
+        - "silent": Drop columns silently without warning
 
     Attributes
     ----------
@@ -395,19 +400,27 @@ def __init__(
         cluster: Optional[str] = None,
         n_bootstrap: int = 0,
         seed: Optional[int] = None,
+        rank_deficient_action: str = "warn",
     ):
         if control_group not in ["never_treated", "not_yet_treated"]:
             raise ValueError(
                 f"control_group must be 'never_treated' or 'not_yet_treated', "
                 f"got '{control_group}'"
             )
 
+        if rank_deficient_action not in ["warn", "error", "silent"]:
+            raise ValueError(
+                f"rank_deficient_action must be 'warn', 'error', or 'silent', "
+                f"got '{rank_deficient_action}'"
+            )
+
         self.control_group = control_group
         self.anticipation = anticipation
         self.alpha = alpha
         self.cluster = cluster
         self.n_bootstrap = n_bootstrap
         self.seed = seed
+        self.rank_deficient_action = rank_deficient_action
 
         self.is_fitted_ = False
         self.results_: Optional[SunAbrahamResults] = None
@@ -756,6 +769,7 @@ def _fit_saturated_regression(
             include_intercept=False,  # Already demeaned, no intercept needed
             robust=True,
             cluster_ids=cluster_ids,
+            rank_deficient_action=self.rank_deficient_action,
         ).fit(X, y)
 
         coefficients = reg.coefficients_
@@ -1153,6 +1167,7 @@ def get_params(self) -> Dict[str, Any]:
             "cluster": self.cluster,
             "n_bootstrap": self.n_bootstrap,
             "seed": self.seed,
+            "rank_deficient_action": self.rank_deficient_action,
         }
 
     def set_params(self, **params) -> "SunAbraham":

diff_diff/triple_diff.py

@@ -330,6 +330,7 @@ def gradient(beta: np.ndarray) -> np.ndarray:
 def _linear_regression(
     X: np.ndarray,
     y: np.ndarray,
+    rank_deficient_action: str = "warn",
 ) -> Tuple[np.ndarray, np.ndarray, float]:
     """
     Fit OLS regression.
@@ -340,6 +341,11 @@ def _linear_regression(
         Feature matrix (n_samples, n_features). Intercept added automatically.
     y : np.ndarray
         Outcome variable.
+    rank_deficient_action : str, default "warn"
+        Action when design matrix is rank-deficient:
+        - "warn": Issue warning and drop linearly dependent columns (default)
+        - "error": Raise ValueError
+        - "silent": Drop columns silently without warning
 
     Returns
     -------
@@ -355,7 +361,8 @@ def _linear_regression(
 
     # Use unified OLS backend
     beta, residuals, fitted, _ = solve_ols(
-        X_with_intercept, y, return_fitted=True, return_vcov=False
+        X_with_intercept, y, return_fitted=True, return_vcov=False,
+        rank_deficient_action=rank_deficient_action,
     )
 
     # Compute R-squared
@@ -400,6 +407,11 @@ class TripleDifference:
     pscore_trim : float, default=0.01
         Trimming threshold for propensity scores. Scores below this value
         or above (1 - pscore_trim) are clipped to avoid extreme weights.
+    rank_deficient_action : str, default="warn"
+        Action when design matrix is rank-deficient (linearly dependent columns):
+        - "warn": Issue warning and drop linearly dependent columns (default)
+        - "error": Raise ValueError
+        - "silent": Drop columns silently without warning
 
     Attributes
     ----------
@@ -478,17 +490,24 @@ def __init__(
         cluster: Optional[str] = None,
         alpha: float = 0.05,
         pscore_trim: float = 0.01,
+        rank_deficient_action: str = "warn",
     ):
         if estimation_method not in ("dr", "reg", "ipw"):
             raise ValueError(
                 f"estimation_method must be 'dr', 'reg', or 'ipw', "
                 f"got '{estimation_method}'"
             )
+        if rank_deficient_action not in ["warn", "error", "silent"]:
+            raise ValueError(
+                f"rank_deficient_action must be 'warn', 'error', or 'silent', "
+                f"got '{rank_deficient_action}'"
+            )
         self.estimation_method = estimation_method
         self.robust = robust
         self.cluster = cluster
         self.alpha = alpha
         self.pscore_trim = pscore_trim
+        self.rank_deficient_action = rank_deficient_action
 
         self.is_fitted_ = False
         self.results_: Optional[TripleDifferenceResults] = None
@@ -744,6 +763,7 @@ def _regression_adjustment(
             include_intercept=False,  # Intercept already in design_matrix
             robust=self.robust,
             alpha=self.alpha,
+            rank_deficient_action=self.rank_deficient_action,
         ).fit(design_matrix, y)
 
         # ATT is the coefficient on G*P*T (index 7)
@@ -937,7 +957,10 @@ def _doubly_robust(
                     if np.sum(mask) > 1:
                         X_cell = np.column_stack([X[mask], T[mask]])
                         try:
-                            _, fitted, _ = _linear_regression(X_cell, y[mask])
+                            _, fitted, _ = _linear_regression(
+                                X_cell, y[mask],
+                                rank_deficient_action=self.rank_deficient_action,
+                            )
                             mu_fitted[mask] = fitted
                         except Exception:
                             mu_fitted[mask] = np.mean(y[mask])
@@ -1166,6 +1189,7 @@ def get_params(self) -> Dict[str, Any]:
             "cluster": self.cluster,
             "alpha": self.alpha,
             "pscore_trim": self.pscore_trim,
+            "rank_deficient_action": self.rank_deficient_action,
         }
 
     def set_params(self, **params) -> "TripleDifference":
@@ -1223,6 +1247,7 @@ def triple_difference(
     robust: bool = True,
     cluster: Optional[str] = None,
     alpha: float = 0.05,
+    rank_deficient_action: str = "warn",
 ) -> TripleDifferenceResults:
     """
     Estimate Triple Difference (DDD) treatment effect.
@@ -1256,6 +1281,11 @@ def triple_difference(
         Column name for cluster-robust standard errors.
     alpha : float, default=0.05
         Significance level for confidence intervals.
+    rank_deficient_action : str, default="warn"
+        Action when design matrix is rank-deficient:
+        - "warn": Issue warning and drop linearly dependent columns (default)
+        - "error": Raise ValueError
+        - "silent": Drop columns silently without warning
 
     Returns
     -------
@@ -1280,6 +1310,7 @@ def triple_difference(
         robust=robust,
         cluster=cluster,
         alpha=alpha,
+        rank_deficient_action=rank_deficient_action,
     )
     return estimator.fit(
         data=data,

diff_diff/twfe.py

@@ -128,16 +128,29 @@ def fit(  # type: ignore[override]
         # For wild bootstrap, we don't need cluster SEs from the initial fit
         cluster_ids = data[cluster_var].values
 
-        # Suppress rank-deficiency warning from solve_ols - TWFE handles its own messaging
-        # with more context-specific error/warning messages
-        with warnings.catch_warnings():
-            warnings.filterwarnings("ignore", message="Rank-deficient design matrix")
+        # Pass rank_deficient_action to LinearRegression
+        # If "error", let LinearRegression raise immediately
+        # If "warn" or "silent", suppress generic warning and use TWFE's context-specific
+        # error/warning messages (more informative for panel data)
+        if self.rank_deficient_action == "error":
             reg = LinearRegression(
-                include_intercept=False,  # Intercept already in X
-                robust=True,  # TWFE always uses robust/cluster SEs
+                include_intercept=False,
+                robust=True,
                 cluster_ids=cluster_ids if self.inference != "wild_bootstrap" else None,
                 alpha=self.alpha,
+                rank_deficient_action="error",
             ).fit(X, y, df_adjustment=df_adjustment)
+        else:
+            # Suppress generic warning, TWFE provides context-specific messages below
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore", message="Rank-deficient design matrix")
+                reg = LinearRegression(
+                    include_intercept=False,
+                    robust=True,
+                    cluster_ids=cluster_ids if self.inference != "wild_bootstrap" else None,
+                    alpha=self.alpha,
+                    rank_deficient_action="silent",
+                ).fit(X, y, df_adjustment=df_adjustment)
 
         coefficients = reg.coefficients_
         residuals = reg.residuals_
@@ -171,12 +184,14 @@ def fit(  # type: ignore[override]
             else:
                 # Only covariates are dropped - this is a warning, not an error
                 # The ATT can still be estimated
-                warnings.warn(
-                    f"Some covariates are collinear and were dropped: "
-                    f"{', '.join(dropped_names)}. The treatment effect is still identified.",
-                    UserWarning,
-                    stacklevel=2,
-                )
+                # Respect rank_deficient_action setting for warning
+                if self.rank_deficient_action == "warn":
+                    warnings.warn(
+                        f"Some covariates are collinear and were dropped: "
+                        f"{', '.join(dropped_names)}. The treatment effect is still identified.",
+                        UserWarning,
+                        stacklevel=2,
+                    )
 
         # Get inference - either from bootstrap or analytical
         if self.inference == "wild_bootstrap":

tests/test_estimators.py

@@ -1058,6 +1058,58 @@ def test_twfe_treatment_collinearity_raises_error(self):
             # If treatment column is dropped, should get informative error
             assert "collinear" in str(e).lower() or "Treatment effect cannot be identified" in str(e)
 
+    def test_rank_deficient_action_error_raises(self, twfe_panel_data):
+        """Test that rank_deficient_action='error' raises ValueError on collinear data."""
+        from diff_diff.estimators import TwoWayFixedEffects
+
+        # Add a covariate that is perfectly collinear with post
+        twfe_panel_data = twfe_panel_data.copy()
+        twfe_panel_data["collinear_cov"] = twfe_panel_data["post"].copy()
+
+        twfe = TwoWayFixedEffects(rank_deficient_action="error")
+        with pytest.raises(ValueError, match="rank-deficient"):
+            twfe.fit(
+                twfe_panel_data,
+                outcome="outcome",
+                treatment="treated",
+                time="post",
+                unit="unit",
+                covariates=["collinear_cov"]
+            )
+
+    def test_rank_deficient_action_silent_no_warning(self, twfe_panel_data):
+        """Test that rank_deficient_action='silent' produces no warning."""
+        import warnings
+        from diff_diff.estimators import TwoWayFixedEffects
+
+        # Add a covariate that is perfectly collinear with another
+        twfe_panel_data = twfe_panel_data.copy()
+        twfe_panel_data["size"] = np.random.normal(100, 10, len(twfe_panel_data))
+        twfe_panel_data["size_dup"] = twfe_panel_data["size"].copy()  # Perfect collinearity
+
+        twfe = TwoWayFixedEffects(rank_deficient_action="silent")
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            results = twfe.fit(
+                twfe_panel_data,
+                outcome="outcome",
+                treatment="treated",
+                time="post",
+                unit="unit",
+                covariates=["size", "size_dup"]
+            )
+
+            # No warnings about rank deficiency or collinearity should be emitted
+            rank_warnings = [x for x in w if "Rank-deficient" in str(x.message)
+                           or "rank-deficient" in str(x.message).lower()
+                           or "collinear" in str(x.message).lower()]
+            assert len(rank_warnings) == 0, f"Expected no rank warnings, got {rank_warnings}"
+
+        # Should still get valid results
+        assert results is not None
+        assert twfe.is_fitted_
+
 
 class TestClusterRobustSE:
     """Tests for cluster-robust standard errors."""