Merge remote-tracking branch 'origin/main' into translation-and-fl-additions

Author: tim-hendriks

docs/implementaties/KIK-V/index.md

@@ -4,7 +4,7 @@
 
 ![type:video](https://www.youtube.com/embed/e57qKcb1ZRw?si=MBryg2leLNIA7pXt)
 
-In het programma KIK-V werken ketenpartijen in de verpleeghuiszorg samen aan het stroomlijnen van de informatie-uitwisseling, aan de hand van een afsprakenset. 
+In het programma KIK-V[^1] werken ketenpartijen in de verpleeghuiszorg samen aan het stroomlijnen van de informatie-uitwisseling, aan de hand van een afsprakenset. 
 
 Voordat KIK-V werd gebruikt, vragen ketenpartijen zoals de zorgkantoren, de NZa, de IGJ en het Zorginstituut aan zorgaanbieders vooral om gegevens aan te leveren via centrale databases om zo het aantal uitvragen aan een zorgaanbieder te beperken. Helaas sluiten deze centrale informatiebronnen niet altijd aan bij de behoeften van de ketenpartijen. Die hebben actuelere gegevens nodig of van een ander detailniveau. Soms zijn aanvullende gegevens nodig of veranderen behoeften door externe factoren. Het gevolg is: juist méér uitvragen aan de zorgaanbieder als datahouder.
 

docs/implementaties/PLUGIN/applicatie.md

@@ -1,32 +1,29 @@
-# Applicatie
+# Applicatie componenten voor decentrale verwerking
 
-Om een federatieve infrastructuur mogelijk te maken, zijn er op technisch vlak twee vereisten: 
+## Applicatiecomponenten van PLUGIN
 
-* Software voor het federatief toegankelijk maken van data
-* De data op de verschillende bronnen dient interoperabel te zijn.
+![](./plugin-overzicht.drawio.svg)
 
-PLUGIN maakt gebruik van **[Vantage6](https://vantage6.ai/)** om data te ontsluiten voor federatief gebruik. De data zelf wordt FAIR (en dus interoperabel) gemaakt door middel van **[HL7 FHIR](https://hl7.org/fhir/)**.
+Het datastation (links) en de federated processing hub (rechts) vormen de twee-eenheid van de PLUGIN/vantage6 architectuur. Hieronder wordt de functie van elke component in meer detail beschreven.
 
-## Vantage6
+!!! note "Gedetailleerde beschrijving applicatiecomponenten vantage6"
 
-Vantage6 is een open-source infrastructuur voor het uitvoeren van een breed spectrum aan federatieve algoritmen. Bij ieder data station wordt een Vantage6 node geïnstalleerd. Een centraal Vantage6 server component faciliteert communicatie en bewaart slechts de tussentijdse resultaten, welke niet terug te herleiden zijn naar een patiënt. Vanuit een user interface en een client kunnen bevoegde gebruikers nieuwe analyses en algoritmen starten, welke rechtstreeks worden opgehaald uit een vertrouwde bibliotheek.
+    === "**vantage6 server**"
 
-![PLUGIN architectuur](../../assets/Architectuurplaat-PLUGIN.jpeg)
+        Om communicatie mogelijk te maken tussen de verschillende nodes, slaat de Vantage6 Server informatie op over onder andere de deelnemende organisaties, de beschikbare nodes, en de invoer en resultaten van alle aangemaakte taken in het systeem. Deze informatie wordt opgevraagd door de nodes met behulp van een REST api en websockets, waardoor het niet nodig is binnenkomende poorten te openen op het data station.
 
-### Vantage6 Server
+        Door middel van authenticatie en authorisatie op basis van aan te wijzen rollen wordt bijgehouden welke acties toegestaan zijn voor o.a. gebruikers en nodes.
 
-Om communicatie mogelijk te maken tussen de verschillende nodes, slaat de Vantage6 Server informatie op over onder andere de deelnemende organisaties, de beschikbare nodes, en de invoer en resultaten van alle aangemaakte taken in het systeem. Deze informatie wordt opgevraagd door de nodes met behulp van een REST api en websockets, waardoor het niet nodig is binnenkomende poorten te openen op het data station.
-Door middel van authenticatie en authorisatie op basis van aan te wijzen rollen wordt bijgehouden welke acties toegestaan zijn voor o.a. gebruikers en nodes.
+    === "**vantage6 node**"
 
-### Algoritmen en Bibliotheek
+        De Vantage6 Node voert openstaande taken uit. Hierbij wordt het aangegeven Docker image uit de bibliotheek gehaald en uitgevoerd, en gekoppeld aan een van de vooraf geconfigureerde databronnen. Voor elke taak wordt door middel van configuratie gecontroleerd of het uitvoeren van de Docker image toegestaan is.
 
-Voor een maximale flexibiliteit in het soort uit te voeren taak, wordt in Vantage6 gebruik gemaakt van [Docker images](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/). Een sjabloon-image bevat vereiste logica zoals het verwerken van inputs en terugsturen van resultaten. Deze kan vervolgens worden uitgebreid met de specifieke logica voor de use-case, zoals bijvoorbeeld een federatieve query of een federated learning algoritme. Het Docker image dat hieruit resulteert wordt opgeslagen in een centrale [Docker registry](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-registry/) (een bibliotheek voor Docker images).
+        Om het algoritme uit te voeren start de node op basis van het binnengehaalde Docker image een Docker container op het data station. Communicatie vanuit het algoritme verloopt hierbij altijd via de node naar de server.
 
-### Vantage6 Node
+    === "**Algoritmen en bibliotheek**"
 
-De Vantage6 Node voert openstaande taken uit. Hierbij wordt het aangegeven Docker image uit de bibliotheek gehaald en uitgevoerd, en gekoppeld aan een van de vooraf geconfigureerde databronnen. Voor elke taak wordt door middel van configuratie gecontroleerd of het uitvoeren van de Docker image toegestaan is.
+        Voor een maximale flexibiliteit in het soort uit te voeren taak, wordt in Vantage6 gebruik gemaakt van [Docker images](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/). Een sjabloon-image bevat vereiste logica zoals het verwerken van inputs en terugsturen van resultaten. Deze kan vervolgens worden uitgebreid met de specifieke logica voor de use-case, zoals bijvoorbeeld een federatieve query of een federated learning algoritme. Het Docker image dat hieruit resulteert wordt opgeslagen in een centrale [Docker registry](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-registry/) (een bibliotheek voor Docker images).
 
-Om het algoritme uit te voeren start de node op basis van het binnengehaalde Docker image een Docker container op het data station. Communicatie vanuit het algoritme verloopt hierbij altijd via de node naar de server.
 
 Wanneer gesproken wordt over specifieke implementaties wordt vaak de term *Aggregator Node* gebruikt. Hiermee wordt de node bedoeld waar aggregatie van deelresultaten plaats vindt. Hoewel het mogelijk is deze node op een aparte locatie te realiseren, verschilt deze technisch gezien niet van andere Vantage6 nodes. Elke Vantage6 Node is dus in potentie een aggregator node. Uitzondering hierop is de [*Secure Aggregator Node*](https://ai.jmir.org/2025/1/e60847). Deze oplossing wordt niet gebruikt binnen PLUGIN, maar bij specifieke use-cases om datalek problematiek tegen te gaan.
 
@@ -36,3 +33,94 @@ Wanneer gesproken wordt over specifieke implementaties wordt vaak de term *Aggre
 ### PLUGIN-ML
 ### PLUGIN-Hub
 ### PLUGIN-Lake
+
+## Federatief leren met PLUGIN/vantage6
+
+De PLUGIN-architectuur is gebaseerd op vantage6. Het gefedereerd leren van een algoritme omvat een reeks gecoördineerde stappen tussen de onderzoeker, de centrale server en de datastations. Dit proces is ontworpen om de analyse uit te voeren zonder dat de brongegevens de lokale omgeving van het datastation verlaten. Hieronder volgt een detailleerde beschrijving wat elk van de applicatiecomponenten hierin doen.
+
+![](./pht-workflow.png)
+
+???+ note "**Authenticatie**"
+
+    De onderzoeker start het proces door te authenticeren bij de centrale Vantage6-server.
+
+??? note "**Taak specificatie**"
+    
+    Na succesvolle authenticatie definieert de onderzoeker een taak. Hierbij wordt opgegeven:
+    *   Welk algoritme (Docker-image) gebruikt moet worden.
+    *   Specifieke inputparameters voor de analyse.
+    *   Het aantal iteraties (indien van toepassing, voor machine learning).
+    *   De identiteit van de *Secure Aggregation Server* (SAS), de node die verantwoordelijk is voor het aggregeren van resultaten.
+
+??? note "**Verzending naar nodes**"
+    
+    De centrale server stuurt de taak door naar de betrokken nodes. De SAS (Secure Aggregation Server, een specifieke node) ontvangt het verzoek als eerste.
+
+??? note "**Start hoofdalgoritme (SAS)**"
+    
+    De SAS downloadt het Docker-image, start het hoofd-algoritme en orkestreert de subtaken die door de datastations uitgevoerd moeten worden.
+
+??? note "**Start subtaken (datastations)**"
+    
+    De datastations ontvangen hun subtaak van de centrale server, downloaden hetzelfde Docker-image en starten het lokale deel van het algoritme. De analyse wordt uitgevoerd op de lokale data.
+
+??? note "**Verzending lokale resultaten**"
+    
+    Na elke trainingscyclus of analysestap stuurt het algoritme op het datastation de lokale resultaten (bijv. modelgewichten of statistische coëfficiënten) naar de SAS. De brongegevens verlaten het datastation niet.
+
+??? note "**Verificatie en aggregatie**"
+    
+    De SAS verifieert de resultaten, extraheert de metadata en voegt de resultaten van alle datastations samen tot een geaggregeerd tussenmodel. Dit voltooit één iteratie.
+
+??? note "**Vervolg-iteraties**"
+    
+    Voor vervolgstappen vragen de datastations de geaggregeerde resultaten van de vorige ronde op bij de SAS om hun lokale modellen verder te trainen. Deze cyclus herhaalt zich totdat het model convergeert of het gewenste aantal iteraties is bereikt.
+
+??? note "**Afronding**"
+    
+    De SAS informeert de onderzoeker dat de taak is voltooid. De onderzoeker kan vervolgens het finale, globale model downloaden van de server. Gedurende het proces heeft niemand, ook de onderzoeker niet, toegang tot de tussenresultaten, wat de veiligheid waarborgt.
+
+## PLUGIN en de European Interoperability Reference Architecture (EIRA)
+
+De architectuur van PLUGIN, gebaseerd op de principes van de Personal Health Train en Vantage6, kan worden beschreven aan de hand van de **European Interoperability Reference Architecture (EIRA)**. EIRA biedt een raamwerk om interoperabele architecturen te ontwerpen door herbruikbare *Architectural Building Blocks (ABBs)* te identificeren.
+
+Hoewel een gedetailleerde mapping naar specifieke EIRA ABB's een technische oefening is (vaak vastgelegd in een Archimate-model), kunnen we de componenten van PLUGIN conceptueel positioneren binnen de EIRA-gedachte. De architectuur is opgebouwd uit logische componenten die elk een specifieke rol vervullen, wat aansluit bij de EIRA-visie. De belangrijkste componenten, beschouwd als ABBs, zijn hieronder weergegeven.
+
+
+!!! note "PLUGIN in termen van EIRA architectural building blocks"
+
+    === "**Processing hub**"
+    
+        Fungeert als een intermediair voor communicatie, beheert metadata van taken en orkestreert de interacties. Dit kan worden gezien als een combinatie van EIRA ABBs gerelateerd aan *Message Exchange*, *Service Registry* en *Process Control*.
+
+    === "**Datastation**"
+        
+        De component binnen de jurisdictie van de datahouder (bv. een ziekenhuis). Het voorziet in de rekenkracht voor de lokale analyse en waarborgt dat data de eigen omgeving niet verlaat. Dit komt overeen met EIRA ABBs voor *Secure Data Processing* en *Service Consumption*.
+
+    === "**Secure Aggregation Server (SAS)**"
+    
+        Een gespecialiseerde node die verantwoordelijk is voor het veilig aggregeren van de lokale resultaten. Dit is een specifieke invulling van een *Data Processing* en *Security* ABB.
+
+    === "**Algoritme (Docker Image)**"
+    
+        Het "treintje" dat de analyse definieert. Het is een zelfstandige, uitvoerbare component die de logica, het model en de API bevat. Dit sluit aan bij het idee van een *Business Logic Component* of *Application Service* in EIRA.
+
+    === "**Beveiligde Communicatiekanalen**"
+    
+        De infrastructuur die veilige data-uitwisseling (van geaggregeerde resultaten, niet brongegevens) mogelijk maakt. Dit valt onder EIRA ABBs zoals *Secure Communication* en *Network Infrastructure*.
+
+Door de architectuur op deze manier in componenten op te delen, wordt een modulaire en interoperabele opzet gerealiseerd die in lijn is met de principes van EIRA voor het bouwen van grensoverschrijdende en sector-overstijgende digitale diensten.
+
+
+## PLUGIN en de composable data stack
+
+![](./datastation-eira.png)
+
+TO DO: uitleggen hoe al deze componenten eigenlijk een-op-een te vertalen zijn naar de moderne lakehouse architectuur.
+
+
+
+
+### Node Beheerder
+
+Vereist voor PLUGIN?

docs/implementaties/PLUGIN/datastation-eira.png

@@ -16,7 +16,7 @@ De PLUGIN infrastructuur implementeert verschillende componenten zoals in onders
     | PLUGIN-ML | gefedereerd leren |
     | PLUGIN-Hub | data pooling |
     | vantage6 server | centrale processing hub waarop gebruikers, organizaties, samenwerkingsverbanden taken en resultaten worden beheerd en georchestreerd |
-    | vantage6 UI | webapplicatie waarmee gebruikers kunnen interacteren met de serve |
+    | vantage6 UI | webapplicatie waarmee gebruikers kunnen interacteren met de server |
     | vantage6 API | programmatische aansturing van de server, incl. Python client en R client |
     | Docker registry | containers die zijn geautoriseerd om decentraal op de datastations uit te voeren |
     | Algorithm store | de metadata over de (algoritme) containers, inclusief ondersteuning van goedkeuringsproces |
@@ -25,8 +25,6 @@ De PLUGIN infrastructuur implementeert verschillende componenten zoals in onders
     | PLUGIN-Lake | Lakehouse voor serverless opslag en ETL transformaties op het datastation |
 
 
-
-
 ??? info "Externe documentatie"
 
     - [PLUGIN programma website](https://plugin.healthcare/)

docs/implementaties/PLUGIN/index.md

@@ -23,3 +23,42 @@ Om de interoperabiliteit van data te garanderen (zie Semantische en syntactische
 ### Data-extractie
 
 De extractie en standaardisering van EPD-data naar de gewenste FHIR profielen is afhankelijk van de EPD-leverancier. In het geval van Chipsoft Hix is scripting beschikbaar. In het geval van dagopname gerelateerde brongegevens biedt Epic functionaliteit aan voor het exporteren hiervan.Data dient te worden gepseudonimiseerd voordat het beschikbaar wordt gemaakt in het data station. Hiervoor zijn voor zowel EPIC als Chipsoft HiX scripts. In het geval van AIOC worden gegevens beschikbaar gesteld op het niveau van de individuele opname, informatie over zorgactiviteiten en ongestructureerde data. Deze data is afkomstig uit ontslagbrieven, polibrieven, operatieverslagen en de PA-verslagen.
+# Gebruik van informatiemodellen en thesauri in PLUGIN
+
+
+## Informatiemodellen voor syntactische interoperabiliteit
+
+Ten tijde van het schrijven van dit document heeft PLUGIN gewerkt met twee verschillende informatiemodellen die elk in een afzonderlijke usecase zijn beproefd c.q. geimplementeerd.
+
+!!! note "Informatiemodellen in PLUGIN"
+
+    === "FHIR"
+
+        Vanuit het originele ontwerp heeft PLUGIN in het gebruik van FHIR geprioriteerd. De overwegingen om dit informatiemodel te gebruiken is beschreven in een artikel door Kapitan et al. (2025).[@kapitan2025data] Een van de belangrijke principes hierin is dat van late-binding: doordat PLUGIN is bedoeld als generieke infrastructuur, is de gedachte dat het opleggen van condities en restricties in de binnenkomende data stapgewijs kan worden gedaan. Uitgaande van FHIR R4 als basis, wordt de data 'getrechterd' naar steeds specifiekere profielen, zijnde het zibs2020 profiel, nl-core en het profiel van de uiteindelijke toepassing, in dit geval de NCR-EHR profiel van de Nederlandse Kankerregistratie. 
+        
+        ![](./late-binding.png)
+
+        Deze aanpak is succesvol beproefd in een usecase met het RadboudUMC, waarbij gegevens voor hoofd-halskanker automatisch uit de Epic FHIR v3 API zijn onttrokken en vertaald naar het target profiel.
+
+    === "AI-ondersteund coderen"
+
+        Voor het project "AI-ondersteund coderen" wordt een specifieke set gegevens gebruikt. DHD heeft hiervoor een AI-model ontwikkeld dat op basis van ongestructureerde data (brievenverslagen) automatisch ICD-10 codes kan genereren voor dagopnames. 
+        
+        Deelnemende ziekenhuizen leveren hiervoor een dataset aan die bestaat uit:
+        
+        *   Brievenverslagen
+        *   Diagnoses
+        *   Opnames
+        *   Subtrajecten
+        *   Zorgactiviteiten
+
+        Binnen het project worden deze gegevens middels gestandaardiseerde extractiescript uit het bronsysteem onttrokken, zijnde Epic of Chipsoft HiX. Het [AIOC informatiemodel](https://plugin.healthcare/fhir/artifacts.html#logical-models-aioc) is een subset van de [Landelijke Basisregistratie Ziekenhuiszorg](https://www.dhd.nl/producten-diensten/registratie-data/ontdek-de-mogelijkheden-van-de-lbz/hulpmiddelen-lbz), een informatiemodel wat sinds 2014 in gebruik is. In principe kan het LBZ model gemapped worden naar FHIR, OMOP of openEHR, maar dit is nog niet gedaan.
+
+In de doorontwkkeling van PLUGIN is voorzien dat andere informatiemodellen (OMOP, openEHR) ondersteund gaan worden, met gebruik van de gestandaardiseerde transformaties tussen de drie informatiemodellen zoals is beschreven in de sectie over [syntactische interoperabiliteit](../../informatie/syntactisch.md).
+
+
+## DHD thesauri als basis voor semantische interoperabiliteit
+
+Voor semantische interoperabiliteit leunt PLUGIN sterk op de expertise en standaarden van DHD (Dutch Hospital Data), en specifiek de [Diagnose- en Verrichtingenthesaurus](https://www.dhd.nl/producten-diensten/registratie-data/oplossingen-voor-registratievraagstukken). Deze thesauri zijn zijn de landelijke standaarden voor de registratie van medische diagnosen respectievelijk verrichtingen. De thesauri bestaan uit lijsten met uniforme termen die worden ingeladen in het epd. Hierdoor kunnen artsen en andere zorgprofessionals de termen aan de bron vastleggen in de taal die zij in de praktijk gebruiken. Elke twee maanden verschijnen nieuwe versies, zodat de lijsten altijd actueel zijn. Door deze thesauri te gebruiken, zorgt PLUGIN ervoor dat analyses die over verschillende ziekenhuizen heen worden uitgevoerd, gebaseerd zijn op data met een consistente en gedeelde betekenis. Zo kunnen concepten automatisch worden afgeleid naar DBC-codes, ICD-10-codes, conciliumcodes (opleidingscodes) en het internationale terminologiestelsel SNOMED.
+
+In de doorontwikkeling van PLUGIN wordt gedacht om de thesauri uit te breiden met de [SSSOM-methode](https://mapping-commons.github.io/sssom/). Daarmee kunnen niet alleen mappings tussen verschillende codestelsel gemaakt worden, maar kan ook aangegeven worden of een mapping een `exactMatch`, een `broadMatch` of een `narrowMatch` is. Dit is van waarde omdat bijvoorbeeld in de huisartsen zorg veel bredere diagnosen worden geregistreerd zoals epilepsie, terwijl in een ziekenhuis of UMC in meer detail de diagnose wordt gecodeerd, bijvoorbeeld focale epilepsie.

docs/implementaties/PLUGIN/informatie.md

@@ -44,4 +44,4 @@ De bestanden aangeleverd door het ziekenhuis komen binnen in een map aanlevering
 * **coderingen** - De AIOC applicatie maakt hier een werkmap aan waar onder andere een kopie van de aangeleverde data, checkpoint bestanden en resultaten komen te staan. Dit is vooral een werkmap voor de data scientists.
 * **epd_output** - Hier worden de uiteindelijke resultaten/output bestanden klaargezet. Deze bestanden kunnen direct in het EPD geïmporteerd worden.
 * **latest** - In deze map wordt het laatste outputbestand van de AIOC applicatie geplaatst. Het bestand in deze map kan gebruikt worden om de resultaten te importeren in het EPD.
-* **TRAIN_DATA** - In deze map worden de trainingsdata opgeslagen. Deze map is alleen voor trainingsziekenhuizen en bevat data van meerdere jaren met ICD-10 codering om het model te trainen.
+* **TRAIN_DATA** - In deze map worden de trainingsdata opgeslagen. Deze map is alleen voor trainingsziekenhuizen en bevat data van meerdere jaren met ICD-10 codering om het model te trainen.