File size: 20,368 Bytes
885338e
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
a22f12f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
885338e
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
419e4fd
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
885338e
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
"""Analysis layer: the Li et al. (2024) relationship typology, spatial joins and
the derived measures the dashboard plots.

Where this departs from the paper, it says so. Li et al. classify a protected
area by comparing it with statistically matched counterfactual sites. No
counterfactual matching is possible from the open country-level series this
dashboard can reach, so the reference point here is the **African median change
over the same period**. That is a descriptive benchmark, not a causal estimate,
and every view that uses it is labelled accordingly.
"""

from __future__ import annotations

import math
from dataclasses import dataclass

import numpy as np
import pandas as pd

# --- The four relationships, Li et al. 2024, Figure 3C ----------------------
SYNERGY = "Synergy"
CONSERVATION_IMPAIRED = "Conservation impaired"
ECONOMY_IMPAIRED = "Economy impaired"
RETREAT = "Retreat"

RELATIONSHIPS = [SYNERGY, ECONOMY_IMPAIRED, CONSERVATION_IMPAIRED, RETREAT]

RELATIONSHIP_COLORS = {
    SYNERGY: "#1B9E8A",
    ECONOMY_IMPAIRED: "#E8B04B",
    CONSERVATION_IMPAIRED: "#3F7FBF",
    RETREAT: "#C4384B",
}

RELATIONSHIP_MEANING = {
    SYNERGY: "Natural land cover held, and human development kept pace or better.",
    ECONOMY_IMPAIRED: "Natural land cover held, but human development lagged.",
    CONSERVATION_IMPAIRED: "Human development kept pace, but natural land cover was lost.",
    RETREAT: "Natural land cover was lost and human development lagged.",
}

# Global shares reported by Li et al. (2024) for 10,143 protected areas, shown
# alongside this dashboard's own counts for context.
LI_GLOBAL_SHARES = {
    SYNERGY: 47.7,
    ECONOMY_IMPAIRED: 42.9,
    CONSERVATION_IMPAIRED: 4.8,
    RETREAT: 4.6,
}


def classify(conservation_ok: bool | None, development_ok: bool | None) -> str | None:
    """Map the two binary outcomes onto the paper's 2x2."""
    if conservation_ok is None or development_ok is None:
        return None
    if conservation_ok and development_ok:
        return SYNERGY
    if conservation_ok and not development_ok:
        return ECONOMY_IMPAIRED
    if not conservation_ok and development_ok:
        return CONSERVATION_IMPAIRED
    return RETREAT


# ---------------------------------------------------------------------------
# Country panel helpers
# ---------------------------------------------------------------------------

def observations_only(indicators: pd.DataFrame) -> pd.DataFrame:
    """Drop UN median-variant projections.

    World Bank rows carry no 'series' column and are observations by
    construction; UN WPP rows after 2024 are projections and must never enter a
    change calculation or the relationship typology.
    """
    if indicators.empty or "series" not in indicators.columns:
        return indicators
    return indicators[indicators["series"].fillna("Estimate") != "Projection"]


def year_span(indicators: pd.DataFrame, code: str) -> tuple[int, int] | None:
    """First and last year an indicator actually has observations for."""
    if indicators.empty:
        return None
    d = indicators[indicators["indicator"] == code]
    if d.empty:
        return None
    return int(d["year"].min()), int(d["year"].max())


def overlapping_span(indicators: pd.DataFrame, codes: list[str]) -> tuple[int, int] | None:
    """The window where every requested indicator has data.

    UN WPP reaches back to 1950 while most World Bank series start in 1990, so a
    naive min/max across the whole panel produces a period in which one of the
    two axes is empty and the typology silently returns nothing.
    """
    spans = [year_span(indicators, c) for c in codes]
    if any(s is None for s in spans):
        return None
    lo = max(s[0] for s in spans)
    hi = min(s[1] for s in spans)
    return (lo, hi) if hi - lo >= 2 else None


