Librairies communes de consultation et échantillonage de corpus sur API-ISTEX

Romain Loth authored on 23 Nov 2015
etc Add 'etc/Pub2TEI/' from commit '5ff9187' 2 years ago
pool_cache finalement rajout d'exemples minimaux pour pool_cache 2 years ago
test sampler: test unitaires simples et correction bug -x (quand ids à exclure du sample) 2 years ago
README.md mention des dépôts upstream: premier jet avant accords 2 years ago
README_ressources_tierces_parties.md suppression ancien Pub2TEI local qui va être remplacé par une nouvelle remote upstream 2 years ago
__init__.py structure de package (maj depuis modifs pour bib-adapt) 2 years ago
api.py utilisation des facettes terms API et fichier de conf 2 years ago
corpusdirs.py plus compatible windows et plus clair 2 years ago
field_combo_count.py utilisation des facettes terms API et fichier de conf 2 years ago
field_value_lists.py utilisation des facettes terms API et fichier de conf 2 years ago
ids_to_table.py petit script ids => interro API => table de métas 2 years ago
libconsulte.conf utilisation des facettes terms API et fichier de conf 2 years ago
sampler.py utilisation des facettes terms API et fichier de conf 2 years ago
README.md

Echantillons de docs depuis l'API ISTEX

3 routines pour requêter/échantilloner/récupérer des documents

Points d'entrée

sampler.py pour piocher une liste d'ID au hasard, (/!\ avec représentativité!)

corpusdirs.py pour récupérer les fulltexts et métadonnées pour une liste d'IDs

Usage courant

L'essentiel tient en 2 commandes:

# échantilloner 100 docs par date
python3 sampler.py -n 100 -c publicationDate -o tab > mes_100_documents.tsv

# récupérer dans mon_nouveau_corpus
python3 corpusdirs.py mon_nouveau_corpus --from_table mes_100_documents.tsv

Explications

Ici on veut 100 documents avec un peu de chaque période dans la base Istex (par exemple pour tester leur qualité OCR).

1) Echantillonner
python3 sampler.py -n 100 -c publicationDate -o tab > mes_100_documents.tsv
  • il va piocher 100 IDS au hasard par quota sur publicationDate.
  • le tirage par quota assure le "un peu de chaque"
    • par ex: dans la base j'ai 2 millions de docs de la période [1960 à 1979] sur 20.000.000 au total
    • la méthode par quota va en tirer 10 de cette période pour les 100 qu'on lui a demandés (règle de 3).
  • le script propose différents formats de sortie: ici on lui a demandé la sortie tabulée avec -o tab
2) Récupérer

Ensuite on veut obtenir les documents : avec corpusdirs.py, on peut lancer les téléchargements dans un nouveau dossier de notre choix.

python3 corpusdirs.py mon_nouveau_corpus --from_table mes_100_documents.tsv
  • on voit qu'on réutilise la table mes_100_documents.tsv obtenue de l'échantilloneur comme liste de documents à télécharger/traiter.
  • corpusdirs va:
    • télécharger les PDF
    • télécharger les XML natifs
      • lier la DTD des XML natifs en local
    • convertir les XML natifs en TEI

Détails techniques

Sorties

Sortie de corpusdirs

Tout cela sera stocké sous mon_nouveau_corpus/data avec la structure suivante:

tree mon_nouveau_corpus

