map-components.qmd

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

# Map components {#sec-map-components}

```{r}
#| echo: false
attr_layers_df = tibble::tribble(
  ~Function, ~Description,
  "tm_grid()", "draws coordinate grid lines of the coordinate system of the main shape object",
  "tm_graticules()", "draws latitude and longitude graticules", 
  "tm_scalebar()", "adds a scale bar", 
  "tm_compass()", "adds a compass rose (north arrow)", 
  "tm_credits()", "adds a text annotation",
  "tm_xlab()", "adds an x axis labels", 
  "tm_ylab()", "adds an y axis labels",
  "tm_logo()", "adds a logo",
  # "tm_inset", "adds an inset map or plot",
  "tm_minimap()", "adds minimap"
)
```

\index{map components}
Map components are visual elements that are not directly related to the data-driven map layers, while providing additional information or context to the map.
They are not tied to the map's coordinates but rather to the map's layout and design.
@tbl-attr-layers-table shows the list of available map components in **tmap**.
It includes functions that draw coordinate grid lines, latitude and longitude graticules, scale bars, north arrows, text annotations, logos, axis labels, and minimaps.
We cover and demonstrate these functions in the following sections.

```{r}
#| label: tbl-attr-layers-table
#| tbl-cap: "Map components in **tmap**."
#| echo: false
#| warning: false
attr_layers_df |>
  kableExtra::kbl(booktabs = TRUE) |>
  kableExtra::kable_styling("striped",
                            latex_options = "striped", 
                            full_width = FALSE) |> 
  kableExtra::column_spec(1, width = "4cm", monospace = TRUE) |>
  kableExtra::column_spec(2, width = "8cm")
```

For the examples in this section, we use a simple map of the Slovenia polygon (not shown).

```{r}
#| message: false
#| fig-show: "hide"
library(tmap)
library(sf)
slo_borders = read_sf("data/slovenia/slo_border.gpkg")
tm = tm_shape(slo_borders) +
  tm_polygons()
tm
```

## Grid lines {#sec-grid-lines}

\index{grid lines}
\index{graticules}
\index{tm\_grid}
\index{tm\_graticules}
The **tmap** package offers two ways to draw coordinate lines: `tm_grid()` and `tm_graticules()`.
The role of `tm_grid()` is to represent the input data’s coordinates.
For example, the `slo_borders` object's CRS is ETRS89-extended / LAEA Europe with the units in meters (@fig-grids-1), and thus the grid lines are in meters.

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

`tm_graticules()`, on the other hand, always shows longitude lines (meridians) and latitude lines (parallels), with degrees as units.
This can be seen with the degree signs in the labels (@fig-grids-2).

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

Both `tm_grid()` and `tm_graticules()` can be placed above or below the map layers, as their position on the map depends on their place in the code.
When they are placed after the map layer (e.g., `tm_polygons()`), the grid lines are plotted on top of the map. 
On the other hand, when `tm_grid()` or `tm_graticules()` is placed before the map layer code, the grid lines are plotted behind the spatial data (@fig-grids-3).

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

Grids and graticules can also be easily customized using several arguments, such as, `x` and `y` (x and y coordinates of the lines), `n.x` and `n.y` (number of horizontal (x) and vertical (y) lines),  `labels.inside.frame`, `ticks`, `lines`
It is also possible to customize their appearance, for example, by changing the colors of the lines (`col`), width (`lwd`), or labels' sizes (`labels.size`).

```{r}
#| label: fig-grids
#| echo: false
#| layout-nrow: 3
#| fig-cap: "Examples of grid lines and graticules."
#| fig-subcap:
#|   - grid lines
#|   - graticules
#|   - graticules behind the map layer
<<grid1>>
<<grid2>>
<<grid3>>
```

## Scale bar {#sec-scale-bar}

\index{scale bar}
\index{tm\_scalebar}
A scale bar is a graphic indicator of the relation between a distance on a map and the corresponding distance in the real world.
Nowadays, it is more often used than a traditional representative fraction (e.g., 1:10000).
Compared to the representative fraction, scale bars work correctly on variable screen sizes or different print sizes, as their sizes change together with the rest of the map. 

