README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  warning = FALSE,
  message = FALSE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  fig.width = 12, 
  fig.height = 9,
  dev = "ragg_png"
)
```

# d6berlin <img src='man/figures/hexlogo.png' align="right" height="151.5" /></a>

<!-- badges: start -->
<!-- badges: end -->

> The `d6berlin` package aims to provide spatial data and template maps for Berlin. The data sets include green spaces, water bodies, district borders, raleways and more. A template map of imperviousness across Berlin with carefully chosen and aesthetically pleasing default is included to serve as a base map to visualize spatial data.

<br>

#

<br>

## Installation

You can install the `d6berlin` package from GitHub:

```{r install, eval=FALSE}
install.packages("devtools")
devtools::install_github("EcoDynIZW/d6berlin")
```

(Note: If you are asked if you want to update other packages either press "No" (option 3) and continue or update the packages before running the install command again.)

Afterwards, load the functionality and data of the package in each session:

```{r library}
library(d6berlin)
```


<br>

#

<br>

## Berlin Data Sets

The package contains several data sets for Berlin. All of them start with `sf_`, e.g. `d6berlin::sf_roads`. Here is a full overview of the data sets that are stored as *simple feature objects* and directly accessible:

```{text}
sf_berlin      -- Berlin border
sf_districts   -- district borders
sf_green       -- green spaces
sf_metro       -- U- and S-train stations
sf_railways    -- railroad lines
sf_roads       -- motorways and streets
sf_water       -- water ways and bodies
```

```{r datasets, echo=FALSE, fig.show="hold", out.width="33%"}
library(ggplot2)

theme_map <- theme_void() + 
  theme(plot.title = element_text(size = 45, hjust = .5, face = "bold", family = "Roboto Mono"),
        plot.margin = margin(b = 12))

ggplot(d6berlin::sf_berlin) + geom_sf() + ggtitle("d6berlin::sf_berlin") + theme_map
ggplot(d6berlin::sf_districts) + geom_sf() + ggtitle("d6berlin::sf_districts") + theme_map
ggplot(d6berlin::sf_green) + geom_sf(color = "transparent", fill = "grey60") + ggtitle("d6berlin::sf_green") + theme_map
ggplot(d6berlin::sf_metro) + geom_sf() + ggtitle("d6berlin::sf_metro") + theme_map
ggplot(d6berlin::sf_railways) + geom_sf() + ggtitle("d6berlin::sf_railways") + theme_map
ggplot(d6berlin::sf_roads) + geom_sf() + ggtitle("d6berlin::sf_roads") + theme_map
ggplot(d6berlin::sf_water) + geom_sf(color = "transparent", fill = "grey60") + ggtitle("d6berlin::sf_water") + theme_map
```

All spatial data sets are projected in **EPSG 4326 (WGS84)**. More information about each data set is available in the help: 

```{r filter-spatial-data, eval=FALSE}
?sf_green
```

> An sf object containing the shape of all green spaces (defined as natural areas and landuse categories "forest", "grass", "meadow", "nature_reserve", "scrub", "heath", "beach", and "cliff") in Berlin. 

Furthermore, you can work with the spatial data as you usually do:

```{r working-with-data}
unique(sf_green$fclass)

sf_forests <- subset(sf_green, fclass == "forest")
head(sf_forests)
```

#

<br>

## A Basic Template Map of Imperviousness

The basic template map shows levels of imperviousness and green areas in Berlin. The imperviousness raster data was derived from [Geoportal Berlin (FIS-Broker)](https://www.stadtentwicklung.berlin.de/geoinformation/fis-broker/) with a resolution of 10m. The vector data on green spaces was collected from data provided by the [OpenStreetMap Contributors](https://www.openstreetmap.org/). The green spaces consist of a mixture of land use and natural categories (namely "forest", "grass", "meadow", "nature_reserve", "scrub", "heath", "beach", "cliff").

The map is projected in **EPSG 4326 (WGS84)**.

```{r example-basic}
base_map_imp()
```

You can also customize the arguments, e.g. change the color intensity, add a globe with a locator pin, change the resolution of the raster, and move the legend to a custom position:

```{r example-custom}
base_map_imp(color_intensity = 1, globe = TRUE, resolution = 500,
             legend_x = .17, legend_y = .12)
