layers.qmd

```{r}
#| echo: false
source("code/before_script.R")
```

# Layers {#sec-layers}

<!-- make sure that the order of the table is consistent with the rest of the chapter! -->
```{r}
#| echo: false
layers_basic_df = tibble::tribble(
  ~Function, ~Element, ~Geometry,
  "tm_polygons()", "polygons (borders and fill)", "polygons",
  "tm_symbols()", "symbols", "points, polygons, and lines", 
  "tm_lines()", "lines", "lines",   
  "tm_text()", "text", "points, polygons, and lines",
  "tm_raster()", "raster", "raster",
  "tm_basemap()", "tile" , "",
  "tm_tiles()", "tile", ""
)
layers_extended_df = tibble::tribble(
  ~Function, ~Element, ~Geometry,
  "tm_borders()", "polygons (borders)", "polygons",
  "tm_fill()", "polygons (fill)", "polygons",
  "tm_bubbles()", "bubbles", "points, polygons, and lines",
  "tm_dots()", "dots", "points, polygons, and lines",
  "tm_markers()", "marker symbols", "points, polygons, and lines",
  "tm_square()", "squares", "points, polygons, and lines",
  "tm_labels()", "text labels", "points, polygons, and lines",
  "tm_labels_highlighted()", "text labels with background", "points, polygons, and lines",
  "tm_iso()", "lines with text labels", "lines",
  "tm_rgb()/tm_rgba()", "raster (RGB image)", "raster"
)
layers_df = rbind(layers_basic_df, layers_extended_df)
```

\index{map layers}
Map layers are the main building blocks of a map.
They specify how the specific data should be visualized -- for example, as polygons, symbols, lines, text labels, or raster.
There is also an interplay between the data and the map layers: raster data can be plotted with the `tm_raster()` or `tm_rgb()` functions, while point data can be visualized with `tm_symbols()`, `tm_dots()`, `tm_bubbles()`, `tm_markers()`, or `tm_squares()`.
Moreover, some data types can be simplified and shown with a different geometry, such as polygons that are usually visualized with `tm_polygons()` but can also be converted into centroids and plotted with `tm_symbols()`.

Each dataset may have one or more map layers, and each layer can be presented in different ways.
For example, a dataset with polygons can be visualized using `tm_polygons()` to display the polygon areas, and then the names of the polygons can be added with `tm_text()`.

@tbl-layers-table shows the available map layers in **tmap**.
They are divided into two groups: basic functions and derived functions.
The basic functions are the main functions for visualizing data, are useful for most cases, and are highly customizable.
The derived functions are built on top of the basic functions but with different default values aimed at specific use cases.

```{r}
#| label: tbl-layers-table
#| tbl-cap: "Available map layers."
#| echo: false
#| warning: false
#| message: false
layers_df |>
  kableExtra::kbl(booktabs = TRUE) |>
  kableExtra::kable_styling("striped",
                            # latex_options = "striped",
                            full_width = FALSE) |>
  kableExtra::pack_rows("Basic functions", 1, 7, color = "white", background = "gray", bold = TRUE) |>
  kableExtra::pack_rows("Derived functions", 8, nrow(layers_df), color = "white", background = "gray", bold = TRUE) |>
  kableExtra::column_spec(1, monospace = TRUE)
```

<!--JN: Idea - add available aesthetics to the above table-->
<!--JN: Idea - also add a simple viz showing different kind of layers here (visual summary)-->

In this chapter, we focus on what map layers are available in **tmap** and how they differ from each other.
@sec-map-variables, on the other hand, is all about how to present information given in variables using colors, sizes, and shapes.

## Polygons {#sec-polygons}

```{r}
#| warning: false
#| message: false
library(tmap)
library(sf)
slo_borders = read_sf("data/slovenia/slo_border.gpkg")
```

