"""WHO (World Health Organization) life expectancy tables for lost_years.
The WHO table is GHO indicator WHOSIS_000001, *life expectancy at birth*. It
has no age dimension: one value per population, year and sex. The lookup
therefore answers questions about age 0 only, and says so in the name of the
column it returns. Asking it for remaining life expectancy at a given age is a
question it cannot answer, so an explicit ``age`` mapping raises instead of
being quietly ignored; use :func:`lost_years.lost_years_hld` for that.
"""
import logging
import sys
from typing import Any
import pandas as pd
import pyarrow.parquet as pq
from .datasets import resolve
from .utils import closest, run_lookup_cli
# Setup logger
logger = logging.getLogger(__name__)
# Not shipped: a packaged copy is stale the day WHO publishes a revision and
# nothing in the wheel would say so. `lost_years update --source who` fetches it.
WHO_FILENAME = "who.parquet"
# Same policy as SSA: report the matched year rather than refuse. See ssa.py.
WHO_YEAR_TOLERANCE = None
WHO_OUTPUT_COLS = [
"who_country",
"who_sex",
"who_year",
"who_life_expectancy_at_birth",
"who_match_status",
]
[docs]
class LostYearsWHOData:
"""WHO life-table lookup, caching the packaged table on first use."""
__df = None
@classmethod
def lost_years_who(
cls,
df: pd.DataFrame,
cols: dict[str, str] | None = None,
year_tolerance: float | None = WHO_YEAR_TOLERANCE,
) -> pd.DataFrame:
"""Append WHO life expectancy at birth to the input DataFrame.
Matches each row on country, sex and year using the column names given
by ``cols``. There is deliberately no age dimension: the packaged WHO
indicator is life expectancy *at birth*, so the returned column is
named for what it holds and an ``age`` mapping is refused.
Args:
df: Pandas DataFrame containing the input data.
cols: Column mapping for country, sex, and year in DataFrame.
None for default mapping: {'country': 'country',
'sex': 'sex', 'year': 'year'}.
year_tolerance: How far, in calendar years, the match may sit from
the requested year. None accepts any distance.
Returns:
Pandas DataFrame with WHO data columns:
'who_country', 'who_sex', 'who_year',
'who_life_expectancy_at_birth', 'who_match_status'.
Raises:
ValueError: If ``cols`` maps an ``age`` column. The WHO table
cannot answer an age-specific question.
Note:
Propagates :class:`lost_years.TableUnavailableError` when no WHO
table has been downloaded yet; run ``lost_years update --source
who`` once to install it.
"""
if cols is not None and "age" in cols:
raise ValueError(
"the WHO table is life expectancy at birth and has no "
"age dimension; drop the 'age' mapping, or use lost_years_hld "
"for remaining life expectancy at a given age"
)
df_cols = {}
for col in ["country", "sex", "year"]:
tcol = col if cols is None else cols[col]
if tcol not in df.columns:
logger.warning("No column `%s` in the DataFrame", tcol)
return df
df_cols[col] = tcol
if cls.__df is None:
cls.__df = (
pq.read_table(resolve("who", WHO_FILENAME))
.to_pandas()
.rename(columns={"country_code": "country", "sex_code": "sex"})
)
years = cls.__df["year"].unique()
records = []
for _, r in df.iterrows():
sex_in = str(r[df_cols["sex"]]).strip().lower()
sex = "MLE" if sex_in in ("m", "male", "mle", "1") else "FMLE"
country = str(r[df_cols["country"]]).strip().upper()
try:
year = closest(years, r[df_cols["year"]], tolerance=year_tolerance)
except ValueError as exc:
logger.warning("No WHO match: %s", exc)
records.append(cls.__no_match(str(exc)))
continue
sdf = cls.__df[
(cls.__df["country"].str.upper() == country)
& (cls.__df["sex"] == sex)
& (cls.__df["year"] == year)
]
if sdf.empty:
records.append(cls.__no_match("no WHO row for country, sex and year"))
continue
best = sdf.iloc[0]
records.append(
{
"who_country": best["country"],
"who_sex": best["sex"],
"who_year": int(best["year"]),
"who_life_expectancy_at_birth": float(best["life_expectancy"]),
"who_match_status": "ok",
}
)
result = df.copy()
appended = pd.DataFrame(records, columns=WHO_OUTPUT_COLS)
for col in WHO_OUTPUT_COLS:
result[col] = appended[col].to_numpy() if records else None
return result
@classmethod
def __no_match(cls, status: str) -> dict[str, Any]:
"""Build an all-missing WHO output record.
Args:
status: Why no life expectancy could be returned.
Returns:
Mapping of output column name to value.
"""
record: dict[str, Any] = dict.fromkeys(WHO_OUTPUT_COLS)
record["who_match_status"] = status
return record
lost_years_who = LostYearsWHOData.lost_years_who
[docs]
def main(argv: list[str] = sys.argv[1:]) -> int:
"""Run the ``lost_years_who`` command line interface.
Args:
argv: Command line arguments, defaulting to the process arguments.
Returns:
0 on success, -1 when a required column is missing or no WHO table has
been installed.
"""
return run_lookup_cli(
argv,
title="Appends WHO life expectancy at birth by country, sex and year",
columns=("country", "sex", "year"),
lookup=lambda df, cols, _: lost_years_who(df, cols=cols),
output_default="lost-years-output.csv",
output_help="Output file with Lost Years data column(s)",
)
if __name__ == "__main__":
sys.exit(main())