Skip to content

REF: Move method of IV2SLS and IVLIML from the model to fit - #873

Merged
bashtage merged 4 commits into
mainfrom
iv-method-in-fit
Nov 11, 2026
Merged

bashtage merged 4 commits into
mainfrom
iv-method-in-fit

Conversation

@bashtage

@bashtage bashtage commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

The numerical method of IV2SLS and IVLIML (#870) is a property of an estimate, not of the model. This moves method from the constructors and from_formula to fit. method was added in 7.2 and has not been released, so there is no deprecation.

  • fit(method=...) validates the method and warns if it is not given, as the constructors did. The FutureWarning now comes from fit.
  • The results report the method of the fit as the public property fit_method ("pinv" for IVGMM, IVGMMCUE and IVJIVE; method is already the estimator name, such as "IV-2SLS"), and their diagnostics use it: the first stage, Sargan, Durbin, Wu-Hausman and the Wooldridge tests. The model no longer stores a method, so one model can be fit with both methods without one fit affecting the next.
  • The rank check is the only value of the model that depends on the method. It is kept per method (_rank_errors, keyed by method). The model is rejected when it is built only if neither method can estimate it, with the 7.1 message. Otherwise fit raises the error of the method it is given. For example, columns that are rank deficient only because of their units now build, and fit(method="pinv") raises with the hint that "qr" accepts them.
  • Both rank tests come from one QR decomposition: the singular values of R give the test of "pinv", and those of R with columns scaled by the column norms give the test of "qr". Building the model costs about the same as on main.
  • The rank tests use the weighted regressors and instruments, which the estimates use. 7.1 tested the unweighted ones. Their condition number can differ greatly: in the new test, the scaled instruments have a condition number of 2.5 without the weights and 4.1e9 with them. This only changes what happens for models with unequal weights. Weights over 600 orders of magnitude on 120 observations now leave the weighted instruments rank deficient, and test_weights_finite expects that.
  • The model keeps the orthonormal basis of the weighted instruments, from the rank test. fit(method="qr") uses it for the estimate, the covariance and the LIML kappa, whose basis of the exogenous regressors is its first columns, so a qr fit does not decompose the data. At n = 1M with 15 instruments a qr fit takes 0.80 s instead of 1.24 s, and at n = 100k with 150 instruments 0.47 s instead of 3.21 s. The cost is an array the size of the instruments kept on the model. IVGMM, IVGMMCUE and IVJIVE do not keep it and use "pinv".
  • The tests, the four example notebooks and the 7.2 notes pass method to fit.

Tests: the fast suite passes locally (23,387 passed). The notebooks run without warnings, and every added line and branch is covered. A new test fits the same model with "qr", then "pinv", and checks each result and its diagnostics against a fit of a fresh model.

🤖 Generated with Claude Code

The numerical method is a property of an estimate, not of the model, so it is
passed to fit and stored on the results, which use it for their diagnostics.
The model no longer stores a method, so one model can be fit with both. The
rank check of each method stays in the model, keyed by the method: the model
is rejected when neither method can estimate it, and fit raises the error of
the method it is given. method was added in 7.2 and has not been released.
The results of IV2SLS and IVLIML report the method of fit as the public
property numerical_method. The results of IVGMM, IVGMMCUE and IVJIVE report
"pinv". The name method is taken by the estimator name, such as "IV-2SLS".
@codecov

codecov Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.69%. Comparing base (5799ee0) to head (8ad1264).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #873   +/-   ##
=======================================
  Coverage   99.69%   99.69%           
=======================================
  Files         202      202           
  Lines       38797    38876   +79     
  Branches     2497     2502    +5     
=======================================
+ Hits        38677    38756   +79     
  Misses         51       51           
  Partials       69       69           
Flag Coverage Δ
adder 99.68% <100.00%> (+<0.01%) ⬆️
subtractor 99.68% <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.

…n fit

The rank tests of both methods now come from one QR decomposition of the
weighted regressors and instruments, which the estimates use. 7.1 tested the
unweighted ones, whose condition number can differ greatly from that of the
weighted ones. The singular values of R give the test of "pinv", and those of
R with columns scaled by the column norms give the test of "qr".

The model keeps the orthonormal basis of the weighted instruments, and fit
with method="qr" uses it for the estimate, the covariance and kappa, whose
basis of the exogenous regressors is its first columns. A qr fit no longer
decomposes the data.
@bashtage
bashtage merged commit d7980a7 into main Nov 11, 2026
21 of 27 checks passed
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.

1 participant