Spaces:
Running
Running
| # Methodology and reproducibility | |
| ## Scope | |
| This is an exploratory, source-aware **comparative education intelligence** dashboard. The eight indicators are selected examples, not a complete education system assessment or an official SDG4 index. The application avoids causal interpretations. | |
| ## Data ingestion | |
| Clicking **Load World Bank data** requests all eight series from the WDI source (ID 2): | |
| `https://api.worldbank.org/v2/country/ARG;BOL;BRA/indicator/SE.PRM.CMPT.ZS;SE.SEC.ENRR;...?source=2&date=2010:2025&format=json&per_page=20000` | |
| The actual URL is assembled from selected economies, indicators and years; users can inspect the exact link in the Data quality view or exported research brief. All retrieval is initiated by the browser. The app never silently substitutes synthetic data after a failed request. | |
| ## Overview | |
| Each country is represented by its **latest non-missing observation within the selected window**. Latest values can be from different years; year and reporting lag are shown. A ranking here is not a same-year ranking. Source-specific measurement definitions remain relevant. | |
| ## Trends | |
| Points show unmodified observations; connecting segments are displayed only for **consecutive reported years**, with gaps remaining visually disconnected. A change compares first and last available values, possibly from different years per country. | |
| ## Country gaps | |
| For two selected countries `A` and `B` in year `t`: | |
| `gap(A,B,t) = reported_value(A,t) - reported_value(B,t)`. | |
| Both observations must exist for **the exact same year**. This is a *between-country level difference*, not an inequality or socioeconomic equity gap inside either country. | |
| ## Associations | |
| A pair is included only if X and Y exist for the same country and calendar year. The displayed sample size counts country-year pairs. Pearson's correlation coefficient is the conventional covariance divided by the product of centered sums of squares. It is not causal, and the application does **not** estimate statistical significance, confidence intervals, fixed effects or corrected clustered standard errors. Repeated years from each country violate independent-sample assumptions; do not treat r as a confirmed structural relationship. | |
| ## Coverage and reporting lag | |
| `coverage = valid_observations / (selected_countries × selected_years × 8_indicators)`. | |
| Mean reporting lag averages `(selected_end_year - latest_available_year)` for each observed country-indicator combination. A country-indicator combination without any reported value is excluded from the lag mean but remains missing in the coverage ratio. This is a reporting *timeliness* statistic, not a data quality score. | |
| ## Research brief | |
| A deterministic descriptive Markdown narrative is assembled directly from currently loaded observations; it does not use an LLM or claim independent verification. Exported CSV and session JSON include a status marking LIVE / SYNTHETIC / IMPORTED and preserve source-derived years and metadata. Source footnotes can be incomplete because the upstream API may not return them for every observation. | |
| ## Missing data | |
| No imputation, interpolation, invented country values, or silent fill-forward of missing data. Number of points and exact reporting years remain visible. Nulls are never converted to zero. Year and observation count constraints are validated. | |
| ## Synthetic demo | |
| `demo-data.js` generates illustrative values deterministically from a fixed mathematical formula, with intentionally missing observations. Demo output is always marked **SYNTHETIC DEMO** and must never be presented as official data. | |
| ## Reproducibility | |
| - Deterministic analysis helpers: `core.js` | |
| - Live API adapter: `worldbank.js` | |
| - Clearly synthetic generator: `demo-data.js` | |
| - Interactive UI: `app.js`, `index.html`, `style.css` | |
| - Unit tests: `node --test tests.mjs` | |
| - Browser QA: `browser_test.py` (requires Python Playwright and Chromium) | |
| - Data dictionary, limitations and privacy: other root Markdown documents. | |
| ## Limitations | |
| World Bank data might have missing observations, definition changes and revision cycles. Gross enrollment can exceed 100%. GDP per capita in current US dollars is not purchasing-power-adjusted. Country-to-country and time-to-time differences do not identify policy impacts. Review original provider metadata and seek specialist input for high-stakes interpretations. | |