Skip to content

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():

FX, LCU-real-2017, PPP-2011, PPP-2017, PPP-2021, USD-real-2017

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:

help(ll.Country('GhanaLSS').food_prices)