# `causalis.scenarios.cuped.refutation.regression_checks`

## Module Contents

### Classes

`RegressionChecks` | Lightweight OLS/regression health checks for CUPED refutation.

### Functions

`design_matrix_checks` | Return rank/conditioning refutation checks for a numeric design matrix.
`near_duplicate_corr_pairs` | Find pairs with absolute correlation very close to one.
`vif_from_corr` | Approximate VIF from inverse correlation matrix of standardized covariates..
`leverage_and_cooks` | Compute leverage, Cook’s distance, and internally studentized residuals.
`winsor_fit_tau` | Refit OLS on winsorized outcome and return treatment coefficient.
`run_regression_checks` | Build a compact payload with design, residual, and influence refutation checks.
`assumption_design_rank` | Check that the design matrix is full rank.
`assumption_condition_number` | Check global collinearity via condition number.
`assumption_near_duplicates` | Check near-duplicate centered covariate pairs.
`assumption_vif` | Check VIF from centered main-effect covariates.
`assumption_ate_gap` | Check adjusted-vs-naive ATE gap relative to naive SE.
`assumption_residual_tails` | Check residual extremes using max standardized residual only.
`assumption_leverage` | Check leverage concentration.
`assumption_cooks` | Check Cook’s distance influence refutation checks.
`assumption_hc23_stability` | Check HC2/HC3 stability when leverage terms approach one.
`assumption_winsor_sensitivity` | Check sensitivity of adjusted ATE to winsorized-outcome refit.
`regression_assumption_rows_from_checks` | Run all CUPED regression assumption tests and return row payloads.
`regression_assumptions_table_from_checks` | Return a table of GREEN/YELLOW/RED assumption flags from checks payload.
`regression_assumptions_table_from_diagnostic_data` | Build assumption table from `CUPEDDiagnosticData` payload.
`regression_assumptions_table_from_estimate` | Build assumptions table from a CUPED estimate.
`regression_assumptions_table_from_data` | Fit CUPED on `CausalData` and return the assumptions flag table.
`overall_assumption_flag` | Return overall GREEN/YELLOW/RED status from an assumptions table.
`style_regression_assumptions_table` | Return pandas Styler with colored flag cells for notebook display.

### Data

`FLAG_GREEN` |
`FLAG_YELLOW` |
`FLAG_RED` |
`FLAG_LEVEL` |
`FLAG_COLOR` |

### API

causalis.scenarios.cuped.refutation.regression_checks.FLAG_GREEN

  ‘GREEN’

causalis.scenarios.cuped.refutation.regression_checks.FLAG_YELLOW

  ‘YELLOW’

causalis.scenarios.cuped.refutation.regression_checks.FLAG_RED

  ‘RED’

causalis.scenarios.cuped.refutation.regression_checks.FLAG_LEVEL

  None

causalis.scenarios.cuped.refutation.regression_checks.FLAG_COLOR

  None

class causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks(/, **data: Any)

  Bases: `pydantic.BaseModel`

  Lightweight OLS/regression health checks for CUPED refutation.

  Initialization

  Create a new model by parsing and validating input data from keyword arguments.

  Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

  `self` is explicitly positional-only to allow `self` as a field name.

  ate_naive: float

    None

  ate_adj: float

    None

  ate_gap: float

    None

  ate_gap_over_se_naive: Optional[float]

    None

  k: int

    None

  rank: int

    None

  full_rank: bool

    None

  condition_number: float

    None

  p_main_covariates: int

    None

  near_duplicate_pairs: list[tuple[str, str, float]]

    ‘Field(…)’

  vif: Optional[Dict[str, float]]

    None

  resid_scale_mad: float

    None

  n_std_resid_gt_3: int

    None

  n_std_resid_gt_4: int

    None

  max_abs_std_resid: float

    None

  max_leverage: float

    None

  leverage_cutoff: float

    None

  n_high_leverage: int

    None

  max_cooks: float

    None

  cooks_cutoff: float

    None

  n_high_cooks: int

    None

  min_one_minus_h: float

    None

  n_tiny_one_minus_h: int

    None

  winsor_q: Optional[float]

    None

  ate_adj_winsor: Optional[float]

    None

  ate_adj_winsor_gap: Optional[float]

    None

causalis.scenarios.cuped.refutation.regression_checks.design_matrix_checks(design: pandas.DataFrame) → tuple[int, int, bool, float]

  Return rank/conditioning refutation checks for a numeric design matrix.

causalis.scenarios.cuped.refutation.regression_checks.near_duplicate_corr_pairs(x: pandas.DataFrame, tol: float, max_pairs: int = 50) → list[tuple[str, str, float]]

  Find pairs with absolute correlation very close to one.

causalis.scenarios.cuped.refutation.regression_checks.vif_from_corr(x: pandas.DataFrame) → Optional[Dict[str, float]]

  Approximate VIF from inverse correlation matrix of standardized covariates..

causalis.scenarios.cuped.refutation.regression_checks.leverage_and_cooks(y: numpy.ndarray, z: numpy.ndarray, params: numpy.ndarray) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

  Compute leverage, Cook’s distance, and internally studentized residuals.

causalis.scenarios.cuped.refutation.regression_checks.winsor_fit_tau(y: pandas.Series, design: pandas.DataFrame, cov_type: str, use_t_fit: bool, winsor_q: Optional[float]) → Optional[float]

  Refit OLS on winsorized outcome and return treatment coefficient.

causalis.scenarios.cuped.refutation.regression_checks.run_regression_checks(y: pandas.Series, design: pandas.DataFrame, result: Any, result_naive: Any, cov_type: str, use_t_fit: bool, corr_near_one_tol: float, tiny_one_minus_h_tol: float, winsor_q: Optional[float]) → causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks

  Build a compact payload with design, residual, and influence refutation checks.

