README.Rmd

---
output: github_document
---

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

<!-- badges: start -->
[![DOI](https://zenodo.org/badge/575766849.svg)](https://zenodo.org/badge/latestdoi/575766849)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->
  
```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# inkr

{inkr} provides efficient and automated access to regional data from [inkar.de](https://www.inkar.de) via a local relational database.

Data from [INKAR](https://www.inkar.de)^[downloaded via ["Datenbankdownload"](https://www.bbr-server.de/imagemap/inkar/download/inkar_2024.zip)] are normalised^[i.e. not a single table with 21 million rows] and imported into a local [DuckDB](https://duckdb.org) database. On attach (e.g. with `library(inkr)`), a [DBI](https://dbi.r-dbi.org/) connection is made from R to this database.

## Installation

You can install {inkr} like so:

```{r eval=FALSE}
remotes::install_github("RegioHub/inkr")
```

## Usage

A local database containing the INKAR data must be built before first use:

```{r eval=FALSE}
library(inkr)

inkar_db_build()
```

```{r include=FALSE}
library(inkr)
```

Afterwards, all the tables in the local INKAR database are accessible in R via an object named `inkar`.^[More precisely, `inkar` contains connections to the tables in the DuckDB database via [DBI](https://dbi.r-dbi.org/) and [dbplyr](https://dbplyr.tidyverse.org/).]

Currently, `inkar` contains the following tables:

```{r}
# See `?inkar` for more details
names(inkar)
```

You can use {dplyr} to work with the tables in `inkar` as if they were in-memory data frames, e.g.:

```{r message=FALSE}
library(dplyr)

inkar$`_regionen` |>
  distinct(raumbezug) |>
  arrange(raumbezug)

inkar$`_indikatoren` |>
  count(bereich)
```

### Example: median income

Find the indicator ID for the median income:

```{r}
inkar$`_indikatoren` |>
  filter(kurzname == "Medianeinkommen")
```

5 counties with the highest median income in 2021:

```{r}
inkar$privateinkommen_und_private_schulden |>
  filter(raumbezug == "Kreise", zeitbezug == 2021) |>
  select(name, m_ek) |>
  arrange(desc(m_ek)) |>
  head(5)
```

## Citation

```{r echo=FALSE, results='asis'}
print(citation("inkr"), bibtex = FALSE)
```

A BibTeX entry for LaTeX users is

```{r echo=FALSE, comment=""}
toBibtex(citation("inkr"))
```

## Copyright notice

The data are made available by the [*Bundesinstitut für Bau-, Stadt- und Raumforschung* (BBSR)](https://www.bbsr.bund.de) in accordance with the [data licence Germany – attribution – version 2.0](https://www.govdata.de/dl-de/by-2-0).

This package is in no way officially related to or endorsed by BBSR.