geonuts/README.Rmd at main · aikatona/geonuts · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
---
title: "geonuts: Identify and Visualise European NUTS Regions"
output:
  github_document:
    toc: false
    toc_depth: 2
---

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

> Identify and visualize European **NUTS** regions from geographic coordinates using Eurostat geospatial data.

<!-- badges: start -->
[![R-CMD-check](https://github.com/aikatona/geonuts/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/aikatona/geonuts/actions/workflows/R-CMD-check.yaml)
[![License: GPL-3](https://img.shields.io/badge/License-GPL--3-blue.svg)](https://github.com/aikatona/geonuts/blob/main/LICENSE.md)
<!-- badges: end -->

## Overview

**geonuts** is a lightweight R package that maps latitude/longitude to EU NUTS regions
(levels 0–3) and provides quick validation maps.

- Fast lookup for many points
- `level = "all"` to return NUTS0–NUTS3 at once
- Optional nearest‐polygon fallback for points just off the coast
- Clean maps with auto-zoom and frequency shading
- Uses official Eurostat layers via **eurostat** (and compatible with **giscoR**)

## Installation

```{r, eval=FALSE}
# install.packages("remotes")
remotes::install_github("aikatona/geonuts")
```

## Quick start

```{r}
library(geonuts)

# Example coordinates (Berlin, Paris, Rome)
lat <- c(52.5200, 48.8566, 41.9028)
lon <- c(13.4050, 2.3522, 12.4964)

# 1) Identify NUTS regions at all levels
nuts_all <- get_nuts(
  latitude   = lat,
  longitude  = lon,
  level      = "all",
  year       = 2021,
  resolution = 20,
  verbose    = FALSE
)
nuts_all
#>   lat    lon nuts0 nuts1   nuts2    nuts3 cntr_code match_status match_dist_km year resolution
#>  ... (table truncated in README for brevity)

# 2) Map (NUTS3) with points
map_nuts(nuts_all, map_level = 3, show_points = TRUE)

# 3) Restrict map to a country (e.g., Italy)
map_nuts(nuts_all, map_level = 3, country = "IT")
```

## Nearest fallback (over water)

```{r}
# A point in the Bay of Biscay plus Berlin
lat2 <- c(52.5200, 43.8000)
lon2 <- c(13.4050, -2.5000)

res <- get_nuts(
  latitude        = lat2,
  longitude       = lon2,
  level           = 3,
  match_strategy  = "nearest",
  nearest_max_km  = 400,
  year            = 2021,
  resolution      = 20,
  verbose         = FALSE
)
res
```

## Notes on data and caching

- Geometries are fetched via `eurostat::get_eurostat_geospatial()` and cached.
- Once downloaded, subsequent calls are much faster and work offline.
- To clear the Eurostat cache:

```{r}
unlink(tools::R_user_dir("eurostat", "cache"), recursive = TRUE)
```

## Functions

- `get_nuts()`: Identify NUTS for coordinates (single level 0/1/2/3 or "all").
- `map_nuts()`: Visualize matches; auto-zoom; optional frequency legend (shown only if any region has count > 1).

## Vignette

A longer walk-through is available as an HTML vignette:

```{r, eval=FALSE}
# Build once locally
devtools::build_vignettes()
browseVignettes("geonuts")
```

## Citation

If you use geonuts in published work, please cite the GitHub repository:

> Katona, A. I., & Kurbucz, M. T. (2025). geonuts: Identify and Visualize European NUTS Regions from Geolocations. GitHub: aikatona/geonuts.