---
title: "Swiss Municipal Data Merger Tool: Manual"
date: "`r format(Sys.Date(), '%d.%m.%Y')`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Swiss Municipal Data Merger Tool: Manual}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

library(SMMT)

```

## Introduction

In Switzerland, the landscape of municipalities is changing rapidly mainly due to mergers. The Swiss Municipality Merger Tool (SMMT) automatically detects these mutations and maps municipalities of an old state to municipalities of a new state. The aim of this vignette is to illustrate how to use the functionality of the SMMT.

This figure shows the decrease in municipalities over time:
<center>
![](municipality_count.png)
</center>

This figure shows the mutations for the decade 2010-2019:
<center>
![](bfs_atlas_mutationen.jpg)
</center>
Source: https://www.atlas.bfs.admin.ch/

## How To

### Setup

1) Download & unpack the Swiss municipality inventory from the Federal Statistical Office website.

```{r, eval=FALSE}
path_inventory_xml <- download_municipality_inventory(path = getwd())
```

2) Import the inventory into the workspace

```{r, eval=FALSE}
mutations_object <- import_CH_municipality_inventory(file_path = path_inventory_xml)
mutations        <- mutations_object$mutations

# Alternative: Use a local available version (e.g. Version from January 1st, 2018):
file_path_inventory_xml <- "path/to/eCH0071_180101.xml"
mutations_object <- import_CH_municipality_inventory(file_path = file_path_inventory_xml)
mutations        <- mutations_object$mutations
```

### Get Mapping Table

1) Define the old state and the new state. Example:

```{r}
old_state <- as.Date("1961-01-01")
new_state <- as.Date("1963-01-01")
```

2) Get mapping table

```{r, echo = FALSE}
mutations <- structure(list(hist_id = c(11227L, 11240L, 13189L),
district_hist_id = c(10025L, 10025L, 10025L),
kanton_abbr = c("AG", "AG", "AG"),
bfs_nr = c(4025L, 4021L, 4021L),
name = c("Daettwil", "Baden", "Baden"),
admission_nr = c(1000L, 1000L, 1004L),
admission_mode = c(20L, 20L, 26L),
admission_date = structure(c(-3653, -3653, -2922), class = c("Date")),
abolition_nr = c(1004L, 1004L, NA),
abolition_mode = c(29L, 26L, NA),
abolition_date = structure(c(-2923, -2923, NA), class = c("Date")),
change_date = structure(c(-2923, -2923, -2922), class = c("Date"))),
row.names = c(NA, -3L), class = c("tbl_df", "tbl", "data.frame"))
```

```{r}
mapping_object <- map_old_to_new_state(mutations, old_state, new_state)
mapping_table  <- mapping_object$mapped
```
Excerpt of mapping table: 

|bfs_nr_new | name_new | bfs_nr_old | name_old |
|-----|------|-----|-----|
|4021 | Baden | 4021 | Baden |
|4021 | Baden | 4025 | Daettwil|


If of relevance, use the information about municipalities which could not be mapped (e.g. due to secessions). For example, if you need to exclude these elements from a dataset.

## Definitions

* Spatial reference (German: Raumbezug): Set of municipalities at a given point in time. For example, the spatial reference of the Federal Population census year 2000 is the 5 December 2000.

## Further information

* Details about the Swiss Municipality inventory (German: Historisiertes Gemeindeverzeichnis) at the Federal Statistical Office : https://www.bfs.admin.ch/bfs/de/home/grundlagen/agvch/historisiertes-gemeindeverzeichnis.html
* Details about the defined standard: https://ech.ch/de/ech/ech-0071/1.2.0