---
title: "Aperçu du package"
date: "`r Sys.Date()`"
output:
   rmarkdown::html_vignette:
     toc: true
     toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Aperçu du package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r packages}
require(sf)
require(terra)
require(mapMCDA)
```

# Introduction

Le package `mapMCDA` facilite la ponderation de plusieurs facteurs de risque
pour produîre une carte de risque épidémiologique.

Néanmoins, l'expertise de l'utilisateur est cruciale. Elle s'exprime à trois
niveaux :

1. Choix des facteurs de risque rélevants

2. Pour chaque facteur, mise en échelle commune de risque (e.g. entre 0 et 100)

3. Évaluation deux-à-deux de l'importance rélative des facteurs de risque


À continuation, on utilise des cartes fournis par le package pour produîre une
carte de risque d'exemple.
__Cette carte n'a aucun valeur épidémiologique.__



# 1. Facteurs de risque

La fonction `mapMCDA_datasets()` permet de charger en mémoire toutes les cartes
disponibles dans le package.

L'objet `cmr` est une simple liste de cartes : objets de type `sf` pour
les cartes vectoriels et de type `SpatRaster` pour les cartes raster.

Pour utiliser d'autre cartographie, utiliser les fonctions `sf::st_read` et
`terra::rast()` respectivement pour des cartes vectoriels ou raster.

On peut aussi bénéficier de la fonction `load_layer()` pour charger tout type
des cartes automatiquement, comme démontré dans le code commenté.

```{r facteurs-risque}
cmr <- mapMCDA_datasets()

# layers <- list.files(
#   system.file("cartography/CMR", package = "mapMCDA"),
#   full.names = TRUE
# )
# cmr <- lapply(layers, load_layer)
# names(cmr) <- rmext(basename(layers)))

```

L'une de ces cartes est celle des unités épidémiologiques, utilisée pour établir
le cadre de travail.

```{r unite-epidemiologique, fig.cap = "Unités épidémiologiques d'exemple pour le Cameroun."}
unites_epi <- cmr$cmr_admin3
par(mar = c(0, 0, 0, 0))
plot(st_geometry(unites_epi))
```

# 2. Mise en échelle

Chaque facteur de risque varie dans une échelle qui lui est propre.
La densité animale, par exemple, varie entre 0 et presque 5500 têtes par $km^2$.

Pour les cartes _vectorielles_, qui representent la localisation des entités
spatiales telles que lacs ou forêts, on considère la __distance__ à dites
entités.

Ce package utilise pour l'instant une fonction linèaire pour la mise en échelle.
Cependant, la rélation peut être directe ou inverse.

```{r mise-echelle, fig.width=4, fig.cap = "Mis en échelle directe ou inverse."}

plot(
  data.frame(x = c(0, 100), y = c(0, 100)),
  type = 'l',
  xaxs = "i",
  yaxs = "i",
  xaxt = "n",
  lab = c(1, 1, 7),
  xlab = c("Échelle originale"),
  ylab = c("Échelle de risque")
)
abline(100, -1)

```

La fonction `risk_layer()` calcule la carte de risque associé à un facteur
concret dans une échelle donnée. Par défault c'est entre 0 et 100. Pour
inverser la rélation il suffit de passer les limits dans l'ordre inverse, e.g.
`c(100, 0)`.

D'ailleurs, elle utilise la carte d'unités épidémiologiques pour établir
les limits de calcul de risque.

```{r risk-layers}

risques <- list(
  dens_animale = risk_layer(
    cmr$animal.density,
    boundaries = unites_epi
    # , scale_target = c(0, 100)  # échelle directe par défault
  ),
  points_eau = risk_layer(
    cmr$water_bodies,
    boundaries = unites_epi,
    scale_target = c(100, 0)  # échelle renversée
  ),
  parcs = risk_layer(
    cmr$national_parks,
    boundaries = unites_epi,
    scale_target = c(100, 0)  # échelle renversée
  )
)

```

On voudrait examiner les cartes de risque ainsi calculées.
Mais pour cela, il faut qu'elles soient _alignées_.
C'est à dire, qu'elles aient les mêmes _extents_, _résolutions_ et _projections_.

On peut se servir de la fonction `align_layers()` qui arrange tout ça pour nous.
Noter que ce pas n'est pas nécessaire pour continuer, car cette fonction est
automatiquement executée si besoin.

```{r align-layers, fig.width = 6, fig.cap = "Niveaux de risque associé à chaque facteur."}
risques_alignes <- align_layers(risques)
plot(terra::rast(risques_alignes), nc = 3, col = grDevices::hcl.colors(50))

```


# 3. Pondération des facteurs de risque

Il y a 3 facteurs à considérer.
Il faut comparer 2-à-2 leurs importances relatives en une échelle de 1 à 9 et
representer ces rélations en une matrice qui doit avoir des 1 dans son diagonale.

Noter que les élements symmetriques doivent être réciproques.

```{r matrice-relations, echo = -1}

M <- matrix(c(
  1,     6, 4,
  1/6,   1, 3,
  1/4, 1/3, 1
), byrow = TRUE, 3, 3)
colnames(M) <- rownames(M) <- names(risques)
knitr::kable(M, digits = 2)
```

Dans cette exemple, on considère que la densité animale est 6 fois plus importante
que la distance aux points d'eau, et 4 fois plus importante que la distance aux
parcs.
Au même temps, que la distance aux points d'eau est 3 fois plus importante que
celle aux parcs.

Le système calcule les coefficients de pondération les plus consistents avec
ces valorations par paires, avec la fonction `compute_weights()`.

```{r compute-weights, fig.width=4, echo = 1, fig.cap = "Pondération des facteurs de risque."}
w <- compute_weights(M)
mapMCDA:::plot_weights(w, rownames(M))
```


# 4. Calcul de la carte de risque

La fonction `wlc()` (pour weighted linear combination) combine tous les facteurs
de risque en utilisant les poids calculés précedament, et produise une carte
de risque qui couvre toute la région.

```{r wlc, fig.width = 6, fig.height = 6, fig.cap = "Carte de risque combiné."}
risque_combine <- wlc(risques, w)
plot(risque_combine, col = hcl.colors(50))
```

Enfin, on peut produîre una carte par unité épidémiologique et dans une échelle
de quelques niveaux de risque.

```{r risk-plot, fig.width = 6, fig.height = 6, fig.cap = "Carte de niveaux de risque par unité épidémiologique."}
risk_plot(unites_epi, v = risk_unit(risque_combine, unites_epi), n = 5)
```