---
title: "Getting started with reiod"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with reiod}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This page is the map: what is in the package, what the cut-offs are, one
complete run from raw columns to every metric, and one thing about survey
weights that affects every number you report.

The run is deliberately brief. Each metric family has its own article, with
worked examples for a single value, a column, and adding results to a data
frame. Links are at the bottom, and in the **Articles** menu above.

## What EIOF is

Intake's **Environmental Impacts of Foods (EIOF)** database gives
country-specific environmental impact values for more than 6,500 foods across
seven impact areas spanning five domains of planetary health. What makes it
unusual is not only its coverage but its adjustment factors: non-edible
portion, processing and cooking yield, so that the *form of food consumed* in
a dietary recall can be matched correctly to the *form of food* the impact
data describes.

Alongside the database, Intake published a set of **dietary environmental
impact metrics** for use with food consumption survey data. These come in
three families:

| Family | Question it answers | Source | Article |
|---|---|---|---|
| Absolute threshold | Is this diet below the per capita daily share of a planetary boundary? | Table 3 | `vignette("table3-absolute")` |
| Relative benchmark | Where does this diet sit in a global reference distribution? | Tables 4a–4g | `vignette("table4-relative")` |
| Composite | Is this diet both healthy and environmentally sound? | Tables 5a, 5b | `vignette("table5-composites")` |

All of them are age- and sex-specific, because average dietary energy
requirement differs across groups.

## What reiod is — and is not

`reiod` implements those metrics in R.

**It does not contain the EIOF database.** It ships the published *cut-offs*
and applies them to impact values you have already derived. The work of
matching food items to impact factors, applying the adjustment factors, and
summing to the respondent-day happens upstream; `reiod` starts where that
ends. It also does not calculate the Global Diet Quality Score — the composite
metrics take a GDQS value as an input.

So the input `reiod` expects is one row per respondent-day, with the impact
totals already summed:

```{r}
head(eiod_demo, 3)
```

The package has **no dependencies beyond base R**: it imports only `stats` and
`utils`, which ship with every R installation. The practical consequence is a
plain vector API: you pass `df$biodiv_pdf`, not `biodiv_pdf`.

## A first run, start to finish

Every step below is covered in depth in its own article. This is the whole
workflow on the demo data, so you can see how the pieces fit before reading
them one at a time.

**1. The demographic group.** Every cut-off is age- and sex-specific, so this
comes first (`vignette("demographic-groups")`):

```{r}
d <- eiod_demo
d$grp <- eiod_age_sex_group(d$age, d$sex)
table(d$grp)
```

**2. Check the inputs** (`vignette("data-checks")`). Your columns can be named
anything; `eiod_demo_map` states which column holds which indicator:

```{r}
eiod_demo_map
summary(eiod_check_data(d, impacts = eiod_demo_map,
                        age = "age", sex = "sex", gdqs = "gdqs"))
```

**3. Table 3, absolute thresholds** (`vignette("table3-absolute")`). One 0/1
column per indicator, `1` meaning below the threshold:

```{r}
abs7 <- eiod_absolute_all(d, d$grp, eiod_demo_map)
round(100 * colMeans(abs7, na.rm = TRUE), 1)
```

**4. Tables 4a–4g, relative bands** (`vignette("table4-relative")`). Bands 1–10
against the fixed global reference distribution:

```{r}
band7 <- eiod_relative_all(d, d$grp, eiod_demo_map)
table(band7$band_ghg)
```

**5. Tables 5a and 5b, composites** (`vignette("table5-composites")`). The
under-twos are set to `NA`, and a message says so:

```{r}
d$hesd  <- eiod_hesd(d$biodiv_pdf, d$gdqs, d$grp, form = "binary")
d$hdlei <- eiod_hdlei(d$biodiv_pdf, d$gdqs, d$grp, form = "binary")
```

**6. Put the results back in your data**, one row per respondent-day:

```{r}
d <- cbind(d, abs7, band7)
head(d[, c("id", "grp", "abs_ghg", "band_ghg", "hesd", "hdlei")])
```

