Skip to content

Imputation-gap capstone: get_reported_*(), get_nibrs_estimate(), imputation_gap() - #4

Merged
jknowles merged 8 commits into
mainfrom
claude/inspiring-wright-usthec
Oct 15, 2026
Merged

jknowles merged 8 commits into
mainfrom
claude/inspiring-wright-usthec

Conversation

@jknowles

Copy link
Copy Markdown
Contributor

Implements specs/plans/2026-10-15-imputation-gap.md (Gitea issue 42). Not for merging on GitHub: the operator lands it locally.

What changed

Task 1, 21a110a: rename. get_estimated_crime() / get_estimated_arson() are now get_reported_crime() / get_reported_arson(). The old names remain as exported aliases that warn through .Deprecated() and are documented on an internal fbiCDE-deprecated page. Tests, README, the fbi vignette, pkgdown and NEWS are updated.

Task 2, 3eeeece: vocabularies. .parse_estimation_lookup() and the .ESTIMATE_OFFENSES map are new. data-raw/api_vocabularies.R now also builds nibrs_estimation_states (57 rows), nibrs_estimation_indicators (71) and nibrs_estimation_years (2021, 2022) from the live lookup. Rebuilding left every existing .rda byte-identical.

Task 3, e4c2b27: get_nibrs_estimate(). One request per call. It returns one row per category with 95% bounds; null bounds become NA and negative bounds are kept as published.

Task 4, b0a0d0f: imputation_gap(). One row per year. Columns: reported, reported_nibrs, reported_other, coverage, coverage_nibrs, published with its bounds, gap with bounds, share_estimated with bounds.

Review fixes, found while knitting the vignette and agreed with the operator in the session:

  • 2f42682 fix: RPE uses the "Revised Rape" indicator (120). The plan mapped it to "Rape" (118), which is NIBRS 11A alone, so imputation_gap(offense = "RPE") compared an 11A estimate with 11A+11B+11C. Texas 2022 came out at −47%; it is −7.3% now. An offline test pins 120, and a live guard checks every offense's Texas 2022 share_estimated stays within 10%.
  • c93a28a fix: clearer message where no estimate total exists. Arizona answers {"data": null} in both years, and Pennsylvania 2021 is a fragment with no total. The error now reads "The FBI publishes no V total for AZ in 2022." Arizona's response is recorded verbatim as a new fixture, nibrs-estimation-state-5-133-2022.json; no existing fixture was touched.
  • a9a122e docs: reporting-format and counting-difference wording, explained under "Changes from the plan".

Task 5, 278ab62: terms and vignette. New vignette("estimates"), a README "Reported, estimated and imputed" section, @seealso links on five reference pages, a sentence in impute_reporting_gaps() saying its imputation is not the FBI's estimate, one wording fix in the geography vignette, and the CLAUDE.md roadmap entry.

Verification

expectations failures errors skipped
Offline suite, this branch 1,404 0 0 43 (all live)
Offline suite, base 99eeef3 1,299 0 0 36
Live suite (FBI_CDE_LIVE=true), this branch 1,584 0 0 0
  • R CMD check --no-manual: Status OK, with 0 errors, 0 warnings and 0 notes (R 4.3.3, UTF-8 session). Every Suggests package was installed, plus qpdf.
  • pkgdown::check_pkgdown(): "No problems found".
  • Locale: run these in a UTF-8 locale. In this container's default C locale, test-ascii-docs.R cannot translate the em-dashes already in man/ and reports 34 warnings; they count as results, so the base shows 1,333 and the check only passes on paper.

Knitted vignette against spec §3.3

share_estimated (vignette) spec §3.3
California 2021 0.8301776 → 83.0% 83.0%
California 2022 0.6546212 → 65.5% 65.5%
United States 2021 0.3040435 → 30.4% 30.4%
United States 2022 0.2411695 → 24.1% 24.1%

The rest of the California rows match too:

  • 2022: reported 193,824, reported_nibrs 71,625, reported_other 122,199, coverage 98.8% against 46.6% NIBRS-only.
  • 2021: reported_other −504.
  • California's own count: 183,546 is still below the FBI's 2021 lower bound (189,849).