\index{polygons}
\index{tm\_polygons}
The main function of visualizing polygons is `tm_polygons()`.
By default, it plots areas of polygons in light gray (`gray85`) and polygons borders in slightly dark gray (`gray25`).
<!-- https://github.com/r-tmap/tmap/blob/master/R/tmap_options.R -->

```{r}
#| eval: false
tm_shape(slo_borders) +
  tm_polygons()
```

Both, colors of areas (polygons' fillings) and colors of borders can be modified using the `fill` and `col` arguments (@fig-tmpolygonsder-1).

```{r}
#| label: tmpolygonsder1
#| eval: false
tm_shape(slo_borders) +
  tm_polygons(fill = "lightblue", col = "black", lwd = 0.5, lty = "dashed")
```

\index{tm\_fill}
In fact, `tm_polygons()` is a combination of two separate functions: `tm_fill()` and `tm_borders()`.
The `tm_fill()` function fills polygons with a fixed color or a color palette representing a selected variable (@fig-tmpolygonsder-2).

```{r}
#| label: tmpolygonsder2
#| eval: false
tm_shape(slo_borders) +
  tm_fill(fill = "lightblue")
```

\index{tm\_borders}
The `tm_borders()` function draws the borders of the polygons only (@fig-tmpolygonsder-3).
It allows you to change the colors of borders, their widths, or the lines type.

```{r}
#| label: tmpolygonsder3
#| eval: false
tm_shape(slo_borders) +
  tm_borders(col = "black", lwd = 0.5, lty = "dashed")
```

```{r}
#| label: fig-tmpolygonsder
#| warning: false
#| echo: false
#| layout-nrow: 3
#| fig-cap: "Example of a map created using tm_polygons() and its derived functions."
#| fig-subcap:
#|   - "tm_polygons()"
#|   - "tm_fill()"
#|   - "tm_borders()"
#| #fig-asp: 0.4
<<tmpolygonsder1>>
<<tmpolygonsder2>>
<<tmpolygonsder3>>
```

More information on colors and how they can be applied and modified is explained in detail in @sec-colors.

## Symbols {#sec-symbols}

```{r}
slo_cities = read_sf("data/slovenia/slo_cities.gpkg")
```

\index{symbols}
Symbols are a versatile type of map layer.
They are usually used to represent point data but can also be used for lines and polygons.
In the latter cases, they are located in the centroid coordinates of each feature.
Their flexibility is also related to the ways symbols can be visualized -- it is possible to show values of a given variable by colors of symbols, their sizes, or shapes (more about that is explained in @sec-map-variables).

\index{tm\_symbols}
The `tm_symbols()` is the main function in **tmap**, allowing to use and modify symbol elements (@fig-tmsymbols1).
By default, this function draws a gray circle symbol with a black border for each element of an input feature.

```{r}
#| label: fig-tmsymbols1
#| warning: false
#| echo: false
#| asp: 0.25
#| fig-cap: A map showing the default tmap symbols.
tm_shape(slo_cities) +
  tm_symbols()
```

In the above example, each symbol is related to one feature (row) in the `slo_cities` object.
However, in a case when we provide multi-element features (such as MULTIPOINT; see @sec-vector-data-model), each multi-element object is first split into a number of single-element features and then plotted.

\index{tm\_squares}
\index{tm\_bubbles}
\index{tm\_dots}
\index{tm\_markers}
The `tm_symbols()` is a very flexible function with a large number of arguments.
While this allows adjusting its results to almost any need, it also makes this function complicated.
Therefore, four additional layers are implemented in **tmap**: `tm_squares()`, `tm_bubbles()`, `tm_dots()`, `tm_markers()`.
All of them use `tm_symbols()`, but with different default values.

`tm_squares()` uses square symbols (`shape = 22`) instead of circles (`shapes = 21`) (@fig-tmsymbols2-1).
<!--scale is 4/3 instead of 1-->
<!-- Martijn, please expand this part -->

```{r}
#| label: tmsymbols21
#| eval: false
tm_shape(slo_cities) +
  tm_squares()
```

<!-- Martijn, what is the main difference between symbols and bubbles?? -->
<!-- Martijn, please expand this part -->
Next, `tm_bubbles()` uses circles with a larger size value than the default one (@fig-tmsymbols2-2).
<!--scale is 4/3 instead of 1-->

```{r}
#| label: tmsymbols22
#| eval: false
tm_shape(slo_cities) +
  tm_bubbles()
```

The main role of `tm_dots()` is to present many locations at the same time.
To do this, this layer has a small size value (`0.02`) at the default (@fig-tmsymbols2-3).

```{r}
#| label: tmsymbols23
#| eval: false
tm_shape(slo_cities) +
  tm_dots()
```

The last additional layer is `tm_markers()`, which uses a marker icon by default (@fig-tmsymbols2-4).

```{r}
#| label: tmsymbols24
#| eval: false
tm_shape(slo_cities) +
  tm_markers()
```

```{r}
#| label: fig-tmsymbols2
#| warning: false
#| echo: false
#| layout-nrow: 2
#| fig-cap: "Maps showing default visualizations using various types of symbols."
#| fig-subcap:
#|   - "tm_squares()"
#|   - "tm_bubbles()"
#|   - "tm_dots()"
#|   - "tm_markers()"
<<tmsymbols21>>
<<tmsymbols22>>
<<tmsymbols23>>
<<tmsymbols24>>
```

In @sec-sizes and @sec-shapes, we learn how to modify the size and shape of symbols, including creating custom shapes.

## Lines {#sec-lines}

```{r}
slo_railroads = read_sf("data/slovenia/slo_railroads.gpkg")
```

\index{lines}
\index{tm\_lines}
The `tm_lines()` function allows the visualization of different types of line data (@fig-tmlines).

```{r}
#| label: fig-tmlines
#| fig-cap: "Example of a map created with tm_lines()."
tm_shape(slo_railroads) + 
  tm_lines()
```

Lines can be presented using different colors, widths, or types (@sec-map-variables).
This allows to show a hierarchy (for example, increased line widths for higher capacity roads) or distinguish between types of objects (for example, blue rivers comparing to gray roads).

## Text {#sec-text}

\index{tm\_text}
\index{tm\_labels}
\index{tm\_labels\_highlighted}
\index{labels}
\index{text}
Text labels are an integral part of many maps.
They can serve several functions, from naming features, indicating relations between them, or representing a given variable's values.
The primary function for creating text labels is `tm_text()`, which adds a label to each spatial feature (@fig-tmtext-1).

```{r}
#| label: tmtext1
#| eval: false
tm = tm_shape(slo_borders) +
  tm_polygons() + 
  tm_shape(slo_cities) +
  tm_dots()
tm +
  tm_text(text = "name")
```

Two additional functions for adding text labels are `tm_labels()` and `tm_labels_highlighted()`.
They are similar to `tm_text()`, but have different defaults.
The `tm_labels()` function is used to add text labels to the map, but also tries to automatically adjust the position of the labels to avoid overlapping with other features (@fig-tmtext-2).

```{r}
#| label: tmtext2
#| eval: false
tm +
  tm_labels(text = "name")
```

The `tm_labels_highlighted()` additionally adds a background color to the labels, which makes them more visible (@fig-tmtext-3).
<!-- explain when to use each one? -->

```{r}
#| label: tmtext3
#| eval: false
tm +
  tm_labels_highlighted(text = "name")
```

```{r}
#| label: fig-tmtext
#| echo: false
#| fig-cap: "Maps with text labels."
#| fig-subcap:
#|   - "tm_text()"
#|   - "tm_labels()"
#|   - "tm_labels_highlighted()"
#| layout-nrow: 3
<<tmtext1>>
<<tmtext2>>
<<tmtext3>>
```

In the above examples, the `text` argument specifies the name of a variable that is used for text labels.
We can further adjust colors (`col`; @sec-colors), sizes (`size`; @sec-sizes), font faces (`fontface`; @sec-ltypography), and background colors (`bgcol`) of labels by providing either a single value or the name of a data variable.

The `tm_text()`, `tm_labels()`, and `tm_labels_highlighted()` functions have many arguments that allow us to adjust the appearance of text labels.
It includes arguments related to the x and y offset of the text labels (`xmod` and `ymod`), and the rotation angle (`angle`).
<!-- any other are worth mentioning? xmod.scale, xmod.legend, xmod.chart, xmod.free, ymod.scale, ymod.legend, ymod.chart, ymod.free	, angle.scale, angle.legend, angle.chart, angle.free		 -->
@fig-tmtext2-1 shows an example of a map with text labels moved a bit to the right and down, and rotated by 12 degrees.

```{r}
#| label: tmtext4
#| eval: false
tm +
  tm_text(text = "name", xmod = 1, ymod = -0.5, angle = 12)
```

Text labels can be further modified with the `opt_tm_text()` function provided to the `options` argument.
It includes a set of arguments that allow for the adjustment of the text labels' appearance, such as `shadow`, `just`, and `remove_overlap` (@fig-tmtext2-2).

```{r}
#| label: tmtext5
#| eval: false
tm +
  tm_text(text = "name", xmod = 1, ymod = -0.5, angle = 12,
          options = opt_tm_text(shadow = TRUE,
                                just = "left",
                                remove_overlap = TRUE))
```

To automatically adjust the position of text labels to avoid overlapping with other features, we can use the `point.label` argument in the `opt_tm_text()` function.
When set to `TRUE`, it use an algorithm to find the best position for each label, which can be useful when there are many overlapping features or when the labels are too close to each other.

```{r}
#| label: tmtext6
#| eval: false
tm +
  tm_text(text = "name", 
          options = opt_tm_text(point.label	= TRUE))
```

```{r}
#| label: fig-tmtext2
#| fig-cap: "Example of a map created with tm_text() with customized options."
#| fig-subcap:
#|   - "with x and y offsets and rotation angle"
#|   - "with shadow and left justification"
#|   - "with point.label = TRUE"
#| echo: false
#| layout-nrow: 3
<<tmtext4>>
<<tmtext5>>
<<tmtext6>>
```

<!-- on_surface -->
<!-- clustering -->

Text labels can be added to spatial (multi-)points, (multi-)lines, and (multi-)polygons, and each case is quite different.
The simplest case is for POINT data, for which each text label is located precisely in the coordinates of the given points (@fig-tmtext).
However, how to add text labels to multipoints, lines, multilines, polygons, or multipolygons?
Should each label correspond to one spatial feature, or should every sub-feature have its own label? 
Where should the labels be placed for lines or polygons -- in the center of a line and the centroid of a polygon, or somewhere else?
The above decisions can be made with the `options` argument of the `tm_text()` function.
By default, text labels are placed in the centroid of each feature; however, we can change this behavior with the `point_per` argument.
The possible options are `"feature"` (default), `"segment"`, and `"largest"`. 
The `"segment"` option labels each subfeature (e.g, each point in a multipoint, each segment in a multilines, and each polygon in a multipolygon) and the `"largest"` option labels only the largest subfeature (e.g., the largest segment in a multilines or the largest polygon in a multipolygon).

Text labels are also often presented together with lines (@sec-lines).
One example is an isopleth -- a line drawn on a map through all points with the same value of a given variable, such as atmospheric pressure or elevation.
Isopleths can be created with the `tm_iso()` function.
This function combines `tm_lines()` and `tm_text()`, where text labels are placed on the isopleths along the lines.
In the example below, we create contour lines (isopleths) from the elevation raster data of Slovenia, and then we plot them on the map with text labels (@fig-tmiso).

```{r}
#| label: fig-tmiso
#| fig-cap: "Example of a map created with tm_iso() showing contour lines with text labels."
#| message: false
library(terra)
slo_elev = rast("data/slovenia/slo_elev.tif")
slo_contours = as.contour(slo_elev, nlevels = 4)
tm_shape(slo_borders) +
  tm_borders() + 
  tm_shape(slo_contours) +
  tm_iso()
```

## Raster {#sec-raster-layer}

```{r}
#| message: false
library(terra)
slo_elev = rast("data/slovenia/slo_elev.tif")
slo_gm = rast("data/slovenia/slo_gm.tif")
```

\index{raster}
\index{tm\_raster}
Visualization of raster data depends on the raster type (continuous or categorical), its resolution, and the number of layers.
@fig-rastertype shows two simple examples of continuous and categorical raster visualizations created with `tm_raster().`
<!-- This function attempts to recognize the type of a given raster -- when the input raster is continuous then the pretty style is used (@fig-rastertype-1). -->

```{r}
#| label: rastertype1
#| eval: false
tm_shape(slo_elev) +
  tm_raster()
```

<!-- However, the continuous scale (`tm_scale_continuous()`) may better represent phenomena that progressively vary in space -- as you can see in @sec-continuous-scales. -->

<!-- On the other hand, when the given raster is categorical, then `tm_raster()` uses `tm_scale_categorical()` automatically (@fig-rastertype-2). -->

```{r}
#| label: rastertype2
#| eval: false
tm_shape(slo_gm) +
  tm_raster()
```

```{r}
#| label: fig-rastertype
#| echo: false
#| message: false
#| layout-nrow: 1
#| fig-cap: "Examples of raster maps."
#| fig-subcap:
#|   - "continuous raster map"
#|   - "categorical raster map"
current_options = tmap_options()
tmap_options(scale = 1.2)
<<rastertype1>>
<<rastertype2>>
tmap_options(current_options)
```

<!-- We can also adjust the legend title, used colors, and many more, in a similar fashion as in the previously mentioned layers. -->

The above examples uses a raster with one layer only.
However, rasters can have many layers, either represented by layers from the **terra** package or dimensions and attributes from the **stars** package.
By default, **tmap** shows all of the layers, where each raster has its own legend.

```{r}
#| results: hide
#| message: false
#| fig-show: hide
raster2 = c(slo_elev, slo_gm)
tm_shape(raster2) +
  tm_raster()
```

We can modify their arrangement with `tm_facets()` (@fig-tmrasterml).

```{r}
#| label: fig-tmrasterml
#| message: false
#| fig-cap: "A map created from a multilayered raster."
#| fig-asp: 0.8
tm_shape(raster2) +
  tm_raster() +
  tm_facets(ncol = 1) +
  tm_layout(panel.labels = c("Elevation", "Geomorphons"))
```

If you want to learn more -- we focus on  how to modify map layout in @sec-map-layout and how to specify and modify facets (also known as small multiples) in @sec-facets.

<!-- raster.warp -->
<!-- raster margins -->

## Tile {#sec-tile-layer}

<!-- here or in the separate view mode chapter? -->

\index{tile layer}
\index{basemaps}
A tile layer is a type of map layer that consists of prerendered raster tiles or vector tiles, usually on online servers.
These tiles are organized in a hierarchical grid structure, where each tile corresponds to a specific geographic area at a specific zoom level.
Thus, depending on the spatial extent of the data, we use different zoom levels to show more or less details.

\index{tm\_basemap}
\index{tile providers}
Tile layers can be used for two purposes: either as a basemap or an overlay layer.
By default, three basemaps are used in the interactive mode (`tmap_mode("view")`): 
`"Esri.WorldGrayCanvas"`, `"OpenStreetMap"`, and  `"Esri.WorldTopoMap"`.
However, we can change the basemaps with a vector with the names of the tile layers' providers to the `tm_basemap()` function (@fig-tmbasemap1).

```{r}
#| eval: false
tmap_mode("view")
tm_basemap(c(StreetMap = "OpenStreetMap", TopoMap = "OpenTopoMap")) +
  tm_shape(slo_cities, is.main = TRUE) + 
  tm_symbols()
```

```{r}
#| label: fig-tmbasemap1
#| cache: false
#| eval: true
#| echo: false
#| message: false
#| fig-cap: "OpenStreetMap tile layer used as a base map with symbols representing cities in Slovenia."
library(tmap)
tmap_mode("view")
tmbasemap1 = tm_basemap(c(StreetMap = "OpenStreetMap", TopoMap = "OpenTopoMap")) +
  tm_shape(slo_cities, is.main = TRUE) + 
  tm_symbols()
view_map(tmbasemap1, "tmbasemap1")
```

In the above code, we made two basemaps available: `"OpenStreetMap"` and `"OpenTopoMap"`, and for the map legend purpose, we renamed them as `StreetMap` and `TopoMap`.
A complete list of available basemaps is in the `leaflet::providers` object and on the https://leaflet-extras.github.io/leaflet-providers/preview/ website^[Additional details can be found in the `leaflet::providers.details` object].
The `tm_basemap(NULL)` function allows to disable basemaps entirely. 
<!-- some more advanced ideas: -->
<!-- explain why some providers do not work -->
<!-- ?do we need to register somewhere?: -->
<!-- https://github.com/leaflet-extras/leaflet-providers -->
<!-- how to add url tiles -->
<!-- how to setup your own server or some references? -->

\index{overlay layers}
The `tm_tiles()` function, on the other hand, draws the tile layer on the top (as an overlay layer) of the previous `tm_` layer.
In the next example, we put the vector `"CartoDB.PositronOnlyLabels"` tiles on top of the previously set basemaps, but below the dots layer (@fig-tmtiles1).

```{r}
#| eval: false
tm_basemap(c(StreetMap = "OpenStreetMap", TopoMap = "OpenTopoMap")) +
  tm_tiles(c(CartoDB = "CartoDB.PositronOnlyLabels")) +
  tm_shape(slo_cities, is.main = TRUE) + 
  tm_symbols()
```

```{r}
#| label: fig-tmtiles1
#| cache: false
#| echo: false
#| message: false
#| fig-cap: "OpenStreetMap tile layer used as a base map with CartoDB tiles on top and symbols representing cities in Slovenia."
tmtiles1 = tm_basemap(c(StreetMap = "OpenStreetMap", TopoMap = "OpenTopoMap")) +
  tm_tiles(c(CartoDB = "CartoDB.PositronOnlyLabels")) +
  tm_shape(slo_cities, is.main = TRUE) + 
  tm_symbols()
view_map(tmtiles1, "tmtiles1")
```

Tile layers are usually created to be used interactively.
We can see it, for example, by the number of details varying depending on the zoom level we set.
That being said, many people find them useful also for static maps, and **tmap** allows us to use them in this way.
It uses the **maptiles** package internally to download the tiles and then plot them as a raster layer.

A complete list of available providers and some [information about zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels) are in the help file of the `?maptiles::get_tiles()` function.
Different map tiles providers offer unique map styles, while zoom levels relate to different levels of detail -- the larger level, the more details we get.

When using map tiles, we should also consider adding their attribution to the map.
Attribution for each provider can be obtained using the `maptiles::get_credit()` function by specifying the provider name, for example, `get_credit("CartoDB.VoyagerNoLabels").`

The code below plots the `"CartoDB.VoyagerNoLabels"` tiles in the background, adds the island outline in light blue color, and puts attribution text in the bottom right corner of the map (@fig-stiles)).

```{r}
#| label: fig-stiles
#| cache: false
#| fig-cap: 'Example of a static map using a downloaded `"CartoDB.VoyagerNoLabels"` tile layer.'
tmap_mode("plot")
tm_basemap("CartoDB.VoyagerNoLabels") + 
  tm_shape(slo_borders) +
  tm_borders(lwd = 5, col = "lightblue") +
  tm_credits(maptiles::get_credit("CartoDB.VoyagerNoLabels"),
             bg.color = "white")
```