Générer les scripts

Deux générateurs, une seule chaîne

Écrire à la main la conversion d’un dossier patient vers OMOP, c’est des centaines de lignes de SQL qui répètent ce que Linkr sait déjà : le mapping de schéma de la base source dit où sont ses patients, ses séjours et ses événements, celui de la base cible dit où OMOP les range, et un projet d’alignement dit à quel concept standard correspond chacun de vos codes.

Chaque générateur écrit ses fichiers dans l’onglet Scripts du pipeline, numérotés pour s’intercaler : le vocabulaire d’abord, puis les patients, les séjours, les événements, et l’élagage du vocabulaire en dernier. Un script écrit à la main s’insère entre eux par son numéro.

Générer les scripts de chargement OMOP

Ce qu’il faut avant

Les deux bases du pipeline doivent avoir un mapping de schéma :

• la source, pour que Linkr sache lire ses patients, ses séjours et ses tables d’événements ;
• la cible, pour qu’il sache où les écrire. Une base OMOP vide créée avec Nouveau depuis un schéma l’a d’office — voir Bases de données.

Sans l’un ou l’autre, la fenêtre le dit (« La base source n’a pas de mapping de schéma », « La base cible n’a pas de mapping de schéma : créez-la depuis un schéma OMOP ») et ne propose rien.

Ouvrir le générateur

Dans l’onglet Scripts, la barre de l’explorateur de fichiers a trois boutons : Nouveau fichier, Importer des fichiers, et la baguette Générer depuis les schémas. Elle ouvre la fenêtre Générer les scripts de chargement OMOP.

La fenêtre se lit de haut en bas : deux réglages, les tables d’événements à répartir, puis la liste des scripts qui seront écrits. Écrire N scripts les crée dans l’onglet Scripts, sans rien exécuter.

Les réglages

• Concepts — comment un code source devient un concept_id OMOP :

Les deux premières options lisent ce que le script de vocabulaire a écrit dans la cible (voir plus bas) : c’est pourquoi 00_vocabulary.sql passe en premier. Un code qui ne trouve pas de correspondance reçoit le concept 0, comme le veut OMOP pour « non aligné ». Le réglage proposé d’emblée est Identifiants source, déjà OMOP quand aucun projet d’alignement n’est rattaché au pipeline, le vocabulaire du pipeline sinon : vérifiez qu’il correspond à la représentation choisie dans l’onglet Vocabulaire.

• Concept de type — la valeur écrite dans chaque colonne *_type_concept_id, qui dit d’où vient l’enregistrement. 32817 signifie EHR, le dossier patient informatisé.

• Tables d’événements et de médicaments — une ligne par table d’événements de la source, telle que son mapping la nomme (« Biologie », « Administrations »…), avec la table OMOP où la charger. Linkr en propose une : la table cible qui porte le même nom dans le mapping de la cible, ou drug_exposure pour une table marquée Médicament. À défaut, la ligne démarre sur Ne pas charger, qui l’écarte ; un avertissement le rappelle sous la liste des scripts.

Ce que produit chaque script

Un script par classe de la source, dans l’ordre où OMOP les attend :

Chaque script vide d’abord sa table (TRUNCATE), puis la remplit d’un seul INSERT … SELECT qui lit la relation standard de la source — celle que son mapping définit, recopiée en tête de requête. Relancer le pipeline recharge donc la table, sans doublons.

-- Generated by Linkr from the source schema "Réa CHU — export": visit → visit_occurrence.
-- Edit freely: regenerating asks before overwriting an edited script.
-- linkr-generated: 5c1e09a4

TRUNCATE target.visit_occurrence;

INSERT INTO target.visit_occurrence (visit_occurrence_id, person_id, visit_concept_id, visit_start_date, visit_start_datetime, visit_end_date, visit_end_datetime, visit_type_concept_id, care_site_id)
WITH linkr_visit AS NOT MATERIALIZED (
  -- la relation « séjours » du mapping de la source
)
SELECT
  s.visit_id AS visit_occurrence_id,
  s.patient_id AS person_id,
  0 AS visit_concept_id,
  CAST(s.start_datetime AS DATE) AS visit_start_date,
  s.start_datetime AS visit_start_datetime,
  COALESCE(CAST(s.end_datetime AS DATE), CAST(s.start_datetime AS DATE)) AS visit_end_date,
  s.end_datetime AS visit_end_datetime,
  32817 AS visit_type_concept_id,
  s.care_site_id AS care_site_id