def to_wide(indicators: pd.DataFrame) -> pd.DataFrame:
    """Long World Bank frame β†’ one row per country-year, one column per code."""
    if indicators.empty:
        return pd.DataFrame()
    wide = indicators.pivot_table(
        index=["iso3", "country", "year"], columns="indicator", values="value"
    ).reset_index()
    wide.columns.name = None
    return wide


def latest_values(indicators: pd.DataFrame, code: str,
                  not_after: int | None = None) -> pd.DataFrame:
    """Most recent non-missing observation of one indicator per country."""
    if indicators.empty:
        return pd.DataFrame(columns=["iso3", "country", "year", "value"])
    d = indicators[indicators["indicator"] == code]
    if not_after is not None:
        d = d[d["year"] <= not_after]
    if d.empty:
        return pd.DataFrame(columns=["iso3", "country", "year", "value"])
    d = d.sort_values("year").groupby("iso3", as_index=False).tail(1)
    return d[["iso3", "country", "year", "value"]].reset_index(drop=True)


def change_between(indicators: pd.DataFrame, code: str, start: int, end: int,
                   tolerance: int = 3) -> pd.DataFrame:
    """Change in one indicator between two years, per country.

    ``tolerance`` allows the nearest observation within N years of each endpoint,
    which keeps sparse series (poverty, literacy) usable.
    """
    empty = pd.DataFrame(columns=["iso3", "country", "start_year", "end_year",
                                  "start_value", "end_value", "change", "pct_change"])
    if indicators.empty:
        return empty
    d = indicators[indicators["indicator"] == code]
    if d.empty:
        return empty

    rows = []
    for iso3, grp in d.groupby("iso3"):
        grp = grp.sort_values("year")
        first = grp[(grp["year"] >= start - tolerance) & (grp["year"] <= start + tolerance)]
        last = grp[(grp["year"] >= end - tolerance) & (grp["year"] <= end + tolerance)]
        if first.empty or last.empty:
            continue
        first = first.iloc[(first["year"] - start).abs().argsort()].iloc[0]
        last = last.iloc[(last["year"] - end).abs().argsort()].iloc[0]
        if first["year"] == last["year"]:
            continue
        change = float(last["value"]) - float(first["value"])
        pct = (change / abs(float(first["value"])) * 100) if first["value"] else math.nan
        rows.append({
            "iso3": iso3,
            "country": grp["country"].iloc[0],
            "start_year": int(first["year"]),
            "end_year": int(last["year"]),
            "start_value": float(first["value"]),
            "end_value": float(last["value"]),
            "change": change,
            "pct_change": pct,
        })
    return pd.DataFrame(rows) if rows else empty


def orient(change: pd.Series, good: str | None) -> pd.Series:
    """Make 'higher is better' true for every indicator.

    Under-5 mortality and poverty improve when they fall, so their change is
    flipped before any comparison.
    """
    if good == "low":
        return -change
    return change


@dataclass
class TypologyResult:
    frame: pd.DataFrame
    conservation_code: str
    development_code: str
    conservation_reference: float
    development_reference: float
    start: int
    end: int

    @property
    def shares(self) -> pd.Series:
        if self.frame.empty:
            return pd.Series(dtype=float)
        counts = self.frame["relationship"].value_counts()
        return (counts / counts.sum() * 100).reindex(RELATIONSHIPS).fillna(0.0)


