---
title: "Introduction to inkaR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to inkaR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    eval = FALSE
)
```

## Overview

The `inkaR` package provides a modern R interface to the [BBSR INKAR](https://www.inkar.de/) database —
**Indikatoren und Karten zur Raum- und Stadtentwicklung** (Indicators and Maps for Spatial and Urban Development).
INKAR is published by the German Federal Institute for Research on Building, Urban Affairs and Spatial Development (BBSR)
and contains hundreds of regional indicators at multiple spatial levels across Germany.

Key features:

- **Browse & Search**: Find indicators offline with `view_indicators()` and `search_indicators()`.
- **Interactive Wizard**: Step-by-step guided download with `select_indicator()`, `select_level()`, and `select_years()`.
- **Bilingual Output**: All results available in German (default) or English (`lang = "en"`).
- **Disk Caching**: API responses are cached locally — repeated calls return instantly.
- **Mapping**: Visualize downloaded data on German administrative maps with `plot_inkar()`.

## Installation

```r
# From GitHub
remotes::install_github("ofurkancoban/inkaR")

library(inkaR)
```

---

## 1. Browsing Indicators

The INKAR database contains hundreds of indicators. `inkaR` ships a local metadata table
(`indicators`) so you can explore and filter without hitting the API.

### View the full list

Opens a searchable, sortable table in the RStudio viewer:

```r
view_indicators()          # German names (default)
view_indicators("en")      # English names
```

### Search by keyword

```r
search_indicators("GDP", lang = "en")
search_indicators("Arbeitslosigkeit")   # German search
```

Each result shows the `ID` (short code) and `M_ID` (numeric API key) you need to download data.

### Retrieve as a data frame

```r
df_meta <- get_indicators("en")
head(df_meta)
```

---

## 2. Interactive Wizard

For guided, step-by-step downloads — especially useful in the RStudio console:

```r
# Step 1 – pick an indicator (searchable menu)
id <- select_indicator(lang = "en")

# Step 2 – pick the spatial level (e.g. KRE, GEM, BLD)
level <- select_level(id)

# Step 3 – pick the year(s)
years <- select_years(id, level)

# Step 4 – download
df <- get_inkar_data(id, level = level, year = years, lang = "en")
```

Each step can also be called independently when you already know some parameters:

```r
select_indicator("employment")   # pre-filters by keyword before showing the menu
```

---

## 3. Downloading Data

`get_inkar_data()` is the main download function.

### Basic download

```r
# GDP (ID "011") for Districts (Kreise) — latest available year
df <- get_inkar_data("011", level = "KRE")
head(df)
#>   Kennziffer        Raumeinheit Aggregat  Zeit              Indikator     Wert
#> 1      01001    Flensburg (KSt)      KRE  2022 Bruttoinlandsprodukt_... 1234.5
```

### Specify year(s)

```r
# Single year
df_2021 <- get_inkar_data("011", level = "KRE", year = 2021)

# Range of years
df_range <- get_inkar_data("011", level = "KRE", year = 2015:2021)
```

### English output

```r
df_en <- get_inkar_data("011", level = "KRE", year = 2021, lang = "en")
head(df_en)
#>   region_id        region_name level_name year         indicator_name   value
#> 1     01001  Flensburg (KSt)        KRE  2021  Gross domestic pro... 1234.5
```

Column names in English mode:

| Column           | Description                       |
|------------------|-----------------------------------|
| `region_id`      | Administrative key (Kennziffer)   |
| `region_name`    | Region name                       |
| `level_name`     | Spatial level (e.g. KRE)          |
| `year`           | Reference year                    |
| `indicator_name` | English indicator label           |
| `value`          | Numeric value                     |

### Multiple indicators at once

Pass a vector of IDs to download and merge automatically:

```r
df_multi <- get_inkar_data(c("011", "q_alo"), level = "KRE", year = 2021, lang = "en")
```

Results are merged by region and year into a wide-format tibble.

### Export to CSV

```r
get_inkar_data("011", level = "KRE", csv = TRUE, export_dir = tempdir())
# Saves: inkar_011_KRE_Bruttoinlandsprodukt_<timestamp>.csv
```

---

## 4. Spatial Levels

Common levels:

| Code  | German name              | English                       |
|-------|--------------------------|-------------------------------|
| `KRE` | Kreise / Kreisfreie Staedte | Districts                  |
| `GEM` | Gemeinden                | Municipalities                |
| `ROR` | Raumordnungsregionen     | Spatial Planning Regions      |
| `BLD` | Bundeslaender            | Federal States                |
| `BND` | Bund                     | Federal Territory (Germany)   |

Not all indicators are available at every level. Use `select_level()` to see which levels
a given indicator supports, or call `get_geographies()` to list all available levels:

```r
get_geographies()
```

---

## 5. Mapping

`plot_inkar()` visualizes a downloaded data frame on German administrative boundaries.
It requires the `ggplot2`, `sf`, and `geodata` packages.

### Automatic Maps via GADM
By default, the function downloads boundaries from [GADM](https://gadm.org/) and caches them. It supports:
- `BND`: Federal Territory (Germany as a whole - GADM Level 0)
- `BLD`: Federal States (GADM Level 1)
- `KRE`: Districts (GADM Level 2)
- `GEM`: Municipalities (GADM Level 3)

```r
# Download GDP for Districts
df <- get_inkar_data("011", level = "KRE", year = 2021, lang = "en")