The `tm_scalebar()` function adds a scale bar.
<!-- Martijn, please check and update the below statement:  -->
By default, it tries to create a scale bar with the width of 1/4 of the whole map, and fills it with several breaks.
It is possible, however, to manually update the values of scale bar's breaks with the `breaks` argument and its size with the `text.size` argument (@fig-scalebar).

```{r}
#| label: fig-scalebar
#| fig-cap: A map with a customized scale bar.
tm +
  tm_scalebar(breaks = c(0, 15, 30), text.size = 1)
```

The `tm_scalebar()` also has several additional arguments, allowing for modification of its colors and position.

Importantly, the scale bar is accurate, depending on a map projection, at standard points or lines only (@sec-proj-types) -- it is never completely correct across the whole map.
The scale bar distortion increases with the true size of the area we are mapping -- it is less visible on local maps, and very prominent on global maps.
For example, try to add a scale bar to a world map seen in the @sec-shapes-and-layers.
The created scale bar are accurate for the equator, but less and less correct going to the north and south poles.

```{r}
#| echo: false
#| eval: false
library(stars)
library(tmap)
worldelevation = read_stars("data/worldelevation.tif")
tm_shape(worldelevation) +
  tm_raster("worldelevation.tif", 
            col.scale = tm_scale(values = terrain.colors(8))) +
  tm_scalebar()
```

## North arrow {#sec-north-arrow}

\index{north arrow}
\index{compass rose}
\index{tm\_compass}
North arrow, also known as a map compass or a compass rose, is a prominent orientation indicator pointing to which way is north^[Orientation may also be shown by graticule or grid lines (@sec-grid-lines).].
The decision on whether to use north arrows or not usually requires some critical thinking.
While, it can be added to every map, north arrows are not always necessary -- especially on maps of large areas (e.g., continents), where the cardinal directions are obvious for most people.
The north arrow is, however, necessary when the north on the map is offset (rotated) and recommended when we want to help orient the map readers. 

We can use the `tm_compass()` function to add the north arrow (@fig-northarrow). 
By default, its *north* is oriented toward the top of the map (the `north` argument of `0`), and the north arrow is represented by an actual arrow (the `type` argument of `"arrow"`).

```{r}
#| label: fig-northarrow
#| fig-cap: "A map with customized north arrow."
tm +
  tm_compass(type = "4star", size = 2, position = c("left", "top"))
```

**tmap** also offers a few other north arrow types, including `"arrow"`, `"4star"`, `"8star"`, `"radar"`, and `"rose"` (@fig-compasses).
The north arrow can be further customized with the `size`, `show.labels`, and `cardinal.directions` arguments, and its colors may be modified (`text.color`, `color.dark`, `color.light`) (@fig-northarrow).
The location of the north arrow, by default, is placed automatically, but can also be changed using the `position` argument (@sec-positions).

```{r}
#| label: fig-compasses
#| fig-cap: "North arrow types."
#| echo: false
#| message: false
#| fig-width: 9
#| fig-asp: 0.22
library(tmap)
data("World")
tm_comp = tm_shape(World) +
    tm_borders(col_alpha = 0) +
    tm_credits('"arrow"', group_id = 1, z = 1, size = 1) +
    tm_compass(type = "arrow", group_id = 1, z = 2, size = 5) + 
    tm_credits('"4star"', group_id = 2, z = 1, size = 1) +
    tm_compass(type = "4star", group_id = 2, z = 2, size = 5) +
    tm_credits('"8star"', group_id = 3, z = 1, size = 1) +
    tm_compass(type = "8star", group_id = 3, z = 2, size = 5) +
    tm_credits('"radar"', group_id = 4, z = 1, size = 1) +
    tm_compass(type = "radar", group_id = 4, z = 2, size = 5) +
    tm_credits('"rose"', group_id = 5, z = 1, size = 1) +
    tm_compass(type = "rose", group_id = 5, z = 2, size = 5) +
    tm_components(1, position = tm_pos_in(0.0, 0.75, just.h = "left", align.h = "center")) +
    tm_components(2, position = tm_pos_in(0.2, 0.75, just.h = "left", align.h = "center")) +
    tm_components(3, position = tm_pos_in(0.4, 0.75, align.h = "center")) +
    tm_components(4, position = tm_pos_in(0.6, 0.75, align.h = "center")) +
    tm_components(5, position = tm_pos_in(0.8, 0.75, align.h = "center")) +
    tm_layout(frame = FALSE, inner.margins = 0)
tm_comp
```

