# Comment lire un rapport Picarones Ce guide est destiné aux utilisateurs qui ouvrent un rapport HTML Picarones pour la première fois — archivistes, conservateurs, chercheurs en humanités numériques, prestataires de numérisation. > **Principe directeur du rapport** : il présente les faits, jamais un > verdict. Aucun moteur n'est étiqueté « recommandé ». L'utilisateur lit > et décide ; l'outil l'équipe pour décider. ## Anatomie du rapport Un rapport Picarones est un fichier HTML autonome (~450 Ko, Chart.js embarqué). Il s'ouvre dans n'importe quel navigateur récent, sans serveur ni connexion réseau. Vous pouvez l'envoyer par e-mail, l'archiver, ou le déposer sur Zenodo (export DOI prévu en Phase 4). Il s'organise en cinq sections, du général vers le spécifique : ### En-tête — synthèse + diagnostic statistique Visible dès l'ouverture, sans navigation. Contient : 1. **Synthèse factuelle** — 3 à 5 phrases générées mécaniquement à partir des résultats. Aucun LLM dans la chaîne, donc le texte est reproductible bit-à-bit. Chaque nombre cité est traçable au JSON de résultats. Voir [docs/explanation/narrative-engine.md] pour la liste complète des faits que le moteur peut détecter. 2. **Critical Difference Diagram** (Friedman-Nemenyi) — un graphique horizontal qui place chaque moteur sur un axe de rang moyen. Les barres horizontales relient les moteurs **statistiquement indiscernables** au seuil α = 0,05. Si deux moteurs sont reliés, leur différence de CER moyen n'est pas significative ; le choix entre eux doit se faire sur d'autres critères (coût, vitesse, robustesse, profil d'erreur). ### Vue Classement Tableau triable par colonne. Chaque en-tête a un petit `?` cliquable qui ouvre le **glossaire contextuel** (définition, ce que la métrique mesure, cas d'usage historique, limites, référence bibliographique). Colonnes principales : - **CER exact** vs **CER diplomatique** : le diplomatique fusionne `ſ=s`, `u=v`, `i=j`, etc. — utile pour les corpus pré-XIXᵉ. - **WER, MER, WIL** : variantes mot-à-mot. - **Ligatures, Diacritiques** : pertinent pour les corpus patrimoniaux. - **Gini** : concentration des erreurs dans le document. Un Gini élevé signale qu'une petite fraction des lignes concentre la majorité des erreurs. - **Ancrage trigrammes** : pour LLM/VLM. Un score bas signale des hallucinations probables. ### Vue Galerie / Document Inspection page par page, avec diff coloré GT/OCR par moteur. Particulièrement utile pour les pipelines OCR+LLM : vous pouvez voir **les trois couches** (image, OCR brut, correction LLM) et identifier les zones où le LLM a apporté de la valeur ou, au contraire, halluciné. ### Vue Caractères Matrice de confusion Unicode + taxonomie des erreurs en 9 classes (confusion visuelle, diacritique, casse, ligature, abréviation, hapax, segmentation, OOV, lacune). Utile pour identifier les **patterns systématiques** d'un moteur — par exemple : « ce moteur fait 40 % d'erreurs d'abréviation, donc il ne saura pas lire mon corpus notarié ». ### Vue Analyses Graphiques Chart.js avancés : - **Vue Pareto qualité/coût/vitesse/carbone**. Les moteurs sur la frontière de Pareto (en vert) sont ceux pour lesquels aucun autre n'offre simultanément un meilleur CER ET un meilleur coût. Choisir hors du front est toujours sous-optimal ; choisir sur le front dépend de vos priorités. Les prix sont indicatifs et datés — voir les hypothèses détaillées sous le graphique. - Histogrammes, radar, scatter plots, courbes de fiabilité. - Bootstrap CI, tests de Wilcoxon pairwise, clustering d'erreurs, matrice de corrélation. ## Le bouton « ⚙ Avancé » Dans la nav (en haut à droite). Ouvre un panneau latéral avec : - **Choix de colonnes visibles** — masquez les colonnes qui ne vous intéressent pas pour réduire la charge cognitive. - **Filtres par strate** — quand le corpus expose `script_type` par document, vous pouvez filtrer (ex. ne voir que les documents en textualis). - **Score composite personnel** — strictement opt-in. Tous les curseurs démarrent à 0. Quand vous ajustez les poids, la formule du score s'affiche en clair sous les curseurs et une nouvelle colonne « Score » apparaît dans le tableau. > ⚠️ **Avertissement explicite affiché dans le panneau** : > « Ces poids reflètent votre cas d'usage. Il n'existe pas de pondération > universellement valide — Picarones ne suggère aucune pondération par > défaut. » > > Picarones ne fait pas de recommandation à votre place. Le score > composite est un outil que vous construisez vous-même. L'état de personnalisation est persisté dans l'URL (`?hidden=…&w=…`), donc vous pouvez partager une vue avec votre équipe en envoyant le lien. ## Le mode « ⊞ Présentation » Masque les éléments techniques (boutons `?`, mode avancé, hints) pour projeter le rapport en réunion ou pour l'imprimer. Les nombres et graphiques restent identiques. ## Export CSV Bouton « ⬇ CSV » dans la nav. Exporte la vue courante (avec les filtres de personnalisation appliqués) en CSV pour réutilisation dans Excel ou LibreOffice. ## Que faire si vous ne savez pas par où commencer ? 1. Lisez la **synthèse en tête** (3 à 5 phrases) — elle pointe les faits saillants. 2. Regardez le **CDD** : si tous les moteurs sont reliés par une seule barre horizontale, votre corpus n'est pas assez discriminant pour trancher sur la base statistique seule. Cherchez d'autres critères (coût, profil d'erreur). 3. Ouvrez la **vue Pareto** : si un moteur du front Pareto est très moins cher que le leader CER, c'est probablement votre meilleur compromis pratique. 4. Consultez les **études de cas** dans `docs/case-studies/` pour voir comment d'autres équipes ont raisonné sur des problèmes similaires. ## Pour aller plus loin - [Glossaire complet] (intégré dans le rapport, accessible via les `?`) - [docs/explanation/narrative-engine.md] — comment ajouter un détecteur - [docs/developer/extending-glossary.md] — comment enrichir le glossaire - [SPECS.md] — spécifications complètes du projet ## Mode `--lazy-images` pour les corpus volumineux Sprint A5 (item M-16 de l'audit institutionnel). Par défaut, le rapport HTML est un **fichier unique** transportable : toutes les images sont embarquées en base64 dans le HTML lui-même. C'est pratique pour partager un rapport par e-mail ou pour archivage, mais le fichier devient lourd dès quelques dizaines de documents : | Taille du corpus | HTML inline | HTML lazy | |---|---|---| | 10 docs | ~5 MB | ~3 MB + dossier d'assets ~2 MB | | 50 docs | ~50 MB | ~3 MB + ~10 MB d'assets | | 500 docs | ~250 MB ramant à charger | ~3 MB + ~100 MB d'assets, chargés à la demande | | 1000 docs | inutilisable en pratique | reste fluide (lazy loading natif HTML) | Pour les bibliothèques numériques qui benchmarkent des milliers de documents, activez le mode lazy : ```bash picarones report --results results.json --output report.html --lazy-images ``` Le rapport produit reste **auto-portant** : il suffit de copier ``report.html`` ET le dossier ``report-assets/`` créé à côté pour partager. Les images sont référencées par chemin relatif et chargées par le navigateur uniquement quand elles entrent dans le viewport (``loading="lazy"`` du HTML5).