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.

library(lczexplore)
dirPath<-paste0(system.file("extdata",package="lczexplore"),"/")
dirPathOSM<-paste0(dirPath,"osm/2022/Redon")
dirPathBDT<-paste0(dirPath,"bdtopo_2_2/Redon")
redonOSM<-importLCZvect(dirPath=dirPathOSM,file="rsu_lcz.geojson",column = "LCZ_PRIMARY")
redonBDT<-importLCZvect(dirPath=dirPathBDT,file="rsu_lcz.geojson",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.


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=F,location="Redon",saveG="")
#>  The column  LCZ_PRIMARY  of the dataset redonBDT is the reference against which the  LCZ_PRIMARY  column of the dataset  redonOSM will be compared.
#> Both sf datasets need to live in the same crs projection (srid / epsg),
#> they will be coerced to the specified reference (redonBDT)
#> Warning: attribute variables are assumed to be spatially constant throughout
#> all geometries

#> Warning: attribute variables are assumed to be spatially constant throughout
#> all geometries

plot of chunk unnamed-chunk-3

comparison$pseudoK
#> [1] 0.4247418

… 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.

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"))
#> [1] "redonOSMgrouped"
#> One vector of levels, one vector of colors, either the same length (case 9: and 10:), or colors longer (case 12:, unused colors were dropped),
#>          reduced to  4: & 5: A single vector was provided, whose names cover the levels in the data (values are expected to be colors).

plot of chunk unnamed-chunk-4

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.


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"))

comparisonGrouped<-compareLCZ(sf1=redonOSMgrouped,column1="grouped",
sf2=redonBDTgrouped, column2="grouped",
repr="alter",
levels=c("urban","industry","vegetation","impervious","pervious","water"),
colors=c("red","black","green","grey","burlywood","blue"))
#>  The column  grouped  of the dataset redonOSMgrouped is the reference against which the  grouped  column of the dataset  redonBDTgrouped will be compared.
#> Both sf datasets need to live in the same crs projection (srid / epsg),
#> they will be coerced to the specified reference (redonOSMgrouped)
#> Warning: attribute variables are assumed to be spatially constant throughout
#> all geometries

#> Warning: attribute variables are assumed to be spatially constant throughout
#> all geometries

plot of chunk unnamed-chunk-5

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.

levCol(sf=redonOSMgrouped,column="grouped",
       levels=c("urban","industry","vegetation","impervious","pervious","water"))

compareLCZ(sf1=redonOSMgrouped,column1="grouped",
sf2=redonBDTgrouped, column2="grouped",
repr="alter",
levels=c("urban","industry","vegetation","impervious","pervious","water")
)
#>  The column  grouped  of the dataset redonOSMgrouped is the reference against which the  grouped  column of the dataset  redonBDTgrouped will be compared.
#> Both sf datasets need to live in the same crs projection (srid / epsg),
#> they will be coerced to the specified reference (redonOSMgrouped)
#> Warning: attribute variables are assumed to be spatially constant throughout
#> all geometries

#> Warning: attribute variables are assumed to be spatially constant throughout
#> all geometries

plot of chunk unnamed-chunk-6

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.

utrfRedonBDT<-importQualVar(dirPath=paste0(
  system.file("extdata", package = "lczexplore"), "/bdtopo_2_2/Redon"),
                            file="rsu_utrf_area.geojson", column="TYPO_MAJ")
