anonymisation/docs/annotation_guide.md

Guide d'Annotation - Dataset de Test

Vue d'Ensemble

Ce guide explique comment utiliser l'outil d'annotation CLI pour créer le dataset de test annoté nécessaire à l'évaluation de la qualité d'anonymisation.

Objectif

Créer un corpus de 27 documents PDF annotés manuellement avec :

• Tous les PII (Personally Identifiable Information) présents
• Le type de chaque PII (NOM, TEL, EMAIL, etc.)
• Le contexte de détection
• Les termes médicaux à préserver

Installation

L'outil d'annotation nécessite PyMuPDF (fitz) :

pip install pymupdf

Utilisation

Lister les documents disponibles

python tools/annotation_tool.py --list

Affiche la liste des 27 documents avec leur statut d'annotation.

Annoter un document spécifique

python tools/annotation_tool.py tests/ground_truth/pdfs/001_simple_unknown_BACTERIO_23018396.pdf

Reprendre l'annotation (mode automatique)

python tools/annotation_tool.py --resume

Trouve automatiquement le prochain document non annoté et lance l'annotation.

Workflow d'Annotation

1. Métadonnées du document

Au démarrage, l'outil demande :

• Nom de l'annotateur : Votre identifiant (ex: annotator_1)
• Type de document :
  • compte_rendu : Compte-rendu hospitalier
  • trackare : Document Trackare
  • anapath : Compte-rendu d'anatomopathologie
  • bacterio : Résultat de bactériologie
  • consultation : Consultation médicale
  • autre : Autre type
• Difficulté globale :
  • simple : 1-2 pages, peu de PII
  • moyen : 3-5 pages, PII variés
  • complexe : >5 pages, nombreux PII

2. Annotation page par page

Pour chaque page :

1. Affichage du texte : Le texte de la page est affiché
2. Confirmation : "Annoter cette page? [O/n]"
3. Annotation des PII : Pour chaque PII détecté

Annotation d'un PII

Pour chaque PII, l'outil demande :

a) Texte du PII

Texte du PII (ou 'q' pour terminer, 's' pour sauter): DUPONT

• Entrez le texte exact du PII tel qu'il apparaît dans le document
• q : Terminer l'annotation de cette page
• s : Sauter cette annotation

b) Type de PII

Type de PII:
  1. NOM
  2. PRENOM
  3. DATE_NAISSANCE
  4. AGE
  5. TEL
  6. EMAIL
  7. ADRESSE
  8. CODE_POSTAL
  9. VILLE
  10. NIR
  11. IPP
  12. NDA
  13. RPPS
  14. FINESS
  15. OGC
  16. NUMERO_PATIENT
  17. NUMERO_LOT
  18. NUMERO_ORDONNANCE
  19. NUMERO_SEJOUR
  20. ETABLISSEMENT
  21. SERVICE
  22. DATE
  23. AUTRE
Choix [1-23]:

c) Contexte

Contexte détecté: Dr. DUPONT a examiné le patient...
Utiliser ce contexte? [O/n]:

• L'outil détecte automatiquement le contexte (50 caractères avant/après)
• Vous pouvez l'accepter ou saisir un contexte manuel

d) PII obligatoire (RGPD)?

PII obligatoire (RGPD)? [O/n]:

• O (défaut) : PII obligatoire selon le RGPD (doit être masqué)
• n : PII optionnel (peut être masqué ou non)

e) Difficulté de détection

Difficulté de détection:
  1. easy (défaut)
  2. medium
  3. hard
Choix [1-3]:

• easy : Facilement détectable (format structuré, contexte clair)
• medium : Détection moyenne (contexte faible, format variable)
• hard : Difficile à détecter (manuscrit, mal orienté, format inhabituel)

f) Méthodes de détection attendues

Méthodes de détection attendues (séparées par des virgules):
  Options: regex, vlm, ner, contextual, trackare
Méthodes [regex,ner]:

• regex : Détectable par expressions régulières
• vlm : Détectable par Vision Language Model (manuscrit, scanné)
• ner : Détectable par Named Entity Recognition
• contextual : Détectable par analyse contextuelle
• trackare : Détectable par extraction Trackare

Exemples :

• Téléphone : regex
• Nom manuscrit : vlm,ner
• Nom après "Dr." : regex,ner,contextual

3. Termes médicaux à préserver

Après l'annotation des PII, l'outil demande les termes médicaux qui ne doivent PAS être masqués :

=== Termes médicaux à préserver ===
Entrez les termes médicaux qui ne doivent PAS être masqués
(un par ligne, ligne vide pour terminer)
Terme médical: Médecin DIM
✓ Ajouté: Médecin DIM
Terme médical: Service de cardiologie
✓ Ajouté: Service de cardiologie
Terme médical: 

Exemples de termes à préserver :

• Noms de services : "Service de cardiologie", "Urgences"
• Fonctions : "Médecin DIM", "Praticien conseil"
• Établissements génériques : "Centre Hospitalier"
• Termes médicaux : "Diabète", "Hypertension"

