Update Tutoriel-geoparsing.ipynb

2fdf5505 · Ludovic Moncla · 4bc43e63 · 2fdf5505
Commit 2fdf5505 authored 2 years ago by Ludovic Moncla
--- a/Tutoriel-geoparsing.ipynb
+++ b/Tutoriel-geoparsing.ipynb
@@ -896,7 +896,7 @@
    "Ce retour à la ligne est due à la largeur de la colonne dans l'œuvre originale. \n",
    "\n",
    "\n",
-    "![CNRS](https://perso.liris.cnrs.fr/lmoncla/ANF-TDM-2022/img/beaufort_originale.png)\n",
+    "![CNRS](https://gitlab.liris.cnrs.fr/lmoncla/tutoriel-anf-tdm-2022-python-geoparsing/-/raw/main/img/beaufort_originale.png?inline=false)\n",
    "\n",
    "\n",
    "Pour vérifier l'hypothèse que ce retour perturbe le repérage par `spaCy`, corrigeons une nouvelle fois le texte.\n"
@@ -1224,7 +1224,7 @@
    "\n",
    "Ce problème d'ambiguïtés peut aussi être illustrer en allant directement interroger le site web du [géoportail](https://www.geoportail.gouv.fr) comme le montre la capture ci-dessous.\n",
    "\n",
