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) :

```bash
pip install pymupdf
```

## Utilisation

### Lister les documents disponibles

```bash
python tools/annotation_tool.py --list
```

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

### Annoter un document spécifique

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

### Reprendre l'annotation (mode automatique)

```bash
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 :

```json
{
  "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

```bash
# 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 :
```bash
ls tests/ground_truth/pdfs/
```

### Erreur "PyMuPDF not found"

Installer PyMuPDF :
```bash
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 ! 🎯**