FROM linkr_visit s;

Au passage, le générateur applique les règles d’OMOP que l’on oublie facilement :

• les dates — une colonne *_date est tirée de son *_datetime ; une date de fin inconnue devient la date de début, quand la colonne est obligatoire ;
• les colonnes obligatoires — un *_concept_id que rien ne remplit reçoit 0 ; toute autre colonne NOT NULL que la source ne sait pas remplir reçoit NULL et un commentaire -- TODO(etl): … qui le signale, plutôt qu’une valeur inventée ;
• les identifiants — un événement sans identifiant propre dans la source est numéroté à chaque exécution, et un TODO rappelle que ces clés changeront d’un chargement à l’autre.

Sous la liste des scripts, des avertissements en orange signalent ce qui n’a pas pu être écrit : une table absente de la DDL de la cible (seules les colonnes que son mapping nomme sont alors écrites), une classe de la source que le mapping de la cible ne place nulle part, une table d’événements laissée à Ne pas charger.

Régénérer sans perdre ses modifications

Un schéma évolue, un mapping se corrige : on régénère. Chaque script généré porte dans son en-tête une ligne -- linkr-generated: suivie d’une empreinte de son contenu, qui permet à Linkr de savoir si quelqu’un l’a modifié depuis. La liste des scripts dit ce qui va se passer pour chacun :

• nouveau — le fichier n’existe pas encore, il sera créé ;
• régénéré — il existe et n’a pas été touché depuis sa génération : il sera remplacé ;
• modifié — écraser — il a été modifié à la main, ou un script écrit à la main porte déjà ce nom. Il n’est pas touché, sauf si vous cochez la case.

Retoucher un script généré est donc sans risque : vos ajustements survivent à la régénération tant que vous ne cochez pas la case.

Générer le vocabulaire depuis un projet d’alignement

Aligner des codes locaux sur des concepts standard se fait dans un projet d’alignement de concepts — une interface faite pour ça, avec suggestions et évaluation. L’onglet Vocabulaire du pipeline sait lire ce travail et le transformer en SQL qui charge ces correspondances dans la base cible.

À gauche, ce qui entre :

• Depuis un projet d’alignement de concepts — le projet dont lire les correspondances.
• Sélectionner les statuts à exporter — les alignements retenus selon leur statut (Approuvé, Non vérifié…), avec pour les approuvés la règle à appliquer : Au moins une approbation, Plus d’approbations que de rejets ou Aucun rejet.
• Inclure tous les concepts sources — charge aussi les codes locaux qu’aucun alignement retenu ne couvre. Sans eux, un code non aligné n’a pas de source_concept_id à écrire dans OMOP.

À droite, ce qui sort :

• Représentation du vocabulaire — CONCEPT + CONCEPT_RELATIONSHIP, la représentation OMOP actuelle ; SOURCE_TO_CONCEPT_MAP, l’ancienne ; ou les deux.
• Fichiers à écrire — l’export des alignements en CSV, le script de vocabulaire 00_vocabulary.sql, qui copie le vocabulaire de référence et vos concepts locaux dans la cible, et le script d’élagage 99_prune_vocabulary.sql, qui l’allège ensuite : il ne garde que les concepts que les tables OMOP utilisent vraiment, leurs ancêtres et ce qui s’y rattache.

Sous chaque fichier déjà présent, une ligne dit où il en est : Déjà à jour s’il est identique à ce qui serait généré, Diffère de ce qui serait généré s’il a été modifié depuis — dans les deux cas, il faut cocher pour le réécrire. On évite ainsi d’écraser un ajustement sans s’en apercevoir.

Pour aller plus loin

• Pipelines ETL — ce qu’est un pipeline, et les rôles source, cible et vocabulaire.
• Construire et exécuter un pipeline — exécuter les scripts générés, puis contrôler ce qui a été chargé.
• Schémas — les mappings dont le générateur tire les scripts de chargement.
• Alignement de concepts — produire les correspondances que le vocabulaire consomme.