Skip to content

docs: a notebook for summary-event allocation, and two findings it surfaced (#533) - #538

Open
Polichinel wants to merge 1 commit into
developmentfrom
docs/533-allocation-notebook
Open

Polichinel wants to merge 1 commit into
developmentfrom
docs/533-allocation-notebook

Conversation

@Polichinel

Copy link
Copy Markdown
Contributor

Adds notebooks/summary_event_allocation.ipynb, following the convention set by acled_cursor_parity.ipynb: a question as the title, narrative markdown, committed outputs.

Unlike that notebook, this one re-runs. Every number is recomputed from the consolidated store, and the three viewpoints come from the same scripts/build_viewpoint.py the pipeline uses. First run builds them (~11 min) and caches under data/viewpoint/allocation_comparison/, which is gitignored.

Six figures

1 One cell, one month: 113,395 → 1,180 → 240
2 December 2021 on the grid, three panels
3 The monthly series a model would be trained on
4 Rank-size head of every state-based cell-month
5 Monthly concentration since 2000
6 The 13 months since 1989 where one cell held >70% of the world

Two findings that came out of writing it

Neither was known before. Both are in §3, measured, with the cells that produce them.

1. Production drops imprecise events, it does not merely mis-place them.

production_parity excludes where_prec ∈ {4, 6}. That is 43,933 events carrying 785,626 fatalities — +22.6% on what production reports today. The new profiles admit them, per ADR-049.

This is the dominant difference between profiles, it is an addition of recorded deaths rather than a redistribution, and anyone comparing totals across a profile switch will meet it before they meet anything else. It is the single most important fact for planning the switch.

2. ceil_split reports deaths that are not in the source.

On the events both builds contain, they agree to within 104 out of 3.47M. The disagreement is not rounding noise in both directions: the legacy splitter rounds each month's share up, so a multi-month event gains a death per month.

Measured against the largest value UCDP ever recorded for each event across every candidate version in the store:

profile events over the ceiling deaths invented
production_parity 74 96
kgi_kti_distributed 0 0
kgi_kti_activity 0 0

96 deaths out of 3.47M is small. It is also live in production today, and it is the current path reporting more than the source contains.

What the notebook asserts

The naive check — "all three builds carry the same total" — is wrong, and I wrote it that way first. It fails for reason 1 above, which is intended behaviour.

What the notebook asserts instead is the property that holds and can fail: no allocator may report more deaths for an event than UCDP ever recorded for it. The guard is not decorative — the same code path returns 74/96 for production_parity and 0/0 for the apportioned builds, so it is seen to fire on real input in the notebook itself.

Not in scope here

No profile change, no pipeline change. production_parity remains what refresh_pipeline.sh invokes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EfeuULbPTqrx4qtNki5dy9

…t surfaced (#533)

Draws the #533 defect and the three candidate allocations against the live
consolidated store: one cell holding 113,395 state-based deaths in December
2021, the same month on the grid, the monthly series a model would train on,
the rank-size head of the whole dataset, and the 13 months since 1989 where
one cell held over 70% of the world.

Writing the conservation check surfaced two things that were not known:

1. production_parity does not merely mis-place imprecise events, it DROPS
   them. 43,933 events carrying 785,626 fatalities (+22.6% on what production
   reports) are excluded by where_prec in (4, 6) and admitted by the new
   profiles. Anyone comparing totals across a profile switch meets this
   first.

2. The legacy ceil_split reports 96 deaths across 74 events that appear in
   no version of the source, because it rounds each month's share up. The
   apportioned profiles exceed the source on zero events. Both numbers come
   from the same code path, so the check is not decorative.

The naive "all three totals are equal" assertion is therefore wrong and is
not what the notebook asserts. It asserts the property that holds and can
fail: no allocator may report more deaths for an event than UCDP ever
recorded for it in any candidate version.

Outputs are committed. First run builds the three viewpoints (~11 min) and
caches them under data/viewpoint/allocation_comparison/, which is gitignored.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EfeuULbPTqrx4qtNki5dy9
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