These percentages are unweighted, on synthetic data. They demonstrate the code,
not a finding; see [Survey weights](#survey-weights) before reporting real
prevalences.

## What is in the package

```{r}
ls("package:reiod")
```

| Group | Functions |
|---|---|
| Demographic group | `eiod_age_sex_group()`, `eiod_as_sex_factor()` |
| Metrics | `eiod_absolute_threshold()`, `eiod_relative_band()`, `eiod_hesd()`, `eiod_hdlei()` |
| Several indicators at once | `eiod_absolute_all()`, `eiod_relative_all()` |
| Decomposed sub-indicators | `eiod_healthy_diet()`, `eiod_sustainable_diet()`, `eiod_low_impact()` |
| Data quality checks | `eiod_check_data()` and five component checks |
| Reference lookups | `eiod_list_indicators()`, `eiod_lookup_cutoff()` |
| Shipped data | `eiod_cutoffs`, `eiod_indicators`, `eiod_demo`, `eiod_demo_map` |

## The seven indicators, and their units

Units matter more here than in most analyses, because a unit error produces a
confidently wrong answer rather than an obvious one. This is the function to
check what the package expects:

```{r}
eiod_list_indicators()
```

The **indicator key** in the first column is what you pass to every function.
Your own column can be called anything — the two never have to match.

## The cut-offs

All 616 published cut-offs ship as `eiod_cutoffs`, in long format:

```{r}
str(eiod_cutoffs)
```

```{r}
table(eiod_cutoffs$table, eiod_cutoffs$metric)
```

### Table 3 — one absolute threshold per group

```{r}
eiod_lookup_cutoff("ghg", metric = "abs")
```

Printed to 15 significant digits on purpose: the published cut-offs need up to
14, and R's default `options(digits = 7)` would make it look as though the
package had rounded the guideline. The `as printed` column is the literal text
transcribed from the paper, so you can check it character for character.

### Tables 4a–4g — nine decile cut-points per group

```{r}
subset(eiod_cutoffs,
       metric == "rel" & indicator == "ghg" & demogroup == 4 &
         !is.na(percentile),
       select = c(percentile, value))
```

### Tables 5a and 5b — no new cut-offs

The composites define none. HESD reuses the Table 3 biodiversity threshold;
HDLEI reuses the Table 4g P30. Both obtain them by *calling* the metric
functions, so there is no second copy in the code and nothing extra in the
data.

### Eight values differ from the published PDF

On Intake's instruction. The `value_source` column marks them:

```{r}
subset(eiod_cutoffs, value_source != "published",
       c(demogroup_label, metric, unit, value))
```

**Supply eutrophication in grams and convert nothing.**
`vignette("eutrophication")` has the whole story.

## Survey weights

`reiod` returns respondent-level indicator vectors and nothing else. **It
applies no survey design.**

Every prevalence you report should come from a design-aware estimator — the
**survey** package, or whatever your analysis uses — or both your point
estimates and your standard errors will be wrong for a complex design. The
percentages printed throughout these articles are unweighted, because they are
demonstrating code rather than reporting results.

```r
library(survey)
des <- svydesign(ids = ~psu, strata = ~stratum, weights = ~wt, data = d)
svymean(~abs_ghg, des, na.rm = TRUE)
svyby(~abs_ghg, ~group, des, svymean, na.rm = TRUE)
```

## Where to go next

Read them in this order the first time:

1. **`vignette("data-checks")`** — what to run before computing anything, and
   why only one check is automatic
2. **`vignette("demographic-groups")`** — the eight age × sex cells every
   cut-off is scaled by
3. **`vignette("table3-absolute")`** — Table 3
4. **`vignette("table4-relative")`** — Tables 4a–4g
5. **`vignette("table5-composites")`** — Tables 5a and 5b

Then as needed:

* `vignette("precision")` — the precision pre-flight check in depth
* `vignette("troubleshooting")` — a broken dataset, fault by fault
* `vignette("eutrophication")` — the one indicator with a unit history