Skip to content
Snippets Groups Projects

Added mapMCDA_English.Rmd

Closed Added mapMCDA_English.Rmd
english_vignette into 35-vignette-mapmcda-get-started-update
Closed David Pleydell requested to merge english_vignette into 35-vignette-mapmcda-get-started-update
Compare
and
2 files
+ 324
− 5
Compare changes
  • Side-by-side
  • Inline
Files
2
vignettes/mapMCDA_English.Rmd 0 → 100644
+ 319
− 0
---
title: "Getting Started"
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
The `mapMCDA` package facilitates the weighting of several risk factors to produce an epidemiological risk map.
However, a user's expertise can be crucial to the interpretation of each risk factor.
This is expressed at three levels within mapMCDA:
1. Choice of relevant risk factors.
2. For each factor, setting a common risk scale (e.g. between 0 and 100).
3. Two-way assessment of the relative importance of the risk factors.
Next, we use the maps provided by the package to produce an example risk map.
__This map has no epidemiological value.__
# 1. Facteurs de risque
<!-- La fonction `mapMCDA_datasets()` permet de charger en mémoire toutes les cartes disponibles dans le package. -->
The function `mapMCDA_datasets()` is used to load into memory all the maps available within the 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. -->
The `cmr` object is a simple list of maps: objects of type `sf` for vectorial for vector maps and of type `SpatRaster` for raster maps.
<!-- Pour utiliser d'autre cartographie, utiliser les fonctions `sf::st_read` et `terra::rast()` -->
<!-- respectivement pour des cartes vectoriels ou raster. -->
To use other maps, use the functions `sf::st_read` and `terra::rast()` for vector and raster maps respectively.
<!-- 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é. -->
You can also use the `load_layer()` function to load any type
of maps automatically, as demonstrated in the commented code.
```{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. -->
One of these maps is that of the epidemiological units, used to establish the working framework.
<!-- ```{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)) -->
<!-- ``` -->
```{r epidemiological-units, fig.cap = "Epidemiological units example for Cameroon."}
epi_units <- cmr$cmr_admin3
par(mar = c(0, 0, 0, 0))
plot(st_geometry(epi_units))
```
<!-- # 2. Mise en échelle -->
# 2. Scaling
<!-------------------------------------------------------------------------------------->
<!-- 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. -->
<!-------------------------------------------------------------------------------------->
Each risk factor varies on its own scale.
Animal density, for example, varies between 0 and almost 5500 heads per $km^2$.
For _vector maps_, which show the location of spatial features such as lakes or forests,
we consider the __distance__ to these entities.
This package currently uses a linear function for scaling.
However, the relationship can be direct or 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) -->
<!-- ``` -->
<!-------------------------------------------------------------------------------------->
```{r scaling, fig.width=4, fig.cap = "Direct or inverse scaling."}
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("Original scale"),
ylab = c("Scale of risk")
)
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. -->
<!------------------------------------------------------------------------------------>
The `risk_layer()` function calculates the risk map associated in a factor with a given scale.
The default value is between 0 and 100.
To reverse the relationship, simply pass the limits in reverse order, e.g.
`c(100, 0)`.
Moreover, it uses the map of epidemiological units to establish risk calculation limits.
<!------------------------------------------------------->
<!-- ```{r risk-layers} -->
<!-- risques <- list( -->
<!-- dens_animale = risk_layer( -->
<!-- cmr$animal.density, -->
<!-- boundaries = epi_units -->
<!-- ), -->
<!-- points_eau = risk_layer( -->
<!-- cmr$water_bodies, -->
<!-- boundaries = epi_units, -->
<!-- scale_target = c(100, 0) # échelle renversée -->
<!-- ), -->
<!-- parks = risk_layer( -->
<!-- cmr$national_parks, -->
<!-- boundaries = epi_units, -->
<!-- scale_target = c(100, 0) # échelle renversée -->
<!-- ) -->
<!-- ) -->
<!-- ``` -->
<!------------------------------------------------------->
```{r risk-layers}
risks <- list(
animal_density = risk_layer(
cmr$animal.density,
boundaries = epi_units
),
water_bodies = risk_layer(
cmr$water_bodies,
boundaries = epi_units,
scale_target = c(100, 0) # renversed scale
),
parks = risk_layer(
cmr$national_parks,
boundaries = epi_units,
scale_target = c(100, 0) # renversed scale
)
)
```
<!--------------------------------------------------------------------------------------->
<!-- 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. -->
<!--------------------------------------------------------------------------------------->
We would like to examine the risk maps calculated in this way.
But to do this, they need to be _aligned_.
In other words, they must have the same _extents_, _resolutions_ and _projections_.
We can use the `align_layers()` function, which arranges all this for us.
Note that this step is not necessary to continue, as this function is
automatically executed if necessary.
<!------------------------------------------------------------------------------------------------->
<!-- ```{r align-layers, fig.width = 6, fig.cap = "Niveaux de risque associé à chaque facteur."} -->
<!-- risques_alignes <- align_layers(risks) -->
<!-- plot(terra::rast(risques_alignes), nc = 3, col = grDevices::hcl.colors(50)) -->
<!-- ``` -->
<!------------------------------------------------------------------------------------------------->
```{r align-layers, fig.width = 6, fig.cap = "Level of risk associated with each risk factor."}
aligned_risks <- align_layers(risks)
plot(terra::rast(aligned_risks), nc = 3, col = grDevices::hcl.colors(50))
```
<!--------------------------------------------->
<!-- # 3. Pondération des facteurs de risque -->
<!--------------------------------------------->
# 3. Weighting of risk factors
<!--------------------------------------------------------------------------------------->
<!-- 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. -->
<!--------------------------------------------------------------------------------------->
There are three factors to conider.
We need to compare their relative importance 2-by-2 on a scale of 1 to 9 and
represent these relationships in a matrix which must have 1's on its diagonal.
<!-- Noter que les élements symmetriques doivent être réciproques. -->
Note that symmetrical elements must be reciprocal.
<!-- ```{r matrice-relations, echo = -1} -->
```{r matrix-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(risks)
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. -->
<!-------------------------------------------------------------------------------------------->
In this example, we consider that animal density is 6 times more important
than the distance to watering holes, and 4 times more important than the distance to parks.
At the same time, the distance to water points is 3 times greater than the distance to parks.
<!---------------------------------------------------------------------------------->
<!-- Le système calcule les coefficients de pondération les plus consistents avec -->
<!-- ces valorations par paires, avec la fonction `compute_weights()`. -->
<!---------------------------------------------------------------------------------->
The system calculates the weighting coefficients that are most consistent with
these pairwise values, using the `compute_weights()` function.
```{r compute-weights, fig.width=4, echo = 1, fig.cap = "Weighting of risk factors."}
w <- compute_weights(M)
mapMCDA:::plot_weights(w, rownames(M))
```
<!--------------------------------------->
<!-- # 4. Calcul de la carte de risque -->
<!--------------------------------------->
# 4. Calculation of the risk map
<!-------------------------------------------------------------------------------------->
<!-- 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. -->
<!-------------------------------------------------------------------------------------->
The `wlc()` function (for weighted linear combination) combines all the risk factors
risk factors using the weights calculated above, and produces a risk map covering the whole region.
<!------------------------------------------------------------------------------------->
<!-- ```{r wlc, fig.width = 6, fig.height = 6, fig.cap = "Carte de risque combiné."} -->
<!-- risque_combine <- wlc(risks, w) -->
<!-- plot(risque_combine, col = hcl.colors(50)) -->
<!-- ``` -->
<!------------------------------------------------------------------------------------->
```{r wlc, fig.width = 6, fig.height = 6, fig.cap = "Map of combined risks."}
combined_risk <- wlc(risks, w)
plot(combined_risk, col = hcl.colors(50))
```
<!------------------------------------------------------------------------------------->
<!-- Enfin, on peut produîre una carte par unité épidémiologique et dans une échelle -->
<!-- de quelques niveaux de risque. -->
<!------------------------------------------------------------------------------------->
Finally, a map can be produced for each epidemiological unit on a homogonized scale of risk.
<!-- ```{r risk-plot, fig.width = 6, fig.height = 6, fig.cap = "Carte de niveaux de risque par unité épidémiologique."} -->
<!-- risk_plot(epi_units, v = risk_unit(combined_risk, epi_units), n = 5) -->
<!-- ``` -->
```{r risk-plot, fig.width = 6, fig.height = 6, fig.cap = "Map of risk level per epidemiological unit."}
risk_plot(epi_units, v = risk_unit(combined_risk, epi_units), n = 5)
```