def build_typology(indicators: pd.DataFrame, conservation_code: str,
                   development_code: str, start: int, end: int,
                   development_good: str | None = "high",
                   conservation_good: str | None = "high") -> TypologyResult:
    """Place each country in the 2x2, using the African median as the reference.

    A country is 'conservation ok' when its change in the conservation indicator
    is at least the African median change, and 'development ok' on the same
    footing for the human development indicator.
    """
    cons = change_between(indicators, conservation_code, start, end)
    dev = change_between(indicators, development_code, start, end)

    cols = ["iso3", "country", "start_year", "end_year", "start_value",
            "end_value", "change"]
    if cons.empty or dev.empty:
        return TypologyResult(pd.DataFrame(), conservation_code, development_code,
                              math.nan, math.nan, start, end)

    merged = cons[cols].merge(dev[cols], on=["iso3", "country"],
                              suffixes=("_cons", "_dev"))
    if merged.empty:
        return TypologyResult(pd.DataFrame(), conservation_code, development_code,
                              math.nan, math.nan, start, end)

    merged["cons_oriented"] = orient(merged["change_cons"], conservation_good)
    merged["dev_oriented"] = orient(merged["change_dev"], development_good)

    cons_ref = float(merged["cons_oriented"].median())
    dev_ref = float(merged["dev_oriented"].median())

    merged["conservation_ok"] = merged["cons_oriented"] >= cons_ref
    merged["development_ok"] = merged["dev_oriented"] >= dev_ref
    merged["relationship"] = [
        classify(c, d) for c, d in zip(merged["conservation_ok"], merged["development_ok"])
    ]

    return TypologyResult(merged.reset_index(drop=True), conservation_code,
                          development_code, cons_ref, dev_ref, start, end)


def association(result: "TypologyResult") -> dict:
    """How strongly the two axes move together, beyond the median split itself.

    The 2x2 here is built by cutting each axis at the African median, so each
    margin is 50/50 *by construction* and the four shares would sit near 25%
    each if conservation and development change were independent. The shares are
    therefore not comparable in level with Li et al., whose categories come from
    counterfactual matching. What the table does carry is the association between
    the two axes: phi (the correlation of the two binary outcomes) and the odds
    ratio, with a Haldane correction so an empty cell does not send it to
    infinity. phi > 0 means countries that held their conservation indicator also
    tended to advance on human development β€” synergy and retreat outnumber the
    two tradeoffs.
    """
    out = {"n": 0, "phi": math.nan, "odds_ratio": math.nan,
           "n11": 0, "n10": 0, "n01": 0, "n00": 0}
    frame = result.frame
    if frame.empty or "conservation_ok" not in frame:
        return out

    cons = frame["conservation_ok"].astype(bool)
    dev = frame["development_ok"].astype(bool)
    n11 = int((cons & dev).sum())        # synergy
    n10 = int((cons & ~dev).sum())       # economy impaired
    n01 = int((~cons & dev).sum())       # conservation impaired
    n00 = int((~cons & ~dev).sum())      # retreat
    out.update(n=len(frame), n11=n11, n10=n10, n01=n01, n00=n00)

    denominator = (n11 + n10) * (n01 + n00) * (n11 + n01) * (n10 + n00)
    if denominator > 0:
        out["phi"] = (n11 * n00 - n10 * n01) / math.sqrt(denominator)

    a, b, c, d = n11 + 0.5, n10 + 0.5, n01 + 0.5, n00 + 0.5
    out["odds_ratio"] = (a * d) / (b * c)
    return out


def coverage(indicators: pd.DataFrame) -> pd.DataFrame:
    """Per indicator: how many countries and which years actually carry data."""
    if indicators.empty:
        return pd.DataFrame(columns=["indicator", "countries", "first", "last", "points"])
    grouped = indicators.groupby("indicator").agg(
        countries=("iso3", "nunique"),
        first=("year", "min"),
        last=("year", "max"),
        points=("value", "size"),
    ).reset_index()
    return grouped.sort_values("countries", ascending=False).reset_index(drop=True)


# ---------------------------------------------------------------------------
# Protected areas Γ— places
# ---------------------------------------------------------------------------

def attach_country_context(pas: pd.DataFrame, indicators: pd.DataFrame,
                           codes: list[str], year: int | None = None) -> pd.DataFrame:
    """Join the latest country value of each requested indicator onto every PA."""
    if pas.empty:
        return pas
    out = pas.copy()
    for code in codes:
        latest = latest_values(indicators, code, not_after=year)
        if latest.empty:
            out[code] = np.nan
            continue
        out = out.merge(
            latest[["iso3", "value"]].rename(columns={"value": code}), on="iso3", how="left"
        )
    return out


