Data methods and their keyword arguments¶
This page is generated
Generated by scripts/gen_data_method_docs.py from the live docstrings
of the generated data methods. Do not edit by hand -- change doc_parts in
lsms_library/country.py and re-run make docs-gen.
Every table a country declares becomes a method on Country:
import lsms_library as ll
gh = ll.Country('GhanaLSS')
gh.food_acquired() # a declared table
gh.food_prices() # derived at API time from food_acquired
These methods are created at attribute-access time from the country's
data_scheme, so they have no source definition for the API reference to pick
up -- which is why they are documented here instead of under
API / Country.
They share one keyword-argument surface. Not every method accepts every
kwarg: passing one where it does not apply raises TypeError naming the
methods that do accept it, rather than being silently ignored.
| kwarg | applies to | what it does |
|---|---|---|
waves= |
all | subset of waves; defaults to all available |
market= |
all | add a cluster_features column (e.g. 'Region') as an m index level |
labels= |
tables with a mapped level | relabel j (scalar form) or any level (dict form) |
units= |
food_prices, food_quantities |
price/quantity basis -- see below |
volume_as_mass= |
food_prices, food_quantities |
treat litres as kg |
currency= |
monetary tables | attach the ISO 4217 code as 'index' or 'column' |
numeraire= |
monetary tables | convert monetary columns to a common numeraire |
basis= |
food_expenditures |
'purchased' or 'total' |
valuation= |
food_expenditures (with basis='total') |
value produced / in-kind rows: 'own_price', 'median_price', or a tuple applied in order; off by default |
period= |
food_expenditures, food_quantities |
rescale by declared wave exposure; None preserves the recorded window; see recall |
age_cuts= |
household_characteristics |
age-bracket boundaries |
currency= and numeraire= are mutually exclusive. Available numeraires come
from lsms_library.conversion.conversion_targets():
food_prices()¶
Documents: units, volume_as_mass, currency, numeraire.
Return food_prices as a DataFrame, aggregated across *waves*.
Parameters
----------
waves : list of str, optional
Subset of waves to include. Defaults to all available.
In a kilogram mode, *waves* selects what is served, not
what the factors are estimated from: they read every
wave, so the result is the all-waves result restricted
to *waves*, and a cold call builds every wave of
``food_acquired`` (GH #1487).
market : str, optional
Column from cluster_features (e.g. 'Region') to add as
an ``m`` index level for demand estimation.
labels : str or dict, optional
**Scalar form** -- label column to use for the ``j`` index
on derived food tables (food_expenditures,
food_quantities, food_prices). Defaults to
``'Preferred'`` (current behaviour). Other values (e.g.
``'Aggregate'``) select a same-named column from the
country's ``food_items`` / ``harmonize_food`` table;
``food_expenditures`` and ``food_quantities`` are
re-aggregated after renaming. A scalar targets ``j`` and
ONLY ``j``, even on a table that also has a mapped column.
**Dict form** -- ``{target: variant}``, where *target*
names a column or index level (case-insensitive) and
*variant* selects the ``'<variant> Label'`` column (falling
back to ``'<variant>'``) of the country's same-named
``categorical_mapping`` table. E.g.
``labels={'Rural': 'Settlement'}`` decodes the raw
settlement code to the finer ladder instead of the
canonical ``Urban``/``Rural``. The key ``'j'`` is routed to
the scalar behaviour, so ``labels={'j': 'Aggregate'}`` and
``labels='Aggregate'`` are the same request.
A trailing ``' Label'`` is stripped, so ``'Aggregate Label'``
is ``'Aggregate'`` and ``'Preferred Label'`` is the no-op.
Every TEXT column of the food label table is selectable
(``'Original'`` on EHCVM countries, per-wave columns); a
NUMERIC column (``'Code'``, ``'FTC Code'``) is refused. A
``j`` the column does not label passes through unrenamed and
is reported on ``result.attrs['labels_unmatched']`` with a
``LabelPassThroughWarning`` (fatal under
``LSMS_LABELS_STRICT=1``). GH #787.
Raises ``LabelUnavailableError`` (a ``KeyError`` subclass)
when the country cannot honour the request -- it curates no
such label column, or the result has no such target at all;
``Feature`` degrades over both. A plain ``KeyError`` means
the mapping table is MALFORMED (no ``Preferred Label``, or
no key column left), which stays loud.
units : {'kgvalue', 'kgprice', 'unitvalue', 'unitprice'}, optional
Price basis. Default ``'kgvalue'`` (Expenditure /
Quantity_kg, currency per kg). Other modes:
``'unitvalue'`` (Expenditure / Quantity, per native
u; rows with u='Value' -- where it is the amount
over itself, 1.0 -- and with u='Unknown' are
dropped and counted in
``attrs['price_rows_dropped']`` as ``currency`` and
``unknown``, GH #1129 / #1068),
``'kgprice'`` (reported Price × kg_factor),
``'unitprice'`` (reported Price as-is).
``food_acquired.Price`` is whatever the source
recorded; in some countries (Uganda, measured:
94-99.9% of rows per wave) it is the statistics
office's own Expenditure / Quantity, so
``'unitprice'`` and ``'unitvalue'`` are NOT
independent sources (GH #845). Raises
``UnitsUnavailableError`` (a ``ValueError``
subclass) naming the country and the missing
column when ``food_acquired`` cannot serve the
mode -- no ``Price`` for the ``*price`` modes
(15 of 20 countries with a ``food_acquired``,
2026-10-17); ``Feature`` drops such countries
with one warning and
``attrs['units_unavailable']`` (GH #828). See
:func:`lsms_library.transformations.food_prices_from_acquired`
and ``slurm_logs/DESIGN_food_prices_units_kwarg_2026-05-06.org``.
volume_as_mass : bool, optional
When ``True`` (default), treat ``1 litre = 1 kg`` for
fluid units (litre, ml, cl) -- a specific-gravity-1
approximation, roughly right for water-based foods
and moderately wrong for cooking oil and alcohol.
Pass ``False`` to drop fluid units from the hand-coded
factor map and from the explicit-metric label parser;
their kg conversion (if any) then comes purely from
data-driven price-ratio inference. See GH #231.
currency : {'index', 'column'}, optional
Attach the ISO 4217 currency code (resolved per wave,
e.g. UGX, NGN, XOF; GhanaLSS 2005-06 -> GHC vs 2016-17
-> GHS) to this monetary table. ``'index'`` appends a
``currency`` index level; ``'column'`` adds a column.
Defaults to ``None`` (omit) for single-country calls;
``Feature(...)`` defaults to ``'index'``. See
:func:`lsms_library.currency.attach_currency`.
numeraire : str, optional
Convert the monetary columns to a comparable basis -- a
target column of ``conversion_factors.org`` (e.g.
``'PPP-2017'``, ``'FX'``, ``'USD-real-2017'``). Mutually
exclusive with ``currency``. Pre-reform redenomination
waves convert on contemporaneous old-currency rows; a
country or date absent from the factor table, or a
blank cell, yields ``NA`` with a warning. See
:func:`lsms_library.conversion.convert`.
food_expenditures()¶
Documents: basis, valuation, period.
Return food_expenditures as a DataFrame, aggregated across *waves*.
Parameters
----------
waves : list of str, optional
Subset of waves to include. Defaults to all available.
market : str, optional
Column from cluster_features (e.g. 'Region') to add as
an ``m`` index level for demand estimation.
labels : str or dict, optional
**Scalar form** -- label column to use for the ``j`` index
on derived food tables (food_expenditures,
food_quantities, food_prices). Defaults to
``'Preferred'`` (current behaviour). Other values (e.g.
``'Aggregate'``) select a same-named column from the
country's ``food_items`` / ``harmonize_food`` table;
``food_expenditures`` and ``food_quantities`` are
re-aggregated after renaming. A scalar targets ``j`` and
ONLY ``j``, even on a table that also has a mapped column.
**Dict form** -- ``{target: variant}``, where *target*
names a column or index level (case-insensitive) and
*variant* selects the ``'<variant> Label'`` column (falling
back to ``'<variant>'``) of the country's same-named
``categorical_mapping`` table. E.g.
``labels={'Rural': 'Settlement'}`` decodes the raw
settlement code to the finer ladder instead of the
canonical ``Urban``/``Rural``. The key ``'j'`` is routed to
the scalar behaviour, so ``labels={'j': 'Aggregate'}`` and
``labels='Aggregate'`` are the same request.
A trailing ``' Label'`` is stripped, so ``'Aggregate Label'``
is ``'Aggregate'`` and ``'Preferred Label'`` is the no-op.
Every TEXT column of the food label table is selectable
(``'Original'`` on EHCVM countries, per-wave columns); a
NUMERIC column (``'Code'``, ``'FTC Code'``) is refused. A
``j`` the column does not label passes through unrenamed and
is reported on ``result.attrs['labels_unmatched']`` with a
``LabelPassThroughWarning`` (fatal under
``LSMS_LABELS_STRICT=1``). GH #787.
Raises ``LabelUnavailableError`` (a ``KeyError`` subclass)
when the country cannot honour the request -- it curates no
such label column, or the result has no such target at all;
``Feature`` degrades over both. A plain ``KeyError`` means
the mapping table is MALFORMED (no ``Preferred Label``, or
no key column left), which stays loud.
period : {'day', 'week', 'month', 'year'}, optional
Rescale each wave from the window its survey recorded
to this one (``month`` = 365.25/12 days, ``year`` =
365.25): value x period_days / exposure_days, where
exposure is ``recall_days * n_asks`` from
``ll.recall()`` -- or the column's own count where the
record has ``n_asks_by_column`` (Burkina Faso 2014
quantities: 1 ask of 4). Default ``None`` returns the recorded
window unchanged. Raises ``PeriodUnavailableError``
(a ``ValueError``) naming every wave whose window is
not established -- not recorded, a weak rung, or
varying within the wave -- and the waves that do
convert (pass them as ``waves=``); ``Feature`` drops
only the unknown waves, with one warning and
``attrs['period_unavailable']``. The conversion is
recorded on ``attrs['period']``, which also discloses,
per wave, how many households the served
``food_acquired`` ``visit`` level shows asked FEWER
times than declared and the understatement that
implies (``shortfall``; the exposure is still one
constant per wave, option A, @ligon 2026-10-20) --
an upper bound, since a food-row count understates
the asks: a visit with no purchases has no rows.
GH #851; see ``docs/guide/recall.md``.
``food_prices`` refuses it: a price is not a flow.
currency : {'index', 'column'}, optional
Attach the ISO 4217 currency code (resolved per wave,
e.g. UGX, NGN, XOF; GhanaLSS 2005-06 -> GHC vs 2016-17
-> GHS) to this monetary table. ``'index'`` appends a
``currency`` index level; ``'column'`` adds a column.
Defaults to ``None`` (omit) for single-country calls;
``Feature(...)`` defaults to ``'index'``. See
:func:`lsms_library.currency.attach_currency`.
numeraire : str, optional
Convert the monetary columns to a comparable basis -- a
target column of ``conversion_factors.org`` (e.g.
``'PPP-2017'``, ``'FX'``, ``'USD-real-2017'``). Mutually
exclusive with ``currency``. Pre-reform redenomination
waves convert on contemporaneous old-currency rows; a
country or date absent from the factor table, or a
blank cell, yields ``NA`` with a warning. See
:func:`lsms_library.conversion.convert`.
household_characteristics()¶
Documents: age_cuts.
Return household_characteristics as a DataFrame, aggregated across *waves*.
Parameters
----------
waves : list of str, optional
Subset of waves to include. Defaults to all available.
market : str, optional
Column from cluster_features (e.g. 'Region') to add as
an ``m`` index level for demand estimation.
labels : str or dict, optional
**Scalar form** -- label column to use for the ``j`` index
on derived food tables (food_expenditures,
food_quantities, food_prices). Defaults to
``'Preferred'`` (current behaviour). Other values (e.g.
``'Aggregate'``) select a same-named column from the
country's ``food_items`` / ``harmonize_food`` table;
``food_expenditures`` and ``food_quantities`` are
re-aggregated after renaming. A scalar targets ``j`` and
ONLY ``j``, even on a table that also has a mapped column.
**Dict form** -- ``{target: variant}``, where *target*
names a column or index level (case-insensitive) and
*variant* selects the ``'<variant> Label'`` column (falling
back to ``'<variant>'``) of the country's same-named
``categorical_mapping`` table. E.g.
``labels={'Rural': 'Settlement'}`` decodes the raw
settlement code to the finer ladder instead of the
canonical ``Urban``/``Rural``. The key ``'j'`` is routed to
the scalar behaviour, so ``labels={'j': 'Aggregate'}`` and
``labels='Aggregate'`` are the same request.
A trailing ``' Label'`` is stripped, so ``'Aggregate Label'``
is ``'Aggregate'`` and ``'Preferred Label'`` is the no-op.
Every TEXT column of the food label table is selectable
(``'Original'`` on EHCVM countries, per-wave columns); a
NUMERIC column (``'Code'``, ``'FTC Code'``) is refused. A
``j`` the column does not label passes through unrenamed and
is reported on ``result.attrs['labels_unmatched']`` with a
``LabelPassThroughWarning`` (fatal under
``LSMS_LABELS_STRICT=1``). GH #787.
Raises ``LabelUnavailableError`` (a ``KeyError`` subclass)
when the country cannot honour the request -- it curates no
such label column, or the result has no such target at all;
``Feature`` degrades over both. A plain ``KeyError`` means
the mapping table is MALFORMED (no ``Preferred Label``, or
no key column left), which stays loud.
age_cuts : tuple of positive numbers, optional
Interior breakpoints between age buckets, passed to
:func:`lsms_library.transformations.roster_to_characteristics`.
Partitions ages into ``len(age_cuts) + 1`` half-open
buckets ``[0, c_0), [c_0, c_1), ..., [c_{n-1}, inf)``.
Defaults to ``(4, 9, 14, 19, 31, 51)``, producing the
compact labels ``00-03``, ``04-08``, …, ``51+``.
Fractional breakpoints (e.g. ``(0.5, 1, 5)``) are
allowed and trigger explicit ``[lo, hi)`` labels.
household_roster()¶
Documents: the common kwargs alone.
Return household_roster as a DataFrame, aggregated across *waves*.
Parameters
----------
waves : list of str, optional
Subset of waves to include. Defaults to all available.
market : str, optional
Column from cluster_features (e.g. 'Region') to add as
an ``m`` index level for demand estimation.
labels : str or dict, optional
**Scalar form** -- label column to use for the ``j`` index
on derived food tables (food_expenditures,
food_quantities, food_prices). Defaults to
``'Preferred'`` (current behaviour). Other values (e.g.
``'Aggregate'``) select a same-named column from the
country's ``food_items`` / ``harmonize_food`` table;
``food_expenditures`` and ``food_quantities`` are
re-aggregated after renaming. A scalar targets ``j`` and
ONLY ``j``, even on a table that also has a mapped column.
**Dict form** -- ``{target: variant}``, where *target*
names a column or index level (case-insensitive) and
*variant* selects the ``'<variant> Label'`` column (falling
back to ``'<variant>'``) of the country's same-named
``categorical_mapping`` table. E.g.
``labels={'Rural': 'Settlement'}`` decodes the raw
settlement code to the finer ladder instead of the
canonical ``Urban``/``Rural``. The key ``'j'`` is routed to
the scalar behaviour, so ``labels={'j': 'Aggregate'}`` and
``labels='Aggregate'`` are the same request.
A trailing ``' Label'`` is stripped, so ``'Aggregate Label'``
is ``'Aggregate'`` and ``'Preferred Label'`` is the no-op.
Every TEXT column of the food label table is selectable
(``'Original'`` on EHCVM countries, per-wave columns); a
NUMERIC column (``'Code'``, ``'FTC Code'``) is refused. A
``j`` the column does not label passes through unrenamed and
is reported on ``result.attrs['labels_unmatched']`` with a
``LabelPassThroughWarning`` (fatal under
``LSMS_LABELS_STRICT=1``). GH #787.
Raises ``LabelUnavailableError`` (a ``KeyError`` subclass)
when the country cannot honour the request -- it curates no
such label column, or the result has no such target at all;
``Feature`` degrades over both. A plain ``KeyError`` means
the mapping table is MALFORMED (no ``Preferred Label``, or
no key column left), which stays loud.
Discovering this at the console¶
The same text is on every generated method, so the authoritative copy is always one call away and can never be staler than the code: