Add gender metrics targets and site support

Author: smkwray

.gitignore

@@ -17,6 +17,7 @@ __pycache__/
 # Private local agent/project planning files
 AGENTS.md
 geoluck_codex_plan.md
+geoluck-R/
 
 # Private agent workflow state
 do/

DATA_SOURCES.md

@@ -46,6 +46,8 @@ Track every external dataset here before or when it is added.
 | Polity 5 | http://www.systemicpeace.org/inscr/p5v2018.xls | 2026-03-11 | Public academic workbook distributed from Systemic Peace; keep the Polity 5 citation and note the manual browser download path because scripted requests currently return HTTP `406` | Raw XLS is kept locally in `data_raw/polity/`; normalized country-year regime-authority rows and compact trailing-decade governance features may be redistributed as derived outputs after citation review and with explicit notes about excluded dissolved states | `src/geoluck/etl/fetch_polity.py`, `src/geoluck/features/build_polity_features.py`, `data_intermediate/polity/` | active |
 | SWIID 9.91 summary CSV | https://fsolt.org/swiid/swiid_downloads/ | 2026-03-11 | SWIID is distributed for academic use with citation; keep the SWIID version note and source-page / Dataverse references in provenance | Raw summary CSV is fetched locally into `data_raw/swiid/`; normalized country-year inequality rows and merged country-decade outcome targets may be redistributed as compact derived outputs after citation review | `src/geoluck/etl/fetch_swiid.py`, `src/geoluck/features/build_outcomes_panel.py`, `data_intermediate/swiid/` | active |
 | World Bank Wealth Accounts produced capital per capita | https://api.worldbank.org/v2/indicator/NW.PCA.PC?format=json | 2026-03-11 | World Bank Wealth Accounts / Changing Wealth of Nations indicator; keep the indicator code `NW.PCA.PC`, source id `59`, and CWON citation in provenance | Raw API payloads are fetched locally into `data_raw/wealth_accounts/`; normalized country-year produced-capital rows and merged country-decade wealth targets may be redistributed as compact derived outputs with source citation review | `src/geoluck/etl/fetch_wealth_accounts.py`, `src/geoluck/features/build_outcomes_panel.py`, `data_intermediate/wealth_accounts/` | active |
+| World Bank female labor-force participation rate (`SL.TLF.CACT.FE.ZS`) | https://api.worldbank.org/v2/indicator/SL.TLF.CACT.FE.ZS?format=json | 2026-03-13 | World Bank open data terms apply; keep the indicator code and source id in provenance | Raw API payloads are fetched locally into `data_raw/female_lfpr/`; normalized country-year female labor-force participation rows and merged country-decade outcome targets may be redistributed as compact derived outputs with source citation review | `src/geoluck/etl/fetch_female_lfpr.py`, `src/geoluck/features/build_outcomes_panel.py`, `data_intermediate/female_lfpr/` | active |
+| World Bank Women, Business and the Law (`SG.LAW.INDX`) | https://api.worldbank.org/v2/indicator/SG.LAW.INDX?format=json | 2026-03-13 | World Bank open data terms apply; keep the indicator code and source id in provenance | Raw API payloads are fetched locally into `data_raw/women_business_law/`; normalized country-year Women, Business and the Law rows and merged country-decade outcome targets may be redistributed as compact derived outputs with source citation review | `src/geoluck/etl/fetch_women_business_law.py`, `src/geoluck/features/build_outcomes_panel.py`, `data_intermediate/women_business_law/` | active |
 | UN World Population Prospects 2024 | https://population.un.org/wpp/downloads | 2026-03-09 | UN DESA public downloads; cite WPP 2024 and keep note that workbook schemas may change across releases | Raw WPP 2024 workbooks are fetched locally into `data_raw/wpp/`; normalized country-year demographic tables and compact decade features may be redistributed as derived outputs with source citation review | `src/geoluck/etl/fetch_wpp.py`, `src/geoluck/features/build_wpp_features.py`, `data_intermediate/wpp/` | active |
 | UNDP Gender Inequality Index 2025 | https://hdr.undp.org/sites/default/files/2025_HDR/HDR25_Statistical_Annex_GII_Table.xlsx | 2026-03-09 | UNDP HDR workbook is publicly downloadable; cite HDR 2025 and preserve the mixed component-year note in provenance | Raw workbook is fetched locally into `data_raw/undp_gii/`; normalized country-level GII and component indicators plus derived gender-gap features may be redistributed as compact derived outputs with source citation review | `src/geoluck/etl/fetch_undp_gii.py`, `src/geoluck/features/build_undp_gii_features.py`, `data_intermediate/undp_gii/` | active |
 | Glottolog CLDF languages | https://raw.githubusercontent.com/glottolog/glottolog-cldf/master/cldf/languages.csv | 2026-03-09 | Open scholarly dataset with attribution; keep note that the raw GitHub branch path is a moving snapshot unless pinned to a release | Raw CSV is fetched locally into `data_raw/glottolog/`; normalized country-language inventory and compact country-level language-count features may be redistributed as derived outputs with source citation review | `src/geoluck/etl/fetch_glottolog.py`, `src/geoluck/features/build_glottolog_features.py`, `data_intermediate/glottolog/` | active |