```

If you think the legend is absolute, there is also an option called `"none"`. (The default is `"bottom"`. You can also use of the predefined setting `"top"` as illustrated below or a custom position as shown in the previous example.)

<br>


## Adding Locations to the Map

Let's assume you have recorded some animal locations or you want to plot another information on top of our base map. For example, let's visualize the Berlin metro stations by adding `geom_sf(data = x)` to the `map` object:

```{r example-add-points}
library(ggplot2)
library(sf)

map <- base_map_imp(color_intensity = .3, resolution = 250, legend = "top")

map + geom_sf(data = sf_metro) ## sf_metro is contained in the d6berlin package
```

**Note:** Since the template map contains many filled areas, we recommend to add geometries with variables mapped to `color|xolour|col` to the template maps.

You can, of course, style the appearance of the points as usual:

```{r example-points-custom}
map + geom_sf(data = sf_metro, shape = 8, color = "red", size = 2)
```

It is also possible to filter the data inside the `geom_sf` function — no need to use `subset`: 

```{r example-points-filter}
library(dplyr) ## for filtering
library(stringr) ## for filtering based on name

map + 
  geom_sf(data = filter(sf_metro, str_detect(name, "^U")), 
          shape = 21, fill = "dodgerblue", size = 2) +
  geom_sf(data = filter(sf_metro, str_detect(name, "^S")), 
          shape = 21, fill = "forestgreen", size = 2)
```

You can also use the `mapping` functionality of ggplot2 to address variables from your data set:

```{r example-points-filter-aes, fig.height=10.5}
map + 
  geom_sf(data = sf_metro, aes(color = type), size = 2) +
  scale_color_discrete(type = c("dodgerblue", "forestgreen"), 
                       name = NULL) +
  guides(color = guide_legend(direction = "horizontal",
                              title.position = "top", 
                              title.hjust = .5))
```

(It looks better if you style the legend in the same horizontal layout.)

<br>

#

<br>

## Custom Styling

Since the output is a `ggplot` object, you can manipulate the result as you like (but don't apply a new theme, this will mess up the legend design):

```{r example-styling, fig.height=10.2}
library(systemfonts) ## for title font

base_map_imp(color_intensity = 1, resolution = 250, globe = TRUE,
             legend_x = .17, legend_y = .12) + 
  geom_sf(data = sf_metro, shape = 21, fill = "white", 
          stroke = .4, size = 4) +
  ggtitle("Metro Stations in Berlin") + 
  theme(plot.title = element_text(size = 30, hjust = .5, family = "Bangers"),
        panel.grid.major = element_line(color = "white", size = .3),
        axis.text = element_text(color = "black", size = 8),
        plot.background = element_rect(fill = "#fff0de", color = NA),
        plot.margin = margin(rep(20, 4)))
```

<br>

#

<br>

## Save Map

Unfortunately, the size of the text elements is fixed. The best aspect ratio to export the map is 12x9 and you can save it with `ggsave()` for example:

```{r, eval=FALSE}
ggsave("metro_map.pdf", width = 12, height = 9, device = cairo_pdf)
```

<br>

#

<details><summary>Session Info</summary>

```{r sessionInfo}
Sys.time()
git2r::repository()
sessionInfo()
```

</details>

-----

<br>

#### Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)

<div style="width:300px; height:200px">

<img src=https://camo.githubusercontent.com/00f7814990f36f84c5ea74cba887385d8a2f36be/68747470733a2f2f646f63732e636c6f7564706f7373652e636f6d2f696d616765732f63632d62792d6e632d73612e706e67 alt="" height="42">

</div>