---
title: "Custom mesohabitat classifications"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Custom mesohabitat classifications}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r plot-options, include=FALSE}
knitr::opts_chunk$set(fig.bg = "white", dev.args = list(bg = "white"))
```

```{r setup}
library(hydromeso)
```

Custom schemes are validated rectangular regions. Required columns are
`class_id`, `label`, `depth_min`, `depth_max`, `velocity_min`, and
`velocity_max`.

```{r}
rules <- data.frame(
  class_id = c(1L, 2L), label = c("Slow", "Fast"),
  depth_min = c(0, 0), depth_max = c(Inf, Inf),
  velocity_min = c(0, 0.5), velocity_max = c(0.5, Inf)
)
custom <- meso_scheme(rules, name = "Two velocity classes")
validate_meso_scheme(custom)
plot_meso_scheme(custom)
```

Overlaps are always rejected. Gaps are rejected unless `allow_gaps = TRUE`;
observations in an allowed gap return `NA`. Validation evaluates exact
breakpoints and representatives of every interval, not a random sample.

```{r error=TRUE}
overlap <- rules
overlap$velocity_min[2] <- 0.4
meso_scheme(overlap)

gap <- rules
gap$velocity_max[1] <- 0.4
gap$velocity_min[2] <- 0.6
meso_scheme(gap)
gap_scheme <- meso_scheme(gap, allow_gaps = TRUE)
classify_mesohabitat_values(1, 0.5, gap_scheme)
```

The custom scheme can be supplied to every table, vector, raster, and scenario
classifier. Users are responsible for scientifically justifying and reporting
custom thresholds and units.

```{r custom-raster-figure, fig.cap="Example raster classified with the custom two-class scheme."}
h <- mesohabitat_example_rasters()
custom_raster <- classify_mesohabitat_raster(
  h$depth, h$velocity, scheme = custom
)
plot_mesohabitat(custom_raster, scheme = custom)
```