Changes from the plan

  1. 2021 was not all NIBRS. The plan's vignette said "In 2021 every report reaching the FBI was NIBRS" and measured the counting difference on the nation in 2021. In six states (AZ, GA, LA, MD, NJ, PA), 2021 summarized counts include summary-format reports. New Jersey: 75% coverage either format against 45% NIBRS-only, and 5,353 of 12,972 violent crimes arrived in the old format. Paterson PD (NIBRS start 2021-06-01) has 607 violent crimes for January to May 2021 and no NIBRS counts behind them. Without those six states, the 2021 counting difference for violent crime is −1.2% (NIBRS counts more), not the +1.1% the national table showed. Agreed changes:
    • The vignette measures the counting difference on Texas 2022, whose two coverages match for every offense: violent crime −0.9%, every offense within 2% except burglary at 5.7%. That keeps the vignette at about 93 requests.
    • A New Jersey example shows the 2021 split; no list of states is hard-coded.
    • Estimated no longer says "in 2022" (vignette, imputation_gap() page, NEWS).
    • The imputation_gap() page quotes the Texas figures in place of "about 1% / 5% / 7%".
    • gap is kept apart from the counting difference: it compares two NIBRS figures. In Texas 2022 it runs from −7.3% to 2.9% of the estimate.
    • Spec §3.3 is left as written (historical). CLAUDE.md's capstone entry records the three facts it gets wrong.
  2. Branch. This session can only push to claude/inspiring-wright-usthec, so the handoff's claude/imputation-gap was not used.
  3. One test constant. The plan's California 2021 coverage value, 0.263218, fails its own tolerance = 1e-6, because testthat's tolerance is relative (off by 1.7e-6). It is written as 0.2632175; the fixture gives 0.2632175442.
  4. README.md. Rendered with pandoc 3.8.2: pandoc 3.6 to 3.8.2 reproduce the committed file, Ubuntu's 3.1.3 does not. One install sentence in the committed file was wrapped by hand, and every render rewraps it; I kept the committed wrapping so the diff shows only real changes.
  5. Smaller wording changes. The fbi vignette drops its "'Estimated' is a legacy name" aside, which the rename made moot. The @seealso lines put vignette("estimates") in backticks.
  6. Commits. Three fix and doc commits sit between Tasks 4 and 5. The handoff forbids force-pushing, so Tasks 2 and 4 could not be amended.

Not in this PR

🤖 Generated with Claude Code

https://claude.ai/code/session_01UY9bUXWGai1iHZLE63yAG8


Generated by Claude Code

Summary rape is the revised definition (NIBRS 11A, 11B and 11C). The
estimates' "Rape" indicator (118) is 11A alone, so imputation_gap()
compared an 11A estimate with all three codes: Texas 2022 came out 47%
below its own NIBRS counts. "Revised Rape" (120) covers all three.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UY9bUXWGai1iHZLE63yAG8
The API answers Arizona (both years) with {"data": null} and
Pennsylvania 2021 with a fragment that has no offense total.
imputation_gap() now says the FBI publishes no total there, and
get_nibrs_estimate() documents the zero-row result. The new fixture is
Arizona's recorded 2022 response.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UY9bUXWGai1iHZLE63yAG8
Six states' 2021 reported counts include summary-format reports (New
Jersey: 5,353 of 12,972 violent crimes), so the estimate models
old-format reporters in 2021 as well as 2022. Measured where every
report arrived in NIBRS (Texas 2022), the counting difference is about
-1% for violent crime, not the +1% the national 2021 figures showed. gap
compares two NIBRS figures, so the counting difference does not enter
it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UY9bUXWGai1iHZLE63yAG8
The vignette follows the plan with the changes agreed in review: the
counting difference is measured on Texas 2022, where every report
arrived in NIBRS, rather than on the nation in 2021, which includes
summary-format reports from six states; a New Jersey example shows
those 2021 reports; and the gap is kept apart from the counting
difference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UY9bUXWGai1iHZLE63yAG8
@github-actions

Copy link
Copy Markdown

Thanks for this — and one thing worth knowing before it happens.

Development happens in a private Gitea repository. Your pull request
will be fetched from here, landed there, and pushed back.

Because that merge preserves your commits at their original SHAs, GitHub will
mark this pull request "Merged" on its own
— without anyone visibly clicking
the Merge button, and possibly without a review comment on this page first.

If your pull request closes as "Merged" and nobody appears to have merged it,
that is the normal, successful outcome — not a rejection.

If it is not going to be merged, you will get an actual reply saying so.

Full details: CONTRIBUTING.md.

@jknowles
jknowles merged commit 9ffabea into main Oct 15, 2026
5 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.

2 participants