food_expenditures is purchased-value-only library-wide — decide: by design, or add total-acquisition-value?

[ligon]

Surfaced by the #218 adversarial review (workflow wuiofz6p0)

Modern food_expenditures (transformations.food_expenditures_from_acquired) sums Expenditure over the acquisition-source level s — but the canonical builder (build_transforms.food_acquired_to_canonical) sets Expenditure = NaN on produced / in-kind s-rows. Net: food_expenditures is purchased value only, for every country.

Verified (BF): food_expenditures summed over s = purchased-only; produced rows present in food_acquired (Quantity retained) but Expenditure structurally 0/NaN. For GhanaSPS, own-production + in-kind ≈ 30.4% of total food value.

The question (library-wide, NOT #218-specific)

• By design? food_expenditures = cash outlay, so own-production (imputed value) legitimately excluded. The total-acquisition VALUE is reconstructable: food_quantities × food_prices(units='unitprice').
• Or a gap? Total acquisition value (purchased + imputed own-production + in-kind) is a common analytic need (rural welfare), and forcing every analyst to reconstruct it is error-prone.

Options

1. Document food_expenditures as purchased-only + a recipe / helper for total acquisition value.
2. Add a value= kwarg or a food_value derived table that imputes produced/in-kind value from unit prices.
3. Carry Expenditure on produced/in-kind rows where the source reports it (e.g. GhanaSPS).

Needs a design decision before the Phase-3 canonicalizations (#218) bake in one convention. Design: slurm_logs/DESIGN_218_food_legacy_retirement.org (rev-2, 'Separate, library-wide question').

[ligon]

Decision implemented: basis= kwarg (purchased default) — PR #584

food_expenditures(basis='purchased'|'total'), purchased the default, mirroring the Phase-4 food_prices/food_quantities units= precedent.

• 'purchased' (default): cash outlay only (s=='purchased') — consistent across all countries, removing the divergence this issue flagged (Serbia/GhanaSPS no longer fold own-production into the default; verified Serbia 25.1M, GhanaSPS 3.49M purchased-only).
• 'total': sum of recorded acquisition value across sources (Serbia 29.7M, GhanaSPS 4.85M); equals purchased where the source recorded no produced/in-kind value (Guatemala, stock-helper countries) — nothing fabricated.

Coverage note: purchased-only default correctly drops own-production-only households (Uganda 2009-10: 2900 vs 2929 HH).

Split out (#585): imputing own-production value at purchase prices so basis='total' is a faithful total everywhere (a modelling step — price granularity, never-purchased items). This issue closes when #584 merges; the imputation continues in #585.