alignement-pascal-francis
===============


Programmes d’alignement des notices bibliographiques INIST avec les documents ISTEX


## Installation 

Il est préférable de copier les différents programmes Perl et le script shell dans un répertoire dont le chemin est indiqué dans la variable globale `$PATH`. Si vous avez un répertoire `bin` dans votre répertoire de connexion, cela se fait avec les commandes : 

```bash
cp */*.pl ~/bin/ 
cp divers/IhfdCat ~/bin/ 
```

Il faut ensuite s’assurer que les différents programmes soient exécutables :

```bash
cd ~/bin/ 
chmod a+xr *.pl IhfdCat
```

Le programme `matchStan2Istex.pl` a besoin de modules Perl qui ne sont pas dans la distribution standard. L’installation se fait avec l’utilitaire `CPAN` et nécessite d’avoir les droits d’administrateur sur la machine. Sous Unix/Linux, il faut utiliser la commande :

```bash
sudo cpan
```

Après le prompt de `CPAN`, tapez la commande `install` avec le nom du module. Par exemple, pour le module `HTTP::CookieJar::LWP`, cela donne : 

```bash
install HTTP::CookieJar::LWP
```

Après l’installation, on sort de `CPAN` par la commande :

```bash
quit
```

À noter que sous Cygwin, un émulateur Unix sous Windows, l’appel à `CPAN` se fait sans `sudo`. 


## Alignement

L’alignement des notices bibliographiques Pascal/Francis de l’**Inist** avec les documents de la base **Istex** se fait en plusieurs étapes, à savoir : 

 - l’alignement proprement dit : pour chaque notice bibliographique, on cherche à l’aide de l’API **Istex** le document ayant le plus de similitudes et on calcule un score qui permettra de décider si l’appariement est bon ou pas. 
 - la correction des erreurs au cours de l’interrogation de l’API, dues soit à un problème de connexion, soit à une erreur de syntaxe dans l’écriture de la requête. 
 - le dédoublonnage : non seulement les bases Pascal et Francis ont des notices en commun, mais il y a également des documents qui ont été indexés plusieurs fois. Après cette étape, seule une notice, avec le meilleur score, est retenue. 
 - la génération des fichiers d’enrichissement au format TEI pour la base **Istex**. 

Pour chacune de ces étapes, on a dans ce dépôt un répertoire et un programme (et les tables de correspondance), comme le montre le schéma ci-dessous : 

```txt
        alignement-pascal-francis
        ├── 01-alignement
        │   └── matchStan2Istex.pl
        ├── 02-correction
        │   └── recupErreurs.pl
        ├── 03-dedoublonnage
        │   └── weedTei.pl
        ├── 04-generation_tei
        │   ├── alignment2tei.pl
        │   └── CC
        │       ├── equivCCFrancis.txt
        │       ├── equivCCPascal.txt
        │       ├── liensLodex.txt
        │       ├── verbFrancisEn.txt
        │       ├── verbFrancisFr.txt
        │       ├── verbPascalEn.txt
        │       └── verbPascalFr.txt
        └── divers
            └── IhfdCat
```

Pour illustrer comment réaliser un alignement, on va prendre l’exemple de la base Pascal 1995 et on va voir toutes les étapes et toutes les commandes utilisées pour réaliser l’alignement. On suppose que nous sommes dans un répertoire `data` avec les sous-répertoires suivants : 

```txt
        data
        ├── Pascal
        │   └── 1995
        │       └── Pascal.strd95.bib
        ├── etape1
        ├── etape2
        ├── etape3
        ├── etape4
        │   └── CC
        └── resultats
```

Évidemment, le répertoire `Pascal` est supposé contenir toutes les bases de 1984 à 2015. Pour chaque année, on a un répertoire contenant les notices dans un système de fichier appelé **HFD** (voir [divers](../../tree/master/divers)). Le répertoire `etape4/CC` contient les tables d’équivalence permettant de verbaliser les codes de classement Pascal et Francis et le répertoire `resultats` contient les résultats déjà obtenus auparavant, résultats qui serviront lors de la phase de dédoublonnage. 

### Étape 1

Le programme d’alignement s’appelle `matchStan2Istex.pl`. La commande de base est : 

```bash
matchStan2Istex.pl -h Pascal/1995/Pascal.strd95.bib > etape1/P1995.txt
```

Comme le traitement peut être assez long, on peut voir la progression en donnant l’heure chaque fois qu’un certain nombre de notices, indiqué par l’option `-v`, ont été traitées : 

```bash
matchStan2Istex.pl -h Pascal/1995/Pascal.strd95.bib -v 10000 > etape1/P1995.txt
```
L’option `-v` fournit également le nom du fichier de notices, le nom et la version du programme d’alignement et la date du traitement. Comme dans l’étape finale de génération des fichiers d’enrichissement, il vous faudra indiquer la date à laquelle l’alignement a été fait et la version du programme `matchStan2Istex.pl` utilisée, il est intéressant de conserver la sortie erreur standard dans un fichier “*log*” : 

```bash
matchStan2Istex.pl -h Pascal/1995/Pascal.strd95.bib -v 10000 > etape1/P1995.txt 2> etape1/logP1995.txt
```

Si l’on veut refaire l’alignement seulement sur un ou plusieurs nouveaux corpus récemment ajoutés à la base **Istex**, il suffit de les indiquer avec l’option `-c` : 

```bash
matchStan2Istex.pl -h Pascal/1995/Pascal.strd95.bib -v 10000 -c droz,taylor-francis > etape1/P1995.txt
```

Dans le cas où le programme est arrêté avant la fin du traitement, on peut reprendre là où il s'est arrêté. Pour cela, il faut voir dans le fichier de sortie `etape1/P1995.txt` l’identifiant **Inist** de la dernière notice dont la réponse est complète, effacer ce qui suit en laissant une ligne blanche et relancer en indiquant le numéro de la dernière notice avec l’option `-r` : 