README.md

@@ -2,7 +2,7 @@
 
 **How much of relative country prosperity can be predicted from geography, natural endowments, resource development, and social structure — and who beats their geography?**
 
-Geoluck is an open-source research project that builds a country-decade panel (1900–2020) and trains machine learning models to predict four prosperity outcomes from tiered feature sets. The results are published as an interactive static site.
+Geoluck is an open-source research project that builds a country-decade panel (1900–2020) and trains machine learning models to predict country-level income, wellbeing, inequality, wealth, and gender outcomes from tiered feature sets. The results are published as an interactive static site.
 
 This is explicitly about **predictive association**, not causal effect.
 
@@ -12,14 +12,17 @@ This is explicitly about **predictive association**, not causal effect.
 
 ## What the site shows
 
-The static site models four outcome metrics, each converted to within-decade percentile ranks:
+The static site models seven outcome metrics, each converted to within-decade percentile ranks:
 
 | Outcome | Definition | Source |
 |---|---|---|
 | **Income** | Log GDP per capita rank | Maddison Project Database 2023 |
 | **Wealth** | Produced capital per capita rank | World Bank Changing Wealth of Nations |
 | **Life expectancy** | Life expectancy at birth rank | World Bank WDI / UN Population Division |
-| **Inequality** | Disposable-income Gini rank (higher = more equal) | SWIID |
+| **Inequality** | Disposable-income Gini rank (higher = more unequal) | SWIID |
+| **Gender inequality** | UNDP Gender Inequality Index rank (higher = more unequal) | UNDP HDR 2025 |
+| **Female LFPR** | Female labor-force participation rate rank | World Bank WDI / ILO |
+| **Women, Business and the Law** | Women, Business and the Law index rank | World Bank |
 
 Predictor features are organized into three independently toggleable tiers:
 

docs/MODEL_SPECS.md

@@ -20,20 +20,24 @@
 ## Evaluation protocol
 
 - Primary maintained public target: `income_rank_pct`
-- Supported exploratory targets via `train-level-models --target`: `income`, `life_expectancy`, `inequality`, `wealth`
+- Supported exploratory targets via `train-level-models --target`: `income`, `life_expectancy`, `inequality`, `wealth`, `gender_inequality`, `female_lfpr`, `women_business_law`
 - Current target columns behind those names:
   - `income` -> `income_rank_pct`
   - `life_expectancy` -> `life_expectancy_rank_pct`
   - `inequality` -> `gini_disp_rank_pct`
   - `wealth` -> `produced_capital_per_capita_rank_pct`
+  - `gender_inequality` -> `gender_inequality_rank_pct`
+  - `female_lfpr` -> `female_labor_force_participation_rank_pct`
+  - `women_business_law` -> `women_business_law_rank_pct`
 - Target-specific feature guardrails:
   - `life_expectancy` excludes the exact WPP life-expectancy column and the crude-death-rate column from the feature matrix to avoid same-source outcome leakage.
