Outil d'extraction de corpus ISTEX

@besagni besagni authored on 5 Apr 2018
outils Version 2.0 (nouvelles options, nouveaux champs) 5 years ago
README.md Version 4.2.3 (Nouvelles fonctionnalités, nouvelles options) 6 years ago
harvestCorpus.pl Petite modification de l’option “-h” 6 years ago
README.md

harvest-corpus

Outil d’extraction de corpus ISTEX

Permet de décharger un corpus de fichiers textes (PDF, TEI, TXT), de fichiers de métadonnées (JSON, Mods, XML) ou de fichiers d’enrichissement depuis la base ISTEX à partir d’une requête ou d’un fichier .corpus. Permet également de renommer les fichiers déchargés et de générer un fichier de notices bibliographiques.

Prérequis

Le programme harvestCorpus.pl fonctionne sous Unix/Linux ainsi qu’avec Cygwin sous Windows. Il utilise plusieurs modules dont la plupart sont présents dans la distribution standard de Perl. Normalement, les seuls modules à installer sont :

  • HTTP::CookieJar::LWP
  • JSON
  • URI::Encode

Usage

    harvestCorpus.pl -q 'requête' [ -a | -emt <type de fichier>[,<type de fichier>]* ]
                     [ -d destination ] [ -n [notices.txt]] [ -p préfixe ] [ -s fichier.corpus ]
                     [ -l nombre ] [ -r [nombre]] [ -iv ] [ -j jeton ]
    harvestCorpus.pl -c fichier.corpus ( -a | -emt <type de fichier>[,<type de fichier>]* )
                     [ -d destination ] [ -n [notices.txt]] [ -p préfixe ] [ -l nombre ]
                     [ -j jeton ]
    harvestCorpus.pl -h

Options

   -a  télécharge tous les fichiers correspondants aux documents
   -c  utilise le fichier “fichier.corpus” comme source d’identifiants pour télécharger
       les documents (incompatible avec les options “-r” et “-s”)
   -d  indique le répertoire de destination des documents (répertoire courant par défaut)
   -h  affiche cette aide
   -e  liste les enrichissements à télécharger, soit “all” pour l’ensemble, soit
       “abesAuthors”, “abesSubjects”, “multicat”, “nb”, “refBibs”, “teeft” ou “unitex”
   -i  ajoute l’indexation automatique, e.g. TEEFT, dans les notices bibliographiques
   -j  indique le jeton d’authentification obtenu sur “https://api.istex.fr/token/”
   -l  limite le nombre maximum de documents téléchargés au nombre fourni en argument
   -m  liste les fichiers de métadonnées à télécharger, soit “all” pour l’ensemble,
       soit “json”, “mods” ou “xml”
   -n  crée un fichier de notices bibliographiques (sans argument, crée le fichier
       “notices.txt” dans le répertoire courant ou celui donné par l’option “-d”)
   -p  indique le préfixe utilisé pour renommer les fichiers téléchargés (par défaut, “f”).
       Ce préfixe est ensuite suivi d’un numéro séquentiel et de l’extension correspondant
       au type de document téléchargé
   -q  indique la requête à utiliser, entre simples quotes en présence de blancs ou de
       caractères spéciaux (incompatible avec l’option “-c”)
   -r  provoque une sortie dans un ordre aléatoire en fonction d’une “graine” aléatoire
       si l’argument est absent ou égal à 0, ou en fonction du nombre entier positif non nul
       fourni en argument (incompatible avec l’option “-c” et limité à 10.000 documents)
   -s  indique le nom du fichier “.corpus” généré. Par défaut, génère le fichier
       “notices.corpus” ou “préfixe.corpus” (cf. option “-p”) dans le répertoire courant
       ou celui donné par l’option “-d” (incompatible avec l’option “-c”)
   -t  liste les fichiers de texte intégral à télécharger, soit “all” pour l’ensemble,
       soit “ocr”, “pdf”, “tei”, “txt” ou “zip”
   -v  garde les métadonnées ISTEX au format JSON dans un fichier “logRequete.txt” dans
       le répertoire courant ou celui donné par l’option “-d”

Authentification

Le téléchargement de certains fichiers, notamment le texte intégral, à partir d’ISTEX n’est autorisé qu’aux membres de l’ESR. Si vous n’avez pas une authentification par adresse IP, il vous faut obtenir un jeton d’accès à l’adresse “https://api.istex.fr/token/”. Après avoir sélectionné votre organisme de tutelle et vous être identifié, vous serez dirigé vers une page au format JSON contenant deux “clés” :

  • _comment” : indication sur l’emploi du jeton d’accès (à ne pas suivre dans le cas présent),
  • _accessToken” : donnant le jeton d’accès à utiliser avec l’option -j.

Exemples

