--- title: "lczexplore_alter" author: "Matthieu Gousseff" date: "`r Sys.Date()`" output: rmarkdown::html_vignette resource_files: - vignettes/Redon.png vignette: > %\VignetteIndexEntry{lczexplore_alter} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` The lczexplore package was developped thanks to the PAENDORA2 (Pour la gestion du confort estival : Données, Outils et Recherche-Action, 2022 -2025, funded by ADEME, a French agency for ecological transition). # Short introduction to lczexplore The purpose of this package is to easily compare different local climate zone (LCZ) classifications on the same study territory. For these LCZ, the `repr="standard"` representation sets proper levels and colors by default. You can read the `lczexplore_english` vignette for an overview. This vignette deals with other cases, when `repr="alter"`, that is: - when one groups LCZ levels into broader categories, - when LCZ levels are expressed in an unexpected format, - or even compares maps of other qualitative variables. # Grouping levels and exploring the resulting broader categories The package `lczexplore ` allows to group several Local Climate Zone levels (LCZ) into broader categories . The `groupLCZ` function allows this grouping, and the main functions of the package allow to specify the expected levels and colors to use. ## From original data... First, let's load the example data of Redon City. ```{r, import-LCZ-files, echo = TRUE, eval = TRUE} library(lczexplore) dirPath <- system.file("extdata/multipleWfs/Redon", package = "lczexplore") redonOSM <- importLCZvect(dirPath = dirPath, file = "osm_lcz.fgb", column = "LCZ_PRIMARY") redonBDT <- importLCZvect(dirPath = dirPath, file = "bdt_lcz.fgb", column = "LCZ_PRIMARY") # ``` If we compare the LCZ classifications produced with GeoClimate and OpenStreetMAp and French BDTOPO data, we can see they seem to quite disagree. ```{r, comparison, fig.dim = c(8, 6), echo = TRUE, eval = TRUE} comparison <- compareLCZ(sf1 = redonBDT, column1 = "LCZ_PRIMARY", wf1 = "BD TOPO v2.2", sf2 = redonOSM, column2 = "LCZ_PRIMARY", wf2 = "Open Street Map", ref = 1, repr = "standard", exwrite = FALSE, location = "Redon", saveG = "") comparison$pseudoK ``` ## ... to grouped levels But maybe the disagreement is not as strong as it seems. One may want to see, for example, if the urban envelopes differ that much. Let's group all the urban LCZ levels in a category and all the vegetation in another one, the remaining LCZ being their own categories. Use the `groupLCZ` function, set the dataset with the argument `sf` and the column with `column`. Then pass as many vectors as there are grouped category, each of them containing the levels to be grouped together. The newly created categories will be stored in the `outCol` column. If the user doesn't specify any name, by default the column is called `"grouped"`. The newly created dataset can be mapped with `showLCZ` function. At this point, we pass the names of the new categories present in the "grouped" column to an LCZlevels vector and the colors associated as a `colors` vector. ```{r, grouping, fig.dim = c(8, 6), echo = TRUE, eval = TRUE} redonOSMgrouped <- groupLCZ(redonOSM, column = "LCZ_PRIMARY", urban = c("1", "2", "3", "4", "5", "6", "7", "8", "9"), industry = "10", vegetation = c("101", "102", "103", "104"), impervious = "105", pervious = "106", water = "107", colors = c("red", "black", "green", "grey", "burlywood", "blue")) levCol(sf = redonOSMgrouped, column = "grouped", LCZlevels = c("urban", "industry", "vegetation", "impervious", "pervious", "water"), colors = c("red", "black", "green", "grey", "burlywood", "blue")) map1 <- showLCZ(redonOSMgrouped, column = "grouped", repr = "alter", wf = "OSM", LCZlevels = c("urban", "industry", "vegetation", "impervious", "pervious", "water"), colors = c("red", "black", "green", "grey", "burlywood", "blue")) ``` # Compare two LCZ classification with the function compareLCZ and the `alter` representation ## Most common case As for standard LCZ, we use the `compareLCZ` function. We specify the names of the `sf1` and `sf2` objects containing the data, and the names of the `column1` and `column2` containing the newly grouped categories. ```{r, common-grouping-case, fig.dim = c(8, 6), echo = TRUE, eval = TRUE} redonBDTgrouped <- groupLCZ(redonBDT, column = "LCZ_PRIMARY", urban = c("1", "2", "3", "4", "5", "6", "7", "8", "9"), industry = "10", vegetation = c("101", "102", "103", "104"), impervious = "105", pervious = "106", water = "107", colors = c("red", "black", "green", "grey", "burlywood", "blue")) map1.1 <- showLCZ(redonBDTgrouped, column = "grouped", repr = "alter", wf = "OSM", LCZlevels = c("urban", "industry", "vegetation", "impervious", "pervious", "water"), colors = c("red", "black", "green", "grey", "burlywood", "blue")) comparisonGrouped <- compareLCZ(sf1 = redonOSMgrouped, column1 = "grouped", wf1 = "osmGpd", sf2 = redonBDTgrouped, column2 = "grouped", wf2 = "bdtGpd", repr = "alter", levels = c("urban", "industry", "vegetation", "impervious", "pervious", "water"), colors = c("red", "black", "green", "grey", "burlywood", "blue")) ``` There are many cases when one doesn't necessarily know the levels of the qualitative variables, or the colors one wants to choose. One may also want to pair the levels and colors in a way that shows their correspondence. The package allows quite some flexibility to the user, thanks to the `levCol` function. This function is designed to be called by `showLCZ` and `compareLCZ` functions, not by the user, but one can use it to see how the levels and colors are dealt with. It outputs a vector of levels and associated colors, as well as a message, explaining the case it dealt with. Here are some examples. ## Levels specified but colors unspecified When levels don't have a particular meaning, using random colors may be enough. One can specify a single vector of levels and no vector of colors. ```{r, no-color-specified, fig.dim = c(8, 6), echo = TRUE, eval = TRUE} levCol(sf=redonOSMgrouped,column="grouped", levels=c("urban","industry","vegetation","impervious","pervious","water")) redonGroupedCompare<-compareLCZ(sf1 = redonOSMgrouped, column1 = "grouped", sf2 = redonBDTgrouped, column2 = "grouped", repr = "alter", levels = c("urban", "industry", "vegetation", "impervious", "pervious", "water") ) ``` ## Colors specified, but not levels If one knows the number of levels of a qualitative variable but not their names, in an exploratory approach, one can simply specify a vector of preferred colors. In this example, we use the `importQualVar` function to explore a classification other than LCZ, namely the urban territory by random forest (UTRF) classification produced by the GeoClimate workflow. ```{r, colors-but-no-levels, fig.dim = c(8, 6), eval = TRUE, echo = TRUE} utrfRedonBDT <- importQualVar(dirPath = paste0( system.file("extdata", package = "lczexplore"), "/utrfFiles"), file = "bdt_utrf_area.fgb", column = "TYPO_MAJ") summary(utrfRedonBDT) summary(utrfRedonBDT$TYPO_MAJ) map3 <- showLCZ(sf = utrfRedonBDT, column = "TYPO_MAJ", repr = "alter", title = " UTRF classification of the French city of Redon", colors = c("red", "black", "green", "grey", "burlywood", "blue", "orange", "lightgreen", "brown")) ``` ## Case when some of the specified colors are not actually colors One may specify a color wrong, or use a name which is known in a certain environment but not known in R. The `levCol` function will replace it with a color chosen from a standard palette. ```{r, these-are-not-colors, echo = TRUE, eval = TRUE} levCol(sf = utrfRedonBDT, column = "TYPO_MAJ", colors = c("red", "black", "green", "grey", "burlywood", "blue", "orange", "lightgreen", "brown")) levCol(sf = utrfRedonBDT, column = "TYPO_MAJ", colors = c("red", "black", "green", "grey", "burlywood", "blue", "orange", "lightgreen", "NOT_COLOR")) ``` ## Case when provided vectors of levels and colors don't cover the levels of the data Sometimes, the data can include unexpected levels, and the user might not specify them within the level vectors passed to the functions. In those cases, a message is produced to alert the user. For instance, if the user forgets to specify the level "water" of the `redonOSMgrouped` dataset. The levels are then deduced from the data and a random color is added. ```{r, some-data-uncovered, echo = TRUE, eval = TRUE} levCol(sf = redonOSMgrouped, column = "grouped", levels = c("urban", "industry", "vegetation", "impervious", "pervious"), colors = c("red", "black", "green", "grey", "burlywood") ) ``` Sometimes, the vector of levels covers the levels of the data, but the vector of colors doesn't. A random color is then assigned to the last level of vector. ```{r, not-enough-colors, echo = TRUE, eval = TRUE} levCol(sf = redonOSMgrouped, column = "grouped", levels = c("urban", "industry", "vegetation", "impervious", "pervious", "water"), colors = c("red", "black", "green", "grey", "burlywood") ) ``` ```{r, another-case, echo = TRUE, eval = TRUE} levCol(sf = redonOSMgrouped, column = "grouped", levels = c("urban", "industry", "vegetation", "impervious", "pervious"), colors = c("red", "black", "green", "grey", "burlywood", "blue") ) ``` All the cases are not listed in this vignette as the messages are hopefully explicit enough. # A trick to group and compare/show all at once Sometimes, one wants to explore how different grouping of levels from the same original pair of datasets compare. In this case, one can do the grouping and the plotting or comparing in one step. One needs to pass the original column names, the grouping vectors and set the argument`tryGroup=TRUE`. If the values of the grouping vectors cover the original values of the datasets, the function will perform grouping before comparing. ```{r, group-and-compare-on the fly, fig.dim = c(8, 6), echo = TRUE, eval = TRUE} map4 <- showLCZ(sf = redonBDT, column = "LCZ_PRIMARY", repr = "alter", urban = c("1", "2", "3", "4", "5", "6", "7", "8", "9"), industry = "10", vegetation = c("101", "102", "103", "104"), impervious = "105", pervious = "106", water = "107", colors = c("red", "black", "green", "grey", "burlywood", "blue"), tryGroup = TRUE) compareLCZ(sf1 = redonBDT, column1 = "LCZ_PRIMARY", sf2 = redonOSM, column2 = "LCZ_PRIMARY", repr = "alter", ref = 2, saveG = "", exwrite = FALSE, location = "Redon", plot = TRUE, urban = c("1", "2", "3", "4", "5", "6", "7", "8", "9"), industry = "10", vegetation = c("101", "102", "103", "104"), impervious = "105", pervious = "106", water = "107", colors = c("red", "black", "green", "grey", "burlywood", "blue"), tryGroup = TRUE) ``` This is meant as an exploratory tool, as the resulting grouped columns are not actually kept after the analysis. Please feel free to contact us if some cases are not handled by the package.