veg2hab 0.3.0a0

Package voor automatisch omzetten van vegetatiekarteringen naar habitatkaarten

veg2hab

• veg2hab
  • Introductie
    • Disclaimer
  • Installatie instructies
    • Installatie binnen ArcGIS Pro
      • Aanvullende opmerkingen
    • Installatie .mdb drivers op Windows
    • Installatie veg2hab op linux
    • Installatie instructies voor IT beheer
  • Gebruikershandleiding
    • Gebruik in ArcGIS Pro
    • Bronbestanden die veg2hab gebruikt
  • Handleiding voor ontwikkelaars
    • Lokale ontwikkeling
    • Nieuwe release
  • Interpretatie van de output-habitattypekartering
    • Algemene kolommen voor het hele vlak
    • Kolommen per deel van het complex

Introductie

veg2hab zet Nederlandse vegetatietypekarteringen automatisch om naar habitattypekarteringen. De library kan op 2 manieren gebruikt worden:

• Als functionaliteit binnen andere (python) software;
• Vanuit ArcGIS Pro.

veg2hab wordt gedistribueerd via PyPI, waar alle toekomstige versies aan toe worden gevoegd.

Disclaimer

Veg2hab is bedoeld als hulpmiddel om sneller vegetatiekarteringen om te zetten naar concept habitattypekaarten. Na de omzetting door veg2hab is over het algemeen nog handwerk van de gebruiker nodig, omdat sommige beperkende criteria niet te automatiseren zijn en expert judgment vereisen. Veg2hab geeft vlakken die het niet automatisch een habittatype (of H0000) kan toekennen de code HXXXX, en beschrijft in de output welke controles de gebruiker handmatig moet doen.

Het wordt gebruikers sterk aangeraden om:

• het rapport van een vegetatiekartering door te lezen, om te controleren of er zaken expliciet afwijken van de typologie vertalingen in de was-wordt lijst, de profieldocumenten of de omzetregels uit het methodiekdocument.
• De output van veg2hab steekproefsgewijs na te lopen, om te zien of de omzetting strookt met de verwachting en kennis over het gebied.
• Na het toepassen van de beperkende criteria het tussenproduct na te lopen en handmatig HXXXX om te zetten naar H0000 of een habitattype, om pas daarna de mozaiekregels en functionele samenhang toe te passen.

Installatie instructies

Installatie binnen ArcGIS Pro

Gebruik van veg2hab is ontwikkeld voor en getest in ArcGIS Pro versie 3.0 en hoger. Installatie vanaf PyPI is veruit het eenvoudigst, en wordt hieronder omschreven:

1. Open ArcGIS Pro.
2. Maak een nieuwe python environment aan voor veg2hab (de default conda environment is read-only en niet geschikt om veg2hab in te installeren):
   • Open de 'Package Manager'.
     
   • Klik op het tandwiel naast 'Active Environment'.
   • Maak een nieuwe environment aan op een locatie naar keuze. Gebruik als 'Source' de default Environment.
     
   • Selecteer de environment en druk op 'OK'.
   • Let op: het aanmaken van een nieuwe environment kan langer dan 5 minuten duren. De status van het aanmaken kan bekeken worden onder Tasks rechtsonderin de Package Manager.
3. Start ArcGIS Pro opnieuw op.
4. Download en installeer veg2hab:
   • Klik op 'New notebook' en wacht tot deze is opgestart. Dit kan tot een minuut duren.
     
   • Download veg2hab met het commando !pip install --upgrade veg2hab. Het uitvoeren van een commandoregel in het notebook kan gedaan worden met Control+Enter of door te klikken op de Run knop. Tijdens het uitvoeren staat er links naast de commandoregel [*]. Dit sterretje verandert in een getal wanneer het notebook klaar is. Het installeren van veg2hab kan enkele minuten duren.
     