```bash
matchStan2Istex.pl -h Pascal/1995/Pascal.strd95.bib -v 10000 -r 95-0419795 > etape1/P1995.txt
```


### Étape 2

Il peut arriver au cours du traitement que la connexion au serveur ne se fasse pas, que l’API ne réponde pas ou que la réponse soit tronquée. Il est facile de vérifier la présence d’erreurs avec la commande : 

```bash
grep ' => ERREUR ' etape1/P1995.txt | sort | uniq -c
```

En présence d’erreurs, on peut retraiter les notices concernées avec le programme `recupErreurs.pl` : 

```bash
recupErreurs.pl -h Pascal/1995/Pascal.strd95.bib -a etape1/P1995.txt -r rP1995.txt > etape2/P1995.txt
```

Le fichier défini par l’option `-r`, à savoir dans notre exemple `rP1995.txt`, sert à recevoir les notices qui ne peuvent être traitées correctement parce que la requête générée entraine une erreur de syntaxe. Normalement, cela ne devrait plus arriver, mais l’option est obligatoire. 

Comme cette étape est rapide, elle peut être réalisée sans même chercher à savoir s’il y a des erreurs ou pas. 


### Étape 3

Lorsque l’alignement a été réalisé sur toutes les bases Pascal et Francis, on peut alors passer à l’étape du dédoublonnage. Pour cela, il faut l'ensemble des résultats, y compris ce qui a été fait bien avant. Le programme de dédoublonnage `weedTei.pl` doit avoir les noms de tous les fichiers. La façon la plus simple de faire cela est de lister l’ensemble de ces fichiers, c’est-à-dire, dans notre exemple, ceux contenus dans le répertoire `etape2` et le répertoire `resultats`, avant d’envoyer le tout sur l’entrée standard de `weedTei.pl` : 

```bash
(find resultats -name '[FP]????.txt'; find etape2 -name 'P????.txt'; find etape2 -name 'F????.txt') | weedTei.pl -f - -r etape3
```

Toujours envoyer la liste des anciens résultats en premier et, pour les résultats récents, la liste des résultats de Pascal avant ceux de Francis. Deux raisons pour cela : 

 - en cas de doublon, et sauf si le nouveau a un score supérieur, on garde l’ancien appariement, donc le fichier d'enrichissement existant et on ne modifie pas la base **Istex** pour rien.
 - dans le cas où les anciens fichiers portent le même nom que les nouveaux, le programme `weedTei.pl` créera les deux fichiers dans le même répertoire, ici `etape3`, et le nouveau fichier écrasera l’ancien (ce qui n’est pas un problème).


### Étape 4

L’étape finale consiste à générer les fichiers d’enrichissement au format TEI dans le système de répertoires à 4 niveaux d’**Istex**. Ces fichiers sont suffixés par `_ipf` (pour **I**ndexation **P**ascal-**F**rancis) et ont l’extension `.tei` comme dans l’exemple suivant : 

```txt
      E
      └── 6
          └── 0
              └── E60DA2B19D7356D5BC7E5612DCBBE9FCAAA9516D
                   └── E60DA2B19D7356D5BC7E5612DCBBE9FCAAA9516D_ipf.tei
```

À la fin, on se retrouve avec 16 répertoires nommés de `0` à `9` et de `A` à `F`.  
La commande de base, avec le programme `alignment2tei.pl`, est : 

```bash
cd etape4
alignment2tei.pl -h ../Pascal/1995/Pascal.strd95.bib -a ../etape3/P1995.txt -d 2020-10-17 -v 2.12.10
```

Comme indiqué à l’étape 1, il faut fournir la date du traitement (au format “*aaaa-mm-jj*”) et la version du programme `matchStan2Istex.pl`. Pour conserver une trace des fichiers générés, vous pouvez créer un fichier “*log*” avec l’option `-l`. 

```bash
alignment2tei.pl -h ../Pascal/1995/Pascal.strd95.bib -a ../etape3/P1995.txt -d 2020-10-17 -v 2.12.10 -l logP1995.txt
```
Dans ce fichier “*log*”, pour chaque notice bibliographique appariée, on a :

 - l’identifiant **Inist** de la notice bibliographique
 - le score de l’alignement

et pour le document **Istex** associé : 

 - l’identifiant **Istex**
 - l’identifiant pérenne ARK
 - le DOI
 - le PII
 - le PMID

Enfin, si, à l’inverse de notre exemple, le répertoire `CC` contenant les tables d’équivalence ne se trouve pas dans le répertoire courant, il faut indiquer son nom et son chemin avec l’option `-c` : 

```bash
alignment2tei.pl -h ../Pascal/1995/Pascal.strd95.bib -a ../etape3/P1995.txt -d 2020-10-17 -v 2.12.10 -l logP1995.txt -c ~/etc/CC
```

Lorsque toutes les bases ont passé avec succès les différentes étapes et que le répertoire `étape4` contient l’ensemble des nouveaux fichiers d’enrichissement, il ne reste plus qu’à archiver le tout :

```bash
zip -r -9 -q enrich.zip [0-9A-F]
```

### Étape 5

Dans notre exemple, avant même de faire toutes les étapes sur toutes les bases Pascal et Francis, nous avions déjà un ensemble de résultats auquel nous avons comparé les nouveaux résultats lors du dédoublonnage. En prévision d’un futur traitement, comme l’ajout d’un nouveau corpus à la base **Istex**, il faut fusionner tous les résultats, anciens et nouveaux. 

Mais, comme le cas ne s'est pas encore présenté, on attend d’avoir un exemple concret pour écrire le script adéquat.