# Data specificaties
## Geospatial rasters
Alle geospatial rasters die aangeboden worden aan MNP worden verondersteld:
* geprojecteerd te zijn in het [RD-New](https://epsg.org/crs_28992/Amersfoort-RD-New.html) (epsg:28992) coordinatenstelsel
* dezelfde extent te hebben in RD-New (meestal, maar niet perse: `left: 0 bottom: 300.000 right: 280.000 top: 625.000`)

Voor het Land-type raster wordt verondersteld:
* 2.5 m resolutie 
* unsigned integer datatype

Voor Environmental factor rasters wordt verondersteld:
* 25 m resolutie
* floating point datatype

MNP werkt het beste met het [Geotiff](https://gdal.org/drivers/raster/gtiff.html) bestandsformaat, maar andere gdal raster drivers werken waarschijnlijk ook. Dit is niet getest. 

## CSV tabellen
Alle input en output tabellen van MNP gebruiken het `*.csv` bestandstype. CSV is een open source bestandstype dat door alle gangbare teksteditors _en_ MS Excel gelezen kan worden.

Een `*.csv` bestand is opgebouwd uit rijen en kolommen. De kolommen worden gescheiden door een komma (`,`) en elke rij staat op een nieuwe regel. De eerste rij wordt verondersteld de kolomnamen te bevatten


## Land type raster legenda tabel
Een `*.csv` tabel die dient als legenda voor het land-type raster, met de volgende opbouw:

|Field|Description|Dimension|Range|Type|Null allowed|
|----|----|----|----|----|----|
|land_type_code|Unieke code ter identificatie van het land-type|-|-|string|False
|land_type_name|Naam van het land-type|-|-|string|False|
|land_type_id|Getal waarmee dit land-type wordt aangeduid in het land-type raster|-|1-∞|integer|False|

MNP verwacht dat alle `land_type_codes` even lang zijn.

Aanvullende kolommen met bijvoorbeeld arealen per land-type zijn toegestaan, maar worden genegeerd.

Gebruikelijk is om de [SNL Natuurbeheertypen](https://www.bij12.nl/onderwerpen/natuur-en-landschap/index-natuur-en-landschap/natuurtypen/) als land-type categorisatie te gebruiken. In dat geval wordt de Beheertype code zoals `N04.04` gebruikt als `land_type_code` en de Beheertype naam `Afgesloten zeearm` als `land_type_name`.

## Land type suitability index tabel
Een `*.csv` tabel waarin de soorten gekoppeld worden aan de land-types middels een _suitability index_ tussen 0-1. In de praktijk wordt een waarde van 0 weggelaten uit de tabel. De opbouw is:

|Field|Description|Dimension|Range|Type|Null allowed|
|----|----|----|----|----|----|
|species_code|Unieke code ter identifcatie van de soort|-|-|string|False|
|land_type_code|Unieke code ter identificatie van het land-type|-|-|string|False
|suitability_index|Geschiktheid van dit land-type voor deze soort|-|0-1|float|False

## Environmental factor suitability index tabel
Een `*.csv` tabel waarin de respons (de `suitability index`) van de soorten richting de Environmental Variable wordt vastgelegd. De `suitability index` wordt trapsgewijs opgebouwd aan de hand van drempelwaarden van de Environmental Variable:

|Suitability index|Environmental Variable waarde|
|----|----|
|0.0| waarde < `percentile_05`
|0.5| `percentile_05` ≤ waarde < `percentile_25`
|1.0|  `percentile_25` ≤ waarde < `percentile_75`
|0.5| `percentile_75` ≤ waarde < `percentile_95`
|0.0| waarde > `percentile_95`

De suitability index waardes (hier `0, 0.5 en 1`) staan niet vast, maar worden opgegeven als parameter. Zie sectie [parameters](#parameters).

De suitability index tabel is als volgt opgebouwd:

|Field|Description|Dimension|Range|Type|Null allowed|
|----|----|----|----|----|----|
|species_code|Unieke code ter identifcatie van de soort|-|-|string|False|
|percentile_05|drempelwaarde van de Environmental Variable|gelijk aan de eenheid van de Environmental Variable|-∞ - ∞|float|False
|percentile_25|drempelwaarde van de Environmental Variable|gelijk aan de eenheid van de Environmental Variable|-∞ - ∞|float|False
|percentile_75|drempelwaarde van de Environmental Variable|gelijk aan de eenheid van de Environmental Variable|-∞ - ∞|float|False
|percentile_95|drempelwaarde van de Environmental Variable|gelijk aan de eenheid van de Environmental Variable|-∞ - ∞|float|False

## Species names tabel
Deze `*.csv` tabel bevat referentiegegevens van mogelijke doelsoorten. Een opgegeven soort wordt door MNP als valide beschouwd als deze genoemd wordt in deze tabel. De opbouw van de tabel is:

|Field|Description|Dimension|Range|Type|Null allowed|
|----|----|----|----|----|----|
|species_code|Unieke code ter identifcatie van de soort|-|-|string|False|
|scientific_name|Latijnse naam van de soort|-|-|string|False
|local_name|Nederlandse naam van de soort|-|-|string|False
## Species traits tabel
In deze `*.csv` tabel worden de soort specifieke eigenschappen (_traits_) vastgelegd. De opbouw is:

|Field|Description|Dimension|Range|Type|Null allowed|
|----|----|----|----|----|----|
|species_code|Unieke code ter identifcatie van de soort|-|-|string|False|
|local_distance|afstand om patches een lokale populatie te clusteren|meter|0-∞|float|False|
|key_population_area|oppervlakte van een keypopulation|hectare|0-∞|float|False|
|group_traits_code|code van soortgroep|-|-|string|False|
|environmental_factor_formula|formule voor de combinatie van relevante environmental-variables tot de omgevingsfactor|-|-|string|False|
|land_type_procedure|strategie voor de interpretatie van de land-types kaart|-|-|string|False|

De kolom `abiotic formula` omschrijft hoe de verschillende Environmental Variables gecombineerd dienen te worden tot een enkele environmental variable factor-waarde. Hierbij wordt gebruikt gemaakt van de opgegeven `name` van de Environmental Variables, hoewel er in de formule ook Environmental Variables genoemd mogen worden die niet opgegeven worden door de gebruiker.

Toegestane berekeningen op de Environmental Variables zijn:
* vermenigvuldiging: e.g. `ph*gvg*ndep`
* minimum: e.g. `min(ph, gvg)`
* combinaties: e.g. `min(ph, gvg*ndep)`, `ndep*min(ph, gvg)`

De kolom `Land type procedure` benoemt de procedure voor de interpretatie van de land-type kaart richting elke soort. Op dit moment alleen de `nature` procedure geimplementeerd, wat betekent dat de land-types direct aan soorten gekoppeld worden middels de _land type suitability indexes_ tabel.

Het MNP model kan uitgebreid worden met alternatieve procudures, bijvoorbeeld een procedure om beheersmaatregelen in beschouwing te nemen. Zodra er meerdere procedures beschikbaar zijn, kan ik deze kolom worden aangegeven welke procedure van toepassing is per soort.

## Group traits tabel
In deze `*.csv` tabel worden soortgroepen gedefinieerd en eigenschappen van elke groep vastgelegd:

|Field|Description|Dimension|Range|Type|Null allowed|
|----|----|----|----|----|----|
|group_code|Unieke code van de groep|-|-|string|False|
|group_name|Unieke naam van de groep|-|-|string|False
|possibly_viable_threshold|drempelwaarde voor aantal _normkeys_ om de soort _possibly viable_ te laten zijn|-|0-∞|False|
|viable_threshold|drempelwaarde voor aantal _normkeys_ om de soort _viable_ te laten zijn|-|0-∞|False|

Soortgroepen kunnen door de gebruiker uitgewerkt en geimplementeerd worden. Een gebruikelijke indeling is:
* Evertebraten, code `E`
* Vertrebraten, code `V`
* Planten, code `P`

## Species selection tabel
Een `*.csv` tabel waarvan alleen de eerste kolom wordt ingelezen, andere kolommen worden genegeerd. De kolomnaam van de eerste kolom is niet relevant. De inhoud van de eerste kolom mag bestaan uit (een mix van):
* species codes
* species scientific names
* species local names

Een voorbeeld van een species subselection tabel is:

|species_identifier|
|----|
|S02000950
|S02001040
|Allium oleraceum
|Vingerzegge
|Ruig schapengras
|Vals heideblauwtje|
|S09000222
|Chalcolestes viridis

Dubbelingen in de tabel worden automatisch verwijderd (in dit voorbeeld `S09000222` en `Vingerzegge`). Opgaves die niet genoemd worden in de _species names_ tabel (in dit geval Chalcolestes viridis) worden genegeerd.

## Relaties tussen input tabellen
![schema van inputtabellen, kolomnamen en relaties](../_images/table_relations.png)

## Detailed tabel in subselection output
In deze tabel staan alle resultaten van alle soorten in de soortselectie. De kolommen zijn:

| Field                            | Description                                                                                              | Dimension         | Range                               | Type    |
|----------------------------------|----------------------------------------------------------------------------------------------------------|-------------------|-------------------------------------|---------|
| species_code                     | Unieke code ter identifcatie van de soort                                                                | -                 | -                                   | string  |
| scientific_name                  | Latijnse naam van de soort                                                                               | -                 | -                                   | string  |
| local_name                       | Nederlandse naam van de soort                                                                            | -                 | -                                   | string  |
| group_name                       | naam van de groep waartoe de soort behoort, ref `group_traits` tabel                                     | -                 | -                                   | string  |
| key_population_area_ha           | oppervlakte van een keypopulation, ref `species_traits` tabel                                            | hectare           | 0-∞                                 | float   |
| possibly_viable_threshold        | drempelwaarde voor aantal normkeys om de soort _possibly viable_ te laten zijn, ref `group_traits` tabel | hectare           | 0-∞                                 | integer |
| viable_threshold                 | drempelwaarde voor aantal normkeys om de soort _viable_ te laten zijn, ref `group_traits` tabel          | hectare           | 0-∞                                 | integer |
| populations                      | aantal populaties van de soort                                                                           | aantal            | 0-∞                                 | integer |
| total_effective_area_m           | effectief areaal in vierkante meter, alle populaties gesommeerd                                          | m^2               | 0-∞                                 | float   |
| total_effective_area_kp          | effectief areaal in sleutelpopulaties, alle populaties gesommeerd                                        | sleutelpopulaties | 0-∞                                 | float   |
| total_normalised_key_populations | effectief areaal in genormaliseerde sleutelpopulaties, alleen sleutelpopulaties gesommeerd               | normkeys          | 0-∞                                 | float   |
| viability_class                  | duurzaamheidsklasse                                                                                      | -                 | 1,2,3                               | integer |
| viability_class_description      | omschrijving van de duurzaamheidsklasse                                                                  | -                 | not viable, possibly viable, viable | string  |