From 84116f6cb2ffd98ce5feda5a8833ec1d772f4ce2 Mon Sep 17 00:00:00 2001
From: David Pleydell <david.pleydell@inrae.fr>
Date: Mon, 18 Mar 2024 12:21:30 +0100
Subject: [PATCH 1/2] Added mapMCDA_English.Rmd
---
vignettes/mapMCDA_English.Rmd | 319 ++++++++++++++++++
vignettes/{mapMCDA.Rmd => mapMCDA_French.Rmd} | 10 +-
2 files changed, 324 insertions(+), 5 deletions(-)
create mode 100644 vignettes/mapMCDA_English.Rmd
rename vignettes/{mapMCDA.Rmd => mapMCDA_French.Rmd} (98%)
diff --git a/vignettes/mapMCDA_English.Rmd b/vignettes/mapMCDA_English.Rmd
new file mode 100644
index 0000000..cc8d87f
--- /dev/null
+++ b/vignettes/mapMCDA_English.Rmd
@@ -0,0 +1,319 @@
+---
+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)
+```
diff --git a/vignettes/mapMCDA.Rmd b/vignettes/mapMCDA_French.Rmd
similarity index 98%
rename from vignettes/mapMCDA.Rmd
rename to vignettes/mapMCDA_French.Rmd
index 86876cb..8c41003 100644
--- a/vignettes/mapMCDA.Rmd
+++ b/vignettes/mapMCDA_French.Rmd
@@ -37,10 +37,11 @@ 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.
+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.
@@ -48,7 +49,7 @@ 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
+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}
@@ -79,7 +80,7 @@ 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.
+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.
@@ -131,7 +132,7 @@ risques <- list(
```
On voudrait examiner les cartes de risque ainsi calculées.
-Mais pour cela, il faut qu'elles soient _aligné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.
@@ -196,4 +197,3 @@ 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)
```
-
--
GitLab
From 1d385bb6f365f03e72c29446591b62dffdaff4e6 Mon Sep 17 00:00:00 2001
From: David Pleydell <david.pleydell@inrae.fr>
Date: Mon, 18 Mar 2024 12:41:34 +0100
Subject: [PATCH 2/2] Updated VignetteIndexEntry
---
vignettes/mapMCDA_English.Rmd | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/vignettes/mapMCDA_English.Rmd b/vignettes/mapMCDA_English.Rmd
index cc8d87f..c3bd969 100644
--- a/vignettes/mapMCDA_English.Rmd
+++ b/vignettes/mapMCDA_English.Rmd
@@ -6,7 +6,7 @@ output:
toc: true
toc_depth: 2
vignette: >
- %\VignetteIndexEntry{Aperçu du package}
+ %\VignetteIndexEntry{Getting Started}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
--
GitLab