5. Activeer veg2hab in het notebook met het commando import veg2hab.
6. Installeer de veg2hab Python Toolbox:
   • Gebruik het commando veg2hab.installatie_instructies() om de locatie van de toolbox te vinden.
   • Ga naar 'Add Toolbox (file)' en voeg de toolbox toe vanaf deze locatie.
     

Als het goed is, wordt de veg2hab toolbox nu getoond in de Geoprocessing tab:

Aanvullende opmerkingen

• In sommige gevallen heeft de gebruiker een ArcGIS Pro omgeving die beheerd wordt door de organisatie, en heeft de gebruiker zelf niet de rechten om alle installatiestappen uit te voeren. Alle stappen tot en met het installeren van veg2hab zullen daarbij door de IT afdeling van de organisatie uitgevoerd worden, zie sectie Installatie instructies voor IT beheer. De gebruiker moet daarna zelf alleen nog veg2hab activeren en de Toolbox installeren.
• Wanneer veg2hab geïmporteerd is en de toolbox is toegevoegd, kan deze instelling bewaard worden door het project op te slaan. Bij opnieuw openen van het project zal veg2hab direct beschikbaar zijn.

Installatie .mdb drivers op Windows

Veg2hab heeft 64-bit drivers nodig voor het openen van Microsoft Access Database bestanden (.mdb). Meestal zijn deze drivers al geïnstalleerd. Dit kan gecontroleerd worden in de ODBC Data Source Administrator:

Als er nog geen driver voor .mdb files is geïnstalleerd, kunnen de volgende stappen gevolgd worden (zie ook deze video):

1. Open het ODBC Data Sources window voor 64 bit.
2. Klik op Add...
3. Selecteer Microsoft Access Driver (*.mdb, *.accdb) en klik op Finish.
4. Geef de source een naam naar keuze en klik op OK.

Installatie veg2hab op linux

Op linux heeft veg2hab een extra dependency. Pyodbc kan namelijk niet overweg met .mdb files op linux, dus gebruiken we hiervoor de mdb-export tool. Deze is te installeren met:

apt install mdbtools

Voor meer informatie, zie: https://github.com/mdbtools/mdbtools

Installatie instructies voor IT beheer

In organisaties waarin de gebruikers van veg2hab geen volledige local admin rechten hebben binnen ArcGIS Pro, moet een groot deel van de installatiestappen door IT- of applicatiebeheer doorgevoerd worden. Hierbij is het van belang dat de IP adressen van de volgende websites niet door de firewall geblokkeerd worden:

Voor het eenmalig aanmaken van een nieuwe conda omgeving:

• repo.anaconda.com
• conda.anaconda.org

Voor het installeren / upgraden naar een nieuwe versie van veg2hab:

• files.pythonhosted.org
• pypi.org

Gebruikershandleiding

Gebruik in ArcGIS Pro

De omzetting van veg2hab van vegetatiekarteringen naar habitattypekaarten gebeurt in tools in de veg2hab Python Toolbox. Om de omzetting te doen, dient de gebruiker eerst de betreffende vegetatiekarteringen in te laden als kaart in ArcGIS Pro.

De omzettool komt in twee smaken:

1. digitale_standaard, voor het omzetten van vegetatiekarteringen die de landelijke digitale standaard gebruiken, die bestaat uit een shapefile gecombineerd met een access database. De gebruiker voert in welke vegetatiekarteringen omgezet moet worden en waar de bijhorende access database te vinden is.
2. vector_bestand, voor het omzetten van vegetatiekarteringen die alle benodigde informatie in de shapefile zelf bevatten. Omdat shapefiles geen standaard kolomnamen hebben, dient de gebruiker hier een handvol inputvelden in te vullen, bijvoorbeeld welke kolom de te gebruiken landelijke typologie bevat.

Let op:

