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 |
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.
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.
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; gives 1 = Kwacha-per-Kwacha for u='Value' rows),
``'kgprice'`` (reported Price × kg_factor),
``'unitprice'`` (reported Price as-is). 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.
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.
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.
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.
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.
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: