---
title: "Get started with giscoR"
description: A brief introduction to giscoR
vignette: >
  %\VignetteIndexEntry{Get started with giscoR}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

<!-- giscoR.qmd is generated from giscoR.qmd.orig. Please edit that file -->



# Introduction

*The full site with more examples and vignettes is available at
<https://ropengov.github.io/giscoR/>.*

[**giscoR**](https://ropengov.github.io/giscoR/) is a package designed to
provide a simple interface to the Eurostat [GISCO geodata
distribution](https://gisco-services.ec.europa.eu/distribution/v2/).

GISCO provides geospatial data for the European Union, its member states and
subnational regions. It supplies geospatial files in different formats, with a
focus on Europe and global datasets such as country boundaries, labels and
coastal lines.

Compatible administrative and statistical datasets are available at multiple
resolutions: high-resolution datasets for small areas (01M, 03M) and lighter
datasets for larger areas (10M, 20M, 60M). They can be available in
[EPSG:4326](https://epsg.io/4326), [EPSG:3035](https://epsg.io/3035) and
[EPSG:3857](https://epsg.io/3857). Grid, transport and basic service datasets
use the formats and coordinate reference systems documented for each dataset.

**giscoR** returns [**sf**
objects](https://r-spatial.github.io/sf/reference/sf.html). See
<https://r-spatial.github.io/sf/> for details.

# Caching

**giscoR** supports caching downloaded datasets. Set the cache directory with:


``` r
gisco_set_cache_dir("./path/to/location")
```

If a file is not available locally, it is downloaded to that directory so
subsequent requests for the same data can read from the local cache.

If downloading fails, you can manually download the file from the [GISCO geodata
distribution](https://gisco-services.ec.europa.eu/distribution/v2/) and place it
in your local cache directory.

# Downloading data

Review the following attribution and licensing requirements before using GISCO
data:

## General copyright

<figure>

<blockquote class="blockquote">

[Eurostat's general copyright notice and license
policy](https://ec.europa.eu/eurostat/web/main/help/copyright-notice) applies.
Some datasets have additional download and usage provisions. The download and
use of these data are subject to acceptance of those provisions. See the
[administrative
units](https://ec.europa.eu/eurostat/web/gisco/geodata/administrative-units) and
[statistical
units](https://ec.europa.eu/eurostat/web/gisco/geodata/statistical-units),
[grids](https://ec.europa.eu/eurostat/web/gisco/geodata/grids) and [basic
services](https://ec.europa.eu/eurostat/web/gisco/geodata/basic-services) for
more details, including source-specific conditions.

</blockquote>

```{=html}
<figcaption class="blockquote-footer">Source: <cite title="GISCO">
<a href="https://ec.europa.eu/eurostat/web/gisco/geodata"
class="external-link uri">https://ec.europa.eu/eurostat/web/gisco/geodata</a>
</cite>
</figcaption>
```

</figure>

## Population grids

`gisco_get_grid()` downloads polygon or cell-center point GeoPackages in
**EPSG:3035** at resolutions from 1 km to 100 km. Population columns use names
such as `TOT_P_2021`. Divide these values by `resolution^2`, not by
`resolution`, to calculate people per square kilometer. Population variables
have year- and country-specific licensing conditions. Consult the official [grid
documentation](https://ec.europa.eu/eurostat/web/gisco/geodata/grids) before
publication or redistribution.

The `gisco_attributions()` function provides guidance on this topic and returns
attribution text in several languages.


``` r
library(giscoR)
c(
  gisco_attributions(lang = "en"),
  gisco_attributions(lang = "fr"),
  gisco_attributions(lang = "de")
) |> cat(sep = "\n\n")
#> © EuroGeographics for the administrative boundaries
#> 
#> © EuroGeographics pour les limites administratives
#> 
#> © EuroGeographics bezüglich der Verwaltungsgrenzen
```

# Basic example

The following example downloads EU member states and candidate countries for
2024.


``` r
library(dplyr)
library(ggplot2)
world <- gisco_get_countries(resolution = 3, epsg = 3035)

world <- world |>
  mutate(
    status = case_when(
      EU_STAT == "T" ~ "Current members",
      CC_STAT == "T" ~ "Candidate countries",
      TRUE ~ NA
    ),
    # Set levels.
    status = factor(status,
      levels = c("Current members", "Candidate countries")
    )
  )

ggplot(world) +
  geom_sf(fill = "#c1c1c1") +
  geom_sf(aes(fill = status), color = "white") +
  guides(fill = guide_legend(direction = "horizontal")) +
  # Center on Europe with EPSG 3035.
  coord_sf(
    xlim = c(2377294, 7453440),
    ylim = c(1313597, 5628510)
  ) +
  scale_fill_manual(
    values = c("#039", "#2782bb"), na.value = "#c1c1c1",
    na.translate = FALSE
  ) +
  theme_minimal() +
  theme(
    panel.background = element_rect(fill = "grey90", color = NA),
    axis.line = element_blank(),
    axis.text = element_blank(),
    panel.grid = element_blank(),
    legend.position = "bottom"
  ) +
  labs(
    title = "EU member states and candidate countries (2024)",
    caption = gisco_attributions(),
    fill = ""
  )
```

<div class="figure">
<img src="./fig-country-1.png" alt="Map of Europe with EU member states in dark blue, candidate countries in light blue and other countries in gray. White outlines separate countries. Candidate countries are concentrated along the eastern and southeastern edges of the EU." width="100%" />
<p class="caption">EU member states and candidate countries (2024)</p>
</div>

You can select specific countries using names in any language, ISO 3166-1
alpha-3 codes or Eurostat codes. However, you cannot mix these identifier types
in a single call.

You can also combine datasets using the same `resolution` and `epsg`. Use the
same `year` when it is available for both datasets:


``` r
cntr <- c("Morocco", "Algeria", "Tunisia", "Libya", "Egypt")

africa_north <- gisco_get_countries(
  country = cntr,
  resolution = "03",
  epsg = "4326", year = "2024"
)

# Order plot facets.
africa_north$NAME_ENGL <- factor(africa_north$NAME_ENGL, levels = cntr)

# Get coastal lines.
coast <- gisco_get_coastal_lines(
  resolution = "03",
  epsg = "4326",
  year = "2016"
)

# Create plot.
ggplot(coast) +
  geom_sf(color = "#B9B9B9") +
  geom_sf(data = africa_north, fill = "#346733", color = "#335033") +
  coord_sf(xlim = c(-13, 37), ylim = c(18.5, 40)) +
  facet_wrap(vars(NAME_ENGL), ncol = 2) +
  labs(caption = gisco_attributions("fr"))
```

<div class="figure">
<img src="./fig-africa-1.png" alt="Faceted map with five panels arranged in two columns, highlighting Morocco, Algeria, Tunisia, Libya and Egypt separately against the same North African coastline. Longitude and latitude provide a shared geographic reference. The panels show the countries in their west-to-east order and allow their shapes and relative sizes to be compared." width="100%" />
<p class="caption">Political map of North Africa</p>
</div>

# Thematic maps with giscoR

This example shows how **giscoR** can be used with Eurostat data. For plotting,
we use the **ggplot2** package. Any package that supports **sf** objects, such
as **tmap**, **mapsf** or **leaflet**, can be used.


``` r
# Load EU member data.
library(giscoR)
library(dplyr)
library(eurostat)
library(ggplot2)

nuts2 <- gisco_get_nuts(
  year = "2021", epsg = "3035", resolution = "10",
  nuts_level = "2"
)
# Get country borders.
borders <- gisco_get_countries(epsg = "3035", year = "2020", resolution = "3")

eu_bord <- borders |>
  filter(CNTR_ID %in% nuts2$CNTR_CODE)

# Retrieve disposable income data from Eurostat.
pps <- get_eurostat("tgs00026") |>
  filter(TIME_PERIOD == "2022-01-01")

nuts2_sf <- nuts2 |>
  left_join(pps, by = "geo") |>
  mutate(
    values_th = values / 1000,
    categ = cut(values_th, c(0, 15, 30, 60, 90, 120, Inf))
  )

# Adjust labels.
labs <- levels(nuts2_sf$categ)
labs[1] <- "< 15"
labs[6] <- "> 120"
levels(nuts2_sf$categ) <- labs

# Create the plot.
ggplot(nuts2_sf) +
  # Add background geometry.
  geom_sf(data = borders, fill = "#e1e1e1", color = NA) +
  geom_sf(aes(fill = categ), color = "grey20", linewidth = .1) +
  geom_sf(data = eu_bord, fill = NA, color = "black", linewidth = .15) +
  # Center on Europe with EPSG 3035.
  coord_sf(xlim = c(2377294, 6500000), ylim = c(1413597, 5228510)) +
  # Configure legends and color.
  scale_fill_manual(
    values = hcl.colors(length(labs), "Geyser", rev = TRUE),
    # Label missing values.
    labels = function(x) {
      ifelse(is.na(x), "No data", x)
    },
    na.value = "#e1e1e1"
  ) +
  guides(fill = guide_legend(nrow = 1)) +
  theme_void() +
  theme(
    text = element_text(colour = "grey0"),
    panel.background = element_rect(fill = "#97dbf2"),
    panel.border = element_rect(fill = NA, color = "grey10"),
    plot.title = element_text(hjust = 0.5, vjust = -1, size = 12),
    plot.subtitle = element_text(
      hjust = 0.5, vjust = -2, face = "bold",
      margin = margin(b = 10, t = 5), size = 12
    ),
    plot.caption = element_text(
      size = 8, hjust = 0, margin =
        margin(b = 4, t = 8)
    ),
    legend.text = element_text(size = 7, ),
    legend.title = element_text(size = 7),
    legend.position = "bottom",
    legend.direction = "horizontal",
    legend.text.position = "bottom",
    legend.title.position = "top",
    legend.key.height = rel(0.5),
    legend.key.width = unit(0.1, "npc")
  ) +
  # Add labels.
  labs(
    title = "Disposable income of private households (2022)",
    subtitle = "NUTS 2 level",
    fill = "euros (thousands)",
    caption = paste0(
      "Source: Eurostat, ", gisco_attributions()
    )
  )
```

<div class="figure">
<img src="./fig-giscor-1.png" alt="Choropleth map of European NUTS 2 regions, colored by household disposable income in thousands of euros. Orange indicates lower income categories and teal indicates higher categories. Gray marks missing data. The legend ranges from below 15 thousand to above 120 thousand euros. Regional differences are visible within countries, including France, Spain and Germany.&#10;" width="100%" />
<p class="caption">Disposable income of private households by NUTS 2 regions (2022)</p>
</div>

Use these examples as a starting point for your own maps.