• Wanneer de gebruiker beschikt over een access database, raden wij aan de digitale_standaard omzetting te gebruiken, ook als de shapefile alle informatie bevat. Hierbij is de kans op handmatige fouten kleiner.
• Vegetatiekarteringen die omgezet worden met vector_bestand moeten beschikken over een landelijke typologie (SBB, VvN of rVvN).
• De eerste keer dat (een nieuwe versie van) veg2hab gebruikt wordt, worden er automatisch een aantal grote bestanden gedownload, waaronder de Landelijke Bodem Kaart. Deze download kan enkele minuten duren, afhankelijk van de internetverbinding.

Bronbestanden die veg2hab gebruikt

Veg2hab is afhankelijk van verschillende bronbestanden tijdens het omzetten van vegetatiekarteringen. Deze bestanden worden automatisch mee geïnstalleerd met veg2hab en zijn niet aanpasbaar door de gebruiker:

• WasWordtLijst (versie 09-feb-2021): dit bestand wordt gebruikt om landelijke vegetatietypologieën in elkaar om te zetten.
• DefinitieTabel (versie 24 maart 2009): dit is een samenvatting van de profieldocumenten.
• Fysisch-Geografische Regio kaart (versie 2013, link naar origineel op Nationaal georegister).
• Landschappelijke Bodem Kaart (versie 2023): dit bestand wordt gebruikt voor het controleren van beperkende criteria met betrekking tot sommige bodemtypen en hoogveen.
• Bodemkaart van Nederland (versie 2021): dit bestand wordt gebruikt voor het controleren van beperkende criteria met betrekking tot bodemtypen.

Let op: bij volgende versies van veg2hab komen er mogelijk meer bronbestanden bij.

Handleiding voor ontwikkelaars

Lokale ontwikkeling

Download de git repository:

git clone https://github.com/Spheer-ai/veg2hab

En installeer alle lokale (developmment) dependencies met:

poetry install

Binnen het project zijn onderstaande stappen gevolgd om deze data in te lezen:

• Clone de volgende repo: https://github.com/pavlov99/mdb-export-all
• Gebruik het bash script om .mdb files om te zetten naar een map met csv bestanden
• De SBB-codes staan in Element.csv

Linting doen we met isort en black:

poetry run black .
poetry run isort .

Unittests worden gedraaid met pytest:

poetry run pytest tests/

Nieuwe release

1. Zorg ervoor dat de laatste bronbestanden in package_data staan met poetry run python release.py create-package-data
2. Maak een nieuwe versie met poetry (major, minor, patch): poetry version {{rule}}
3. Pas de __init__.py version variabele aan zodat deze overeen komt met de nieuw poetry version.
4. Pas veg2hab.pyt zodat de nieuwe version in SUPPORTED_VERSIONS staat. Heb je aanpassingen gedaan aan veg2hab.pyt sinds de laatste release, zorg er dan voor dat de SUPPORTED_VERSIONS = [{{new_version}}] wordt gezet.
5. Draai python release.py check-versions om te checken dat je geen fouten hebt gemaakt.
6. Push nu eerst je nieuwe wijzigingen (mochten die er zijn), naar github: (git add, git commit, git push)
7. Maak een nieuwe tag: git tag v$(poetry version -s)
8. Push de tag naar git git push origin tag v$(poetry version -s)
9. Github actions zal automatisch de nieuwe versie op PyPI zetten.

Interpretatie van de output-habitattypekartering

De habitattypekaarten die door veg2hab gemaakt worden, bevatten twee soorten attribute kolommen:

• Kolommen die vanuit het Gegevens Leverings Protol verplicht zijn.
• Kolommen die informatie bevatten over de omzetting naar habitattypen. Deze velden beginnen met een underscore-teken ( _ ) en zijn nuttig voor het controleren van een omzetting, of wanneer er nog een handmatige stap noodzakelijk is.

Verder zijn er een aantal kolommen die gelden voor het hele vlak, en kolommen die een deel van een complex beschrijven. Deze laatsten eindigen altijd op een cijfer, om het deel van het complex aan te geven. In geval van een niet-complex vlak, zijn alleen de kolommen <kolomnaam>1 ingevuld.

