Labcodeset onderhoud

Onderhoud

Database structuur

In de collectie data/lab_concepts zit een <lab_concept> element per rij in de LCS. Hierin zit het Engelse en Nederlandse LOINC concept zoals uit LOINC geïmporteerd. DE Nederlandse Long Common Name wordt gegenereerd, deze wordt toegevoegd bij gebruik van de functies in api-labterm.xqm.

Er zijn meer children in <lab_concept>: materials, units, outcomes en errors. Voor errors zie de gebruikershandleiding. De andere bevatten <material> of <unit> een of <valueSet> met een @ref attribuut wat wijst naar een @id in de collecties materials.xml, units.xml of ordinals.xml. Er is ook een methods child mogelijk, maar dat wordt (nog?) niet gebruikt.

Lab concepts leunen erg op de Panels. De panel structuur wordt geimporteerd uit loinc.

Naast de lab_concepts zijn er nog:

local_panels, met de Nederlandse varianten op internationale panels
loinc-system-to-snomed: een mapping tabel tussen System en Snomed, meestal children van Specimen (maar niet altijd)
materials, units, ordinals, nominals met de te gebruiken bronnen. Er is maar een nominale lijst, deze is nu hard-coded aanwezig
prerelease, hierin kunnen concepten uit de LOINC prerelease tabel opgenomen worden. De prerelease HTML tabel kan ingelezen worden met een Jupyter Notebook.
old_data, hierin zitten data van voor een LOINC-upgrade, wordt automatisch overschreven de volgende keer

Rijen uit units en materials mogen nooit verwijderd worden, uitgegeven id's moeten uniek blijven, deze moeten status=retired krijgen als ze niet meer gebruikt worden.

Nieuwe LOINC release

Wanneer er een nieuwe release van LOINC geïnstalleerd is, moeten de concepten in de Labcodeset bijgewerkt worden. Dat gebeurt door een eXist gebruiker met 'dba' rechten, door het draaien van de XQuery (in helpers) 'update-from-loinc.xquery'.

Deze zal:

LOINC concepten vervangen door de nieuwere LOINC concepten
Controleren of status LOINC <> ACTIVE is voor concepten die wel 'active' zijn in LCS
Alle assen behalve Component (dus: System, Property, Timing, Scale, Method) controleren op wijzigingen tussen de LCS versie en de nieuwe LOINC versie
Foutmelding toevoegen voor beide bovenstaande issue, en indien van toepassing de status in LCS van 'active' naar 'update' zetten.
Alle concepten die na bovenstaande controles 'active' zijn in de LCS, controleren op nieuwe fouten (b.v. als gevolg van een gewijzigde panel inhoud). Deze worden bij fouten alsnog op 'update' gezet.

Stappen: Vooraf:

tellen van errors (count-errors.xquery) en statussen (count-status.xquery), bewaar resultaten
maak een "vooraf" publicatie

Uitvoeren:

installeer laatste LOINC release (doe dit pas na de "vooraf" stap, anders worden wijzigingen in panels niet goed geregistreerd)
draai update-from-loinc.xquery, kan een tijd duren (tel eventueel status tussendoor om voortgang te zien
de praktijk wijst uit dat een reindex zinvol kan zijn
draai update-all-nllongnames.xquery: deze werkt de NL longname bij aan de hand van de nieuwe NL concepten uit de release (opgeslagen longNames performen veel sneller, als er geen NL longName is wordt die 'on the fly' samengesteld)
draai check-active-concepts.xquery: deze zal fouten n.a.v. de LOINC release signaleren, o.a. panels die members erbij hebben, of members die niet meer 'active' zijn, deze controles kunnen pas gedraaid worden nadat alle concepten zijn bijgewerkt

Na draaien:

tellen van errors (count-errors.xquery) en statussen (get-lab-concepts-counts.xquery)
er zullen meestal concepten van active->update zijn gezet, meld deze aan de gebruikers (ze zijn ook te vinden met err:FOUT zoekopdrachten)
maak een "achteraf" publicatie
maak een delta vooraf-achteraf
controleren en verwijderen van old-data als alles goed gegaan is
de eventuele prerelease.xml leeg maken of vervangen door de laatste prerelease van LOINC
controleer met err:PRERELEASE of er nog prerelease concepten in de database zitten, dat zou niet zo moeten zijn. Indien toch, overleg met gebruikers.
meld gebruikers dat e.e.a. afgerond is, stuur (link naar) delta mee

Bijwerken LOINC-Snomed mapping

In de LOINC-Snomed tabel (loincsystem-to-snomed.xml) zitten de mappings tussen LOINC System en Snomed concepten. Voor één LOINC System kunnen meerdere rijen voorkomen, b.v. LOINC System "Bld/Tiss" mapt op Snomed concept "Blood (Specimen)" en "Tissue (Specimen)". Deze tabel is geïmporteerd uit de LOINC-Snomed mapping van Regenstrief. Daarnaast zitten er rijen in die niet in die mapping zitten, dat zijn de "dubbele" Systems (Bld/Tiss) en aparte gevallen (^Mother).

Publicatie

Gebruikers kunnen een publicatie maken. Het publicatieproces genereert:

lab-concepts-full-{timestamp}.xml, dit is de uitvoer van het publicatieproces.
lab-concepts-{timestamp}.xml, een vereenvoudigde versie, gemaakt met simplify-publication.xsl, dit is de te publiceren versie. Door de 2-fasen aanpak is het eindgebruikersformaat eenvoudig aan te passen.
lab-concepts-{timestamp}.html, een leesbare versie, gemaakt uit de full-versie met publicatie2html.xsl.

Noot: de eerste publicatie kent deze 3 varianten niet, alleen een lab-concepts-{timestamp}.xml met een 'full' versie erin.

Wanneer een <publication... attribuut @publication="true" heeft, is verwijderen via de UI niet mogelijk, en hebben alle gebruikers, ook guest, 'read' toegang. Zetten van @publication gebeurt via Oxygen.

Diffs

Worden gemaakt met diff-publications.xquery, nu nog vanuit de db, UI is todo. Input zijn twee timestamps zoals die in @effectiveDate in een publicatie zitten. Als invoer worden 2 full publicaties gebruikt. Uitvoer is:

diff-{timestamp}-{timestamp}.xml
diff-{timestamp}-{timestamp}.html

Prerelease

Het inlezen van prereleases van https://loinc.org/prerelease/ gebeurt met een Jupyter notebook, te vinden op: https://github.com/Nictiz/Labcodeset Deze kan (b.v.) gedraaid worden op Colab (alternatieven zijn Azure, Binder of Jupyterlab lokaal installeren). Volg de volgende stappen:

ga naar https://colab.research.google.com/
log in met Google credentials, kan gewoon een GMail account of zo zijn
kies File -> Upload notebook...
Kies de Github tab
Voer "nictiz" in in zoekveld en Enter, er komt een dropdown waar Nictiz/Labcodeset gekozen kan worden
Kies bij de notebooks die verschijnen prerelease/prerelease.ipynb
Volg de instructies. "Run" zit bij Colab in de [>] vakjes. Alle vakjes [>] aanklikken
Je kunt naar 'Acceptatie' testen bij de dropdown.
Je kunt ook naar "Productie".
De notebook overschrijft dan met de meest recente prerelease van Regenstrief. Prereleases zijn cumulatief, dus dat is in orde, alleen na een nieuwe LOINC release zet Regenstrief de prelease tabel weer op leeg.
Let wel altijd op: even visueel de uitvoer controleren na inlzen van de Regenstrief HTML prerelease: als ze weer iets wijzigen, kan het zijn dat de code niet werkt.