Skip to content

docs: clarify DiD predict support contract#580

Open
shawcharles wants to merge 1 commit into
igerber:mainfrom
shawcharles:docs/did-predict-contract
Open

docs: clarify DiD predict support contract#580
shawcharles wants to merge 1 commit into
igerber:mainfrom
shawcharles:docs/did-predict-contract

Conversation

@shawcharles

Copy link
Copy Markdown
Contributor

Closes #579.

Summary

This PR clarifies the current DifferenceInDifferences.predict() contract without adding prediction semantics.

predict() is present on the sklearn-like estimator surface, but it currently raises NotImplementedError. The updated docs and error message make that explicit: out-of-sample prediction is unsupported pending a broader post-estimation result-object design, and fitted training-data predictions are available through results_.fitted_values after fit().

Changes

  • Update DifferenceInDifferences.predict() docstring and NotImplementedError message.
  • Add a regression test for the fitted predict() unsupported contract.
  • Add a short API docs note and include predict in the DifferenceInDifferences method autosummary.
  • Do not implement prediction or alter result-object semantics.

Validation

  • PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest tests/test_methodology_did.py::TestResultsObject::test_predict_contract_points_to_fitted_values -q
  • PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest tests/test_methodology_did.py::TestResultsObject -q
  • PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest tests/test_methodology_did.py -q
  • PYTHONPATH=. DIFF_DIFF_BACKEND=python .venv-py39/bin/python -m pytest tests/test_methodology_did.py::TestResultsObject::test_predict_contract_points_to_fitted_values -q
  • python -m ruff check diff_diff/estimators.py
  • git diff --check

Docs build note: make -C docs html SPHINXOPTS="-W" currently reaches completion but exits non-zero on pre-existing tutorial 19 DID unknown-target warnings. Those warnings are addressed separately in PR #572.

Security / privacy

Confirmed: no secrets or PII in this PR.

@shawcharles shawcharles force-pushed the docs/did-predict-contract branch from 42bc17c to ed50c11 Compare July 2, 2026 13:29
@shawcharles shawcharles marked this pull request as ready for review July 2, 2026 13:29
@shawcharles

Copy link
Copy Markdown
Contributor Author

Ready for review from my side.

I rebased the branch onto current upstream/main, resolved the test-file conflict by keeping both the new upstream multi-absorb tests and this PR's focused predict() contract test, and reran the relevant checks:

  • PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest tests/test_methodology_did.py::TestResultsObject::test_predict_contract_points_to_fitted_values -q
  • PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest tests/test_methodology_did.py -q
  • PYTHONPATH=. DIFF_DIFF_BACKEND=python .venv-py39/bin/python -m pytest tests/test_methodology_did.py::TestResultsObject::test_predict_contract_points_to_fitted_values -q
  • python -m ruff check diff_diff/estimators.py
  • git diff --check upstream/main...HEAD
  • python -m sphinx -b html docs docs/_build/html -W --keep-going

Scope note: this only documents and tests the current unsupported DifferenceInDifferences.predict() contract. It does not add prediction behaviour or change post-estimation design.

GitHub currently reports the workflow runs as action_required and no PR checks are exposed yet, so this is ready whenever you want to approve/run CI and/or apply the usual ready-for-ci path.

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.

Clarify DifferenceInDifferences.predict() support contract

1 participant