# Guide d'analyse de corpus **Version**: 1.0.0-rc.4 *(re-verified)* **Dernière mise à jour**: 2026-07-20 --- ## Vue d'ensemble ClioDeck offre des outils d'analyse de corpus permettant d'explorer vos sources indexées de manière quantitative et visuelle. Ces fonctionnalités complètent le RAG en offrant une vue d'ensemble de votre corpus. ### Fonctionnalités principales - **Knowledge Graph** : Visualisation des relations entre documents - **Textométrie** : Statistiques lexicales (fréquences, n-grams, richesse) - **Topic Modeling** : Détection automatique de thèmes (BERTopic) - **Topic Timeline** : Évolution temporelle des thèmes --- ## Accès à l'explorateur de corpus 1. Ouvrez votre projet dans ClioDeck 2. Passez en mode **Explore** (barre de modes en haut : Explore / Brainstorm / Write / Export) 3. Sélectionnez l'onglet **Corpus Explorer** (les onglets Similarity et Textometrics couvrent respectivement le Similarity Finder — détail d'implémentation dans [FEATURE_SIMILARITY_FINDER.md](./FEATURE_SIMILARITY_FINDER.md) — et la textométrie) 4. L'explorateur charge automatiquement les statistiques --- ## Knowledge Graph ### Description Le Knowledge Graph visualise les relations entre les documents de votre corpus sous forme de graphe interactif. ### Types de nœuds | Type | Représentation | Description | |------|---------------|-------------| | **Document** | Cercle | Un PDF indexé | Le type de nœud « Auteur » (`includeAuthorNodes`) est **activable depuis l'interface depuis la RC4**. Il était jusque-là désactivé en dur des deux côtés où il est appelé. ### Types de liens | Type | Description | |------|-------------| | **Citation** | Un document cite un autre document du corpus | | **Similarity** | Similarité sémantique au-dessus du seuil | | **Co-citation** | Deux documents cités ensemble | ### Interactions - **Clic sur un nœud** : Affiche les métadonnées du document - **Zoom** : Molette de la souris - **Pan** : Cliquer-glisser sur le fond - **Déplacer un nœud** : Cliquer-glisser sur le nœud ### Paramètres | Paramètre | Description | Défaut | |-----------|-------------|--------| | **Seuil de similarité** | Minimum pour créer un lien | 0.7 | Il n'y a pas de bascule « Afficher les communautés » — dès qu'une communauté est détectée pour un nœud, sa couleur en dépend automatiquement, sans réglage possible pour l'activer ou le désactiver. ### Algorithmes utilisés - **Layout** : ForceAtlas2 (force-directed) - **Communautés** : Louvain clustering - **Centralité** : degré total (liens entrants + sortants), pas de betweenness centrality --- ## Textométrie ### Description Le panneau de textométrie calcule des statistiques lexicales sur l'ensemble du corpus indexé. ### Statistiques globales | Métrique | Description | |----------|-------------| | **Total des mots** | Nombre total de mots (sans stopwords) | | **Mots uniques** | Taille du vocabulaire | | **Richesse lexicale** | Ratio vocabulaire / total | | **Documents** | Nombre de documents analysés | | **Moyenne mots/document** | Longueur moyenne | ### Onglets d'analyse #### 1. Mots fréquents Liste des mots les plus fréquents dans le corpus, après suppression des stopwords. | Colonne | Description | |---------|-------------| | **Mot** | Le terme | | **Occurrences** | Nombre d'apparitions | | **Fréquence** | Pourcentage du total | #### 2. Bigrammes Séquences de 2 mots les plus fréquentes. **Exemples** : "première guerre", "sources primaires", "histoire sociale" #### 3. Trigrammes Séquences de 3 mots les plus fréquentes. **Exemples** : "première guerre mondiale", "histoire du temps", "fin du siècle" ### Interprétation - **Haute richesse lexicale** (> 0.3) : Vocabulaire varié, corpus diversifié - **Basse richesse lexicale** (< 0.1) : Vocabulaire répétitif, corpus homogène - **N-grams récurrents** : Expressions caractéristiques du domaine --- ## Topic Modeling ### Description Le Topic Modeling utilise BERTopic pour identifier automatiquement les thèmes présents dans votre corpus. ### Prérequis Le Topic Modeling nécessite l'environnement Python : 1. Installation **manuelle**, déclenchée depuis Paramètres → Topic Modeling (pas automatique au premier usage) 2. Dépendances : BERTopic, sentence-transformers, UMAP ### Lancer l'analyse 1. Dans l'explorateur de corpus, cliquez sur **Analyser les topics** 2. Configurez les paramètres si nécessaire 3. Attendez la fin de l'analyse (peut prendre plusieurs minutes) ### Paramètres | Paramètre | Description | Défaut | |-----------|-------------|--------| | **Nombre de topics** | Nombre de thèmes à détecter — seul paramètre réellement modifiable dans l'interface (`CorpusTopicsSection.tsx`) | 10 (pas « Auto » — `useCorpusData.ts` initialise `numTopics` à 10) | | **Taille min. topic** | Documents minimum par thème | Pas de contrôle dans l'interface — la valeur envoyée est **codée en dur à 3** (`useCorpusData.ts`, `minTopicSize: 3`), qui écrase le défaut de 5 du service Python (`main.py`) | | **Langue** | Langue du corpus | Multilingue — codé en dur (`language: 'multilingual'`), pas de sélecteur | ### Résultats Chaque topic est représenté par : | Élément | Description | |---------|-------------| | **ID** | Numéro du topic (0, 1, 2...) | | **Keywords** | Mots-clés caractéristiques | | **Taille** | Nombre de documents | | **Documents représentatifs** | Exemples de documents du topic | ### Topic -1 (Outliers) Le topic -1 contient les documents qui n'ont pas pu être classés dans un thème. Cela peut indiquer : - Des documents atypiques - Un corpus trop diversifié - Un nombre de topics trop bas --- ## Topic Timeline ### Description La Topic Timeline visualise l'évolution des thèmes au fil du temps. ### Affichage - **Axe X** : Années - **Axe Y** : Nombre de documents - **Courbes** : Un thème par couleur ### Interprétation - **Pic** : Thème dominant pour une période - **Tendance croissante** : Sujet émergent - **Tendance décroissante** : Sujet en déclin ### Prérequis Pour que la timeline fonctionne : 1. Les documents doivent avoir une date (métadonnées BibTeX) 2. Le Topic Modeling doit avoir été exécuté --- ## Statistiques du corpus ### Informations affichées | Statistique | Description | |-------------|-------------| | **Documents** | Nombre de PDFs indexés | | **Chunks** | Nombre de segments indexés | | **Citations** | Citations internes (entre documents du corpus) | | **Citations extraites** | Total des citations détectées | | **Langues** | Langues détectées | | **Période** | Plage d'années couverte | | **Auteurs** | Nombre d'auteurs distincts | --- ## Export des résultats ### Formats disponibles | Donnée | Formats | |--------|--------| | Knowledge Graph | GEXF (pour Gephi et compatibles) | | Topics | JSON, CSV, ou Markdown | Il n'y a pas d'export dédié pour les statistiques globales ou la timeline. ### Procédure Des boutons d'export dédiés apparaissent directement dans l'explorateur de corpus, à côté des résultats concernés (topics et graphe) — pas de menu contextuel à chercher. --- ## Bonnes pratiques ### Pour le Knowledge Graph - **Ajustez le seuil de similarité** : Plus haut = moins de liens, plus lisible - **Corpus homogène** : Les graphes sont plus pertinents sur des corpus thématiques - **Minimum 10 documents** : En dessous, le graphe est peu informatif ### Pour la textométrie - **Indexez tous vos PDFs** : Les statistiques sont plus représentatives - **Comparez les n-grams** : Ils révèlent les expressions du domaine - **Attention aux outliers** : Un mot très fréquent peut fausser l'analyse ### Pour le Topic Modeling - **Corpus suffisant** : Minimum 20-30 documents pour des résultats fiables - **Homogénéité linguistique** : Fonctionne mieux avec une seule langue - **Patience** : L'analyse peut prendre plusieurs minutes --- ## Dépannage ### Le Knowledge Graph est vide **Causes possibles** : - Aucun document indexé - Seuil de similarité trop élevé **Solutions** : - Indexez des PDFs - Baissez le seuil de similarité (ex: 0.5) ### Le Topic Modeling échoue **Causes possibles** : - Python non installé - Dépendances manquantes - Pas assez de documents **Solutions** : - Installez Python 3.11+ - Relancez l'installation des dépendances - Ajoutez plus de documents — 5 est le minimum strictement imposé par le service (`min_length=5`), mais 20-30 donnent des résultats bien plus fiables en pratique ### Statistiques incohérentes **Causes possibles** : - Index désynchronisé - Documents corrompus **Solutions** : - Il n'existe pas d'action de reconstruction d'index — seule une purge complète existe (Paramètres → Actions), qui efface tout et exige une réindexation intégrale des PDF - Vérifiez les PDFs problématiques --- ## Références ### Algorithmes - **BERTopic** : [Maarten Grootendorst](https://maartengr.github.io/BERTopic/) - **HDBSCAN** : Clustering hiérarchique basé sur la densité - **UMAP** : Réduction de dimensionnalité ### Métriques - **Richesse lexicale** : Type-Token Ratio (TTR) - **Louvain** : Détection de communautés - **ForceAtlas2** : Layout de graphe force-directed ### Bibliographie - Blei, D. M., Ng, A. Y., & Jordan, M. I. (2003). Latent Dirichlet Allocation. *JMLR*. - Grootendorst, M. (2022). BERTopic: Neural topic modeling with a class-based TF-IDF procedure.