Skip to content

ENH: Add Cragg-Donald test of reduced rank for first-stage regression (#622) - #713

Open
AyuG619 wants to merge 1 commit into
bashtage:mainfrom
AyuG619:add-cragg-donald-test
Open

ENH: Add Cragg-Donald test of reduced rank for first-stage regression (#622)#713
AyuG619 wants to merge 1 commit into
bashtage:mainfrom
AyuG619:add-cragg-donald-test

Conversation

@AyuG619

@AyuG619 AyuG619 commented Aug 13, 2026

Copy link
Copy Markdown

Summary

Implements the Cragg-Donald test of reduced rank for the first-stage
regression, addressing issue #622. With multiple endogenous variables,
the existing per-variable first-stage F-statistics can be individually
large even when the instruments cannot jointly identify all endogenous
regressors (e.g., when their fitted values are highly correlated). This
adds a joint diagnostic that correctly flags that failure mode.

Implementation

  • New cragg_donald function in linearmodels.iv.common, alongside the
    existing f_statistic.
  • New cragg_donald cached property on FirstStageResults, alongside
    the existing diagnostics property.
  • Reuses the existing annihilate/proj utilities for partialling out
    exogenous regressors and projecting onto instruments, consistent with
    other diagnostics in this module.
  • Returns a WaldTestStatistic/InvalidTestStatistic, matching existing
    conventions (e.g. sargan, wu_hausman, f_statistic).
  • The reported p-value uses the asymptotic chi2(k-m+1) distribution
    (Anderson 1951), not Stock-Yogo (2005) finite-sample critical values,
    which require choosing a tolerance for maximal size distortion/bias
    and so are intentionally left out of scope.

Testing

  • Validated against an independent reference implementation
    (mlondschien/ivmodels) on the exact example data from IV2SLS first_stage reports "wrong" first stage F-statistic #622, matching
    to ~10 significant figures.
  • Degenerate-case tests for k < m (too few instruments) and m == 0 (no
    endogenous regressors) -- the latter caught by running the existing
    result_checker-based test suite in test_results.py, which exercises
    the OLS-like (no endogenous/instruments) fit path across all four IV
    estimator types.
  • Full existing test suite (test_postestimation.py, test_results.py)
    passes with no regressions.

Closes #622

@codecov

codecov Bot commented Aug 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.54%. Comparing base (273d7f1) to head (b214bc6).

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #713   +/-   ##
=======================================
  Coverage   99.54%   99.54%           
=======================================
  Files         101      101           
  Lines       17426    17488   +62     
  Branches     1430     1432    +2     
=======================================
+ Hits        17347    17409   +62     
  Misses         29       29           
  Partials       50       50           
Flag Coverage Δ
adder 99.53% <100.00%> (+<0.01%) ⬆️
subtractor 99.53% <100.00%> (+<0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

IV2SLS first_stage reports "wrong" first stage F-statistic

1 participant