XX-attr-layers.qmd

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

# Attributes layers {#sec-attributes-layers}

```{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", 
  "tm_credits()", "adds a text annotation", 
  "tm_logo()", "adds a logo",
  "tm_xlab()", "adds an x axis labels", 
  "tm_ylab()", "adds an y axis labels",
  "tm_minimap()", "adds minimap in the view mode only"
)
```

<!-- intro about attribute layers -->
@tbl-attr-layers-table

```{r}
#| label: tbl-attr-layers-table
#| echo: false
#| warning: false
tinytable::tt(attr_layers_df, caption = "Attribute layers.") |>
  tinytable::style_tt(j = 1, monospace = TRUE)
# library(magrittr)
# library(kableExtra)
# options(kableExtra.html.bsTable = TRUE)
# knitr::kable(attr_layers_df, 
#              caption = "Attribute layers.",
#              caption.short = "Attribute layers.",
#              booktabs = TRUE) |>
#   kableExtra::kable_styling("striped",
#                             latex_options = "striped", 
#                             full_width = FALSE) |> 
#   kableExtra::column_spec(1, bold = TRUE, monospace = TRUE)
```

```{r}
#| message: false
library(tmap)
library(sf)
ei_borders = read_sf("data/easter_island/ei_border.gpkg")
ei_points = read_sf("data/easter_island/ei_points.gpkg")
volcanos = subset(ei_points, type == "volcano")
```

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

```{r}
#| fig-show: hide
tm = tm_shape(ei_borders) +
  tm_polygons()
tm
```

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

The **tmap** package offers two ways to draws coordinate lines - `tm_grid()` and `tm_graticules()`.
The role of `tm_grid()` is to represent the input data’s coordinates.
For example, the `ei_borders` object's CRS is UTM zone 12S with the units in meters (@fig-grids-1), and thus the grid lines are in meters.

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

`tm_graticules()` 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(ei_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 `tm_grid()` or `tm_graticules()` is placed after the map layer (e.g., `tm_polygons()`), the grid lines are plotted on the 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(ei_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-ncol: 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}

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.
<!-- 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, 1, 2), text.size = 1)
```

The `tm_scalebar()` also has several additional arguments, allowing to modify its colors, and position (@sec-north-arrow).

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. <!--toDo we need to add an explanation what are standard points and lines in the second chapter!!-->
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 will be 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}

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. 
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"`).
**tmap** offers also a few other north arrow types, including `"4star"` (@fig-northarrow), `"8star"`, `"radar"`, and `"rose"`.
The north arrow can be also 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).

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

The location of the north arrow, by default, is placed automatically, but can also be changed using the `position` argument.
<!-- to update -->
<!-- It expects a vector of two values, specifying the x and y coordinates. -->
<!-- The x coordinate can be set with `"left"`, `"LEFT"`, `"center"`, `"right"`, or `"RIGHT"`, while the y coordinate uses `"top"`, `"TOP"`, `"center"`, `"bottom"`, or `"BOTTOM"`. -->
<!-- The arguments with all letters uppercase result in a position closer to the map frame (without margins). -->
<!-- Alternatively, `position` can be specified with numeric values between 0 and 1 representing the x and y value of the left bottom corner of the north arrow. -->

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}

<!-- Text on maps serves many purposes - some are related to spatial objects (e.g., text labels, section \@ref(text)), while other are used to inform the map reader about the presented content (e.g., map title, section \@ref(layout-elements)). -->
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 more than one time (@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-multiples), it is also possible to provide each facet 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).

## Logo {#sec-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 will places 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`).

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

```{r}
tm +
  tm_xlab("X") +
  tm_ylab("Y")
```

<!-- when this is useful? -->

## Minimap {#sec-minimap}

```{r}
tmap_mode("view")
```

```{r}
tm + 
  tm_minimap()
```

<!-- mention/reference inset maps -->

```{r}
tmap_mode("plot")
```