-  - `inequality` excludes the merged SWIID Gini outcome columns from the feature matrix.
+  - `inequality` excludes the merged SWIID Gini outcome columns plus near-target Fragile States Index inequality and total-score columns from the feature matrix.
   - `wealth` excludes the merged Wealth Accounts level/log/rank outcome columns from the feature matrix.
+  - `gender_inequality`, `female_lfpr`, and `women_business_law` exclude the merged gender-target outcome columns plus the UNDP GII feature block from the feature matrix to avoid same-theme target leakage.
 - Unit of training: country within decade
 - Primary split: within-decade cross-validation
 - Current metrics: `r2`, `rmse`, `mae`, `spearman`
-- Additional association exports: numeric feature correlations with income, population, life expectancy, inequality, and wealth target columns when they are present in the shared outcomes table
+- Additional association exports: numeric feature correlations with income, population, life expectancy, inequality, wealth, gender inequality, female LFPR, and Women, Business and the Law target columns when they are present in the shared outcomes table
 - Near-term additions: leave-region-out checks, calibration diagnostics, rank-hit metrics
 
 ## Maintained feature-set experiments

docs/UI_DATA_PAYLOADS.md

@@ -22,6 +22,7 @@ The UI should read the mirrored `web/public/data/` copies.
   - `bundle_summary_path`
   - `bundle_feature_effects_path`
   - `bundle_country_contributions_index_path`
+  - `bundle_permutation_importance_path`
 
 ### `model_summary.json`
 - Selected public income model diagnostics.
@@ -47,6 +48,9 @@ These are the new UI-builder payloads for all maintained targets and all non-emp
   - `life_expectancy`
   - `inequality`
   - `wealth`
+  - `gender_inequality`
+  - `female_lfpr`
+  - `women_business_law`
 - For each target:
   - `best_overall`
   - `bundles[]`
@@ -87,6 +91,9 @@ Note:
   - `bundle_country_contributions_life_expectancy.json`
   - `bundle_country_contributions_inequality.json`
   - `bundle_country_contributions_wealth.json`
+  - `bundle_country_contributions_gender_inequality.json`
+  - `bundle_country_contributions_female_lfpr.json`
+  - `bundle_country_contributions_women_business_law.json`
 - Each target payload contains `bundles[]`.
 - Each bundle contains `countries[]`.
 - Each country row contains:
@@ -101,6 +108,19 @@ Important:
 - `prediction` is aligned to the cross-validated bundle prediction export for the selected contributing spec.
 - For some bundles, the exact best-scoring spec may not have contribution rows. In those cases the payload uses the best available exported spec for that bundle instead of dropping the bundle entirely.
 
+### `bundle_permutation_importance.json`
+- Held-out permutation-importance summary for each target and bundle.
+- Covers the same maintained targets as `bundle_summary.json`.
+- Each target has `bundles[]`.
+- Each bundle includes:
+  - `top_permutation_features`
+  - `block_summary`
+
+Interpretation:
+- `delta_r2_mean` is the mean drop in held-out `R^2` when a feature or feature block is shuffled.
+- Larger positive `delta_r2_mean` means the model depends more on that feature or block for predictive accuracy.
+- This is a predictive-value metric, not a causal-effect estimate and not the same thing as a country-level up/down contribution.
+
 ## Tier semantics
 
 Bundle payloads use these maintained labels:

src/geoluck/cli.py

@@ -12,6 +12,7 @@
 from geoluck.etl.fetch_cru_cy import run_fetch as run_fetch_cru_cy
 from geoluck.etl.fetch_eia_company_imports import run_fetch as run_fetch_eia_company_imports
 from geoluck.etl.fetch_energy_institute_reserves import run_fetch as run_fetch_energy_institute
+from geoluck.etl.fetch_female_lfpr import run_fetch as run_fetch_female_lfpr
 from geoluck.etl.fetch_freedom_house import run_fetch as run_fetch_freedom_house
 from geoluck.etl.fetch_fsi import run_fetch as run_fetch_fsi
 from geoluck.etl.fetch_gcmt import run_fetch as run_fetch_gcmt
@@ -45,6 +46,9 @@
 from geoluck.etl.fetch_wealth_accounts import run_fetch as run_fetch_wealth_accounts
 from geoluck.etl.fetch_wgi import run_fetch as run_fetch_wgi
 from geoluck.etl.fetch_wocqi import run_fetch as run_fetch_wocqi
