---
title: "Step 2: Choice of a biome scheme"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Step 2: Choice of a biome scheme}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
Sys.setenv(OPENBLAS_NUM_THREADS = "1")
Sys.setenv(OMP_NUM_THREADS      = "1")
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(biomes)
data(bombacoideae_occurrences)

run_raster <- isTRUE(as.logical(Sys.getenv("NOT_CRAN", "false")))
if (run_raster) {
  run_raster <- tryCatch({ biomes_download(quiet = TRUE); TRUE },
                         error = function(e) FALSE)
}
```

# Goal

[Step 1](step1-assembly-of-occurrence-records-and-biome-schemes.html) gave us occurrence records and
the 31 biome schemes. With 31 schemes to choose from, this step picks the one that
best fits *your* data, so the choice is explicit and reproducible rather than
defaulting to a familiar scheme.

> **Terms.** A **biome scheme** is one of the 31 classification systems; a **biome**
> is a category within it; a **biome scheme number** (1-31) identifies a scheme. A
> **biome definition** is the concept on which a scheme delimits its biomes; the
> `definition` argument restricts the ranking to the schemes sharing one definition.

---

# 1. Rank the schemes for your data

`biomes_rank()` scores every scheme for your occurrences and proposes a single
best-fitting scheme. Each scheme is rated on three complementary, data-driven
criteria:

- **coverage**: share of records that fall on a defined biome.
- **effective number of biomes**: `exp(H')`, the effective number of biomes
  the records occupy (rewards schemes that spread the data over several
  well-populated biomes).
- **granularity**: occupied biomes divided by the total number of biomes in the
  scheme.

The three criteria are min-max scaled to `[0, 1]` across the compared schemes and
averaged (equal weights) into a **composite score**. The best-scoring scheme is
returned in `attr(ranking, "best_scheme")`.

Because the scaling is relative to the compared schemes, a composite score is only
comparable among schemes that were ranked together, and a scaled value of 0 means
"lowest among the compared schemes", not zero. A criterion that does not vary among
the compared schemes is left out of the composite (see `attr(ranking, "criteria_used")`),
and a single compared scheme gets no composite score. Ties in the composite score
are broken by the publication year of the scheme (more recent first; see `tiebreaker`).

```{r, eval = run_raster}
ranking <- biomes_rank(bombacoideae_occurrences, verbose = FALSE)
best    <- attr(ranking, "best_scheme")
best
head(ranking)
```

The result is a data frame with one row per scheme; the key columns are `scheme`
(the biome scheme number), `scheme_name`, `composite_score` and `is_best`.

### Rank within one biome definition

Comparing schemes built on different biome definitions can mislead, so restrict the
ranking to the schemes sharing one definition with `definition`:

```{r, eval = run_raster}
r_veg <- biomes_rank(bombacoideae_occurrences, definition = "vegetation", verbose = FALSE)
attr(r_veg, "best_scheme")

table(biomes_information$biome_definition)   # how many schemes per group
```

`definition = "all"` (the default) ranks all 31 schemes. The biome definitions are
`"climate"`, `"vegetation"`, `"land_cover"`, `"ecoregion"`, `"integrative"` and
`"anthropogenic"`.

---

# 2. Inspect the ranking

The `rank` panel of `biomes_visualise()` shows the composite score per scheme with
the best scheme highlighted:

```{r, eval = run_raster && requireNamespace("ggplot2", quietly = TRUE), fig.width = 7, fig.height = 5}
biomes_visualise(bombacoideae_occurrences, panels = "rank")
```

Treat the ranking as a **shortlist**, not an authoritative answer: the most suitable
scheme ultimately depends on your research question. Inspect the criterion-specific
columns of the ranking and use `biomes_info()` to pick the scheme whose concept and
resolution match your data.

The integer in `attr(ranking, "best_scheme")` is exactly the biome scheme number you
pass as `scheme` to the classification and visualisation functions next.

---

# Next

You have a chosen biome scheme. Continue with
[Step 3: Occurrences-to-biome classification](step3-occurrence-to-biome-classification.html).