---
title: "Tutorial: Site-Level KPI Calculators"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Tutorial: Site-Level KPI Calculators}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

# 1. Why site-level KPIs?

Country-level SDG statistics tell you where a jurisdiction stands; they do
not tell you how *your operation* performs. MineSDG v0.3.0 adds a family of
site-level KPI calculators aligned with the disclosure conventions mining
teams already report against:

| KPI family | SDG | Framework convention |
|---|---|---|
| GHG intensity (Scope 1+2) | 13 | GHG Protocol; GRI 305-4; SASB EM-MM-110a.1 |
| Energy intensity, renewable share | 7 | GRI 302; SASB EM-MM-130a.1 |
| Water recycling, net consumption | 6 | GRI 303; ICMM Water Position Statement |
| Land rehabilitation rate | 15 | GRI 11.7 / 304-3; ICMM Principle 7 |
| TRIFR / LTIFR / fatality rate | 8.8 | GRI 403-9; ICMM per-1M-hours convention |
| Workforce diversity & localisation | 5, 8 | GRI 405-1; GRI 202-2 |
| Community investment ratio | 1, 17 | GRI 203-1; ICMM Principle 9 |
| Tailings & waste-rock ratios | 12 | GRI 306 / 11.8; GISTM context |

All calculators are pure functions — no network access, no side effects —
so they can be embedded in pipelines, reports, and the Shiny dashboard.

# 2. Working with the demo data

The package bundles `demo_mine_sites`, a synthetic six-site, six-year panel:

```{r}
head(demo_mine_sites[, 1:8])
```

Take one site-year:

```{r}
site <- demo_mine_sites[demo_mine_sites$site_id == "CU-ATAC" &
                          demo_mine_sites$year == 2024, ]
```

# 3. Individual calculators

**Climate (SDG 13):**

```{r}
calculate_ghg_intensity(
  scope1_t = site$ghg_scope1_t,
  scope2_t = site$ghg_scope2_t,
  ore_processed_kt = site$ore_processed_kt
)
```

**Energy (SDG 7):**

```{r}
calculate_energy_intensity(
  energy_gj = site$energy_gj,
  ore_processed_kt = site$ore_processed_kt,
  renewable_gj = site$energy_gj * site$renewable_energy_pct / 100
)
```

**Safety (SDG 8.8), per one million hours worked:**

```{r}
calculate_safety_performance(
  hours_worked = site$hours_worked,
  recordable_injuries = site$recordable_injuries,
  lost_time_injuries = site$lost_time_injuries,
  fatalities = site$fatalities
)
```

**Water (SDG 6.4), land (SDG 15.3), community (SDG 1), waste (SDG 12):**

```{r}
calculate_water_efficiency(site$water_withdrawal_m3,
                           site$water_discharge_m3,
                           site$water_recycled_m3)

calculate_land_restoration(site$land_disturbed_ha,
                           site$land_rehabilitated_ha)

calculate_community_investment(site$community_investment_musd,
                               site$revenue_musd)

calculate_waste_intensity(site$ore_processed_kt,
                          site$tailings_kt,
                          waste_rock_kt = site$waste_rock_kt)
```

# 4. Using your own data

Shape one row per site-year with the column names shown in
`?demo_mine_sites`. Any missing fields are simply skipped by the scorecard
engine (next tutorial). A minimal example:

```{r}
my_site <- data.frame(
  site_id = "MY-MINE", year = 2025,
  ore_processed_kt = 12000,
  ghg_scope1_t = 420000, ghg_scope2_t = 180000,
  hours_worked = 5.2e6, recordable_injuries = 18,
  lost_time_injuries = 6, fatalities = 0
)

calculate_ghg_intensity(my_site$ghg_scope1_t, my_site$ghg_scope2_t,
                        my_site$ore_processed_kt)$ghg_intensity
```

Continue with `vignette("sdg-ontology-and-scorecard")` to turn these raw
KPIs into a weighted 0-100 SDG scorecard, or launch the dashboard with
`run_minesdg_dashboard()`.