docs(#601): record the sampling universe, exclusions and sub-samples in 38 country CONTENTS.org

[ligon]

Records, in each country's _/CONTENTS.org, what the survey documentation claims its sample represents — the declared universe, the exclusions, and the sub-samples/oversamples that live inside a wave.

Refs #601, #603, #654.

What this is (and is not)

This is evidence, not representation.

• Every universe/exclusion/sub-sample statement is quoted verbatim, with a file + page locator or a named catalog field, and a note on whether the statement is held in this repo or lives only in World Bank NADA catalog metadata (a moving target the library does not hold).
• Gaps are recorded as gaps, naming exactly what was searched — per the standing rule in CLAUDE.md against unevidenced "no module here" claims. "None found" never means "none exists".
• Nothing is inferred from the .dta files. No microdata was opened. What a survey claims and what its data contain are two different facts and are kept apart deliberately.
• No schema is proposed. No YAML key, no data_scheme.yml change, no code. design(#601): the population record — declaring what a sample represents [DECISION NEEDED] #603 owns the decision about how the library represents any of this; this PR only makes sure the evidence exists to decide from.

Only lsms_library/countries/*/_/CONTENTS.org is touched — 38 files, all additions, no deletions.

Countries

38 sections applied: Afghanistan, Albania, Armenia, Azerbaijan, Benin, Burkina Faso, Cambodia, China, Côte d'Ivoire, Ethiopia, EthiopiaRHS, GhanaLSS, GhanaSPS, Guatemala, Guinea-Bissau, Guyana, India, Iraq, Kazakhstan, Kosovo, Liberia, Malawi, Mali, Nepal, Niger, Nigeria, Pakistan, Panama, Peru, Senegal, Serbia, Serbia and Montenegro, South Africa, Tajikistan, Tanzania, Timor-Leste, Togo, Uganda.

Four had no _/CONTENTS.org at all and now have one: Afghanistan, Armenia, Peru, Serbia and Montenegro.

How much is actually there

Counting a country as carrying the item if at least one of its waves has it stated in documentation (not inferred):

	count
carry a documented exclusion (institutional, geographic, security, residence-duration, …)	30 of 38
record no exclusion statement anywhere — a checked gap, not a finding of "nothing excluded"	8 (Cambodia, GhanaSPS, Guatemala, Guyana, India, Iraq, Kazakhstan, Tajikistan)
carry a documented oversample, booster, panel/refresh split, module sub-sample or disproportionate allocation	31 of 38
state that no oversample is documented	7 (Benin, Guatemala, Guinea-Bissau, Kazakhstan, Niger, South Africa, Togo)

Two patterns recur across the corpus and are flagged wherever they appear:

• Specialization lives inside a wave, not as a whole wave. Uganda's 20% target-tracking sub-frame, Ethiopia's structural 10-of-12 agricultural households in every rural EA, Malawi's IHPS panel drawn inside IHS3, Nigeria's conflict-area oversample (W3) then rural-Borno exclusion (W4), Mali's rural Lourd/Léger split, Iraq's one-third time-use module, India's double-rate 30-village oversample, Azerbaijan's three separately-drawn sub-populations. Unweighted country means are frequently not what they look like.
• NADA boilerplate is not a statistical office's claim. The sentence "The survey covered all de jure households excluding prisons, hospitals, military barracks, and school dormitories." appears verbatim in 15 waves, including countries with no plausible shared instrument. Every section that carries it says so explicitly and grades it as weaker evidence than survey-specific prose.

Tensions with existing text — flagged, never overwritten

Nine countries' evidence disagrees with something already in the file. In every case both sides are quoted in place, the disagreement is named, and nothing existing was edited or deleted:

• Azerbaijan — the DDI says the 3-valued weight is exactly the intended three-group post-stratification factor W and "weighting factors must be applied"; the existing Data Quality note calls it a fallback and advises treating Azerbaijan as effectively unweighted. Resolving it needs a data check that was deliberately not run.
• Côte d'Ivoire — the catalog describes a rotating two-year CILSS panel (half replaced each year); the existing text says households were followed across 4 waves. Left for whoever implements panel_ids.
• Ethiopia — the ESS covered all urban areas from wave 2; the existing Overview's "rural and small-town areas in waves 1-3" applies to wave 1 alone. A one-word fix is suggested, not applied. Also an open question on ESPS-5 longitudinal weights.
• GhanaLSS — GSS's own GLSS3 report documents a rotating panel with a half-retained GLSS1→GLSS2 sample; the existing Survey Program text says there is no such mechanism (defensible from GLSS3 on, not before). Plus: GLSS5's agriculture sections use a flat grossing-up factor of 637.89, not weight.
• Guinea-Bissau — the DDI splits each EA between the two vagues, which contradicts the repo-wide EHCVM convention that each grappe is visited in exactly one vague. Settling it needs a grappe × vague crosstab.
• Mali — only 2018-19 and 2021-22 are EHCVM; 2014-15 and 2017-18 are EAC-I, a different survey (and in 2014-15 the rural observation unit is the agricultural holding, not the household). The Overview's opening line should be amended.
• Nepal — "no rotating panel or refreshment sample" reads as "no panel", but NLSS-II and NLSS-III each drew a separate panel sample; bears on the weight/panel_weight → wt_hh mapping. Also a catalog-id error in Data Acquisition Status (NLSS II = 74, not 1000).
• Nigeria — wt_wave5 is the wave-4-to-5 longitudinal combined-sample weight, not a "general wave weight". The library's mappings are correct; only the annotation is wrong.
• Uganda — the 2015-16 DDI puts the each-wave one-third rotation in the future conditional; the existing text states it unqualified. Also a 3,123-vs-3,200 discrepancy within the primary sources, recorded so a reader who meets 3,200 knows it is documentation inconsistency, not a second sample.

Placement

Each section went where it belongs in that file's existing structure — beside the country's own Sampling Design / Survey Program material where that exists, above the issue list otherwise — cross-referencing rather than duplicating. Malawi and Uganda are filed one level down as the last subsection of their existing * Sampling Design, placed so that every "…above" reference in the new prose resolves correctly.

Verified before commit: the inserted block is byte-identical to the drafted fragment in all 38 files (quotes untouched, no reflow); headings nest; #+begin_/#+end_ blocks and drawers balance; tables are non-ragged; no stray fragment markers. Two pre-existing org level-jumps (Guinea-Bissau, Togo plot_features) are untouched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Su5JKX3wKChyfMAdXrdCTr