---
title: "Maps and plots with ColOpenData"
output: 
  rmarkdown::html_vignette:
    df_print: tibble
vignette: >
  %\VignetteIndexEntry{Maps and plots with ColOpenData}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = identical(tolower(Sys.getenv("NOT_CRAN")), "true")
)
```

::: {style="text-align: justify;"}
**ColOpenData** can be used to access open geospatial data from Colombia. This data is retrieved from the National Geostatistical Framework (MGN), published by the National Administrative Department of Statistics (DANE). The MGN contains the political-administrative division and is used to reference census statistical information.

This package contains the 2018's version of the MGN, which also included a summarized version of the National Population and Dwelling Census (CNPV) in different aggregation levels. Each level is stored in a different dataset, which can be retrieved using the `download_geospatial()` function, which requires three arguments:

-   `spatial_level` character with the spatial level to be consulted
-   `simplified` logical for indicating if the downloaded spatial data should be a simplified version of the geometries. Simplified versions are lighter but less precise, and are recommended for easier applications like plots. Default is \code{TRUE}.
-   `include_geom` logical for including (or not) geometry. Default is `TRUE`
-   `include_cnpv` logical for including (or not) CNPV demographic and socioeconomic information Default is `TRUE`.

Available levels of aggregation come from the official spatial division provided by DANE, with their names corresponding to:
:::

```{r available datasets, echo = FALSE}
code <- c(
  "DPTO", "MPIO",
  "MPIOCL", "MZN",
  "SECR", "SECU",
  "SETR", "SETU",
  "ZU"
)
level <- c(
  "Department", "Municipality",
  "Municipality including Class", "Block", "Rural Sector", "Urban Sector",
  "Rural Section", "Urban Section", "Urban Zone"
)
dictionary_key <- c(
  "DANE_MGN_2018_DPTO", "DANE_MGN_2018_MPIO",
  "DANE_MGN_2018_MPIOCL", "DANE_MGN_2018_MZN",
  "DANE_MGN_2018_SECR", "DANE_MGN_2018_SECU",
  "DANE_MGN_2018_SETR", "DANE_MGN_2018_SETU",
  "DANE_MGN_2018_ZU"
)

mgncnpv <- data.frame(
  Code = code, Level = level, Name = dictionary_key,
  stringsAsFactors = FALSE
)
knitr::kable(mgncnpv)
```

::: {style="text-align: justify;"}
In this vignette you will learn:

1.  How to download geospatial data using **ColOpenData**.
2.  How to use census data included in geospatial datasets.
3.  How to visualize spatial data using **leaflet** and **ggplot2**.

We will be using geospatial data at the level of Department ("dpto") and we will calculate the percentage of dwellings with internet connection at each department. Later, we will build some plots using the previously mentioned approaches for dynamic and static plots.

We will start by importing the needed libraries.
:::

```{r library imports, results = "hide", warning = FALSE, message = FALSE}
library(ColOpenData)
library(dplyr)
library(sf)
library(ggplot2)
library(leaflet)
```

::: {style="text-align: justify;"}
**Disclaimer: all data is loaded to the environment in the user's R session, but is not downloaded to user's computer. Spatial datasets can be very long and might take a while to be loaded in the environment**
:::

## Downloading geospatial data

::: {style="text-align: justify;"}
First, we download the data using the function `download_geospatial()`, including the geometries and the census related information. The `simplified` parameter is used to download a lighter version, since simple plots do not require precise spatial information.
:::

```{r download data}
dpto <- download_geospatial(
  spatial_level = "dpto",
  simplified = TRUE,
  include_geom = TRUE,
  include_cnpv = TRUE
)

head(dpto)
```

::: {style="text-align: justify;"}
To understand which column contains the internet related information, we will need the corresponding dataset dictionary. To download the dictionary we can use the `geospatial_dictionary()` function. This function uses as parameters the dataset name to download the associated information and language of this information. For further information please refer to the documentation on dictionaries previously mentioned.
:::

```{r dictionary for urban sections}
dict <- geospatial_dictionary(spatial_level = "dpto", language = "EN")

head(dict)
```

::: {style="text-align: justify;"}
To calculate the percentage of dwellings with internet connection, we will need to know the number of dwellings with internet connection and the total of dwellings in each department. From the dictionary, we get that the number of dwellings with internet connection is [viv_internet]{.underline} and the total of dwellings is [viviendas]{.underline}. We will calculate the percentage as follows:
:::

```{r}
internet_cov <- dpto %>% mutate(internet = round(viv_internet / viviendas, 2))
```

## Static plots (ggplot2)

::: {style="text-align: justify;"}
[`ggplot2`](https://ggplot2.tidyverse.org/) can be used to generate static plots of spatial data by using the geometry `geom_sf()`. Color palettes and themes can be defined for each plot using the aesthetic and scales, which can be consulted in the `ggplot2` [documentation](https://ggplot2.tidyverse.org/reference/index.html#scales). We will use a gradient with a two-color diverging palette, to make the differences more visible.
:::

```{r ggplot2}
ggplot(data = internet_cov) +
  geom_sf(mapping = aes(fill = internet), color = NA) +
  theme_minimal() +
  theme(
    plot.background = element_rect(fill = "white", colour = "white"),
    panel.background = element_rect(fill = "white", colour = "white"),
    panel.grid = element_blank(),
    axis.text = element_blank(),
    axis.ticks = element_blank()
  ) +
  scale_fill_gradient("Percentage", low = "#10bed2", high = "#deff00") +
  ggtitle(
    label = "Internet coverage",
    subtitle = "Colombia"
  )
```

## Dynamic plots (leaflet)

::: {style="text-align: justify;"}
For dynamic plots, we can use [`leaflet`](https://rstudio.github.io/leaflet/), which is an open-source library for interactive maps. To create the same plot we first will create the color palette.
:::

```{r define color palette}
colfunc <- colorRampPalette(c("#10bed2", "#deff00"))
pal <- colorNumeric(
  palette = colfunc(100),
  domain = internet_cov[["internet"]]
)
```

::: {style="text-align: justify;"}
With the previous color palette we can generate the interactive plot. The package also includes open source maps for the base map like [OpenStreetMap](https://www.openstreetmap.org/#map=5/4.632/-74.299) and [CartoDB](https://carto.com/basemaps). For further details on `leaflet`, please refer to the package's [documentation](https://rstudio.github.io/leaflet/reference/index.html).
:::

```{r leaflet}
leaflet(internet_cov) %>%
  addProviderTiles(providers$CartoDB.Positron) %>%
  addPolygons(
    stroke = TRUE,
    weight = 0,
    color = NA,
    fillColor = ~ pal(internet_cov[["internet"]]),
    fillOpacity = 1,
    popup = paste0(internet_cov[["internet"]])
  ) %>%
  addLegend(
    position = "bottomright",
    pal = pal,
    values = ~ internet_cov[["internet"]],
    opacity = 1,
    title = "Internet Coverage"
  )
```