+from geoluck.etl.fetch_women_business_law import (
+    run_fetch as run_fetch_women_business_law,
+)
 from geoluck.etl.fetch_worldclim import run_fetch as run_fetch_worldclim
 from geoluck.etl.fetch_wpp import run_fetch as run_fetch_wpp
 from geoluck.features.build_alesina_fractionalization_features import (
@@ -156,7 +160,8 @@
     "income",
     "--target",
     help=(
-        "Prediction target to use. Available: income, life_expectancy, inequality, wealth."
+        "Prediction target to use. Available: income, life_expectancy, inequality, "
+        "wealth, gender_inequality, female_lfpr, women_business_law."
     ),
 )
 PERMUTATION_IMPORTANCE_OPTION = typer.Option(
@@ -267,14 +272,23 @@ def build_outcomes_panel() -> None:
     typer.echo(f"wpp_input={result.wpp_input_path}")
     if result.swiid_input_path is not None:
         typer.echo(f"swiid_input={result.swiid_input_path}")
+    if result.undp_gii_input_path is not None:
+        typer.echo(f"undp_gii_input={result.undp_gii_input_path}")
+    if result.female_lfpr_input_path is not None:
+        typer.echo(f"female_lfpr_input={result.female_lfpr_input_path}")
     if result.wealth_input_path is not None:
         typer.echo(f"wealth_input={result.wealth_input_path}")
+    if result.women_business_law_input_path is not None:
+        typer.echo(f"women_business_law_input={result.women_business_law_input_path}")
     typer.echo(f"output={result.output_path}")
     typer.echo(f"rows={result.row_count}")
     typer.echo(f"decades={result.decades}")
     typer.echo(f"life_expectancy_rows={result.life_expectancy_rows}")
     typer.echo(f"inequality_rows={result.inequality_rows}")
+    typer.echo(f"gender_inequality_rows={result.gender_inequality_rows}")
+    typer.echo(f"female_lfpr_rows={result.female_lfpr_rows}")
     typer.echo(f"wealth_rows={result.wealth_rows}")
+    typer.echo(f"women_business_law_rows={result.women_business_law_rows}")
 
 
 @app.command("fetch-natural-earth")
@@ -357,6 +371,39 @@ def fetch_undp_gii(
     typer.echo(f"unmatched_countries={result.unmatched_country_count}")
 
 
+@app.command("fetch-female-lfpr")
+def fetch_female_lfpr(
+    force: bool = typer.Option(False, help="Redownload the female LFPR indicator payload."),
+) -> None:
+    """Fetch and normalize the World Bank / ILO female LFPR series."""
+    result = run_fetch_female_lfpr(force=force)
+    typer.echo(f"raw_countries={result.raw_countries_path}")
+    typer.echo(f"raw_indicators={result.raw_indicators_path}")
+    typer.echo(f"tidy={result.tidy_path}")
+    typer.echo(f"provenance={result.provenance_path}")
+    typer.echo(f"rows={result.row_count}")
+    typer.echo(f"countries={result.country_count}")
+    typer.echo(f"years={result.year_min}-{result.year_max}")
+
+
+@app.command("fetch-women-business-law")
+def fetch_women_business_law(
+    force: bool = typer.Option(
+        False,
+        help="Redownload the Women, Business and the Law indicator payload.",
+    ),
+) -> None:
+    """Fetch and normalize the World Bank Women, Business and the Law index."""
+    result = run_fetch_women_business_law(force=force)
+    typer.echo(f"raw_countries={result.raw_countries_path}")
+    typer.echo(f"raw_indicators={result.raw_indicators_path}")
+    typer.echo(f"tidy={result.tidy_path}")
+    typer.echo(f"provenance={result.provenance_path}")
+    typer.echo(f"rows={result.row_count}")
+    typer.echo(f"countries={result.country_count}")
+    typer.echo(f"years={result.year_min}-{result.year_max}")
+
+
 @app.command("fetch-global-solar-atlas")
 def fetch_global_solar_atlas(
     force: bool = typer.Option(False, help="Refetch the Global Solar Atlas point samples."),