<!--
SPDX-FileCopyrightText: 2025 Climate Service Center Germany (GERICS), Helmholtz-Zentrum Hereon

SPDX-License-Identifier: CC-BY-4.0
-->

# 🔬 Dive into the Background Theory

This section provides a deeper look into the data, mathematics, and methodology behind RegionMatch.

You do **not** need this section to *use* the plugin. It is intended for users who want to understand how similarity is computed, how data are prepared, and how configuration choices influence the results.

---

## 1. Mathematical Description of Similarity

This section describes how RegionMatch translates multidimensional regional characteristics into a single similarity score.

### 1.1 Feature Selection and Weighting

Let {math}`A` denote the set of comparison aspects:

* climate
* sociodemography
* orography
* land use

Each aspect {math}`a \in A` is associated with a feature vector:

```{math}
X_a \subseteq \mathbb{R}^n
```

Users assign a numeric weight to each aspect:

```{math}
w_a \in \{0,\; 0.5,\; 1\}
``` 

| Weight {math}`w_a` | Meaning          |
| ------------------ | ---------------- |
| 1.0                | high relevance   |
| 0.5                | medium relevance |
| 0.0                | low relevance    |

The sum of all weights defines the maximum possible similarity score:

```{math}
S_{\text{max}} = \sum_{a \in A} w_a
``` 

This implies that the *scale of the similarity score depends directly on the selected weights*.

---

### 1.2 Distance Calculation

For each aspect {math}`a`, the distance between the reference region {math}`x_0 \in \mathbb{R}^n` and another region {math}`x_i \in \mathbb{R}^n` is computed using the **standardised Euclidean distance**:

```{math}
d_a(x_0, x_i) = \sqrt{ \sum_{j=1}^{n} \frac{(x_{0j} - x_{ij})^2}{\sigma_j^2} }
``` 

where {math}`\sigma_j^2` denotes the variance of feature {math}`j` across all regions.

In the implementation, this is computed using:

```
scipy.spatial.distance.cdist(
    target_features,
    all_features,
    metric="seuclidean",
    V=variances,
)
```

Standardisation ensures that indicators with large numeric ranges do not dominate the distance calculation.

---

### 1.3 Similarity Score Construction

Raw distances are transformed into similarity values by normalising and inverting the distance range:

```{math}
s_a(x_0, x_i) = 1 - \frac{d_a(x_0, x_i) - d_{\min}}{d_{\max} - d_{\min}}
``` 

This transformation ensures that:

* values close to **1** indicate high similarity
* values close to **0** indicate low similarity

Each aspect-specific similarity is then weighted according to user-defined relevance:

```{math}
S(x_i) = \sum_{a \in A} w_a \cdot s_a(x_0, x_i)
```
with
```{math}
w_a \in \{0,\; 0.5,\; 1\}
``` 
---

## 2. Data Basis

RegionMatch relies on a harmonised table that combines administrative, sociodemographic, land use, orographic, and climate information for all German districts (NUTS3 level).

### 2.1 Overview of Input Data