The `position` argument also works in the same way in other functions, such as `tm_scalebar()`, `tm_credits()`, `tm_logo()`, and in some of the `tm_layout()` arguments: `legend.position`, `title.position`, or `chart.position`.

## Text annotation {#sec-text-annotation}

\index{text annotation}
\index{map credits}
\index{tm\_credits}
Text annotations, also known as map credits, are used to store additional information about the created map.
They can include the source of data, the name of the author, the date of map creation, or information about the map projection.
Text annotations are created with the `tm_credits()` function, which can be used one or more times in the same map (@fig-credits).

```{r}
#| label: fig-credits
#| fig-cap: "A map with placeholders for text annotations."
tm +
  tm_credits("Data source: ", fontface = "italic") +
  tm_credits("Author: ", fontface = "bold")
```

The first argument of `tm_credits()` is the text, which can be spread over multiple lines with the line break symbol `\n`.
When the created map has several facets (@sec-facets), it is also possible to provide each facet with a different text.
In that case, a vector of characters is expected, where you can use `""` to omit the credits for specific facets.
Text annotations can also be further customized by changing their sizes (`size`), colors (`color`), positions, and fonts (@sec-fonts-on-maps).

## Axis labels {#sec-axis-labels}

\index{axis labels}
\index{tm\_xlab}
\index{tm\_ylab}
The `tm_xlab()` and `tm_ylab()` functions add x and y-axis labels to the map (@fig-axis-labels).
These labels can be used to describe the coordinates of the map, such as longitude and latitude, or faceting variables (@sec-customizing-facets).

```{r}
#| label: fig-axis-labels
#| fig-cap: A map with x and y axis labels.
tm +
  tm_xlab("X coordinates") +
  tm_ylab("Y coordinates")
```

By default, the x and y-axis labels are placed at the bottom and left sides of the map, respectively, in a horizontal orientation.
The additional arguments of these functions allow changing the labels' size, color, rotation, space between the labels and the map, and their side.

## Logo {#sec-logo}

\index{logo}
\index{tm\_logo}
Logos on maps can serve a similar purpose as text annotation or accompany them.
They can represent your affiliation, funding institution, data sources, logos, etc.
The `tm_logo()` function adds PNG images, either from a file or URL, to the map (@fig-logos).

```{r}
#| label: fig-logos
#| fig-cap: "A map with an array of R logos."
tm +
  tm_logo("https://www.r-project.org/logo/Rlogo.png",
          height = 2) +
  tm_logo(c("https://www.r-project.org/logo/Rlogo.png",
            "https://www.r-project.org/logo/Rlogo.png"),
          height = 1)
```

There are two ways to use multiple logos.
Many `tm_logo()` functions place logos on top of each other, while providing a vector of PNG files will show them next to each other.
Additional arguments include the height of the logo (`height`, the width is scaled automatically) and its position (`position`).

## Minimap {#sec-minimap}

\index{minimap}
\index{tm\_minimap}
The minimap is a small overview map that shows the extent of the main map within a larger context.
The `tm_minimap()` function adds a minimap of a globe to the main map, as illustrated in @fig-minimap. 

```{r}
#| label: fig-minimap
#| fig-cap: "A map with a minimap."
tm + 
  tm_minimap()
```

The `tm_minimap()` function is simple and straightforward, but does not offer too many customization options.
If you want to create a more advanced minimap, you can use the `tm_inset()` function, which is described in @sec-inset-maps.