-    "![Résultats sur le géoportail](https://perso.liris.cnrs.fr/lmoncla/ANF-TDM-2022/img/geoportail-arques.png)\n"
+    "![Résultats sur le géoportail](https://gitlab.liris.cnrs.fr/lmoncla/tutoriel-anf-tdm-2022-python-geoparsing/-/raw/main/img/geoportail-arques.png)\n"
   ]
  },
  {

 %% Cell type:markdown id: tags:
 ![CNRS](https://anf-tdm-2022.sciencesconf.org/data/header/LOGO_CNRS_CMJN_150x150.png)
 # Tutoriel - ANF TDM 2022 Python Geoparsing
 Supports pour l'atelier [Librairies Python et Services Web pour la reconnaissance d’entités nommées et la résolution de toponymes](https://anf-tdm-2022.sciencesconf.org/resource/page/id/11) de la formation CNRS [ANF TDM 2022](https://anf-tdm-2022.sciencesconf.org).
 **Animateurs**: [Ludovic Moncla](https://ludovicmoncla.github.io) (INSA Lyon) et [Alice Brenon](https://perso.liris.cnrs.fr/abrenon/) (CNRS / INSA Lyon)
 ## 1. En bref
 Dans ce tutoriel, nous allons apprendre plusieurs choses :
 - Charger des jeux de données :
  - à partir de fichiers txt importés depuis le disque dur ;
  - à partir de la librairie Python [Perdido](https://github.com/ludovicmoncla/perdido) dans un [Pandas dataframe](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) (articles encyclopédiques et descriptions de randonnées).
 - Manipuler et interroger un dataframe
 - Utiliser les librairies [Stanza](https://stanfordnlp.github.io/stanza/index.html), [spaCy](https://spacy.io) et [Perdido](https://github.com/ludovicmoncla/perdido) pour la reconnaissance d'entités nommées
  - afficher les entités nommées annotées ;
  - comparer les résultats de `Stanza`, `spaCy` et `Perdido` ;
  - discuter les dimites des 3 outils pour la tâche de NER.
 - Utiliser la librarie `Perdido` pour le geoparsing et le geocoding :
  - cartographier les lieux geocodés ;
  - illustrer la problématique de désambiguïsation des toponymes.
 %% Cell type:markdown id: tags:
 ## 2. Configurer l'environnement
 %% Cell type:markdown id: tags:
 * Si vous avez déjà configuré votre environnement, soit avec conda, soit avec pip (voir le fichier [README.md](https://gitlab.liris.cnrs.fr/lmoncla/tutoriel-anf-tdm-2022-python-geoparsing/-/blob/main/README.md)), vous pouvez ignorer la section suivante et passer directement à la 2.2.
 * Si vous exécutez ce notebook depuis Google Colab, vous devez exécuter les cellules suivantes :
 %% Cell type:markdown id: tags:
 ### 2.1 Installer les librairies Python (uniquement si vous n'avez pas configuré l'environnement Python)
 %% Cell type:code id: tags:
 ``` python
 ! pip install perdido==0.1.27
 ! pip install stanza==1.4.2
 ```
 %% Cell type:markdown id: tags:
 * Télécharger les données :
 %% Cell type:code id: tags:
 ``` python
 ! mkdir data
 ! wget https://gitlab.liris.cnrs.fr/lmoncla/tutoriel-anf-tdm-2022-python-geoparsing/-/blob/main/data/edda-volume01-4083.txt -O data/edda-volume01-4083.txt
 ! wget https://gitlab.liris.cnrs.fr/lmoncla/tutoriel-anf-tdm-2022-python-geoparsing/-/blob/main/data/edda-volume02-1365.txt -O data/edda-volume02-1365.txt
 ! wget https://gitlab.liris.cnrs.fr/lmoncla/tutoriel-anf-tdm-2022-python-geoparsing/-/blob/main/data/lge-beaufort.txt -O data/lge-beaufort.txt
 ```
 %% Cell type:markdown id: tags:
 ### 2.2 Importer les librairies
 Tout d'abord, nous allons charger certaines bibliothèques spécifiques de `Perdido` que nous utiliserons dans ce notebook. Ensuite, nous importons quelques outils qui nous aideront à analyser et à visualiser le texte.
 %% Cell type:code id: tags:
 ``` python
 import warnings
 warnings.filterwarnings('ignore')
 from perdido.geoparser import Geoparser
 from perdido.geocoder import Geocoder
 from perdido.datasets import load_edda_artfl, load_edda_perdido, load_choucas_perdido
 from spacy import displacy
 ```
 %% Cell type:markdown id: tags:
 ## 3. Chargement et exploration des données
 ### 3.1 Chargement d'un document texte à partir d'un fichier
 %% Cell type:code id: tags:
 ``` python
 # On définit une fonction qui prend en paramètre le chemin d'un fichier et qui retourne sont contenu
 def load_txt(filepath):
    with open(filepath) as f:
        return f.read()
 ```
 %% Cell type:code id: tags:
 ``` python
 # On utilise la fonction précédente pour récupérer le contenu de l'article encyclopédique 'Arques' (volume01-4083.txt) présent dans le dossier data
 arques = load_txt('data/edda-volume01-4083.txt')
 ```
 %% Cell type:markdown id: tags:
 * Afficher le contenu du fichier
 %% Cell type:code id: tags:
 ``` python
 print(arques)
 ```
 %% Cell type:markdown id: tags:
 ### 3.2 Chargement d'un jeu de données à partir de la librairie Perdido
 La libraire de geoparsing [Perdido](https://github.com/ludovicmoncla/perdido) embarque deux jeux de données :
 1. des articles encyclopédiques (volume 7 de l'Encyclopédie de Diderot et d'Alembert (1751-1772)), fournit par l'[ARTFL](https://encyclopedie.uchicago.edu) dans le cadre du projet [GEODE](https://geode-project.github.io) ;
 2. des descriptions de randonnées (chaque description est associée à sa trace GPS. Elles proviennent du site [www.visorando.fr](https://www.visorando.com) et ont été collectées dans le cadre du projet [ANR CHOUCAS](http://choucas.ign.fr).
 Dans un premier temps nous allons nous intéresser au jeu de données des articles encyclopédiques. Ce jeu de données est présent dans la librairie en deux versions, une version "brute" (articles fournis par l'ARTFL) au format dataframe et une version déjà annotée par Perdido (format PerdidoCollection). Nous allons charger la version brute et voir comment manipuler un dataframe.
 %% Cell type:markdown id: tags:
 * Charger le jeu de données :
 %% Cell type:code id: tags:
 ``` python
 dataset_artfl = load_edda_artfl()
 data_artfl = dataset_artfl['data']
 ```
 %% Cell type:markdown id: tags:
 * Afficher les informations sur le jeu de données :
 %% Cell type:code id: tags:
 ``` python
 data_artfl.info()
 ```
 %% Cell type:markdown id: tags:
 On remarque que certaines colonnes ont une donnée manquante (3384 lignes non nulles contre 3385 lignes au total). Pour la suite des opérations que nous allons réaliser il est nécessaire de supprimer les lignes incomplètes.
 * Supprimer la ligne incomplète :
 %% Cell type:code id: tags:
 ``` python
 data_artfl.dropna(inplace=True)     # data_artfl = data_artfl.dropna()
 ```
 %% Cell type:markdown id: tags:
 * Vérifier le résultat :
 %% Cell type:code id: tags:
 ``` python
 data_artfl.info()
 ```
 %% Cell type:markdown id: tags:
 * Afficher la liste des premiers articles :
 %% Cell type:code id: tags:
 ``` python
 data_artfl.head()
 ```
 %% Cell type:markdown id: tags:
 ### 3.3 Manipulation d'un dataframe
 %% Cell type:markdown id: tags:
 Nous avons maintenant accès à tous les attributs et méthodes de l'objet [dataframe](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html). Par exemple, nous pouvons facilement connaître le nombre de lignes dans notre dataframe qui correspond au nombre d'articles dans notre corpus :
 %% Cell type:code id: tags:
 ``` python
 n = data_artfl.shape[0]
 print('Il y a ' + str(n) + ' articles dans le jeu de données.')
 ```
 %% Cell type:markdown id: tags:
 #### 3.3.1 Recherche par métadonnées
 Maintenant que les données sont chargées dans un dataframe, nous pouvons sélectionner des groupes d'articles sur la base de leurs métadonnées.
 Pour cela on utilise la méthode [loc()](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.loc.html).
 %% Cell type:markdown id: tags:
 * Selectionner la ligne du dataframe qui correspond à l'article 'FRONTIGNAN' :
 %% Cell type:code id: tags:
 ``` python
 frontignan = data_artfl.loc[data_artfl['head'] == 'FRONTIGNAN']
 frontignan
 ```
 %% Cell type:markdown id: tags:
 * Récupérer les valeurs des attributs (colonnes) :
 %% Cell type:code id: tags:
 ``` python
 print('volume :', frontignan.volume.item())   # similaire à frontignan['volume'].item()
 print('number :', frontignan.number.item())
 print('text :', frontignan.text.item())
 ```
 %% Cell type:markdown id: tags:
 Nous pouvons également filtrer les données sur la base de l'auteur.
 * Extraire les articles rédigés par Jaucourt :
 %% Cell type:code id: tags:
 ``` python
 req = 'Jaucourt'
 d_Jaucourt = data_artfl.loc[data_artfl['author'] == req]
 n = d_Jaucourt.shape[0]
 print(str(n) + ' articles ont été rédigés par '+ req)
 ```
 %% Cell type:markdown id: tags:
 * Afficher les 5 premiers :
 %% Cell type:code id: tags:
 ``` python
 d_Jaucourt.head()
 ```
 %% Cell type:markdown id: tags:
 ### 3.3.2 Recherche par mots-clés
 %% Cell type:markdown id: tags:
 Autre exemple, nous pouvons filtrer les articles en fonction de leur classification dans l'*Encyclopédie*.
 Pour cela nous utiliserons la colonne `normclass`, qui indique la classifications retenue (et normalisée) par l'ARTFL.
 Par exemple pour la classe 'Géographie', nous pouvons faire la requête suivante (le résultat est stocké dans un nouveau dataframe `d_geo` :
 %% Cell type:code id: tags:
 ``` python
 req = 'Géographie'
 d_geo = data_artfl[data_artfl['normClass'].str.contains(req, case=False)]
 n = d_geo.shape[0]
 print(str(n) + ' articles sont classés en '+ req)
 ```
 %% Cell type:code id: tags:
 ``` python
 req = 'ville de'
 d_geo = data_artfl[data_artfl['text'].str.contains(req, case=False)]
 n = d_geo.shape[0]
 print(str(n) + " articles contiennent l'expression '"+ req + "'")
 ```
 %% Cell type:markdown id: tags:
 ### 3.3.3 Regroupements
 %% Cell type:markdown id: tags:
 On peut également regrouper les données selon un ou plusieurs attributs (colonnes) et compter le nombre de données de chaque groupe avec les méthodes [groupby()](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.groupby.html) et [count()](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.count.html).
 * Afficher le nombre d'articles classés en Géographie par auteur :
 %% Cell type:code id: tags:
 ``` python
 d_geo.groupby(['author'])["filename"].count()
 ```
 %% Cell type:markdown id: tags:
 Dans cette partie nous avons vu brievement comment manipuler un dataframe pour selectionner certaines données en filtrant selon certaines métadonnées ou par une recheche par mot clés. Ces opérations sont utiles mais un peu limitées, nous allons voir dans la suite de ce notebook comment enrichir les métadonnées et en particulier comment annoter les entités nommées présents dans les textes.
 %% Cell type:markdown id: tags:
 ## 4. Reconnaissance d'Entités Nommées (NER)
 La reconnaissance d'entités nommées, *Named Entity Recognition* (NER) en anglais, est une tâche très importante et incontournable en traitement automatique des langues (TAL) et en compréhension du langage naturel (NLU en anglais).
 Cette tâche consiste à rechercher des objets textuels (un mot, ou un groupe de mots, souvent associés aux noms propres) catégorisables dans des classes telles que noms de personnes, noms d'organisations ou d'entreprises, noms de lieux, quantités, distances, valeurs, dates, etc.
 Les typologies et les jeux d'étiquettes sont dépendents de chaque outil.
 Dans cet atelier nous allons expérimenter et comparer trois outils de NER :
 1. [Stanza](https://stanfordnlp.github.io/stanza/index.html)
 2. [spaCy](https://spacy.io)
 3. [Perdido](https://github.com/ludovicmoncla/perdido)
 %% Cell type:markdown id: tags:
 ### 4.1 Stanza NER
 `Stanza` est une librairie Python de traitement du langage naturel. Elle contient des outils, qui peuvent être utilisés dans une chaîne de traitement, pour convertir du texte en listes de phrases et de mots, pour générer les formes de base de ces mots, leurs parties du discours et leurs caractéristiques morphologiques, pour produire une analyse syntaxique de dépendance, et pour reconnaître les entités nommées.
 `Stanza` se base sur des modèles entrainés par des réseaux de neurones à partir de la bibliothèque [PyTorch](https://pytorch.org) et permet de traiter plus de 70 langues.
 Dans cette partie nous allons voir comment utiliser `Stanza` pour la reconnaissance d'entités nommées à partir de textes en français.
 %% Cell type:markdown id: tags:
 * Importer la librairie `Stanza` :
 %% Cell type:code id: tags:
 ``` python
 import stanza
 ```
 %% Cell type:markdown id: tags:
 * Télécharger le modèle pré-entrainé pour le français :
 %% Cell type:code id: tags:
 ``` python
 stanza.download('fr')
 ```
 %% Cell type:markdown id: tags:
 * Instancier et paramétrer la chaîne de traitement :
 %% Cell type:code id: tags:
 ``` python
 stanza_parser = stanza.Pipeline(lang='fr', processors='tokenize,ner')
 ```
 %% Cell type:markdown id: tags:
 * On utilise la variable `arques` qui contient le texte chargé précédemment à partir du fichier txt
 %% Cell type:code id: tags:
 ``` python
 print(arques)
 ```
 %% Cell type:markdown id: tags:
 * Executer la reconnaissance d'entités nommées :
 %% Cell type:code id: tags:
 ``` python
 arques_stanza = stanza_parser(arques)
 ```
 %% Cell type:markdown id: tags:
 * Afficher la liste des entités nommées repérées. Avec Stanza, le résultat de l'analyse est un itérateur:
 %% Cell type:code id: tags:
 ``` python
 # On définit une fonction qui prend en paramètre le retour du traitement par Stanza, qui parcourt et affiche la liste des entités et leur type
 def show_ents(stanza_output):
    for ent in stanza_output.ents:
        print(ent.text, ent.type)
 ```
 %% Cell type:code id: tags:
 ``` python
 # On utilise la fonction précédente pour afficher la liste des entités repérées
 show_ents(arques_stanza)
 ```
 %% Cell type:markdown id: tags:
 ### 4.2 SpaCy NER
 `spaCy` est également une librairie Python de traitement du langage naturel.
 Elle se compose de modèles pré-entrainés et supporte actuellement la tokenisation et l'entrainement pour plus de 60 langues. Elle est dotée de modèles de réseaux de neuronnes pour l'étiquettage, l'analyse syntaxique, la reconnaissance d'entités nommées, la classification de textes, l'apprentissage multi-tâches avec des transformateurs pré-entraînés comme BERT, ainsi qu'un système d'entraînement prêt pour la production et un déploiement simple des modèles. `spaCy` est un logiciel commercial, publié en open-source sous la licence MIT.
 Dans cette partie nous allons voir comment utiliser `spaCy` pour la reconnaissance d'entités nommées toujours à partir de notre exemple en français.
 %% Cell type:markdown id: tags:
 * Installer le modèle français pré-entrainé de `spaCy` :
 %% Cell type:code id: tags:
 ``` python
 !python -m spacy download fr_core_news_sm
 ```
 %% Cell type:markdown id: tags:
 * Importer la librarie `spaCy` :
 %% Cell type:code id: tags:
 ``` python
 import spacy
 ```
 %% Cell type:markdown id: tags:
 * Charger le modèle français pré-entrainé de `spaCy`
 %% Cell type:code id: tags:
 ``` python
 spacy_parser = spacy.load('fr_core_news_sm')
 ```
 %% Cell type:markdown id: tags:
 * Executer la reconnaissance d'entités nommées :
 %% Cell type:code id: tags:
 ``` python
 arques_spacy = spacy_parser(arques)
 ```
 %% Cell type:markdown id: tags:
 * Afficher la liste des entités nommées repérées. Les sorties de SpaCy sont dans un format similaire à celui de Stanza mais les étiquettes sont portées par l'attribut `label_` et pas `type`:
 %% Cell type:code id: tags:
 ``` python
 for ent in arques_spacy.ents:
    print(ent.text, ent.label_)
 ```
 %% Cell type:markdown id: tags:
 * `spaCy` fournit également une fonction pour effectuer un rendu plus graphique des annotations avec `displaCy` :
 %% Cell type:code id: tags:
 ``` python
 displacy.render(arques_spacy, style="ent", jupyter=True)
 ```
 %% Cell type:markdown id: tags:
 On remarque des différences entre les résultats de Stanza et de spaCy. En particulier spaCy repère trois entités à tord (faux positifs) : `Géog`, `Long` et `lat`, là où Stanza ne repérait à tord que `Géog)`. Et spaCy ne repère pas la première occurrence `ARQUES` sans doute du au fait que le mot est en majuscule.
 %% Cell type:markdown id: tags:
 ### 4.3 Perdido Geoparser
 `Perdido` est une librairie Python pour le geoparsing de texte en français. Le geoparsing se décompose en deux tâches : le geotagging et le geocoding. Le geotagging est similaire à la tâche de reconnaissance des entités nommées avec un focus particulier pour le repérage d'information spatiale. En plus des entités nommées, nous nous intéressons en particuliers aux relations entres ces entités telles que les relations spatiales (distances, topologie, orientation, etc.).
 Le geocoding (ou résolution de toponymes) a pour rôle d'attribuer aux entités de lieux des coordonnées géographiques non ambigues.
 `Perdido` s'appuie sur une approche hybride principalement construite à base de règles pour la repérage et la classification des entités nommées. La librairie est disponible en 2 versions : une version standard et une version spécialement adaptée pour les articles encyclopédiques.
 Dans cette partie nous allons voir comment utiliser `Perdido` pour la reconnaissance d'entités nommées toujours à partir de notre exemple `Arques`.
 %% Cell type:markdown id: tags:
 * Instancier et paramétrer la chaîne de traitement :
 %% Cell type:code id: tags:
 ``` python
 geoparser = Geoparser(version="Encyclopedie")
 ```
 %% Cell type:markdown id: tags:
 * Executer la reconnaissance d'entités nommées :
 %% Cell type:code id: tags:
 ``` python
 arques_perdido = geoparser(arques)
 ```
 %% Cell type:markdown id: tags:
 Perdido effectuant la tâche de geocoding en plus du NER, le temps de traitement est plus long qu'avec Stanza ou spaCy, du fait de l'interrogation de ressources geographiques externes pour chaque nom de lieu repéré.
 %% Cell type:markdown id: tags:
 * Afficher la liste des entités nommées repérées :
 %% Cell type:code id: tags:
 ``` python
 for ent in arques_perdido.named_entities:
    print(ent.text, ent.tag)
 ```
 %% Cell type:markdown id: tags:
 * Afficher de manière graphique les entités nommées avec `displaCy` grâce à la méthode de conversion `to_spacy_doc`:
 %% Cell type:code id: tags:
 ``` python
 displacy.render(arques_perdido.to_spacy_doc(), style="ent", jupyter=True)
 ```
 %% Cell type:markdown id: tags:
 * Un rendu similaire mais qui permet de visualiser les entités imbriquées (`style="ent"` -> `style="span"`) :
 %% Cell type:code id: tags:
 ``` python
 displacy.render(arques_perdido.to_spacy_doc(), style="span", jupyter=True)
 ```
 %% Cell type:markdown id: tags:
 Cet exemple permet d'illustrer les différences qu'il peut y avoir entre des outils de NER généraliste et ou un outil de geoparsing. On observe ici que Perdido permet une annotation plus fine grâce aux entités imbriquées (ville de, petite rivière) ainsi que le repérage des coordonnées géographiques. En fonction du besoin le repérage de ces éléments peut etre utile pour les traitements suivants ou les analyses qui s'appuient sur ces résultats.
 %% Cell type:markdown id: tags:
 ### 4.4 Expérimentations et comparaison
 %% Cell type:markdown id: tags:
 * Charger l'article `Beaufort` (volume 2, numéro 1365) disponible dans le dossier `data` :
 %% Cell type:code id: tags:
 ``` python
 beaufort = load_txt('data/edda-volume02-1365.txt')
 print(beaufort)
 ```
 %% Cell type:markdown id: tags:
 * Perdido
 %% Cell type:code id: tags:
 ``` python
 beaufort_perdido = geoparser(beaufort)
 displacy.render(beaufort_perdido.to_spacy_doc(), style="ent", jupyter=True)
 displacy.render(beaufort_perdido.to_spacy_doc(), style="span", jupyter=True)
 ```
 %% Cell type:markdown id: tags:
 * spaCy
 %% Cell type:code id: tags:
 ``` python
 beaufort_spacy = spacy_parser(beaufort)
 displacy.render(beaufort_spacy, style="ent", jupyter=True)
 ```
 %% Cell type:markdown id: tags:
 Dans cet exemple, `spaCy` repère le mot `Oron` comme une entité de personne alors que `Perdido` le repère comme un lieu.
 On observe qu'il manque l'accent au mot «rivière». Corrigeons le texte pour voir s'il est possible d'améliorer la reconnaissance.
 %% Cell type:code id: tags:
 ``` python
 normalized_beaufort = beaufort.replace('riviere', 'rivière')
 normalized_beaufort_spacy = spacy_parser(normalized_beaufort)
 displacy.render(normalized_beaufort_spacy, style="ent", jupyter=True)
 ```
 %% Cell type:markdown id: tags:
 Ce changement ne corrige pas l'erreur d'annotation, au contraire l'entité n'est même plus repérée. Cependant, on observe également un saut de ligne entre les mots «rivière» et «d'Oron».
 Ce retour à la ligne est due à la largeur de la colonne dans l'œuvre originale.
-![CNRS](https://perso.liris.cnrs.fr/lmoncla/ANF-TDM-2022/img/beaufort_originale.png)
+![CNRS](https://gitlab.liris.cnrs.fr/lmoncla/tutoriel-anf-tdm-2022-python-geoparsing/-/raw/main/img/beaufort_originale.png?inline=false)
 Pour vérifier l'hypothèse que ce retour perturbe le repérage par `spaCy`, corrigeons une nouvelle fois le texte.
 %% Cell type:code id: tags:
 ``` python
 normalized_beaufort = normalized_beaufort.replace('\n', '')
 normalized_beaufort_spacy = spacy_parser(normalized_beaufort)
 displacy.render(normalized_beaufort_spacy, style="ent", jupyter=True)
 ```
 %% Cell type:markdown id: tags:
 Cette fois l'entité étendue incluant le nom commun «rivière» a été reconnu par `spaCy`, qui a pu ainsi corriger le type de l'entité nommée et se rendre compte que l'Oron était un lieu et pas une personne.
 Essayons maintenant avec `Stanza`.
 %% Cell type:markdown id: tags:
 - Stanza
 %% Cell type:code id: tags:
 ``` python
 beaufort_stanza = stanza_parser(beaufort)
 show_ents(beaufort_stanza)
 ```
 %% Cell type:markdown id: tags:
 Stanza a directement repéré que l'Oron était un lieu mais veut, comme SpaCy, annoter «Géog» qui ne devrait pas l'être.
 Regardons maintenant ce que l'on dit sur la même ville de Beaufort un peu plus d'un siècle plus tard, fin XIXème siecle, dans [La Grande Encyclopédie](https://www.collexpersee.eu/projet/disco-lge/) (LGE).
 %% Cell type:code id: tags:
 ``` python
 lge_beaufort = load_txt('data/lge-beaufort.txt')
 print(lge_beaufort)
 ```
 %% Cell type:markdown id: tags:
 Cette fois l'article est un peu plus long et comporte des césures de lignes importantes, définissons donc une fonction pour recoller les morceaux :
 %% Cell type:code id: tags:
 ``` python
 def join_lines(s):
    return s.replace('¬\n', '').replace('-\n', '').replace('\n', ' ')
 ```
 %% Cell type:code id: tags:
 ``` python
 normalized_lge_beaufort = join_lines(lge_beaufort)
 normalized_lge_beaufort
 ```
 %% Cell type:markdown id: tags:
 * Perdido
 %% Cell type:code id: tags:
 ``` python
 lge_beaufort_perdido = geoparser(normalized_lge_beaufort)
 displacy.render(lge_beaufort_perdido.to_spacy_doc(), style="span", jupyter=True)
 ```
 %% Cell type:markdown id: tags:
 * spaCy
 %% Cell type:code id: tags:
 ``` python
 lge_beaufort_spacy = spacy_parser(normalized_lge_beaufort)
 displacy.render(lge_beaufort_spacy, style="ent", jupyter=True)
 ```
 %% Cell type:markdown id: tags:
 * Stanza
 %% Cell type:code id: tags:
 ``` python
 lge_beaufort_stanza = stanza_parser(normalized_lge_beaufort)
 show_ents(lge_beaufort_stanza)
 ```
 %% Cell type:markdown id: tags:
 Quelques observations :
 1. Seul Perdido repère la date (1841).
 2. spaCy ne classe pas correctement Albertville (Personne) contrairement à Perdido et Stanza (Lieu), spaCy ne repère pas l'entité Heni IV contrairement à Perdido et Stanza.
 3. Stanza repère et classe correctement l'entité "Saint-Maximede-Bf.aufort", Perdido la repère mais ne sait pas la classer et spaCy ne la repère pas.
 %% Cell type:markdown id: tags:
 ## 5. Geoparsing / Geocoding
 En complément de la tâche de reconnaissance des entités nommées la librairie `Perdido` propose également celle de résolution des toponymes, on parle alors de *Geoparsing*. Cette tâche consiste a associer à un nom de lieu des coordonnées géographiques non ambigus. De manière classique elle s'appuie sur le repérage des entités spatiales identifées lors de la reconnaissance des entités nommées et fait appel à des ressources externes de type *gazetier* (ou dictionnaires topographique) pour localiser les lieux.
 %% Cell type:markdown id: tags:
 ### 5.1 Perdido Geoparser
 %% Cell type:markdown id: tags:
 * Revenons à l'article `ARQUES`
 %% Cell type:code id: tags:
 ``` python
 print(arques)
 displacy.render(arques_perdido.to_spacy_doc(), style="ent", jupyter=True)
 ```
 %% Cell type:markdown id: tags:
 * En plus de pouvoir afficher la liste des entités nommées comme nous l'avons fait précédemmment, nous pouvons directement afficher la carte des lieux localisés
 %% Cell type:code id: tags:
 ``` python
 # afficher la carte des lieux localisés
 arques_perdido.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 Par défaut, lors de l'instanciation du `Geoparser()`, seul [OpenStreetMap](https://www.openstreetmap.org/) est utilisé pour le geocoding et au maximum un résultat est retourné pour chaque lieu (nous verrons dans la suite comment paramétrer le geocoding).
 On a déjà ici un aperçu de la difficulté de la tâche de résolution des toponymes. En effet, un grand nombre d'ambiguïtés existent tels que plusieurs lieux ayant le même nom, plusieurs noms pour un même lieu ou encore le fait qu'un lieu ne soit pas référencé dans les ressources que l'on interroge.
 %% Cell type:markdown id: tags:
 ### 5.2 Perdido Geocoder
 En complément du `Geoparser` qui prend en paramètre un texte et qui fait la reconnaissance d'entités nommées en amont de l'étape de geocoding, `Perdido` propose également une fonction de geocoding disctincte prenant en paramètre directement un nom de lieu (ou une liste de noms de lieux).
 %% Cell type:code id: tags:
 ``` python
 geocoder = Geocoder()
 doc = geocoder(['Arques', 'France', 'Normandie', 'Caux'])
 # afficher la carte des lieux localisés
 doc.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 ### 5.3 Résolution de toponymes / désambiguïsation
 #### 5.3.1 Exemple : Arques
 * Cherchons à localiser la ville `Arques`
 %% Cell type:code id: tags:
 ``` python
 geocoder = Geocoder()
 doc = geocoder('Arques')
 doc.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 On remarque que par défaut, la localisation retournée pour le nom de lieu `Arques` n'est pas celle que l'on recherche. En effet, le texte indique qu'il s'agit d'une ville de Normandie, or ici la localisation proposée est située dans le Pas-de-Calais !
 Changeons les paramètres du `Geocoder` (ces paramètres sont similaires pour le `Geoparser`) pour essayer de retrouver la bonne localisation.
 * Augmenter le nombre de résultats retournés par les gazetiers interrogés
 %% Cell type:code id: tags:
 ``` python
 geocoder = Geocoder(max_rows=10)
 doc = geocoder('Arques')
 doc.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 On observe parmi les 10 localisations retournées par OpenStreetMap (gazetier par défaut) qu'aucune ne se situe en Normandie.
 * Remplacer OpenStreetMap par l'IGN
 %% Cell type:code id: tags:
 ``` python
 geocoder = Geocoder(sources=['ign'])
 doc = geocoder('Arques')
 doc.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 On observe que le premier résultat retourné par l'IGN ne se situe ni en Normandie (comme attendu), ni dans le Pas-de-Calais comme le premier résultat retourné par OpenStreetMap.
 * Augmenter le nombre de résultats retournés par l'IGN
 %% Cell type:code id: tags:
 ``` python
 geocoder = Geocoder(sources=['ign'], max_rows=10)
 doc = geocoder('Arques')
 doc.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 Cette fois-ci on retrouve bien une localisation en Normandie au sud de Dieppe avec pour nom `Arques-la-Bataille'. On peut faire l'hypotèse que le nom a évolué car cette localisation se situe bien dans le Pays de Caux (voir illustration ci-dessous, source [Wikipedia](https://fr.wikipedia.org/wiki/Pays_de_Caux)) comme l'indique le texte de l'article.
 ![Pays de Caux](https://upload.wikimedia.org/wikipedia/commons/thumb/4/4e/Carte_pays_Caux1.png/497px-Carte_pays_Caux1.png)
 Ce problème d'ambiguïtés peut aussi être illustrer en allant directement interroger le site web du [géoportail](https://www.geoportail.gouv.fr) comme le montre la capture ci-dessous.
-![Résultats sur le géoportail](https://perso.liris.cnrs.fr/lmoncla/ANF-TDM-2022/img/geoportail-arques.png)
+![Résultats sur le géoportail](https://gitlab.liris.cnrs.fr/lmoncla/tutoriel-anf-tdm-2022-python-geoparsing/-/raw/main/img/geoportail-arques.png)
 %% Cell type:markdown id: tags:
 Il reste néanmoins le problème de retrouver cette localisation de manière automatique.
 Plusieurs approches existent dans la littérature mais ne sont pas encore implémentées dans `Perdido`.
 Cet exemple illustre bien la difficulté de la problématique de désambiguïsation des toponymes avec notamment la gestion des natures de lieux différentes (pays, régions, communes, lieux-dits, lac, rivières, etc.) associés à un même nom, l'homonymie, la non exaustivité des ressources, l'évolution des noms au cours du temps ou encore les erreurs d'orthographe.
 %% Cell type:markdown id: tags:
 * Afficher la carte obtenue après le geoparsing avec l'IGN et 10 résultats max par nom de lieu
 %% Cell type:code id: tags:
 ``` python
 geoparser = Geoparser(sources=['ign'], max_rows=10)
 doc = geoparser(arques)
 doc.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 ### 5.4 Le cas des descriptions de randonnées
 Prenons maintenant l'exemple du geoparsing de descriptions de randonnées. Certaines solutions de désambiguisation ont pu être développées et intégrées au sein de la librairie `Perdido` (d'autres sont en cours d'intégration). Les solutions décrites dans la suite de cette partie ont été développées dans le cadre des projets [Perdido](http://erig.univ-pau.fr/PERDIDO/) (2012-2015) et [ANR CHOUCAS](http://choucas.ign.fr) (2017-2022).
 > Ludovic Moncla, Walter Renteria-Agualimpia, Javier Nogueras-Iso and Mauro Gaio (2014). "Geocoding for texts with fine-grain toponyms: an experiment on a geoparsed hiking descriptions corpus". In Proceedings of the 22nd ACM SIGSPATIAL International Conference on Advances in Geographic Information Systems, pp 183-192.
 > Mauro Gaio and Ludovic Moncla (2019). “Geoparsing and geocoding places in a dynamic space context.“ In The Semantics of Dynamic Space in French: Descriptive, experimental and formal studies on motion expression, 66, 353.
 Nous avons choisi un exemple pour illustrer les différentes phases du processus que nous avons mis en place dans le cadre du geoparsing de descriptions de randonnées :
 1. filtrer les résultats en fonction du pays
 2. filtrer les résultats en fonction d'une zone géographique définie
 3. regrouper les résultats en utilisant un algorithme de clustering spatial (DBSCAN, *density-based spatial clustering of applications with noise*)
 4. selectionner le cluster qui contient le plus d'entités distinctes
 La librairie Perdido utilise la méthode DBSCAN implémentée dans la librairie [Scikit-Learn](https://scikit-learn.org/stable/modules/generated/sklearn.cluster.DBSCAN.html).
 Cette stratégie est adaptée pour une description d'itinéraire où les différents lieux cités sont supposés être localisés à proximité les uns des autres.
 %% Cell type:markdown id: tags:
 * Charger le jeu de données CHOUCAS de descriptions de randonnées fourni par `Perdido`
 %% Cell type:code id: tags:
 ``` python
 dataset_choucas = load_choucas_perdido()
 data_choucas = dataset_choucas['data']
 data_choucas.to_dataframe().head()
 ```
 %% Cell type:code id: tags:
 ``` python
 len(data_choucas)
 ```
 %% Cell type:markdown id: tags:
 * Sélectionner une randonnée (parmi les 30)
 %% Cell type:code id: tags:
 ``` python
 id_rando = 2
 doc = data_choucas[id_rando]
 ```
 %% Cell type:code id: tags:
 ``` python
 doc.text
 ```
 %% Cell type:code id: tags:
 ``` python
 displacy.render(doc.to_spacy_doc(), style="ent", jupyter=True)
 ```
 %% Cell type:code id: tags:
 ``` python
 doc.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 On observe ici le résultat déjà pré-traité par `Perdido`. Nous allons maintenant illustrer le processus de désambiguïsation.
 %% Cell type:markdown id: tags:
 On recommence le processus de geoparsing en entier à partir du texte de la randonnées choisie.
 %% Cell type:code id: tags:
 ``` python
 geoparser = Geoparser()
 doc_geoparsed = geoparser(doc.text)
 ```
 %% Cell type:code id: tags:
 ``` python
 doc_geoparsed.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 On voit clairement la différence par rapport au résultat précédent. Nous allons alors essayer de retrouver le même résultat en déroulant les différentes étapes pour désambiguïser avec `Perdido`.
 Pour gagner un peu de temps lors des prochaines executions nous allons faire directement appel à la fonction de geocoding à partir de la liste des noms de lieux.
 * Récuperer la liste des noms de lieux (sans doublon)
 %% Cell type:code id: tags:
 ``` python
 places_list = list(set([ent.text for ent in doc_geoparsed.ne_place]))
 print(places_list)
 ```
 %% Cell type:markdown id: tags:
 #### 5.4.1 Ajout d'un filtre "code pays"
 %% Cell type:code id: tags:
 ``` python
 # instancier le geocoder avec le code pays
 geocoder = Geocoder(country_code = 'fr')
 doc_geocoded = geocoder(places_list)
 # ajouter la trace GPS
 doc_geocoded.geometry_layer = doc.geometry_layer
 doc_geocoded.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 #### 5.4.2 Ajout d'un filtre "bounding box"
 %% Cell type:code id: tags:
 ``` python
 bbox = [5.62216508714297, 45.051683489057, 7.18563279407213, 45.9384576816403] # zone d'intervention du PGHM Isère
 # instancier le geocoder avec le code pays et une bounding box
 geocoder = Geocoder(country_code = 'fr', bbox = bbox)
 doc_geocoded = geocoder(places_list)
 # ajouter la trace GPS
 doc_geocoded.geometry_layer = doc.geometry_layer
 # affiche la carte
 doc_geocoded.get_folium_map()
 ```
 %% Cell type:markdown id: tags:
 #### 5.4.3 Clustering par densité spatiale
 %% Cell type:code id: tags:
 ``` python
 # appliquer la désambiguïsation
 doc_geocoded.cluster_disambiguation()
 doc_geocoded.get_folium_map()
 ```