# Plot — light theme (default)
plot_inkar(df)

# Dark theme
plot_inkar(df, mode = "dark")
```

Below is an example of the dark mode map output generated by `plot_inkar()`:

![](map_output.jpg)


### Custom Geometries
If you want to use custom boundaries (e.g. `ROR` Raumordnungsregionen, or custom shapefiles), you can pass an `sf` object directly to the `geom` parameter. `plot_inkar()` will skip the GADM download and merge your data with the custom spatial data frame:

```r
# Load your custom spatial data frame (e.g. from an sf shapefile)
# my_shapes <- sf::read_sf("path/to/shapes.shp")

# Plot using custom geometry
# plot_inkar(df, geom = my_shapes)
```

---

## 6. Caching

`inkaR` caches API responses to your user data directory (`tools::R_user_dir("inkaR", "cache")`).
Caches expire after 24 hours. To clear them manually:

```r
clear_inkar_cache()
```

---

## 7. Analysis Helpers

### Filter to specific regions or districts
You can filter downloaded datasets to specific regions using either the plural or singular helpers. For districts, you can also filter by their administrative key (Kennziffer/ID):

```r
df <- get_inkar_data("011", level = "KRE", lang = "en")

# Filter regions (by name)
df_cities <- compare_regions(df, c("Berlin", "Hamburg", "München"))
df_city   <- compare_region(df, "Berlin") # Singular alias

# Filter districts (by name or district ID/Kennziffer)
df_districts <- compare_districts(df, c("01001", "Hamburg"))
df_district  <- compare_district(df, "02000") # Singular alias
```

### Plot trends over time

```r
inkar_trends(df, regions = c("Berlin", "Hamburg"))
```

### Theme-filtered search

```r
get_themes()                                   # list all themes
search_indicators("employment", theme = "Arbeitsmarkt")
view_indicators("en", theme = "Bevölkerung")
```

---

## Quick Reference

| Function              | Purpose                                          |
|-----------------------|--------------------------------------------------|
| `inkar()`             | English shortcut — latest year, EN output        |
| `get_inkar_data()`    | Download indicator data from the API             |
| `inkaR()`             | Full-featured download with interactive wizard   |
| `view_indicators()`   | Browse all indicators in a viewer table          |
| `search_indicators()` | Search indicators by keyword                     |
| `get_indicators()`    | Return indicator metadata as a data frame        |
| `get_themes()`        | List indicator themes/domains                    |
| `select_indicator()`  | Interactive menu to pick an indicator            |
| `select_level()`      | Interactive menu to pick a spatial level         |
| `select_years()`      | Interactive menu to pick year(s)                 |
| `get_geographies()`   | List available spatial levels                    |
| `compare_regions()`   | Filter downloaded data to named regions          |
| `compare_region()`    | Singular alias for `compare_regions()`           |
| `compare_districts()` | Filter data by district names or IDs             |
| `compare_district()`  | Singular alias for `compare_districts()`          |
| `inkar_trends()`      | Line chart of indicator values over time         |
| `plot_inkar()`        | Plot downloaded data on a map                    |
| `clear_inkar_cache()` | Clear the local API response cache               |

