Coverage¶

The country × feature × wave coverage/readiness model behind ll.coverage() and the make matrix CLI.

coverage_matrix ¶

Country × Feature × Wave coverage / readiness model.

The importable core behind bench/matrix.py and the ll.coverage() reader. Composes existing machinery — it does not reinvent sanity checks or the declared matrix:

axes / declared coverage -> :mod:lsms_library.catalog + Country.waves + Wave.data_scheme (config only; no builds, no auth);
per-wave readiness -> :func:diagnostics.load_feature builds the country-level table once; we slice it on the t index level and run the existing :func:diagnostics.is_this_feature_sane per wave.

See .coder/charter-coverage-matrix.md and .coder/ledger/coverage-matrix.md.

Tier ladder (worst→best; each derived from existing machinery only):

========== =========================================================== tier meaning ========== =========================================================== n/a no per-wave readiness applies (country-level-only feature, or the built table has no t axis) absent feature applies to the country but its source is not declared for this wave (feature ∉ Wave.data_scheme ∪ derived) declared source present for the wave; readiness not assessed (coverage-only run) dropped source declared for the wave but the wave is missing / empty in the built table (the silent-drop bug class, e.g. Iraq #532) broken the country-level build raised, or the whole feature is empty builds wave slice is non-empty but SanityReport.ok is False sane wave slice is non-empty and SanityReport.ok is True blessed sane and listed in the git-tracked blessing file ========== ===========================================================

coverage ¶

coverage(refresh: bool | str = False, *, countries=None, features=None, snapshot: Path | None = None) -> pd.DataFrame

Return the country × feature × wave status table.

Parameters:

Name	Type	Description	Default
`refresh`	`bool \| str`	`False` — load the committed snapshot (the last `make matrix` readiness run). Raises `FileNotFoundError` with guidance if absent. `"coverage"` (or `True`) — recompute the live coverage layer fresh from config (no builds, no auth). Always current; no readiness tiers. `"readiness"` — recompute the full matrix in-process (heavy; builds every cell). Mostly for tests / one-offs.	`False`
`countries`	`list[str] \| None`	Restrict a refresh; ignored when reading the snapshot.	`None`
`features`	`list[str] \| None`	Restrict a refresh; ignored when reading the snapshot.	`None`
`snapshot`	`Path \| None`	Override the snapshot location (env `LSMS_COVERAGE_SNAPSHOT` also works).	`None`

Returns:

Type	Description
`pandas.DataFrame (columns: country, feature, wave, tier, coverage, n_rows, detail)`

build_matrix ¶

build_matrix(countries=None, features=None, *, readiness=True, blessed=None, log=lambda _m: None) -> pd.DataFrame

Build the full (country × feature × wave) status table.

Parameters:

Name	Type	Description	Default
`countries`	`list[str] \| None`	Restrict the sweep; `None` = all.	`None`
`features`	`list[str] \| None`	Restrict the sweep; `None` = all.	`None`
`readiness`	`bool`	If `False`, emit only the cheap coverage layer (no builds, no auth).	`True`
`blessed`	`set \| None`	Blessed-cell set; defaults to :func:`load_blessed`.	`None`
`log`	`callable`	Progress sink (one line per country).	`lambda _m: None`

grade_feature ¶

grade_feature(country_name, feature, waves, co, env, *, avail_by_wave=None, blessed=frozenset(), readiness=True) -> list[dict]

Per-wave cells for one (country, feature).

Builds the country-level table at most once (readiness=True) and grades each wave by slicing on t and reusing is_this_feature_sane.

avail_by_wave maps wave -> available-feature set; :func:build_matrix precomputes it once per country (it is identical across that country's features). When None we compute it here, keeping the function self-contained for tests / one-off calls.

grade_country_level ¶

grade_country_level(country_name, feature, co, env, *, blessed=frozenset(), readiness=True) -> dict

Grade a country-level-only feature (panel_ids / updated_ids): wave=None.

load_blessed ¶

load_blessed(path: Path | None = None) -> set[tuple[str, str, str]]

Return the git-tracked set of blessed (country, feature, wave) cells.

CSV with header country,feature,wave (wave blank for country-level features). Missing file → empty set.

save_snapshot ¶

save_snapshot(df: DataFrame, path: Path | None = None) -> Path

Write the status table to the git-tracked snapshot CSV.

default_snapshot_path ¶

default_snapshot_path() -> Path

Resolve the status snapshot CSV (env → CWD → repo root).