---
title: "geonuts: Identify and Visualise European NUTS Regions"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Geonuts: Identify and Visualise European NUTS Regions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5,
  message = FALSE,
  warning = FALSE
)
```

## Overview

The *geonuts* package provides simple tools to identify European NUTS regions (Nomenclature of Territorial Units for Statistics) based on geographic coordinates, and to visualise the results on a map. It builds on Eurostat’s geospatial layers via *eurostat* and *giscoR*.

## 1. Identify NUTS regions

```{r example-getnuts}
library(geonuts)

# Example coordinates for European capitals
lat <- c(52.5200, 48.8566, 41.9028)
lon <- c(13.4050,  2.3522, 12.4964)

# Identify NUTS regions (all levels)
nuts_all <- get_nuts(
  latitude = lat,
  longitude = lon,
  level = "all",
  year = 2021,
  resolution = 20,
  verbose = FALSE
)

nuts_all
```

## 2. Visualise NUTS regions

```{r example-mapnuts}
# Create a map for the most granular (NUTS3) level
map_nuts(nuts_all, map_level = 3, show_points = TRUE)
```

You can also filter the map to a single country:

```{r example-mapnuts-country}
map_nuts(nuts_all, map_level = 3, country = "IT")
```

## 3. Single-level example

If you only need one level (e.g., NUTS2):

```{r example-single-level}
nuts2 <- get_nuts(lat, lon, level = 2, year = 2021, resolution = 20)
head(nuts2)
```

## 4. Working offline and caching

Eurostat layers are cached automatically by *eurostat* and *giscoR*, so once downloaded,
subsequent calls to `get_nuts()` and `map_nuts()` are offline-safe and much faster.

To clear cached shapefiles manually:

```{r example-cache-reset, eval = FALSE}
unlink(tools::R_user_dir("eurostat", "cache"), recursive = TRUE)
```

## Summary

| Function | Purpose |
|-----------|----------|
| `get_nuts()` | Identify NUTS regions from latitude–longitude pairs |
| `map_nuts()` | Visualise NUTS regions and matched points on a map |