Recall windows and period=¶
food_expenditures() and food_quantities() return the survey's recorded
window by default. Passing period='day', 'week', 'month' or 'year'
rescales the flow using its declared wave exposure:
value_in_period = recorded_value * target_days / exposure_days
exposure_days = recall_days * n_asks_for_this_column
A month is 365.25/12 days and a year is 365.25 days. No conversion is applied
when period=None. This is a change of reference period, not an estimate of
unobserved acquisitions, a correction for missing interviews or a claim that
the window represents the whole year. Prices are not flows: food_prices,
food_acquired and unrelated tables refuse non-None period= explicitly.
import lsms_library as ll
record = ll.recall('Mali')
daily = ll.Country('Mali').food_expenditures(period='day')
Inspect the recall record before choosing a period. The packaged records currently establish a single declared exposure for 59 of 71 food cells. The remaining cells have no established window or vary within the wave. Questionnaire, variable-label and config-comment rungs remain distinct; a config-comment assertion converts but stays visibly weaker than a quoted questionnaire. Filename guesses and not-recorded cells do not convert.
ll.recall() includes n_asks_by_column where a column differs from the
module's count. Burkina Faso 2014 expenditure covers four seven-day asks
(28 days), while quantity covers only the first ask (7 days). Mali 2014-15
covers two seven-day asks (14 days). Its existing public series remains
collapsed: this metadata correction adds no visit axis and changes no default
quantity, expenditure, identifier or missing-value treatment.
Unavailable waves¶
Country raises lsms_library.errors.PeriodUnavailableError if a requested
conversion cannot be established. The error names the country, table, target,
unavailable waves and reasons, and convertible waves. No known wave is returned
scaled alongside an unknown wave left on its original clock. Vocabulary and
unsupported-table refusals precede the data read. Exposure availability is
checked on represented wave values: declaring a source does not prove it has
rows. Empty results remain healthy even if the requested recall is unknown;
existing metadata-proven-absent subsets also stay empty.
Feature('food_expenditures')(..., period='day') follows Contract B: keep
convertible wave rows, drop unavailable cells, emit one aggregate warning and
record their names in attrs['period_unavailable']. If none survives, the
existing canonical empty index remains available. The explicit period request
keeps Country's strict guards. On typed failure, a private one-shot continuation
finishes the same full unconverted result's normal poststeps, then Feature
slices and converts it. There is no second method call or smaller wave read to
recompute kilogram factors. Whole-read kilogram diagnostics retain that inference scope;
population, recall, sampling and derivation records describe the served slice.
What the conversion record means¶
attrs['period'][country] records the target, days, column and each wave's
exposure, factor, ask-count source and evidence rung. The exposure is one
declared constant per wave. If a served food table carries visits, the record
can disclose a food-row shortfall proxy. A zero-acquisition visit has no food
rows, so this is an upper bound on missing asks, not household cover status.
It never changes the denominator or household weights. The historical Burkina
food-row 9.3% / -3.94% result has that qualification; it is not a fresh measure
or a household missing-interview correction.
For collapsed Mali the record says shortfall_source='no-visit-level' and
shortfall=None. Where no visit frame is read, including a degraded Feature
slice, it says not-measured. No household ask count is invented. A future
visit carrier or household cover-status correction requires its own design.
The conversion uses declared exposure, not realized time between interviews. It does not equalize recall decay, first-ask effects, diary design, item lists or other survey measurement differences. Harmonizing the period does not make the underlying surveys interchangeable.
The evidence source is .coder/coverage/food_recall.csv; regenerate packaged
records with scripts/promote_recall_records.py. Preserve evidence citations
and qualifications when updating it. The library reads the packaged YAML,
including from an installed wheel; it does not depend on the checkout CSV.