Download methods.py from idiouf/African-Conservation-Human-Development-Observatory: direct link, hf CLI and curl.
- Browser
- Download file 22.2 kB
-
https://huggingface.co/spaces/idiouf/African-Conservation-Human-Development-Observatory/resolve/main/methods.py
- Command line
-
hf download hf://spaces/idiouf/African-Conservation-Human-Development-Observatory/methods.py
-
curl -L -o methods.py https://huggingface.co/spaces/idiouf/African-Conservation-Human-Development-Observatory/resolve/main/methods.py
22.2 kB
| """The detailed Data, methods and analyses text, in English and French. | |
| Kept out of app.py so the page can be read and corrected on its own. Every claim | |
| here must match the code in sources.py and analysis.py — if a computation | |
| changes, this file changes with it. | |
| """ | |
| from __future__ import annotations | |
| SECTIONS: dict[str, list[dict]] = { | |
| "English": [ | |
| { | |
| "key": "provenance", | |
| "icon": "🗄️", | |
| "title": "Where every number comes from", | |
| "body": """ | |
| **Protected areas — Wikidata (CC0), or WDPA when a token is set.** | |
| A SPARQL query asks for every item that is an instance of, or a subclass of, | |
| *protected area* (Q473972), located in a country that is part of Africa, and | |
| carrying coordinates. It returns name, country, ISO3, latitude and longitude, | |
| reported area, year of establishment and IUCN category. Wikidata enforces a | |
| 60-second limit and the subclass walk can exceed it, so the connector falls back | |
| to querying countries in batches of six. Items with several coordinate statements | |
| appear more than once; the largest reported area is kept and the rest dropped. | |
| Unlabelled items — those whose name is just a Q-number — are removed, since they | |
| are of no use to a reader. Setting `PROTECTED_PLANET_TOKEN` replaces all of this | |
| with the authoritative WDPA from Protected Planet. | |
| **Education, health, income, conservation cover — World Bank Open Data (CC BY 4.0).** | |
| Fifteen indicator series, all 54 African countries, 1990 onwards, paged through | |
| the public v2 API. No key. An indicator the API declines is reported by name on | |
| this page rather than silently skipped. | |
| **Demography and dependency — UN World Population Prospects 2024 (CC BY 3.0 IGO).** | |
| Read from `unpopulation_data*.csv` in the repository, not from the network: the UN | |
| Data Portal has no open bulk endpoint. This is the same file, and the same | |
| indicator identifiers, as the Africa Population Atlas — so the two dashboards | |
| report identical numbers. Only the **median variant** is loaded; high, low and | |
| probabilistic variants are dropped as the file is read. The extract repeats rows | |
| across sex and age breakdowns for the totals requested, so one value per | |
| country-indicator-year is taken as the median of the duplicates. | |
| **Boundaries — geoBoundaries (CC BY 4.0).** One simplified ADM0 file per country, | |
| fetched from GitHub eight at a time. The single global file exists but weighs | |
| 401 MB, which is why it is not used. | |
| **Effectiveness scores — supplied by you.** Nothing is downloaded; see *Matching | |
| uploaded scores* below. | |
| **Freshness.** Downloads are cached for seven days. A `cache_*` snapshot committed | |
| next to the app takes precedence and never expires — the connector table above | |
| shows its age in days, so a stale snapshot is visible rather than assumed. | |
| """, | |
| }, | |
| { | |
| "key": "derived", | |
| "icon": "🧮", | |
| "title": "How each derived measure is computed", | |
| "body": """ | |
| **Human pressure index — ordinal, 0–100.** | |
| Four components, in order of preference: population density (UN WPP where the | |
| extract is present, World Bank otherwise), the child dependency ratio, the rural | |
| population share, and the number of protected areas within 50 km. Each is | |
| converted to a percentile rank *across the mapped estate*, the available | |
| percentiles are averaged, and the result is multiplied by 100. The components | |
| that actually fed it are printed under the map, because they depend on which | |
| sources loaded. | |
| This index ranks parks by how busy their setting is. It is **not** a count of | |
| people living within 10 km of a boundary — three of its four inputs are national | |
| averages, so two parks in the same country differ only by their neighbour count. | |
| The real measurement needs gridded population clipped to a buffer around each | |
| boundary polygon. | |
| **Protected areas within 50 km.** | |
| Latitude and longitude are projected onto a sphere of radius 6,371 km and the | |
| straight-line (chord) distance is used. At 50 km the chord is shorter than the | |
| great-circle arc by well under a metre, so the distinction does not matter here. | |
| **Assigning a park to a region.** | |
| Point-in-polygon against the boundary file, indexed with an R-tree. A park that | |
| falls inside no polygon — small islands, points digitised just offshore — is left | |
| without a region rather than snapped to the nearest one. | |
| **Change between two years.** | |
| The nearest observation within ±3 years of each endpoint is used, which keeps | |
| sparse series such as poverty headcount and adult literacy usable. The years | |
| actually used are reported in the results table, so a country compared over | |
| 1993–2022 is never presented as if it were 1990–2024. If both endpoints resolve | |
| to the same year the country is dropped. | |
| **Direction.** | |
| Under-5 mortality and the poverty headcount improve when they fall. Their change | |
| is negated before any comparison, so that "higher is better" holds for every | |
| indicator on both axes. | |
| **Estimates and projections.** | |
| WPP 2024 runs to 2100. Every row after 2024 is a median-variant projection and is | |
| removed before any change calculation, the typology, the map and the park | |
| profiles. Projections appear only under *Trajectories*, drawn dashed behind a | |
| marked line. | |
| **Overlapping period.** | |
| UN series reach back to 1950 while most World Bank series start in 1990. Taking | |
| the minimum and maximum across the whole panel would produce a window in which | |
| one axis is empty and the typology would silently return nothing. The period | |
| slider is therefore restricted to the window where **both** selected indicators | |
| have observations, and resets when you change either one. | |
| **Matching uploaded scores.** | |
| By identifier first when the file has one, then by normalised name within the same | |
| country, then by normalised name alone. Normalising lowercases, strips | |
| punctuation, and removes the words *national, park, reserve, nature, wildlife, | |
| forest, game, marine, protected, area, conservancy*, so "Akagera National Park" | |
| and "Akagera National" meet. The page reports how many rows matched and lists | |
| those that did not — a half-join is never silent. | |
| """, | |
| }, | |
| { | |
| "key": "typology", | |
| "icon": "⚖️", | |
| "title": "The four relationships, and what they can and cannot say", | |
| "body": """ | |
| Li et al. (2024) assessed 10,143 protected areas worldwide. For each one they | |
| compared natural land cover change inside the park, and nightlight change in | |
| settlements within 10 km of its boundary, with **statistically matched | |
| counterfactual sites** — places with similar historical nightlights, population, | |
| land cover, slope, elevation, human footprint, precipitation and temperature that | |
| happen not to be protected. Crossing the two outcomes gives four relationships: | |
| synergy (47.7% of parks), economy impaired (42.9%), conservation impaired (4.8%) | |
| and retreat (4.6%). | |
| **What this dashboard does instead.** Counterfactual matching cannot be rebuilt | |
| from open country-level series, so a country here is placed by comparing its | |
| change with the **African median change over the same period**, on each axis | |
| independently. | |
| **The consequence, stated plainly.** Cutting each axis at the median makes each | |
| margin 50/50 *by construction*. If conservation and human development change were | |
| statistically independent, the four quadrants would each hold about a quarter of | |
| countries. **The shares on this page are therefore not comparable in level with | |
| Li et al.'s** — the paper's figures are printed beside them as context for the | |
| framework, not as a benchmark to beat. | |
| **What the table does carry** is the association between the two axes, which the | |
| median split does not force. The page reports the phi coefficient — the | |
| correlation between the two binary outcomes — and the odds ratio, computed with a | |
| Haldane correction so that an empty cell does not send it to infinity. A positive | |
| phi means countries that held their conservation indicator also tended to advance | |
| on human development: synergy and retreat outnumber the two tradeoffs. A phi near | |
| zero means the two move independently. That association is a genuine finding of | |
| this data; the quadrant percentages, on their own, are close to arithmetic. | |
| **And it remains description, not cause.** Nothing here identifies the effect of | |
| protection. Two countries can share a quadrant for entirely unrelated reasons. | |
| """, | |
| }, | |
| { | |
| "key": "scope", | |
| "icon": "🔍", | |
| "title": "What each analysis supports", | |
| "body": """ | |
| | Page | Supports | Does not support | | |
| |---|---|---| | |
| | **Overview** | Where the estate is, and the national conditions around it | Any statement about conditions *inside* a park, or within its buffer | | |
| | **Protected areas** | Screening — which parks sit in the busiest settings, and their country context | Comparing two parks in the same country on human conditions: three of the four pressure inputs are national | | |
| | **Human conditions** | Cross-country comparison of education, health, income, demography and dependency | Subnational variation, which is exactly where the interesting differences sit | | |
| | **Relationships** | Whether conservation and development changes are associated across African countries | The causal effect of protection on either outcome | | |
| | **Trajectories** | How indicators have moved since 1990, estimates and projections kept apart | Forecasting; the UN projections are one median scenario under stated assumptions | | |
| The park-level scatter, once effectiveness scores are uploaded, supports a | |
| correlation between a park's score and its country's human development level. It | |
| does not control for anything, and the country value repeats across every park in | |
| that country — so treat clusters, not individual points, as the signal. | |
| """, | |
| }, | |
| { | |
| "key": "repro", | |
| "icon": "🔁", | |
| "title": "Reproducing this", | |
| "body": """ | |
| Every figure on this dashboard is derived by code in two files: `sources.py` | |
| fetches, `analysis.py` computes. Neither invents a value — a connector that fails | |
| disables its features and says so in the table above. | |
| - `python selftest.py` runs every connector and prints its state, row count and | |
| the exact error when one fails. | |
| - `python prefetch.py` downloads everything once and writes a `cache_*` snapshot | |
| to commit, so the app opens instantly and everyone sees the same vintage. | |
| - `python make_fixtures.py && python test_app.py` runs the offline suite: the | |
| typology, the direction handling, the projection guard, the overlapping-period | |
| rule, the score matching and every page in both languages. | |
| The full indicator registry, with each code, unit, group, source and direction, | |
| is listed above under *Sources and licences*. | |
| """, | |
| }, | |
| ], | |
| "Français": [ | |
| { | |
| "key": "provenance", | |
| "icon": "🗄️", | |
| "title": "D'où vient chaque chiffre", | |
| "body": """ | |
| **Aires protégées — Wikidata (CC0), ou la WDPA si un jeton est fourni.** | |
| Une requête SPARQL demande tout élément instance ou sous-classe d'*aire protégée* | |
| (Q473972), situé dans un pays d'Afrique et porteur de coordonnées. Elle renvoie | |
| nom, pays, code ISO3, latitude et longitude, superficie déclarée, année de | |
| création et catégorie UICN. Wikidata impose une limite de 60 secondes et le | |
| parcours des sous-classes peut la dépasser : le connecteur bascule alors sur des | |
| requêtes par groupes de six pays. Les éléments portant plusieurs coordonnées | |
| apparaissent en double ; on conserve la plus grande superficie déclarée. Les | |
| éléments sans libellé — dont le nom se réduit à un numéro Q — sont écartés. | |
| Définir `PROTECTED_PLANET_TOKEN` remplace le tout par la WDPA officielle. | |
| **Éducation, santé, revenu, couverture protégée — Banque mondiale (CC BY 4.0).** | |
| Quinze séries, les 54 pays africains, depuis 1990, via l'API v2 publique. Sans | |
| clé. Un indicateur refusé par l'API est nommé sur cette page, jamais ignoré en | |
| silence. | |
| **Démographie et dépendance — Nations Unies, WPP 2024 (CC BY 3.0 IGO).** | |
| Lu depuis `unpopulation_data*.csv` dans le dépôt, non depuis le réseau : le portail | |
| de l'ONU n'offre pas de point d'accès ouvert en masse. C'est le même fichier et | |
| les mêmes identifiants d'indicateurs que l'Atlas démographique de l'Afrique — les | |
| deux tableaux de bord donnent donc des chiffres identiques. Seule la **variante | |
| médiane** est chargée ; les variantes haute, basse et probabilistes sont écartées | |
| à la lecture. L'extrait répète des lignes selon le sexe et l'âge pour les totaux | |
| demandés : on retient la médiane des doublons par pays-indicateur-année. | |
| **Frontières — geoBoundaries (CC BY 4.0).** Un fichier ADM0 simplifié par pays, | |
| téléchargé par lots de huit depuis GitHub. Le fichier mondial unique existe mais | |
| pèse 401 Mo, d'où ce choix. | |
| **Scores d'efficacité — fournis par vous.** Rien n'est téléchargé ; voir | |
| *Appariement des scores* ci-dessous. | |
| **Fraîcheur.** Les téléchargements sont mis en cache sept jours. Un instantané | |
| `cache_*` committé à côté de l'application est prioritaire et n'expire jamais — | |
| le tableau des connecteurs affiche son âge en jours, pour qu'un instantané | |
| périmé se voie au lieu d'être supposé. | |
| """, | |
| }, | |
| { | |
| "key": "derived", | |
| "icon": "🧮", | |
| "title": "Comment chaque mesure dérivée est calculée", | |
| "body": """ | |
| **Indice de pression humaine — ordinal, 0–100.** | |
| Quatre composantes, par ordre de préférence : densité de population (WPP si | |
| l'extrait est présent, Banque mondiale sinon), ratio de dépendance des enfants, | |
| part de population rurale, et nombre d'aires protégées à moins de 50 km. Chacune | |
| est convertie en rang centile *sur l'ensemble des aires cartographiées*, les | |
| centiles disponibles sont moyennés, le résultat est multiplié par 100. Les | |
| composantes réellement utilisées sont affichées sous la carte, car elles | |
| dépendent des sources chargées. | |
| Cet indice classe les aires selon l'affluence de leur contexte. Ce n'est **pas** | |
| un décompte de personnes vivant à moins de 10 km d'une limite : trois de ses | |
| quatre entrées sont des moyennes nationales, donc deux aires d'un même pays ne | |
| diffèrent que par leur nombre de voisines. La vraie mesure exige une population | |
| maillée découpée sur un tampon autour de chaque polygone. | |
| **Aires protégées à moins de 50 km.** | |
| Latitude et longitude sont projetées sur une sphère de rayon 6 371 km et l'on | |
| utilise la distance en ligne droite (corde). À 50 km, la corde est plus courte que | |
| l'arc de grand cercle de bien moins d'un mètre : la distinction est sans effet. | |
| **Rattachement d'une aire à une région.** | |
| Test point-dans-polygone sur le fichier de frontières, indexé par un R-tree. Une | |
| aire ne tombant dans aucun polygone — petites îles, points numérisés juste au | |
| large — reste sans région plutôt que d'être rattachée à la plus proche. | |
| **Variation entre deux années.** | |
| On retient l'observation la plus proche à ±3 ans de chaque borne, ce qui rend | |
| exploitables les séries lacunaires comme le taux de pauvreté ou l'alphabétisation. | |
| Les années effectivement utilisées figurent dans le tableau de résultats : un pays | |
| comparé de 1993 à 2022 n'est jamais présenté comme allant de 1990 à 2024. Si les | |
| deux bornes tombent sur la même année, le pays est écarté. | |
| **Sens de lecture.** | |
| La mortalité des moins de 5 ans et le taux de pauvreté s'améliorent en baissant. | |
| Leur variation est donc inversée avant toute comparaison, pour que « plus élevé | |
| vaut mieux » soit vrai sur les deux axes. | |
| **Estimations et projections.** | |
| Le WPP 2024 va jusqu'en 2100. Toute ligne postérieure à 2024 est une projection en | |
| variante médiane, retirée avant tout calcul de variation, la typologie, la carte | |
| et les fiches. Les projections n'apparaissent que dans *Trajectoires*, en tirets | |
| derrière une ligne marquée. | |
| **Période commune.** | |
| Les séries ONU remontent à 1950, la plupart des séries Banque mondiale commencent | |
| en 1990. Prendre le minimum et le maximum de tout le panel produirait une fenêtre | |
| où un axe est vide et la typologie ne renverrait rien, en silence. Le curseur de | |
| période est donc restreint à la fenêtre où les **deux** indicateurs choisis ont | |
| des observations, et il se réinitialise dès que vous changez l'un des deux. | |
| **Appariement des scores déposés.** | |
| Par identifiant d'abord si le fichier en porte un, puis par nom normalisé au sein | |
| du même pays, puis par nom normalisé seul. La normalisation met en minuscules, | |
| retire la ponctuation et supprime les mots *national, park, reserve, nature, | |
| wildlife, forest, game, marine, protected, area, conservancy* — ainsi « Akagera | |
| National Park » et « Akagera National » se rejoignent. La page indique combien de | |
| lignes ont été appariées et liste les autres : une jointure partielle n'est jamais | |
| silencieuse. | |
| """, | |
| }, | |
| { | |
| "key": "typology", | |
| "icon": "⚖️", | |
| "title": "Les quatre relations, et ce qu'elles peuvent dire ou non", | |
| "body": """ | |
| Li et al. (2024) ont évalué 10 143 aires protégées dans le monde. Pour chacune, | |
| ils comparent la variation du couvert naturel à l'intérieur du parc, et la | |
| variation des lumières nocturnes dans les localités situées à moins de 10 km de | |
| sa limite, à des **sites contrefactuels appariés statistiquement** — des lieux aux | |
| lumières historiques, population, couvert, pente, altitude, empreinte humaine, | |
| précipitations et températures semblables, mais non protégés. Le croisement des | |
| deux résultats donne quatre relations : synergie (47,7 % des aires), économie | |
| entravée (42,9 %), conservation entravée (4,8 %) et repli (4,6 %). | |
| **Ce que fait ce tableau de bord à la place.** L'appariement contrefactuel ne peut | |
| être reconstruit à partir de séries nationales ouvertes : un pays est donc situé | |
| en comparant sa variation à la **variation médiane africaine sur la même | |
| période**, indépendamment sur chaque axe. | |
| **La conséquence, dite franchement.** Couper chaque axe à la médiane rend chaque | |
| marge 50/50 *par construction*. Si les variations de conservation et de | |
| développement humain étaient statistiquement indépendantes, chaque quadrant | |
| contiendrait environ un quart des pays. **Les parts affichées ici ne sont donc pas | |
| comparables en niveau à celles de Li et al.** — les chiffres de l'article sont | |
| rappelés à côté comme repère du cadre conceptuel, non comme référence à égaler. | |
| **Ce que le tableau porte réellement**, c'est l'association entre les deux axes, | |
| que la coupe médiane n'impose pas. La page indique le coefficient phi — la | |
| corrélation entre les deux résultats binaires — et le rapport de cotes, calculé | |
| avec une correction de Haldane pour qu'une case vide ne l'envoie pas à l'infini. | |
| Un phi positif signifie que les pays ayant tenu leur indicateur de conservation | |
| ont aussi eu tendance à progresser en développement humain : synergie et repli | |
| l'emportent sur les deux arbitrages. Un phi proche de zéro signifie que les deux | |
| évoluent indépendamment. Cette association est un résultat réel de ces données ; | |
| les pourcentages par quadrant, seuls, relèvent surtout de l'arithmétique. | |
| **Et cela reste descriptif, non causal.** Rien ici n'identifie l'effet de la | |
| protection. Deux pays peuvent partager un quadrant pour des raisons sans rapport. | |
| """, | |
| }, | |
| { | |
| "key": "scope", | |
| "icon": "🔍", | |
| "title": "Ce que chaque analyse permet", | |
| "body": """ | |
| | Page | Permet | Ne permet pas | | |
| |---|---|---| | |
| | **Vue d'ensemble** | Situer le réseau d'aires et les conditions nationales autour | Toute affirmation sur les conditions *à l'intérieur* d'une aire ou dans son tampon | | |
| | **Aires protégées** | Un criblage : quelles aires sont dans les contextes les plus peuplés, et leur contexte national | Comparer deux aires d'un même pays sur les conditions humaines : trois des quatre entrées de l'indice sont nationales | | |
| | **Conditions humaines** | Comparer les pays sur l'éducation, la santé, le revenu, la démographie et la dépendance | La variation infranationale, là où se logent justement les écarts intéressants | | |
| | **Relations** | Savoir si les variations de conservation et de développement sont associées entre pays africains | L'effet causal de la protection sur l'un ou l'autre résultat | | |
| | **Trajectoires** | Suivre les indicateurs depuis 1990, estimations et projections séparées | Prévoir ; les projections ONU sont un scénario médian sous hypothèses déclarées | | |
| Le nuage de points au niveau des aires, une fois les scores déposés, permet une | |
| corrélation entre le score d'une aire et le niveau de développement humain de son | |
| pays. Il ne contrôle rien, et la valeur nationale se répète pour toutes les aires | |
| du même pays : lisez les regroupements, non les points isolés. | |
| """, | |
| }, | |
| { | |
| "key": "repro", | |
| "icon": "🔁", | |
| "title": "Reproduire ces résultats", | |
| "body": """ | |
| Chaque chiffre de ce tableau de bord est produit par deux fichiers : | |
| `sources.py` récupère, `analysis.py` calcule. Aucun des deux n'invente de valeur — | |
| un connecteur en échec désactive ses fonctions et le signale dans le tableau | |
| ci-dessus. | |
| - `python selftest.py` exerce chaque connecteur et affiche son état, son nombre de | |
| lignes et l'erreur exacte en cas d'échec. | |
| - `python prefetch.py` télécharge tout une fois et écrit un instantané `cache_*` à | |
| committer : l'application s'ouvre instantanément et tout le monde voit le même | |
| millésime. | |
| - `python make_fixtures.py && python test_app.py` lance la suite hors ligne : la | |
| typologie, le sens de lecture, le garde-fou des projections, la règle de période | |
| commune, l'appariement des scores et chaque page dans les deux langues. | |
| Le registre complet des indicateurs — code, unité, groupe, source et sens — figure | |
| plus haut, sous *Sources et licences*. | |
| """, | |
| }, | |
| ], | |
| } | |
| def sections(language: str) -> list[dict]: | |
| return SECTIONS.get(language, SECTIONS["English"]) | |