Country

Country

Country(country_name: str, preload_panel_ids: bool = False, verbose: bool = False, trust_cache: bool = False)

Primary interface to a single country's LSMS survey data.

Provides access to all survey waves, standardized tables, and panel data. Tables listed in data_scheme are available as callable attributes (e.g. country.food_expenditures()).

Parameters:

Name	Type	Description	Default
country_name	str	Directory name under lsms_library/countries/ (e.g. 'Uganda', 'Tanzania').	required
preload_panel_ids	bool	If True, compute panel ID mappings eagerly at construction time. Default is False (lazy).	False
verbose	bool	Enable verbose logging.	False
trust_cache	bool	If True, read existing cached Parquet files directly without validating their hashes. Useful on clusters with pre-built data.	False

Examples:

>>> import lsms_library as ll
>>> uga = ll.Country('Uganda')
>>> uga.waves
['2005-06', '2009-10', ...]
>>> uga.data_scheme
['food_acquired', 'household_roster', ...]
>>> food = uga.food_expenditures()

waves property

waves: list[str]

List of names of waves available for country.

data_scheme property

data_scheme: list[str]

List of data objects available for country.

resources property

resources: dict[str, Any]

formatting_functions property

formatting_functions: dict[str, Callable[..., Any]]

categorical_mapping property

categorical_mapping: dict[str, DataFrame]

Get the categorical mapping for the country. Searches current directory, then parent directory.

mapping property

mapping: dict[str, Any]

panel_ids property

panel_ids: dict[str, Any] | None

Raw panel-ID tables keyed by wave. Computed lazily on first access.

updated_ids property

updated_ids: dict[str, dict[str, str]] | None

Mapping {old_id: new_id} per wave for ID harmonization. Computed lazily.

cached_datasets

cached_datasets() -> list[str]

List dataset names currently cached for this country.

test_all_data_schemes

test_all_data_schemes(waves: list[str] | None = None) -> dict[str, str]

Test whether all method_names in obj.data_scheme can be successfully built. Falls back to Makefile if not in data_scheme.