Algemene kolommen voor het hele vlak

Area: Oppervlakte van het vlak in m2.

Opm: Opmerkingen bij het vlak, overgenomen uit de bronkartering. Hiervoor moet de gebruiker expliciet een opmerkingenkolom selecteren bij het draaien van veg2hab.

Datum: Datum waarop een vlak is ingetekend, overgenomen uit de bronkartering. Hiervoor moet de gebruiker expliciet een datumkolom selecteren bij het draaien van veg2hab.

ElmID: Een uniek ID voor ieder vlak. Deze wordt in eerste instantie overgenomen uit de bronkartering, tenzij deze niet voor ieder vlak uniek is; in dat geval is een warning gegeven en is er een nieuw uniek ID voor ieder vlak aangemaakt.

_Samnvttng: Verkorte weergave met toegekende habitattypen en hun percentages in het complex. Dit is een combinatie van alle kolommen Habtype{i} en Perc{i}.

_LokVegTyp: Het in de bronkartering opgegeven lokale vegetatietype, als er een lokaal vegetatietype kolom is opgegeven.

_LokVrtNar: De landelijke typologie waar lokale vegetatietypen in de bronkartering naar zijn vertaald (SBB, VvN of beide). Als dit SBB is, zijn de bijbehorende VvN-typen door veg2hab uit de waswordtlijst gehaald. Als er naar VvN of naar beide is vertaald, wordt deze stap overgeslagen.

Kolommen per deel van het complex

Habtype{i}: Habitattype dat door veg2hab is toegekend aan dit complex-deel. HXXXX betekent dat er nog geen eenduidig habitattype kan worden toegekend. Hiervoor is nog een vervolgstap in veg2hab of handmatige inspectie nodig.

Perc{i}: Percentage van het vlak dat door dit complex-deel wordt bedekt.

Opp{i}: Oppervlakte van dit complex-deel in m2.

Kwal{i}: Kwaliteit van dit complex-deel. Dit kan zijn G (goed), M (matig) of X (nvt).

Opm{i}: Opsomming van informatie over het vlak dat veg2hab uit de FGR- en Bodemkaart heeft gehaald.

VvN{i}/SBB{i}: De VvN- en/of SBB-code die door de bronkartering aan het complex-deel zijn toegekend. Een waarde Null of None betekent dat in de bronkartering voor deze typologie is opgegeven, en dat de waswordtlijst ook geen vertaling bevat.

_Status{i}: Beslissings-status van veg2hab voor dit complex-deel. Kolom _Uitleg{i} geeft verdere uitleg over deze status. Mogelijke statussen en hun uitleg zijn:

• HABTYPE_TOEGEKEND: veg2hab heeft één habitattype gevonden waaraan dit vlak voldoet.
• VOLDOET_AAN_MEERDERE_HABTYPEN: veg2hab heeft meerdere habitattypen gevonden waaraan dit vlak voldoet. De gebruiker moet hierin een keuze maken.
• VOLDOET_NIET_AAN_HABTYPEVOORWAARDEN: Het vlak voldoet niet aan de beperkende criteria en/of mozaiekregels voor de habitattypen die mogelijk van toepassing zijn. Veg2hab kent aan dit vlak H0000 toe.
• VEGTYPEN_NIET_IN_DEFTABEL: De vegetatietypen van het vlak zijn op geen enkel syntaxonomisch niveau in de definitietabel gevonden en leiden dus niet tot een habitattype. Veg2hab kent aan dit vlak H0000 toe.
• GEEN_OPGEGEVEN_VEGTYPEN: Er zijn in de vegetatiekartering geen (habitatwaardige)vegetatietypen opgegeven voor dit vlak. Er is dus geen habitattype toe te kennen. Veg2hab kent aan dit vlak H0000 toe.
• NIET_GEAUTOMATISEERD_VEGTYPE: Het vlak heeft een vegetatietype dat niet geautomatiseerd kan worden omgezet naar een habitattype. De gebruiker moet hier een handmatige controle uitvoeren.
• NIET_GEAUTOMATISEERD_CRITERIUM: Er zijn placeholder mitsen/mozaiekregels gevonden; deze kunnen niet door Veg2Hab worden gecontroleerd. De gebruiker moet hier een handmatige controle uitvoeren.
• WACHTEN_OP_MOZAIEK: Er is te weinig informatie over de habitattypen van omliggende vlakken (teveel HXXXX)
• MINIMUM_OPP_NIET_GEHAALD: het vlak voldoet aan de voorwaarden voor een habitattype, maar haalt (in functionele samenhang) niet het minimum benodigde oppervlak.