def assign_regions(pas: pd.DataFrame, boundaries: dict) -> pd.DataFrame:
    """Point-in-polygon assignment of each PA to an administrative region.

    Falls back to leaving the region blank rather than guessing when shapely is
    unavailable or a point sits outside every polygon (islands, coastal PAs).
    """
    if pas.empty or not boundaries.get("features"):
        out = pas.copy()
        out["region"] = pd.NA
        return out

    try:
        from shapely.geometry import Point, shape
        from shapely.strtree import STRtree
    except Exception:
        out = pas.copy()
        out["region"] = pd.NA
        return out

    geometries, names, isos = [], [], []
    for feature in boundaries["features"]:
        try:
            geometries.append(shape(feature["geometry"]))
        except Exception:
            continue
        props = feature.get("properties", {})
        names.append(props.get("name") or props.get("shapeName") or "")
        isos.append(props.get("iso3", ""))

    if not geometries:
        out = pas.copy()
        out["region"] = pd.NA
        return out

    tree = STRtree(geometries)
    regions, region_isos = [], []
    for lat, lon in zip(pas["lat"], pas["lon"]):
        if pd.isna(lat) or pd.isna(lon):
            regions.append(pd.NA)
            region_isos.append(pd.NA)
            continue
        point = Point(float(lon), float(lat))
        hit = None
        for idx in tree.query(point):
            index = int(idx)
            if geometries[index].contains(point):
                hit = index
                break
        regions.append(names[hit] if hit is not None else pd.NA)
        region_isos.append(isos[hit] if hit is not None else pd.NA)

    out = pas.copy()
    out["region"] = regions
    out["region_iso3"] = region_isos
    return out


def neighbour_counts(pas: pd.DataFrame, radius_km: float = 50.0) -> pd.Series:
    """How many other protected areas sit within ``radius_km`` of each one.

    A cheap proxy for how clustered the estate is; equal-angle degrees are
    converted with a cosine correction so the radius is roughly metric.
    """
    if pas.empty:
        return pd.Series(dtype=int)
    lat = np.radians(pas["lat"].astype(float).to_numpy())
    lon = np.radians(pas["lon"].astype(float).to_numpy())
    earth_km = 6371.0
    x = earth_km * np.cos(lat) * np.cos(lon)
    y = earth_km * np.cos(lat) * np.sin(lon)
    z = earth_km * np.sin(lat)
    pts = np.column_stack([x, y, z])

    counts = np.zeros(len(pts), dtype=int)
    chunk = 512
    for start in range(0, len(pts), chunk):
        block = pts[start:start + chunk]
        d = np.linalg.norm(block[:, None, :] - pts[None, :, :], axis=2)
        counts[start:start + chunk] = (d <= radius_km).sum(axis=1) - 1
    return pd.Series(counts, index=pas.index)


def pressure_index(pas: pd.DataFrame) -> pd.Series:
    """Rank-based 0–100 index of human pressure around each protected area.

    Components, in order of preference (UN World Population Prospects first,
    World Bank as the fallback when the WPP extract is not present):

    * population density of the country            β€” how crowded the setting is
    * child dependency ratio (0–14 per 100 of 15–64) β€” the dependent-young burden
      Li et al. found bound up with the economy-impaired and retreat cases
    * rural population share                       β€” reliance on land around parks
    * protected areas within 50 km                 β€” how contested the landscape is

    Each component is converted to a percentile across the mapped estate and the
    percentiles are averaged, so the index is ordinal: it says which parks sit in
    busier settings, not how many people live within 10 km of a boundary. That
    number needs gridded population clipped to a buffer, which this dashboard
    does not have.
    """
    if pas.empty:
        return pd.Series(dtype=float)

    density = "UN:54" if "UN:54" in pas.columns and pas["UN:54"].notna().any() else "EN.POP.DNST"
    components = [
        (density, False),
        ("UN:83", False),
        ("SP.RUR.TOTL.ZS", False),
        ("neighbours_50km", False),
    ]

    parts = []
    for column, invert in components:
        if column in pas.columns and pas[column].notna().any():
            ranked = pas[column].rank(pct=True)
            parts.append(1 - ranked if invert else ranked)

    if not parts:
        return pd.Series(np.nan, index=pas.index)

    stacked = pd.concat(parts, axis=1)
    return (stacked.mean(axis=1) * 100).round(1)