Par souci de clarté, on suppose dans les exemples suivants ne pas avoir besoin de l’option -j et du jeton d’accès qui est d’une taille non négligeable.

1 - Requête simple

Téléchargement des fichiers PDF et TEI des articles de la revue “Biofutur” dans le répertoire “FichiersPDF” en les renommant avec le préfixe “biofutur” tout en créant un fichier Biofutur.corpus et en conservant les réponses de l’API ISTEX :

   harvestCorpus.pl -q '(host.title:"Biofutur" OR host.issn:"0294-3506")' -t pdf,tei -d FichiersPDF -s Biofutur.corpus -p biofutur -v

2 - Utilisation du fichier .corpus

À l’aide du fichier “Biofutur.corpus” ainsi créé, téléchargement dans le répertoire “Metadata” des métadonnées au format Mods correspondants aux fichiers téléchargés précédemment :

   harvestCorpus.pl -c Biofutur.corpus -m mods -d Metadata

3 - Tirage aléatoire

Création d’un échantillon de 1000 fichiers textes provenant d’Elsevier, choisi de façon aléatoire, et génération du fichier Elsevier/els.corpus et du fichier de notices bibliographiques Elsevier/els.txt :

   harvestCorpus.pl -q corpusName:elsevier -t txt,ocr -d Elsevier -p els -n -l 1000 -r

Fichiers générés par harvestCorpus.pl

1 - Fichier .corpus

Le programme génère un fichier contenant des informations sur le corpus, comme la requête utilisée, la date de création et le nombre de documents obtenus. Après ces métadonnées, on trouve une ligne avec l’indication [ISTEX] suivi de l’identifiant de chaque document, un par ligne, sous la forme d’un type d’identifiant, ark ou id, suivi de sa valeur. En commentaire, on peut également trouver le nom du fichier correspondant (sans l’extension qui dépend du type de fichier téléchargé).

Par défaut, ce fichier se nomme id.corpus ou préfixe.corpus en présence de l’option -p et il se trouve soit dans le répertoire courant, soit dans le répertoire indiqué par l’option -d.

Le texte ci-dessous correspond au début du fichier Elsevier/els.corpus obtenu avec l’exemple “3 - Tirage aléatoire”.

#
# Fichier .corpus
#
title        : <à compléter> 
author       : BESAGNI
publisher    : <à compléter> 
query        : corpusName:elsevier
date         : Mardi 6 Mars 2018 09:52:50
license      : CC-By ?
versionInfo  : 1.0 ?
randomSeed   : 1520326370561
total        : 1000 / 6015985 documents

[ISTEX]
ark ark:/67375/6H6-WVMBX405-F                  # els00001
ark ark:/67375/6H6-B8WM60RB-M                  # els00002
ark ark:/67375/6H6-ZL2X5PWP-B                  # els00003
ark ark:/67375/6H6-GSLCZHZG-R                  # els00004
ark ark:/67375/6H6-BZZDVT14-P                  # els00005
ark ark:/67375/6H6-SC5QFP5J-0                  # els00006
...

2 - Fichier logRequete.txt

Avec l’option -v, il est possible de conserver l’ensemble des informations envoyées par l’API ISTEX lors de l’exécution d’une requête. Ces métadonnées sont conservées dans le fichier logRequete.txt qui se trouve soit dans le répertoire courant, soit dans le répertoire indiqué par l’option -d.

Ce fichier est notamment utilisé par le programme statsCorpus.pl pour extraire les principales informations concernant chaque document du corpus, comme le titre, le nom du périodique, la date de publication, l’éditeur, la version de PDF, etc.

3 - Fichier de notices bibliographiques

Avec l’option -n, le programme génère un fichier de notices bibliographiques qui donne une vision synthétique du corpus dans un format familier aux documentatlistes. Si l’option -n n’a pas d’argument, le fichier s’appelle notices.txt et il se trouve soit dans le répertoire courant, soit dans le répertoire indiqué par l’option -d.

L’exemple ci-dessous correspond au début du fichier Elsevier/els.txt généré avec l’exemple “3 - Tirage aléatoire” et la première notice est celle du fichier “els00001” du fichier Elsevier/els.corpus donné en exemple.

#
# Requête : "corpusName:elsevier"
#
# Nombre de réponses : 1000 / 6015985
#

1/1000
NO : ISTEX ark:/67375/6H6-WVMBX405-F (corpus Elsevier)
TI : Genesis of complex deformation on the slopes of the Drina river
DT : Journal ; Abstract
SO : International Journal of Rock Mechanics and Mining Sciences and 
     Geomechanics Abstracts ; ISSN 0148-9062 ; 1992 ; vol. 29 ; n° 3 ; p. A191
LA : Anglais
LO : PII 0148-9062(92)94075-3 ; DOI 10.1016/0148-9062(92)94075-3
   
...