sdg11 0.1.0__py3-none-any.whl

sdg11/__init__.py

@@ -0,0 +1,73 @@
+"""sdg11 - UN Sustainable Development Goal 11 urban indicators from open data.
+
+Indicators follow the published UN-Habitat / WHO metadata and the Degree of
+Urbanisation manual. This is an independent open-source implementation, not an
+official UN product.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from ._result import IndicatorResult
+from .air_quality import (
+    WHO_2021_ANNUAL,
+    annual_mean,
+    assign_nearest_station,
+    population_weighted_concentration,
+)
+from .citations import ALL_CITATIONS, Citation
+from .components import label
+from .config import run_config
+from .degurba import (
+    RURAL,
+    URBAN_CENTRE,
+    URBAN_CLUSTER,
+    DegurbaResult,
+    classify_degurba,
+)
+from .geometry import project_lonlat
+from .housing import is_overcrowded, slum_proportion
+from .land import built_up_area_km2, land_consumption, land_consumption_from_grids
+from .network import WalkNetwork
+from .open_space import (
+    average_open_space_share,
+    open_space_access,
+    open_space_share,
+    polygons_area_km2,
+)
+from .report import Report, report
+from .transport import capacity_class, public_transport_access
+
+__all__ = [
+    "__version__",
+    "ALL_CITATIONS",
+    "Citation",
+    "DegurbaResult",
+    "IndicatorResult",
+    "Report",
+    "RURAL",
+    "URBAN_CENTRE",
+    "URBAN_CLUSTER",
+    "WHO_2021_ANNUAL",
+    "WalkNetwork",
+    "annual_mean",
+    "assign_nearest_station",
+    "average_open_space_share",
+    "built_up_area_km2",
+    "capacity_class",
+    "classify_degurba",
+    "is_overcrowded",
+    "label",
+    "land_consumption",
+    "land_consumption_from_grids",
+    "open_space_access",
+    "open_space_share",
+    "polygons_area_km2",
+    "population_weighted_concentration",
+    "project_lonlat",
+    "public_transport_access",
+    "report",
+    "run_config",
+    "slum_proportion",
+]

sdg11/_result.py

@@ -0,0 +1,117 @@
+"""Result container shared by every indicator function."""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+
+from .citations import Citation
+
+
+def _jsonable(value: Any) -> Any:
+    """Convert numpy scalars/arrays and nested containers into JSON-safe values."""
+    if isinstance(value, Citation):
+        return value.to_dict()
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v) for v in value]
+    if isinstance(value, np.ndarray):
+        return _jsonable(value.tolist())
+    if isinstance(value, np.generic):
+        return _jsonable(value.item())
+    if isinstance(value, float) and not math.isfinite(value):
+        return None
+    return value
+
+
+@dataclass
+class IndicatorResult:
+    """Outcome of one SDG 11 indicator computation.
+
+    Attributes:
+        indicator: Official indicator code, e.g. ``"11.2.1"``.
+        name: Short human-readable indicator name.
+        value: Headline value in ``unit`` (``None`` when it is mathematically undefined,
+            e.g. a zero population growth rate in 11.3.1).
+        unit: Unit of ``value`` (``"%"``, ``"ratio"``, ``"ug/m3"``...).
+        components: Intermediate quantities and companion metrics, keyed by name.
+        metadata: Indicator code, method version, parameters and citations.
+        how_to_report: Short guidance on reporting the value.
+        disaggregation: Optional breakdown of ``value`` by population group.
+        warnings: Data-quality notes raised during the computation.
+    """
+
+    indicator: str
+    name: str
+    value: Optional[float]
+    unit: str
+    components: Dict[str, Any] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    how_to_report: str = ""
+    disaggregation: Dict[str, Any] = field(default_factory=dict)
+    warnings: List[str] = field(default_factory=list)
+
+    @property
+    def citations(self) -> List[Citation]:
+        """Citations attached to the method."""
+        cites = self.metadata.get("citations", [])
+        return [c for c in cites if isinstance(c, Citation)]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a JSON-serialisable dictionary."""
+        out: Dict[str, Any] = {
+            "indicator": self.indicator,
+            "name": self.name,
+            "value": self.value,
+            "unit": self.unit,
+            "components": self.components,
+            "disaggregation": self.disaggregation,
+            "metadata": self.metadata,
+            "how_to_report": self.how_to_report,
+            "warnings": self.warnings,
+        }
+        result = _jsonable(out)
+        assert isinstance(result, dict)
+        return result
+
+    def to_json(self, indent: Optional[int] = 2) -> str:
+        """Serialise to a JSON string."""
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+    def formatted_value(self, digits: int = 2) -> str:
+        """Value rounded for tables, or ``"n/a"`` when undefined."""
+        if self.value is None or not math.isfinite(self.value):
+            return "n/a"
+        return f"{self.value:.{digits}f}"
+
+    def __str__(self) -> str:
+        unit = "" if self.unit in ("", "ratio") else f" {self.unit}"
+        return f"SDG {self.indicator} {self.name}: {self.formatted_value()}{unit}"
+
+
+def build_metadata(
+    indicator: str,
+    method_version: str,
+    citations: List[Citation],
+    parameters: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Assemble the standard metadata block used by every result."""
+    from . import __version__
+
+    return {
+        "indicator": indicator,
+        "method_version": method_version,
+        "software": f"sdg11 {__version__}",
+        "parameters": dict(parameters or {}),
+        "citations": list(citations),
+        "disclaimer": (
+            "Computed with the open-source sdg11 package; not an official UN or "
+            "UN-Habitat product. Validate against national statistical procedures "
+            "before official reporting."
+        ),
+    }

sdg11/air_quality.py

@@ -0,0 +1,166 @@
+"""SDG 11.6.2 - Annual mean levels of fine particulate matter in cities (population weighted).
+
+The custodian agency (WHO) defines the indicator as the annual mean concentration of
+PM2.5 (or PM10) to which the urban population is exposed, weighted by population::
+
+    C_pw = sum(P_i * C_i) / sum(P_i)
+
+over the population units ``i`` (grid cells or neighbourhoods) of the city. Exposure
+is compared with the 2021 WHO air quality guideline levels and interim targets.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+from ._result import IndicatorResult, build_metadata
+from .citations import WHO_11_6_2, WHO_AQG_2021
+from .geometry import as_points, nearest
+
+METHOD_VERSION = "WHO 11.6.2 metadata, population-weighted annual mean (sdg11 v1)"
+
+#: 2021 WHO annual-mean levels in ug/m3: interim targets 1-4 and the guideline (AQG).
+WHO_2021_ANNUAL: Dict[str, Dict[str, float]] = {
+    "PM2.5": {"IT-1": 35.0, "IT-2": 25.0, "IT-3": 15.0, "IT-4": 10.0, "AQG": 5.0},
+    "PM10": {"IT-1": 70.0, "IT-2": 50.0, "IT-3": 30.0, "IT-4": 20.0, "AQG": 15.0},
+}
+
+HOW_TO_REPORT = (
+    "Report the population-weighted annual mean concentration in ug/m3 for the city "
+    "(urban centre), the pollutant (PM2.5 preferred), reference year, concentration source "
+    "(monitors, satellite-derived model or fusion) and population source. Add the share of "
+    "the population exposed above the WHO 2021 guideline and interim targets."
+)
+
+
+def _pollutant_key(pollutant: str) -> str:
+    key = pollutant.strip().upper().replace("_", ".").replace(" ", "")
+    if key in ("PM2.5", "PM25"):
+        return "PM2.5"
+    if key == "PM10":
+        return "PM10"
+    raise ValueError("pollutant must be 'PM2.5' or 'PM10'.")
+
+
+def annual_mean(
+    values: Any, expected_count: Optional[int] = None, min_coverage: float = 0.75
+) -> Tuple[Optional[float], float]:
+    """Annual mean of a monitor time series with a data-completeness check.
+
+    Args:
+        values: Daily (or hourly) concentrations; ``NaN`` marks missing records.
+        expected_count: Records expected in the year (e.g. 365 or 8760). Defaults to the
+            length of ``values``.
+        min_coverage: Minimum share of valid records (75 % is the usual criterion).
+
+    Returns:
+        ``(mean, coverage)``; ``mean`` is ``None`` when coverage is insufficient.
+    """
+    arr = np.asarray(values, dtype=float).ravel()
+    n_expected = int(expected_count) if expected_count is not None else arr.size
+    if n_expected <= 0:
+        raise ValueError("expected_count must be positive.")
+    valid = arr[np.isfinite(arr)]
+    coverage = valid.size / n_expected
+    if coverage < min_coverage or valid.size == 0:
+        return None, coverage
+    return float(valid.mean()), coverage
+
+
+def assign_nearest_station(
+    population_xy: Any,
+    station_xy: Any,
+    station_values: Any,
+    max_distance_m: float = float("inf"),
+) -> np.ndarray:
+    """Give each population point the value of its nearest monitoring station.
+
+    Points farther than ``max_distance_m`` from any station get ``NaN`` (and are then
+    excluded by :func:`population_weighted_concentration`).
+    """
+    vals = np.asarray(station_values, dtype=float).ravel()
+    if vals.shape[0] != as_points(station_xy).shape[0]:
+        raise ValueError("station_values must have one value per station.")
+    dist, idx = nearest(population_xy, station_xy)
+    out = np.full(dist.shape[0], np.nan)
+    ok = (idx >= 0) & (dist <= max_distance_m)
+    out[ok] = vals[idx[ok]]
+    return out
+
+
+def population_weighted_concentration(
+    concentration: Any,
+    population: Any,
+    pollutant: str = "PM2.5",
+    year: Optional[int] = None,
+) -> IndicatorResult:
+    """Population-weighted annual mean PM concentration (SDG 11.6.2).
+
+    Args:
+        concentration: Annual mean concentration (ug/m3) per population unit; any shape,
+            ``NaN`` for missing values.
+        population: Population per unit, same shape as ``concentration``.
+        pollutant: ``"PM2.5"`` or ``"PM10"``.
+        year: Optional reference year stored in the metadata.
+    """
+    key = _pollutant_key(pollutant)
+    c = np.asarray(concentration, dtype=float).ravel()
+    p = np.asarray(population, dtype=float).ravel()
+    if c.shape != p.shape:
+        raise ValueError("concentration and population must have the same shape.")
+    p = np.where(np.isfinite(p) & (p > 0), p, 0.0)
+    ok = np.isfinite(c) & (c >= 0)
+    warnings: List[str] = []
+    excluded = float(p[~ok].sum())
+    total = float(p.sum())
+    if excluded > 0:
+        warnings.append(
+            f"{excluded:.0f} residents ({100.0 * excluded / total:.1f} %) live in units without "
+            "a valid concentration and were excluded."
+        )
+    covered = float(p[ok].sum())
+    value: Optional[float] = None
+    if covered > 0:
+        value = float((p[ok] * c[ok]).sum() / covered)
+    else:
+        warnings.append("No population with a valid concentration; the indicator is undefined.")
+    exceed: Dict[str, Any] = {}
+    for level, threshold in WHO_2021_ANNUAL[key].items():
+        above = ok & (c > threshold)
+        exceed[level] = {
+            "threshold_ug_m3": threshold,
+            "population_above": float(p[above].sum()),
+            "share_above_pct": 100.0 * float(p[above].sum()) / covered if covered else None,
+        }
+    components: Dict[str, Any] = {
+        "pollutant": key,
+        "population_weighted_mean_ug_m3": value,
+        "unweighted_mean_ug_m3": float(c[ok].mean()) if ok.any() else None,
+        "min_ug_m3": float(c[ok].min()) if ok.any() else None,
+        "max_ug_m3": float(c[ok].max()) if ok.any() else None,
+        "total_population": total,
+        "population_with_data": covered,
+        "n_units": int(c.size),
+        "n_units_with_data": int(ok.sum()),
+        "who_2021_exceedance": exceed,
+        "ratio_to_who_guideline": (
+            value / WHO_2021_ANNUAL[key]["AQG"] if value is not None else None
+        ),
+    }
+    return IndicatorResult(
+        indicator="11.6.2",
+        name=f"Population-weighted annual mean {key}",
+        value=value,
+        unit="ug/m3",
+        components=components,
+        metadata=build_metadata(
+            "11.6.2",
+            METHOD_VERSION,
+            [WHO_11_6_2, WHO_AQG_2021],
+            {"pollutant": key, "year": year},
+        ),
+        how_to_report=HOW_TO_REPORT,
+        warnings=warnings,
+    )

sdg11/citations.py

@@ -0,0 +1,160 @@
+"""Bibliographic references for the methods implemented in :mod:`sdg11`.
+
+The indicator metadata documents are maintained by the custodian agencies on the
+UN Statistics Division SDG metadata repository. They are revised from time to
+time; always check the current version before official reporting.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Dict, Optional
+
+
+@dataclass(frozen=True)
+class Citation:
+    """A single reference."""
+
+    key: str
+    authors: str
+    year: str
+    title: str
+    publisher: str
+    url: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Optional[str]]:
+        return asdict(self)
+
+    def __str__(self) -> str:
+        text = f"{self.authors} ({self.year}). {self.title}. {self.publisher}."
+        if self.url:
+            text += f" {self.url}"
+        return text
+
+
+_METADATA = "https://unstats.un.org/sdgs/metadata/files/"
+
+UN_HABITAT_11_1_1 = Citation(
+    key="unhabitat-11.1.1",
+    authors="UN-Habitat",
+    year="current",
+    title=(
+        "SDG indicator metadata 11.1.1: Proportion of urban population living in slums, "
+        "informal settlements or inadequate housing"
+    ),
+    publisher="United Nations Statistics Division, SDG metadata repository",
+    url=_METADATA + "Metadata-11-01-01.pdf",
+)
+
+UN_HABITAT_11_2_1 = Citation(
+    key="unhabitat-11.2.1",
+    authors="UN-Habitat",
+    year="current",
+    title=(
+        "SDG indicator metadata 11.2.1: Proportion of population that has convenient "
+        "access to public transport, by sex, age and persons with disabilities"
+    ),
+    publisher="United Nations Statistics Division, SDG metadata repository",
+    url=_METADATA + "Metadata-11-02-01.pdf",
+)
+
+UN_HABITAT_11_3_1 = Citation(
+    key="unhabitat-11.3.1",
+    authors="UN-Habitat",
+    year="current",
+    title=(
+        "SDG indicator metadata 11.3.1: Ratio of land consumption rate to population growth rate"
+    ),
+    publisher="United Nations Statistics Division, SDG metadata repository",
+    url=_METADATA + "Metadata-11-03-01.pdf",
+)
+
+WHO_11_6_2 = Citation(
+    key="who-11.6.2",
+    authors="World Health Organization",
+    year="current",
+    title=(
+        "SDG indicator metadata 11.6.2: Annual mean levels of fine particulate matter "
+        "(e.g. PM2.5 and PM10) in cities (population weighted)"
+    ),
+    publisher="United Nations Statistics Division, SDG metadata repository",
+    url=_METADATA + "Metadata-11-06-02.pdf",
+)
+
+WHO_AQG_2021 = Citation(
+    key="who-aqg-2021",
+    authors="World Health Organization",
+    year="2021",
+    title=(
+        "WHO global air quality guidelines: particulate matter (PM2.5 and PM10), ozone, "
+        "nitrogen dioxide, sulfur dioxide and carbon monoxide"
+    ),
+    publisher="World Health Organization, Geneva",
+    url="https://www.who.int/publications/i/item/9789240034228",
+)
+
+UN_HABITAT_11_7_1 = Citation(
+    key="unhabitat-11.7.1",
+    authors="UN-Habitat",
+    year="current",
+    title=(
+        "SDG indicator metadata 11.7.1: Average share of the built-up area of cities that "
+        "is open space for public use for all, by sex, age and persons with disabilities"
+    ),
+    publisher="United Nations Statistics Division, SDG metadata repository",
+    url=_METADATA + "Metadata-11-07-01.pdf",
+)
+
+DEGURBA_MANUAL_2021 = Citation(
+    key="degurba-manual-2021",
+    authors="European Commission, FAO, ILO, OECD, UN-Habitat and World Bank",
+    year="2021",
+    title=(
+        "Applying the Degree of Urbanisation: A methodological manual to define cities, "
+        "towns and rural areas for international comparisons (2021 edition)"
+    ),
+    publisher="Publications Office of the European Union, Luxembourg",
+    url="https://ec.europa.eu/eurostat/web/products-manuals-and-guidelines/-/ks-02-20-499",
+)
+
+DIJKSTRA_2021 = Citation(
+    key="dijkstra-2021",
+    authors="Dijkstra, L., Florczyk, A. J., Freire, S., Kemper, T., Melchiorri, M., "
+    "Pesaresi, M. and Schiavina, M.",
+    year="2021",
+    title=(
+        "Applying the Degree of Urbanisation to the globe: A new harmonised definition "
+        "reveals a different picture of global urbanisation"
+    ),
+    publisher="Journal of Urban Economics 125, 103312",
+    url="https://doi.org/10.1016/j.jue.2020.103312",
+)
+
+UNSC_2020_DEGURBA = Citation(
+    key="unsc-51-2020",
+    authors="United Nations Statistical Commission",
+    year="2020",
+    title=(
+        "Report on the fifty-first session: endorsement of the Degree of Urbanisation as the "
+        "recommended "
+        "method for delineating cities, urban and rural areas for international "
+        "statistical comparisons"
+    ),
+    publisher="UN Statistical Commission, 51st session",
+    url="https://unstats.un.org/unsd/statcom/51st-session/",
+)
+
+ALL_CITATIONS = {
+    c.key: c
+    for c in (
+        UN_HABITAT_11_1_1,
+        UN_HABITAT_11_2_1,
+        UN_HABITAT_11_3_1,
+        WHO_11_6_2,
+        WHO_AQG_2021,
+        UN_HABITAT_11_7_1,
+        DEGURBA_MANUAL_2021,
+        DIJKSTRA_2021,
+        UNSC_2020_DEGURBA,
+    )
+}

sdg11/cli.py

@@ -0,0 +1,127 @@
+"""Command-line interface: ``sdg11 degurba``, ``report``, ``demo`` and ``citations``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__, io
+from .citations import ALL_CITATIONS
+from .config import run_config
+from .degurba import classify_degurba
+
+
+def _cmd_degurba(args: argparse.Namespace) -> int:
+    grid, area, info = io.read_grid(args.grid)
+    cell = args.cell_area_km2 if args.cell_area_km2 is not None else area
+    if cell is None:
+        print(
+            "Cell area unknown for this format; assuming 1 km2 (use --cell-area-km2).",
+            file=sys.stderr,
+        )
+        cell = 1.0
+    result = classify_degurba(
+        grid,
+        cell_area_km2=cell,
+        fill_gaps=not args.no_gap_fill,
+        backend=args.backend,
+    )
+    print(f"Degree of Urbanisation (level 1) for {args.grid}")
+    print(f"Grid {grid.shape[0]} x {grid.shape[1]} cells, cell area {cell:g} km2")
+    print(
+        f"Urban centres: {result.components['n_urban_centres']}, "
+        f"urban clusters: {result.components['n_urban_clusters']}"
+    )
+    print()
+    print(result.summary_table())
+    for w in result.warnings:
+        print(f"warning: {w}", file=sys.stderr)
+    if args.out:
+        io.write_grid(args.out, result.classes, info)
+        print(
+            f"\nClass grid written to {args.out} (3 urban centre, 2 urban cluster, 1 rural, 0 no data)"
+        )
+    if args.json:
+        Path(args.json).write_text(json.dumps(result.to_dict(), indent=2), encoding="utf-8")
+        print(f"Summary written to {args.json}")
+    return 0
+
+
+def _cmd_report(args: argparse.Namespace) -> int:
+    rep = run_config(args.config)
+    rep.save(json_path=args.json, markdown_path=args.markdown)
+    if args.json:
+        print(f"JSON report written to {args.json}", file=sys.stderr)
+    if args.markdown:
+        print(f"Markdown report written to {args.markdown}", file=sys.stderr)
+    if not args.quiet:
+        print(rep.to_markdown())
+    return 0
+
+
+def _cmd_demo(args: argparse.Namespace) -> int:
+    from .synthetic import write_synthetic_city
+
+    path = write_synthetic_city(args.directory)
+    print(f"Synthetic example data written to {args.directory}")
+    print(f"Run: sdg11 report {path}")
+    return 0
+
+
+def _cmd_citations(args: argparse.Namespace) -> int:
+    for c in ALL_CITATIONS.values():
+        print(f"- {c}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sdg11",
+        description="Compute UN SDG 11 urban indicators and the Degree of Urbanisation.",
+    )
+    parser.add_argument("--version", action="version", version=f"sdg11 {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    p_deg = sub.add_parser("degurba", help="Classify a population grid (DEGURBA level 1).")
+    p_deg.add_argument("grid", help="Population grid: .tif (needs rasterio), .asc, .npy or .csv")
+    p_deg.add_argument("--cell-area-km2", type=float, default=None, help="Override the cell area.")
+    p_deg.add_argument("--out", help="Write the class grid (.tif, .asc, .npy or .csv).")
+    p_deg.add_argument("--json", help="Write the summary as JSON.")
+    p_deg.add_argument("--no-gap-fill", action="store_true", help="Skip urban-centre gap filling.")
+    p_deg.add_argument("--backend", choices=["auto", "scipy", "numpy"], default="auto")
+    p_deg.set_defaults(func=_cmd_degurba)
+
+    p_rep = sub.add_parser("report", help="Run every indicator in a TOML configuration.")
+    p_rep.add_argument("config", help="Path to the TOML configuration file.")
+    p_rep.add_argument("--json", help="Write the JSON report here.")
+    p_rep.add_argument("--markdown", help="Write the Markdown report here.")
+    p_rep.add_argument("--quiet", action="store_true", help="Do not print the Markdown report.")
+    p_rep.set_defaults(func=_cmd_report)
+
+    p_demo = sub.add_parser("demo", help="Write a synthetic example dataset and config.")
+    p_demo.add_argument("directory", help="Output folder (created if missing).")
+    p_demo.set_defaults(func=_cmd_demo)
+
+    p_cit = sub.add_parser("citations", help="List the methodological references.")
+    p_cit.set_defaults(func=_cmd_citations)
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 1
+    try:
+        return int(args.func(args))
+    except (OSError, ValueError, KeyError, ImportError) as exc:
+        print(f"sdg11: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())