Compagnon d'exploration bibliométrique HLA × Complications

Site compagnon permettant d'explorer la cartographie des co-occurrences textuelles entre allèles HLA et complications de transplantation rénale, avec accès systématique aux publications sources.

⚠️ Nature des données

Ce site cartographie des co-occurrences textuelles dans la littérature indexée PubMed : quels allèles HLA et quelles complications sont mentionnés ensemble, et à quelle fréquence par rapport au hasard.

Ce ne sont pas des associations cliniques ni causales. Un signal fort peut refléter une mode de publication, un biais d'indexation ou une erreur d'extraction.

Extraction automatique par NLP — précision mesurée 78,75 %, accord sur la détection de négation kappa = 0,44 (modéré). Environ 1 mention sur 5 est erronée. Toute lecture clinique exige de relire les sources ; le site y conduit systématiquement.

---

État du projet

Prototype en cours de construction. Objectif : support de discussion avec le chef du laboratoire HLA avant passage à l'échelle.

Élément	État
Document de conception	✅ docs/specs
Schéma SQLite + builder	✅ scripts/build_sqlite.py — 8 validations
Données synthétiques de développement	✅ scripts/gen_synthetic.py
Interface Next.js	✅ allèle, complication, article, auteur, graphe, recherche
Garde-fous automatisés	✅ routes + vocabulaire (src/__tests__/)
Bascule vers les données réelles	🔜 procédure documentée

---

Périmètre

	Inclus	Exclu
Corpus	A — espace allélique, N = 5 581	B — espace éplétique, N = 359
Navigation	HLA → complication → articles	—
Mise à jour	Corpus figé, versionné	Ingestion PubMed temps réel

Les univers A (allélique) et B (éplétique) sont strictement scindés : corpus distincts, dénominateurs statistiques distincts, vocabulaires d'entités distincts. Aucune vue ne les combine.

---

Architecture

Pipeline Python (externe)          Ce dépôt
─────────────────────────          ──────────────────────────────
PubMed → filtrage → NLP → stats
            │
            ▼
      CSV versionnés  ──────────►  build_sqlite.py
                                        │
                                        ▼
                                  corpus_A_v1.2.sqlite
                                  (artefact de build, + SHA-256)
                                        │
                                        ▼
                                   Next.js (lecture seule)

Principes :

• La base est un artefact de build, reconstructible et vérifiable par son SHA-256. Elle n'est jamais éditée via l'interface.
• Clés naturelles partout : pmid, forme IPD-IMGT (HLA-DQB1*02:01). Deux builds sur les mêmes sources produisent des clés identiques.
• Chaque valeur agrégée est traçable en deux clics jusqu'aux phrases sources qui la produisent.

---

Stack

Couche	Choix
Framework	Next.js (App Router) + TypeScript
Base de données	SQLite en fichier versionné, lecture seule
Recherche	FTS5 (SQLite natif)
Graphes	Sigma.js + graphology
Graphiques	Observable Plot
Styles	Tailwind

Dépendances épinglées

Trois choix de versions sont délibérés. Ils paraissent arbitraires au milieu des autres plages ^, mais les « corriger » casse le build. Le projet cible Node 20 en local ; engines accepte aussi Node 22, que Vercel utilise (Node 20 n'y est plus proposé) :

• better-sqlite3 figé à 12.2.0, sans ^. C'est la dernière version publiant un binaire précompilé pour Node 20 / win32-x64 (ABI 115). Au-delà, npm install bascule sur node-gyp, qui échoue sans toolchain MSVC (« You need to install Visual Studio »). À réévaluer en passant à Node 22+.
• jsdom maintenu en ^26. jsdom@27 tire @asamuzakjp/css-color@4, qui fait un require() d'un module ESM : ERR_REQUIRE_ESM au démarrage du worker Vitest sous Node 20.
• vitest.config.mts, et non .ts. Vitest 4 charge sa config en CJS ; l'extension .ts déclenche ERR_REQUIRE_ESM sur std-env. L'alternative ("type": "module") casserait postcss.config.mjs et tailwind.config.ts.

---

Données de développement

Le prototype se développe sur un jeu de données synthétique conforme au contrat de schéma, en attendant le rapatriement des sorties réelles du pipeline.

⚠️ Toute interface alimentée par les données synthétiques affiche un bandeau explicite. Les chiffres synthétiques ne doivent jamais être pris pour des résultats.

Le builder est écrit pour avaler les CSV réels sans modification. Bascule par une commande.

Déploiement (Vercel)

La base n'étant pas versionnée, npm run build déclenche d'abord scripts/ensure-db.mjs (prebuild) : si la base est absente, il la reconstruit depuis data/synthetic avec scripts/build_sqlite.py (Python, bibliothèque standard). next.config.ts force ensuite l'inclusion de dist/*.sqlite dans les fonctions serverless (outputFileTracingIncludes).

---

Documentation

• Document de conception complet — modèle de données, prototypes UI, décisions et justifications.
• Organes et strates statistiques — corpus multi-organe (sept organes), ?organe= dans l'URL, statistiques recalculées par strate, garde-fous.
• Bascule vers les données réelles — repère de vérification, correspondance des CSV, retrait du bandeau synthétique, checklist de re-vérification.

---

Contexte scientifique

Ce site accompagne une série de publications bibliométriques sur le rôle du typage HLA dans les complications de transplantation, suivant la méthodologie de Donthu et al. (2021) — Performance Analysis + Science Mapping.