| Data                     | Unit  | Aspect           | Source                                 |
| ------------------------ | ----- | ---------------- | -------------------------------------- |
| NUTS_CODE                | n.a.  | Description      | [Bundesamt für Kartografie und Geodäsie](https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/verwaltungsgebiete/nuts-gebiete-1-250-000-stand-31-12-nuts250-31-12.html) |
| NUTS_NAME                | n.a.  | Description      | [Bundesamt für Kartografie und Geodäsie](https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/verwaltungsgebiete/nuts-gebiete-1-250-000-stand-31-12-nuts250-31-12.html) |
| Total area               | km²   | Sociodemographic | [DESTATIS](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/Administrativ/Archiv/Standardtabellen/04_KreiseVorjahr.html) |
| Total population         | n.a.  | Sociodemographic | [DESTATIS](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/Administrativ/Archiv/Standardtabellen/04_KreiseVorjahr.html) |
| Population density       | 1/km² | Sociodemographic | [DESTATIS](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/Administrativ/Archiv/Standardtabellen/04_KreiseVorjahr.html) |
| Population over 65       | %     | Sociodemographic | [Deutschlandatlas](https://www.deutschlandatlas.bund.de/DE/Karten/Wo-wir-leben/003-Flaechennutzung.html) |
| Urban & traffic areas    | %     | Land use         | [Deutschlandatlas](https://www.deutschlandatlas.bund.de/DE/Karten/Wo-wir-leben/003-Flaechennutzung.html) |
| Agricultural land        | %     | Land use         | [Deutschlandatlas](https://www.deutschlandatlas.bund.de/DE/Karten/Wo-wir-leben/003-Flaechennutzung.html) |
| Forest area              | %     | Land use         | [Deutschlandatlas](https://www.deutschlandatlas.bund.de/DE/Karten/Wo-wir-leben/003-Flaechennutzung.html) |
| Orography type           | n.a.  | Orography        | [NUKLEUS ensemble](https://ch1187.gitlab-pages.dkrz.de/Information/Data.html) |
| Hot days                 | days  | Climate          | [NUKLEUS ensemble](https://ch1187.gitlab-pages.dkrz.de/Information/Data.html) |
| Longest dry spell        | days  | Climate          | [NUKLEUS ensemble](https://ch1187.gitlab-pages.dkrz.de/Information/Data.html) |
| Heavy precipitation days | days  | Climate          | [NUKLEUS ensemble](https://ch1187.gitlab-pages.dkrz.de/Information/Data.html) |
| Tropical nights          | days  | Climate          | [NUKLEUS ensemble](https://ch1187.gitlab-pages.dkrz.de/Information/Data.html) |

Climate indicators are based on near-surface values, provided as 30-year means for the historical period and as changes relative to the historical period for +2 °C and +3 °C global warming levels.

---

## 3. Climate Indicators

The following climate indicators are used:

| Indicator                | Abbreviation | Definition                                         |
| ------------------------ | ------------ | -------------------------------------------------- |
| Hot days                 | TXge30       | Days with daily maximum temperature ≥ 30 °C        |
| Tropical nights          | TR           | Days with daily minimum temperature > 20 °C        |
| Heavy precipitation days | R30mm        | Days with precipitation ≥ 30 mm                    |
| Longest dry spell        | CDD          | Longest sequence of days with precipitation < 1 mm |

Indicator definitions follow the [Climpact](https://climpact-sci.org/indices/) standard indices.

---

## 4. Spatial Aggregation of Climate Data

German district geometries are derived from NUTS3 shapefiles provided by the Federal Agency for Cartography and Geodesy (german: [Bundesamt für Kartografie und Geodäsie](https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/verwaltungsgebiete/nuts-gebiete-1-250-000-stand-31-12-nuts250-31-12.html)). These geometries are converted to GeoJSON and filtered to include only land districts.

The geometries are then used to spatially aggregate climate model output using `regionmask`, `xarray`, and cosine-latitude weighting.

This approach allows efficient computation of district-level climate indicators.

---

## 5. Orography Classification

Orography is provided as elevation (meters above sea level) in the NUKLEUS model data.

Each district is assigned an orography type based on the *maximum elevation* within its boundaries:

| Type           | Condition   | Code |
| -------------- | ----------- | ---- |
| Lowland        | max < 200 m | 0    |
| Upland         | 200–500 m   | 1    |
| Highlands      | 500–1500 m  | 2    |
| High mountains | ≥ 1500 m    | 3    |

These numeric codes are used directly in the similarity calculation.

---

## 6. Code Structure and Data Updates

### 6.1 Main Components

* `run_plugin.py`: Core similarity computation
* `utils.py`: Visualisation, mapping, and output generation
* `prepare_data.py`: Input data preparation

### 6.2 Updating the Data Basis

Data preparation is decoupled from the plugin logic and handled via scripts in `data/`.

Running the preparation workflow:

* downloads updated sociodemographic and land use data
* computes climate indicators
* determines orography types
* assembles the final input table used by the plugin

This separation ensures reproducibility and easier maintenance.

---