#> Reading query `select * from rsu_utrf_area limit 0'
#> from data source `/tmp/RtmpOcck5X/Rinstef0a33b0f7ee/lczexplore/extdata/bdtopo_2_2/Redon/rsu_utrf_area.geojson' 
#>   using driver `GeoJSON'
#> Simple feature collection with 0 features and 12 fields
#> Bounding box:  xmin: NA ymin: NA xmax: NA ymax: NA
#> Projected CRS: RGF93 v1 / Lambert-93
#> Reading layer `rsu_utrf_area' from data source 
#>   `/tmp/RtmpOcck5X/Rinstef0a33b0f7ee/lczexplore/extdata/bdtopo_2_2/Redon/rsu_utrf_area.geojson' 
#>   using driver `GeoJSON'
#> Simple feature collection with 1553 features and 12 fields
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: 316325.7 ymin: 6738046 xmax: 321773.5 ymax: 6743279
#> Projected CRS: RGF93 v1 / Lambert-93
summary(utrfRedonBDT)
#>      ID_RSU        TYPO_MAJ   UNIQUENESS_VALUE            geometry  
#>  Min.   :  32   pd     :174   Min.   :0.000065   POLYGON      :433  
#>  1st Qu.: 768   ba     : 70   1st Qu.:0.385894   epsg:2154    :  0  
#>  Median :1066   local  : 44   Median :0.785246   +proj=lcc ...:  0  
#>  Mean   :1115   icio   : 34   Mean   :0.678903                      
#>  3rd Qu.:1514   pcio   : 26   3rd Qu.:1.000000                      
#>  Max.   :2126   psc    : 25   Max.   :1.000000                      
#>                 (Other): 60
summary(utrfRedonBDT$TYPO_MAJ)
#>    ba local    pd   psc  pcio  icio    id  pcif  icif 
#>    70    44   174    25    26    34    24    14    22

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"))
#> [1] "utrfRedonBDT"
#> 2: No level vector, but a color vector which size covers the number of levels in the data.

plot of chunk unnamed-chunk-7

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.

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.

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.

levCol(sf=redonOSMgrouped,column="grouped",
       levels=c("urban","industry","vegetation","impervious","pervious","water"),
       colors=c("red","black","green","grey","burlywood")
)

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 argumenttryGroup=TRUE. If the values of the grouping vectors cover the original values of the datasets, the function will perform grouping before comparing.


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)
#> [1] "redonBDT"
#> Level names in your 1st dataset didn't match original data.
#>       As tryGroup=TRUE, the function groupLCZ will try to create a "grouped" column with level names and levels specified in (...).
#>       If this doesn't work, compareLCZ function may fail.
#> Case 14: with at least a color or 15:, or 17: or 18:, then reduced to  Case one vector of levels, one of colors, the vector of colors being shorter, some colors were picked, case 11:, reduced to  4: & 5: A single vector was provided, whose names cover the levels in the data (values are expected to be colors). your may want to check your vector of colors

plot of chunk unnamed-chunk-12



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)
#>  The column  LCZ_PRIMARY  of the dataset redonBDT is the reference against which the  LCZ_PRIMARY  column of the dataset  redonOSM will be compared.
#> Both sf datasets need to live in the same crs projection (srid / epsg),
#> they will be coerced to the specified reference (redonOSM)
#> Level names in your 1st dataset didn't match original data.
#>       As tryGroup=TRUE, the function groupLCZ will try to create a "grouped" column with level names and levels specified in (...).
#>       If this doesn't work, compareLCZ function may fail.
#> As tryGroup=TRUE, the function groupLCZ will try to create a "grouped" column with level names and levels specified in (...).
#>       If this doesn't work, compareLCZ function may fail.
#> Warning: attribute variables are assumed to be spatially constant throughout
#> all geometries

#> Warning: attribute variables are assumed to be spatially constant throughout
#> all geometries

plot of chunk unnamed-chunk-12 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.

lczexplore_alter

Matthieu Gousseff

2023-10-25

Short introduction to lczexplore

Grouping levels and exploring the resulting broader categories

From original data…

… to grouped levels

Compare two LCZ classification with the function compareLCZ and the `alter` representation

Most common case

Levels specified but colors unspecified

Colors specified, but not levels

Case when some of the specified colors are not actually colors

Case when provided vectors of levels and colors don’t cover the levels of the data

A trick to group and compare/show all at once

lczexplore_alter

Matthieu Gousseff

2023-10-25

Short introduction to lczexplore

Grouping levels and exploring the resulting broader categories

From original data…

… to grouped levels

Compare two LCZ classification with the function compareLCZ and the alter representation

Most common case

Levels specified but colors unspecified

Colors specified, but not levels

Case when some of the specified colors are not actually colors

Case when provided vectors of levels and colors don’t cover the levels of the data

A trick to group and compare/show all at once

Compare two LCZ classification with the function compareLCZ and the `alter` representation