---
title: "Tutorial: SDG Ontology, Site Scorecards & Dashboard"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Tutorial: SDG Ontology, Site Scorecards & Dashboard}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(MineSDG)
```

------------------------------------------------------------------------

# 1. The SDG-to-Mining ontology

MineSDG formalises the relationship between the 17 SDGs and mining-sector
materiality as a queryable dataset, `sdg_mining_ontology`. Each goal is
mapped to a mining domain, a 1-5 materiality rating, a material topic, and
references into GRI 11 (the 2024 mining sector standard), the ICMM Mining
Principles, SASB EM-MM metrics and SEBI BRSR principles.

```{r}
explore_sdg_ontology(goal = 6)

explore_sdg_ontology(domain = "biodiversity")[, c("goal", "material_topic",
                                                  "gri_reference")]
```

The five core-materiality goals for mining (rating 5) are health & safety
(SDG 3), water (SDG 6), climate (SDG 13) and land/biodiversity (SDG 15) —
consistent with how ICMM members and GRI 11 frame sector materiality.

```{r}
sdg_mining_ontology[sdg_mining_ontology$materiality == 5,
                    c("goal", "goal_name", "mining_domain")]
```

# 2. The KPI registry

`mining_kpi_registry` defines 18 site KPIs with units, SDG targets,
improvement direction, and indicative *good* / *poor* reference thresholds
that anchor 0-100 scoring:

```{r}
list_mining_kpis(sdg_goal = 8)
```

> **Calibration note.** The bundled thresholds are indicative sector
> reference points. For production use, copy the registry and calibrate
> `good_value` / `poor_value` to your commodity, scale and jurisdiction,
> then pass your version to `score_site_sdg(registry = ...)`.

# 3. Scoring a site

`score_site_sdg()` takes one site-year of raw operational data, derives
every KPI it can, rescales each between the registry thresholds (respecting
direction), aggregates to SDG-goal level, and weights goals by ontology
materiality into a composite:

```{r}
site <- demo_mine_sites[demo_mine_sites$site_id == "FE-PILB" &
                          demo_mine_sites$year == 2024, ]
result <- score_site_sdg(site)
result
```

Drill into the KPI detail:

```{r}
result$scorecard
```

# 4. Portfolio comparison

Score every site for the latest year:

```{r}
latest <- demo_mine_sites[demo_mine_sites$year == 2024, ]
portfolio <- do.call(rbind, lapply(seq_len(nrow(latest)), function(i) {
  s <- score_site_sdg(latest[i, ])
  data.frame(site_id = s$site_id, composite = s$composite_score,
             grade = s$grade)
}))
portfolio[order(-portfolio$composite), ]
```

# 5. Offline SDG analytics

`demo_sdg_country` mirrors the output of `fetch_sdg_country_data()`, so the
full analytics layer runs without network access:

```{r}
dt <- demo_sdg_country[demo_sdg_country$indicator == "6.4.1", ]
compute_sdg_stability(dt)
```

# 6. The Shiny dashboard

Everything above is wrapped in an interactive dashboard:

```{r, eval = FALSE}
run_minesdg_dashboard()
```

Five tabs: **Portfolio Overview** (composite scores and grades per site),
**Site Deep-Dive** (KPI trend lines and the latest scorecard),
**SDG Alignment** (ontology explorer with materiality chart),
**KPI Registry**, and **Data** (bundled demo or a CSV upload following the
`demo_mine_sites` schema). Requires the `shiny` package; `DT` is optional
for enhanced tables.