def pressure_components(pas: pd.DataFrame) -> list[str]:
    """Which columns actually fed the pressure index, for display in the UI."""
    density = "UN:54" if "UN:54" in pas.columns and pas["UN:54"].notna().any() else "EN.POP.DNST"
    candidates = [density, "UN:83", "SP.RUR.TOTL.ZS", "neighbours_50km"]
    return [c for c in candidates if c in pas.columns and pas[c].notna().any()]


def summarise_by_country(pas: pd.DataFrame) -> pd.DataFrame:
    """Estate size and protected area count per country."""
    if pas.empty:
        return pd.DataFrame(columns=["iso3", "country", "n_pas", "area_km2"])
    grouped = pas.groupby(["iso3", "country"], as_index=False).agg(
        n_pas=("pa_id", "count"),
        area_km2=("area_km2", "sum"),
        median_area_km2=("area_km2", "median"),
    )
    return grouped.sort_values("n_pas", ascending=False).reset_index(drop=True)


def match_effectiveness(pas: pd.DataFrame, scores: pd.DataFrame) -> tuple[pd.DataFrame, dict]:
    """Join uploaded effectiveness scores onto the protected area table.

    Matching is by id when the upload has one, then by normalised name within a
    country, then by normalised name alone. The report tells the user exactly
    how many rows matched and which did not, so a silent half-join is visible.
    """
    report = {"uploaded": len(scores), "matched": 0, "unmatched": []}
    if pas.empty or scores.empty:
        return pas.assign(effectiveness=np.nan), report

    def norm(s: pd.Series) -> pd.Series:
        return (s.astype(str).str.lower()
                .str.replace(r"[^a-z0-9 ]", " ", regex=True)
                .str.replace(r"\b(national|park|reserve|nature|wildlife|forest|"
                             r"game|marine|protected|area|conservancy)\b", " ", regex=True)
                .str.replace(r"\s+", " ", regex=True).str.strip())

    left = pas.copy()
    left["_key"] = norm(left["name"])
    right = scores.copy()
    right["_key"] = norm(right["name"])

    merged = None
    if "pa_id" in right.columns and right["pa_id"].notna().any():
        right["pa_id"] = right["pa_id"].astype(str)
        left["pa_id"] = left["pa_id"].astype(str)
        merged = left.merge(right[["pa_id", "score"]].dropna(subset=["pa_id"]),
                            on="pa_id", how="left")
    else:
        merged = left.copy()
        merged["score"] = np.nan

    if "iso3" in right.columns and right["iso3"].notna().any():
        by_country = right.dropna(subset=["iso3"])[["iso3", "_key", "score"]]
        by_country = by_country.drop_duplicates(["iso3", "_key"])
        merged = merged.merge(by_country, on=["iso3", "_key"], how="left",
                              suffixes=("", "_country"))
        merged["score"] = merged["score"].fillna(merged.pop("score_country"))

    by_name = right[["_key", "score"]].drop_duplicates("_key")
    merged = merged.merge(by_name, on="_key", how="left", suffixes=("", "_name"))
    merged["score"] = merged["score"].fillna(merged.pop("score_name"))

    merged = merged.rename(columns={"score": "effectiveness"}).drop(columns=["_key"])
    report["matched"] = int(merged["effectiveness"].notna().sum())

    matched_keys = set(norm(merged.loc[merged["effectiveness"].notna(), "name"]))
    report["unmatched"] = [
        n for n, k in zip(scores["name"], norm(scores["name"])) if k not in matched_keys
    ][:40]
    return merged, report