causalis.scenarios.cuped.refutation.regression_checks.assumption_design_rank(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks) → Dict[str, Any]

  Check that the design matrix is full rank.

causalis.scenarios.cuped.refutation.regression_checks.assumption_condition_number(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, warn_threshold: float = 100000000.0, red_multiplier: float = 100.0) → Dict[str, Any]

  Check global collinearity via condition number.

causalis.scenarios.cuped.refutation.regression_checks.assumption_near_duplicates(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, red_pairs_threshold: int = 3) → Dict[str, Any]

  Check near-duplicate centered covariate pairs.

causalis.scenarios.cuped.refutation.regression_checks.assumption_vif(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, warn_threshold: float = 20.0, red_multiplier: float = 2.0) → Dict[str, Any]

  Check VIF from centered main-effect covariates.

causalis.scenarios.cuped.refutation.regression_checks.assumption_ate_gap(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, yellow_threshold: float = 2.0, red_threshold: float = 2.5) → Dict[str, Any]

  Check adjusted-vs-naive ATE gap relative to naive SE.

causalis.scenarios.cuped.refutation.regression_checks.assumption_residual_tails(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, yellow_abs_std_resid: float = 7.0, red_abs_std_resid: float = 10.0) → Dict[str, Any]

  Check residual extremes using max standardized residual only.

causalis.scenarios.cuped.refutation.regression_checks.assumption_leverage(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, yellow_multiplier: float = 5.0, red_multiplier: float = 10.0, red_floor: float = 0.5) → Dict[str, Any]

  Check leverage concentration.

causalis.scenarios.cuped.refutation.regression_checks.assumption_cooks(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, yellow_threshold: float = 0.1, red_threshold: float = 1.0) → Dict[str, Any]

  Check Cook’s distance influence refutation checks.

causalis.scenarios.cuped.refutation.regression_checks.assumption_hc23_stability(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, cov_type: str, tiny_one_minus_h_tol: float = 1e-08) → Dict[str, Any]

  Check HC2/HC3 stability when leverage terms approach one.

causalis.scenarios.cuped.refutation.regression_checks.assumption_winsor_sensitivity(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, winsor_reference_se: Optional[float] = None, yellow_sigma: float = 1.0, red_sigma: float = 2.0, yellow_ratio: float = 0.1, red_ratio: float = 0.25) → Dict[str, Any]

  Check sensitivity of adjusted ATE to winsorized-outcome refit.

causalis.scenarios.cuped.refutation.regression_checks.regression_assumption_rows_from_checks(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, cov_type: str = 'HC2', condition_number_warn_threshold: float = 100000000.0, vif_warn_threshold: float = 20.0, tiny_one_minus_h_tol: float = 1e-08, winsor_reference_se: Optional[float] = None) → list[Dict[str, Any]]

  Run all CUPED regression assumption tests and return row payloads.

causalis.scenarios.cuped.refutation.regression_checks.regression_assumptions_table_from_checks(checks: causalis.scenarios.cuped.refutation.regression_checks.RegressionChecks, cov_type: str = 'HC2', condition_number_warn_threshold: float = 100000000.0, vif_warn_threshold: float = 20.0, tiny_one_minus_h_tol: float = 1e-08, winsor_reference_se: Optional[float] = None) → pandas.DataFrame

  Return a table of GREEN/YELLOW/RED assumption flags from checks payload.

causalis.scenarios.cuped.refutation.regression_checks.regression_assumptions_table_from_diagnostic_data(diagnostic_data: causalis.data_contracts.causal_diagnostic_data.CUPEDDiagnosticData, cov_type: str = 'HC2', condition_number_warn_threshold: float = 100000000.0, vif_warn_threshold: float = 20.0, tiny_one_minus_h_tol: float = 1e-08, winsor_reference_se: Optional[float] = None) → pandas.DataFrame

  Build assumption table from `CUPEDDiagnosticData` payload.

causalis.scenarios.cuped.refutation.regression_checks.regression_assumptions_table_from_estimate(data_or_estimate: causalis.dgp.causaldata.CausalData | causalis.data_contracts.causal_estimate.CausalEstimate, estimate: Optional[causalis.data_contracts.causal_estimate.CausalEstimate] = None, style_regression_assumptions_table: Optional[Callable[[pandas.DataFrame], Any]] = None, cov_type: Optional[str] = None, condition_number_warn_threshold: float = 100000000.0, vif_warn_threshold: float = 20.0, tiny_one_minus_h_tol: float = 1e-08) → Any

  Build assumptions table from a CUPED estimate.

  Supports both call styles:

  1. `regression_assumptions_table_from_estimate(estimate, ...)`

  2. `regression_assumptions_table_from_estimate(data, estimate, ...)`

causalis.scenarios.cuped.refutation.regression_checks.regression_assumptions_table_from_data(data: causalis.dgp.causaldata.CausalData, covariates: Sequence[str], model_kwargs: Optional[Dict[str, Any]] = None, fit_kwargs: Optional[Dict[str, Any]] = None) → pandas.DataFrame

  Fit CUPED on `CausalData` and return the assumptions flag table.

causalis.scenarios.cuped.refutation.regression_checks.overall_assumption_flag(table: pandas.DataFrame) → str

  Return overall GREEN/YELLOW/RED status from an assumptions table.

causalis.scenarios.cuped.refutation.regression_checks.style_regression_assumptions_table(table: pandas.DataFrame)

  Return pandas Styler with colored flag cells for notebook display.