4. Sauvegarde

Les annotations sont sauvegardées automatiquement dans :

tests/ground_truth/pdfs/<nom_du_pdf>.annotations.json

Format de Sortie

Le fichier JSON généré contient :

{
  "pdf_path": "tests/ground_truth/pdfs/001_simple_unknown_BACTERIO_23018396.pdf",
  "metadata": {
    "annotator": "annotator_1",
    "annotation_date": "2024-01-15T10:30:00",
    "document_type": "bacterio",
    "page_count": 1,
    "difficulty": "simple"
  },
  "annotations": [
    {
      "id": "ann_001",
      "page": 0,
      "type": "NOM",
      "text": "DUPONT",
      "bbox": null,
      "context": "Dr. DUPONT a examiné le patient",
      "mandatory": true,
      "difficulty": "easy",
      "detection_method_expected": ["regex", "ner", "contextual"]
    }
  ],
  "medical_terms_to_preserve": [
    "Médecin DIM",
    "Service de cardiologie"
  ],
  "statistics": {
    "total_pii": 1,
    "by_type": {
      "NOM": 1
    }
  }
}

Bonnes Pratiques

Exhaustivité

• Annoter TOUS les PII : Ne pas oublier les PII peu évidents
• Vérifier toutes les pages : Même les pages qui semblent vides
• Inclure les PII partiels : Ex: "M. D***" si le nom est partiellement masqué

Cohérence

• Utiliser les mêmes types : "NOM" pour tous les noms de famille
• Contexte significatif : Inclure suffisamment de contexte pour comprendre
• Difficulté réaliste : Évaluer objectivement la difficulté de détection

Qualité

• Texte exact : Copier-coller le texte exact du PII
• Pas de fautes : Vérifier l'orthographe
• Termes médicaux : Lister tous les termes à préserver

Types de PII - Guide de Référence

Type	Description	Exemples
NOM	Nom de famille	DUPONT, MARTIN
PRENOM	Prénom	Jean, Marie
DATE_NAISSANCE	Date de naissance	15/03/1980
AGE	Âge	45 ans
TEL	Téléphone	01 23 45 67 89
EMAIL	Email	jean.dupont@example.com
ADRESSE	Adresse postale	12 rue de la Paix
CODE_POSTAL	Code postal	75001
VILLE	Ville	Paris
NIR	Numéro de sécurité sociale	1 80 03 75 001 234 56
IPP	Identifiant Permanent Patient	12345678
NDA	Numéro de Dossier Administratif	23042753
RPPS	Numéro RPPS (médecin)	10001234567
FINESS	Numéro FINESS (établissement)	750000001
OGC	Numéro OGC	257
NUMERO_PATIENT	Numéro de patient	PAT-12345
NUMERO_LOT	Numéro de lot	LOT-2024-001
NUMERO_ORDONNANCE	Numéro d'ordonnance	ORD-12345
NUMERO_SEJOUR	Numéro de séjour	SEJ-2024-001
ETABLISSEMENT	Nom d'établissement	CHU de Bordeaux
SERVICE	Nom de service	Cardiologie
DATE	Date quelconque	15/01/2024
AUTRE	Autre type de PII	-

Estimation du Temps

• Document simple (1-2 pages) : 15-30 minutes
• Document moyen (3-5 pages) : 30-60 minutes
• Document complexe (>5 pages) : 1-2 heures

Total pour 27 documents : ~20-30 heures

Validation

Après annotation, vérifier :

1. Tous les PII sont annotés : Relire le document
2. Types corrects : Vérifier la cohérence des types
3. Contexte pertinent : Le contexte aide à comprendre le PII
4. Termes médicaux : Liste complète des termes à préserver

Commandes Utiles

# Lister les documents
python tools/annotation_tool.py --list

# Annoter le prochain document
python tools/annotation_tool.py --resume

# Annoter un document spécifique
python tools/annotation_tool.py tests/ground_truth/pdfs/001_simple_unknown_BACTERIO_23018396.pdf

# Compter les documents annotés
ls tests/ground_truth/pdfs/*.annotations.json | wc -l

# Afficher les statistiques d'un document annoté
cat tests/ground_truth/pdfs/001_simple_unknown_BACTERIO_23018396.annotations.json | jq '.statistics'

Dépannage

Erreur "Fichier introuvable"

Vérifier que le PDF existe :

ls tests/ground_truth/pdfs/

Erreur "PyMuPDF not found"

Installer PyMuPDF :

pip install pymupdf

Annotations écrasées par erreur

Les annotations sont sauvegardées dans des fichiers .annotations.json séparés. Si vous écrasez par erreur, il n'y a pas de backup automatique. Faites des commits Git réguliers !

Support

Pour toute question ou problème :

1. Consulter ce guide
2. Vérifier les exemples dans tests/ground_truth/pdfs/
3. Contacter l'équipe projet

---

Bon courage pour l'annotation ! 🎯