---
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** package
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="EU member states and candidate countries (2024)" width="100%" />
<p class="caption">EU member states and candidate countries (2024)</p>
</div>

You can select specific countries by name 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 by using the same `resolution`, `epsg` and
(optionally) `year`:


``` 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="Political map of North Africa" 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="Disposable income of private households by NUTS 2 regions (2022)" 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.