_Uitleg{i}: Uitleg bij de kolom _Status{i} van dit complex-deel.

_VvNdftbl{i}/_SBBdftbl{i}: Deze kolommen bevatten een lijst met alle vegetatietypen die voor dit vlak zijn teruggevonden in de definitietabel, welke regel van de definitietabel het betreft, en naar welk habitattype het vlak mogelijk vertaalt. Een waarde None in _VvNdftbl betekent dat de regel is gevonden op SBB-code, en vice-versa.

_Mits_opm{i}/_Mozk_opm{i}: Hier staat informatie over de mitsen/mozaiekregels die in definitietabelregels gevonden zijn. Wat hier staat hangt af van de status:

• VOLDOET_AAN_MEERDERE_HABTYPEN, NIET_GEAUTOMATISEERD_CRITERIUM, WACHTEN_OP_MOZAIEK: De beperkende criteria en mozaiekregels worden getoond van alle definitietabelregels die mogelijk op het vlak van toepassing zijn. Definitietabelregels waarvan veg2hab volledig heeft kunnen controleren dat ze niet van toepassing zijn, worden weggelaten.
• VOLDOET_NIET_AAN_HABTYPEVOORWAARDEN: Alle beperkende criteria en mozaiekregels worden getoond. Deze kloppen allemaal niet, anders zou het vlak een habitattype (of HXXXX) hebben gekregen.
• HABTYPE_TOEGEKEND, MINIMUM_OPP_NIET_GEHAALD: Alleen de beperkende criteria en mozaiekregel van de regel uit de definitietabel die tot het habitattype hebben geleid, worden getoond.
• VEGTYPEN_NIET_IN_DEFTABEL, GEEN_OPGEGEVEN_VEGTYPEN, NIET_GEAUTOMATISEERD_VEGTYPE: Er zijn geen regels in de definitietabel gevonden voor de huidige vegetatietypen, dus er worden ook geen mitsen/mozaiekregels weergegeven.

Voor ieder beperkend criterium en mozaiekregel is weergegeven of deze klopt (TRUE), niet klopt (FALSE), of niet door veg2hab beoordeeld kan worden (CANNOT_BE_AUTOMATED). Een mozaiekregel kan ook nog uitgesteld zijn (POSTPONE); in dit geval is er te weinig informatie over de habitattypen van omliggende vlakken, omdat deze nog te veel HXXXX hebben om een mozaiekregeloordeel te kunnen vellen.

_MozkPerc{i}: Als dit complex-deel een mozaiekregel heeft, zijn hier de omringingspercentages van aangenzende habitattypen weergegeven. De getoonde percentages zijn diegene die gebruikt zijn om de mozaiekregel te beoordelen. Aangezien het mogelijk is dat een mozaiekregel beoordeeld kan worden voordat alle omliggende vlakken al een habitattype hebben gekregen (bijvoorbeeld als er al 50% van een verkeerd habitattype omheen ligt), kloppen deze soms niet met wat uiteindelijk om het vlak ligt (er kan meer HXXXX staan dan in de output kartering zo is).