mon_nouveau_corpus
   ├── data
   │   ├── A-pdfs
   │   │   ├── els-63DD13DF0D6186E15D0C15A3CF0E68FC01BC22F8.pdf
   │   │   ├── wil-2027F65F05E2F0DDEA37C64869B5729F5CDA8B3C.pdf
   │   │   ├── oup-652D02E55E57E3091F4D2B2B28219844A770F83D.pdf
   │   │   └── (...)
   │   ├── B-xmlnatifs
   │   │   ├── els-63DD13DF0D6186E15D0C15A3CF0E68FC01BC22F8.xml
   │   │   ├── wil-2027F65F05E2F0DDEA37C64869B5729F5CDA8B3C.xml
   │   │   ├── oup-652D02E55E57E3091F4D2B2B28219844A770F83D.xml
   │   │   └── (...)
   │   └── C-goldxmltei
   │       ├── els-63DD13DF0D6186E15D0C15A3CF0E68FC01BC22F8.tei.xml
   │       ├── wil-2027F65F05E2F0DDEA37C64869B5729F5CDA8B3C.tei.xml
   │       ├── oup-652D02E55E57E3091F4D2B2B28219844A770F83D.tei.xml
   │       └── (...)
   └── meta
      ├── infos.tab          # tableau TSV résumé (date, titre, auteur 1, ID,  corpus...)
      ├── basenames.ls         # liste des noms de fichiers
      └── shelf_triggers.json    # liste des sous-dossiers remplis

Chaque sous-dossier s'appelle "shelf" ou "étagère". Il est faisable d'en ajouter d'autres dans la configuration de corpusdirs.

Sortie tabulée de l'échantillonneur

L'échantilloneur a 3 types de sorties possibles, selon l'option -o

  • "ids": simplement une liste d'identifiants de l'api
    • ex: sampler.py -o ids -n 20 > my_ids.txt
  • "docs": télécharger les docs pdf uniquement dans un dossier echantillon_$date-$heure
    • ex: sampler.py -o docs -n 20
  • "tab": sortie tabulée
    • ex: sampler.py -o tab -n 20 > my_tab.tsv
    • peut être utilisée dans excel
    • peut être utilisée corpusdirs pour un téléchargements des docs plus avancé
istex_id corpus pub_period pdfver ... title
63DD13D... els [1980 TO 1989] 1.2 ... Measurements of the total transmittance of the solar radiation...
2027F65... wil [2000 TO *] 1.4 ... Appropriate dosing of antiarrhythmic drugs in Japan...
652D02E... oup [* TO 1959] 1.2 ... "Once upon a time."
etc etc etc etc etc etc

Valeurs pour chaque facette

Pour calculer la représentativité, l'échantilloneur doit connaître les facettes possibles d'un champ. Si on lui donne comme critère de représentativité corpusName, il va s'informer en interrogeant la route facette correspondante de l'API. Pour d'autres champs, il utilise des listes des valeurs possibles (toutes comme pour categories.wos ou une partition en paquets pour les facettes de type range, les langues et les genres). Ces listes sont inscrites dans le module field_value_lists.py

Les champs utilisables comme critère d'échantillonnage sont:

  • corpusName
  • qualityIndicators.pdfVersion
  • qualityIndicators.refBibsNative
  • language
  • genre
  • categories.wos
  • publicationDate
  • copyrightDate
  • qualityIndicators.pdfCharCount

Interaction avec l'API

api.py gère toute l'interaction lowlevel avec l'API.
Les fonctions principales sont les suivantes :

search(q, limit=None, n_docs=None, outfields=('title', 'host.issn', 'fulltext'), i_from=0)
terms_facet(facet_name, q='*')
count(q, api_conf={'host': 'api.istex.fr', 'route': 'document'})
write_fulltexts(doc_id, tgt_dir='.', login, passw, api_types=['fulltext/pdf', 'metadata/xml']`

Les modules sampler.py et corpusdirs.py l'importent et utilisent ces fonctions.

TODO

  • pour les formats tabulés, mettre la liste des colonnes dans un config externe
    • Toutes les colonnes actuelles: istex_id,corpus,pub_year,pub_period,pdfver,pdfwc,bibnat,author_1,lang,doctype_1,cat_sci,title
  • rétablir contrainte -w sur sampler
  • ajouter une étagère par défaut pour les MODS2TEI dans corpusdirs

Dépôts upstream

Cette librairie importe:

# pour plus d'infos:
python3 sampler.py -h
python3 corpusdirs.py -h