1. Accueil
  2. Docs
  3. Pour tout savoir sur Lodex !
  4. Les routines et graphes

Les routines et graphes

Définition d’une routine

Liste des routines disponibles dans Lodex

Nom de la routine

  • explication de la routine
  • avec quel(s) graphe(s) elle s’utilise (illustration avec graphique utilisé)
  • comment on la déclare dans “valeur” lors de la création d’un modèle (/api/run/nom de la routine/identifiant/)
  • limites de l’utilisation de la routine

Nom du graphe

  • quelle routine pour aboutir à ce graphique
  • choix du graphe, que veut-on visualiser, avantages à utiliser un graphe plutôt qu’un autre ?

Comment créer une routine non disponible dans Lodex (à faire ?)

Routines et graphes

1. Les routines

Les routines de LODEX sont des scripts, fournis par LODEX ou stockables n’importe où sur le web, qui peuvent effectuer des agrégations, des calculs, des reformatages et renvoyer des données sous une forme utilisable (souvent un format de type graphique).

Les routines sont appelées via l’API web de LODEX, et s’appliquent à un champ (ou plus). Quand on connaît le nom de la routine à utiliser (disons routine-exemple), il suffit de l’ajouter derrière /api/run/ pour obtenir la route à utiliser (comme valeur de champ pour un format graphique): /api/run/routine-exemple.

Déclaration des routines dans le fichier de configuration

Pour qu’une routine soit utilisable dans LODEX via son API, il faut qu’elle soit déclarée dans le champ routines du fichier de configuration.–> comment ?? Où est le fichier de config ??
Le nom de la routine doit être exactement le même que celui du fichier en ligne (avec l’extension .ini).
Le résultat d’une routine peut être visualisé à partir d’une URL de la forme:
http://url-instance/api/run/routine/identifiant
où :
  • url-instance est l’URL de l’instance
  • routine est la routine utilisée
  • identifiant est le code attributé par LODEX au champ représenté (voir dans le modèle)

 

Lors de la création d’un modèle, elles doivent être déclarées dans la partie “Comment la valeur est créée” : copie d’écran ?

/api/run/routine/identifiant

où :
  • routine est la routine utilisée
  • identifiant est le code attributé par LODEX au champ représenté (voir dans le modèle)

 

Le choix de la routine conditionne le format (le graphique) d’affichage souhaité.

La description des routines et des graphiques qui se déclinent dans les parties suivantes ont pour but de préciser quelle routine doit être utilisée pour afficher quel type de graphique.

Routines disponibles dans Lodex (de la routine aux graphes)

 

all-document

Donne, pour tout le corpus, le contenu de tous les documents en JSON.

classif-by

Elle est destinée à un type de graphique permettant de visualiser les évolutions diachroniques du poids de thématiques contenues dans les documents d’un corpus.

Cette routine doit alors être déclarée dans Value (Valeur) selon : /api/run/classif-by/identifiant/ où identifiant est le code attribué par LODEX au champ représenté.–> à expliquer

Cette routine est destinée à être utilisée avec le format graphique :

  • [StreamGraph] -[AreaGraph] (à venir)

count-all

Compte le nombre de documents du corpus.

Elle peut être utilisée, par exemple, avec le format Text – Emphased Number (Texte – Chiffre en gras) pour afficher le nombre de documents sur la page d’accueil de l’instance.

Elle doit alors être déclarée dans Value (Valeur) selon : /api/run/count-all/–> à expliquer

exemple

count-by-fields

Compte le nombre de documents du corpus pour chacun des champs déclarés dans le modèle.

exemple

cross-by

Croise les éléments pour un champ ou plusieurs champs et compte le nombre d’occurences de chaque croisement.

Crée les paires (source et target) entre les éléments de 2 champs (champs identiques ou différents) déclarés selon :

  • /api/run/cross-by/identifiant1/identifiant1/

  • /api/run/cross-by/identifiant1/identifiant2/

et compte, pour chaque paire, le nombre de co-occurrences.

Cette routine se comporte comme la routine pairing-with , le petit +: elle sait interpréter les paramètres associés aux graphiques:

Nombre max de champs (=maxSize) Valeur maximum à afficher (=maxValue) Valeur minimum à afficher (=minValue) Trier par valeur/label (=sortBy)

Elle peut, en particulier, être utilisée avec les formats Network (Réseau) et Heat Map (carte de chaleur).

Attention : dans le cas où cette routine s’applique à un seul champ (/api/run/cross-by/identifiant1/identifiant1/), elle conserve les auto-paires (source et cible identiques). Cela peut être intéressant avec le format Heat Map pour visualiser la diagonale, mais peut être gênant avec d’autres formats.

exemple

decompose-by

Croise les éléments pour un champ ou plusieurs champs et compte le nombre d’occurences de chaque croisement.

Crée les paires (source et target) entre les valeurs de 1 champ ou plusieurs champs (champs identiques ou différents) selon :

/api/run/decompose-by/identifiant1/

/api/run/decompose-by/identifiant1/identifiant2/

et compte, pour chaque paire, le nombre de co-occurrences.

Cette routine se comporte comme la routine graph-by, le petit +: elle sait interpréter les paramètres associés aux graphiques:

Nombre max de champs (=maxSize) Valeur maximum à afficher (=maxValue) Valeur minimum à afficher (=minValue) Trier par valeur/label (=sortBy)

Elle peut, en particulier, être utilisée avec les formats Network (Réseau) et Heat Map (carte de chaleur)

Attention : dans le cas où cette routine s’applique à plusieurs champs (/api/run/decompose-by/identifiant1/identifiant2/), elle crée les paires identifiant1/identifiant2 mais aussi identifiant1/identifiant1 et identifiant2/identifiant2, ce qui peut ne pas être adapté pour un réseau.

exemple

distinct-ISO3166-1-alpha2-from

Fournit le nombre de fois où un pays apparaît selon son :

  • nombre d’occurrences si le champ n’est pas dédoublonné
  • nombre de documents si le champ est dédoublonné

Elle est, en particulier, utilisée avec le format Cartography pour représenter les pays du corpus sur une carte du monde.

Attention : avant d’utiliser cette routine, il peut être utile de vérifier que les formes d’écriture des pays verbalisés du corpus correspondent bien aux formes d’écriture des pays dans la table de correspondance.

exempleg61g = PaysENGRSansFrance (pays verbalisé en anglais: Algeria, Argentina, Australia, etc.)

distinct-ISO3166-1-alpha3-from

Transforme les valeurs verbalisées du champ pays en leurs codes ISO 3 et compte le nombre de fois où ce pays apparaît (code ISO 3), selon son :

  • nombre d’occurrences si le champ n’est pas dédoublonné
  • nombre de documents si le champ est dédoublonné

Elle est, en particulier, utilisée avec le format Cartography (Cartographie) pour représenter les pays du corpus sur une carte du monde.

Attention : avant d’utiliser cette routine, il peut être utile de vérifier que les formes d’écriture des pays verbalisés du corpus correspondent bien aux formes d’écriture des pays dans la table de correspondance.

exempleg61g = PaysENGRSansFrance (pays verbalisé en anglais: Algeria, Argentina, Australia, etc.).

distinct-alpha-2-alpha3-from

Transforme les codes ISO 2 du champ pays en leurs codes ISO 3 et compte le nombre de fois où ce pays apparaît (identifiant), selon son :

  • nombre d’occurrences si le champ n’est pas dédoublonné
  • nombre de documents si le champ est dédoublonné

Elle est, en particulier, utilisée avec le format Cartography (Cartographie) pour représenter les pays du corpus sur une carte du monde.

Attention : avant d’utiliser cette routine, il peut être utile de vérifier que les codes ISO 2 des pays du corpus correspondent bien aux codes ISO 2 dans la table de correspondance.

distinct-alpha-3-ISO3166-1-from

Transforme les intitulés verbalisés (Anglais ou Français) des pays du champ représenté en leurs codes ISO 3 et compte le nombre de fois où ces pays apparaissent selon leur :

  • nombre d’occurrences si le champ n’est pas dédoublonné
  • nombre de documents si le champ est dédoublonné

Attention : avant d’utiliser cette routine, il peut être utile de vérifier que les verbalisations des pays du corpus correspondent bien aux codes ISO 3 dans la table de correspondance.

distinct-alpha-3-alpha2-from

Transforme les codes ISO 3 des pays du champ représenté en leurs codes ISO 2 et compte le nombre de fois où ce pays (identifiant) apparaît selon son :

  • nombre d’occurrences si le champ n’est pas dédoublonné
  • nombre de documents si le champ est dédoublonné

Attention : avant d’utiliser cette routine, il peut être utile de vérifier que les codes ISO 3 des pays du corpus correspondent bien aux codes ISO 3 dans la table de correspondance.

distinct-by

Compte, pour chaque élément du champ représenté (identifiant), le nombre de fois où cet élément apparaît selon son :

  • nombre d’occurrences si le champ n’est pas dédoublonné
  • nombre de documents si le champ est dédoublonné

Cette routine se comporte comme la routine distinct-by-field. Contrairement à celle-ci elle n’interprète pas les paramètres associés aux graphiques.

Cette routine peut être utilisée avec les formats graphiques :

Elle doit alors être déclarée dans Value (Valeur) selon :

/api/run/distinct-by/identifiant/ où identifiant est le code attribué par LODEX au champ représenté.

exemple

distinct-by-field

Compte, pour chaque élément du champ représenté (identifiant), le nombre de fois où cet élément apparaît selon son :

  • nombre d’occurrences si le champ n’est pas dédoublonné
  • nombre de documents si le champ est dédoublonné

Cette routine se comporte comme la routine distinct-by, le petit +: elle sait interpréter les paramètres associés aux graphiques:

Nombre max de champs (=maxSize) Valeur maximum à afficher (=maxValue) Valeur minimum à afficher (=minValue) Trier par valeur/label (=sortBy)

Cette routine peut être utilisée avec les formats graphiques :

Elle doit alors être déclarée dans Value (Valeur) selon :

/api/run/distinct-by/identifiant/ où identifiant est le code attribué par LODEX au champ représenté.

exemple

distribute-by-date

Sert à créer des chronologies qui conservent les années sans document/de valeur nulle.

Cette routine est utilisée de manière optimale avec le format graphique :

  • Bar Chart(Diagramme à barres et histogramme)

Elle doit alors être déclarée dans Value (Valeur) selon :

/api/run/distribute-by-date/**identifiantChampDatePublication **/

exemple où TwkU représente les années de publication

distribute-by-decadal

Sert à créer des chronologies en regroupant les valeurs par décennie (utile pour des années dispersées sur plusieurs siècles).

Cette routine est utilisée de manière optimale avec le format graphique :

  • Bar Chart (Diagramme à barres et histogramme)

Elle doit alors être déclarée dans Value (Valeur) selon :

/api/run/distribute-by-decadal/identifiant/

exemple où TwkU représente les années de publication

distribute-by-interval

Routine destinée à des graphiques pour lesquels on souhaite regrouper des valeurs (nombres entiers ou décimaux) dans des intervalles de pas “1”.

Cette routine peut être utilisée avec les formats graphiques :

Elle doit alors être déclarée dans Value (Valeur) selon :

/api/run/distribute-by-interval/identifiant/

exemple où GeKM représente les scores de qualité, valeurs décimales uniques pour chaque document du corpus

get-fields

pour utiliser des nombres affectés à des champs des ressources (pas de comptage, utilise la valeur numérique du champ), il faut pouvoir générér des paires _id / value contenant les valeurs de deux champs (en général, un libellé et un nombre, par exemple pour un camembert).

Pour sélectionner le libellé, on donne l’identifiant du champ contenant le libellé comme identifiant1, puis on ajoute l’identifiant du champ contenant la valeur numérique comme identifiant2.

/api/run/get-fields/identifiant1/identifiant2/

Exemples de ressources:

nom de fichier Unitex-anglais Unitex-français
wiley 4460007 12832
elsevier 5879095 82652
springer-journals 1424762 20131

résultat de la routine:

{
  "data": [
    {
      "_id": "wiley",
      "value": 4460007
    },
    {
      "_id": "elsevier",
      "value": 5879095
    },
    {
      "_id": "springer-journals",
      "value": 1424762
    }
  ]
}

graph-by

Croise les éléments pour un champ ou plusieurs champs et compte le nombre d’occurences de chaque croisement.

Crée les paires (source et target) entre les valeurs de 1 champ ou plusieurs champs (champs identiques ou différents) selon :

/api/run/graph-by/identifiant1/

/api/run/graph-by/identifiant1/identifiant2/

et compte, pour chaque paire, le nombre de co-occurrences.

Cette routine se comporte comme la routine decompose-by. Contrairement à celle-ci elle n’interprète pas les paramètres associés aux graphiques.

Elle peut, en particulier, être utilisée avec les formats Network (Réseau) et Heat Map (carte de chaleur)

Attention : dans le cas où cette routine s’applique à plusieurs champs (/api/run/graph-by/identifiant1/identifiant2/), elle crée les paires identifiant1/identifiant2 mais aussi identifiant1/identifiant1 et identifiant2/identifiant2, ce qui peut ne pas être adapté pour un réseau.

exemple

exemple 2 où Xmzn = CodeCNRS2015 et WXcA = Web of Science Category(ies) Résultat de la routine graph-by avec deux paramètres

labeled-resources

Récupère les ressources, mais en enlevant les champs _id, publicationDate, uri, et total. Tous les autres champs sont fournis.

De plus, les chaînes numériques (comme "123") sont converties en nombres (comme 123).

C’est utile pour des formats comme Vega Lite.

Comme elle retourne tous les champs, aucun champ n’est fourni en paramètre.

Attention: ce sont les identifiants des champs qui sont fournis, pas leurs libellés.

Exemple de résultat:

[
  {
    "z5Yi": "May 14, 2019",
    "uNp0": "multicat",
    "cniQ": 11350203
  },
  {
    "z5Yi": "May 14, 2019",
    "uNp0": "unitex",
    "cniQ": 2743607
  },
  {
    "z5Yi": "May 14, 2019",
    "uNp0": "teeft",
    "cniQ": 2148348
  },
  {
    "z5Yi": "May 14, 2019",
    "uNp0": "nb",
    "cniQ": 3180498
  },
  {
    "z5Yi": "May 14, 2019",
    "uNp0": "refbibs",
    "cniQ": 5655020
  }
]

pairing-with

Croise les éléments pour un champ ou plusieurs champs et compte le nombre d’occurences de chaque croisement.

Crée les paires (source et target) entre les éléments de 2 champs (champs identiques ou différents) déclarés selon :

  • /api/run/pairing-with/identifiant1/identifiant1/

  • /api/run/pairing-with/identifiant1/identifiant2/

et compte, pour chaque paire, le nombre de co-occurrences.

Cette routine se comporte comme la routine cross-by. Contrairement à celle-ci elle n’interprète pas les paramètres associés aux graphiques.

Elle peut, en particulier, être utilisée avec les formats Network (Réseau) et Heat Map (carte de chaleur).

Attention : dans le cas où cette routine s’applique à un seul champ (/api/run/pairing-with/identifiant1/identifiant1/), elle conserve les auto-paires (source et cible identiques). Cela peut être intéressant avec le format Heat Map pour visualiser la diagonale, mais peut être gênant avec d’autres formats.

exemple

sparql-query

Elle sert à faire des graphiques de distribution en prenant ses données dans un tripleStore et non dans Lodex.

Elle est cohérence avec les graphiques pouvant utiliser distinct-by.ini:

Ses résultats doivent ressembler à ceux de distinct-by.ini.

Version minimale de lodex : 9.8.1

Ce type de graphique nécessite la structure suivante : un champ total correspondant au nombre d’éléments un champ data qui est la liste des éléments à afficher dans le graphique. Chaque élément possède 2 champs également. Un champ _id qui correspond au nom de l’élément et un champ value qui correspond à la valeur numérique qui lui est associée.

Attention : créer directement sa requête dans le tripleStore de data.istex.fr via YASGUI

Copier le lien de partage –> ce lien sera la valeur à reporter dans un champ LODEX préalablement configuré.

Insérer ce lien dans un nouveau champ DATASET lodex et récupérer son identifiant (ici Kl67 )

Créer un autre champ type graphique au niveau du DATASET pour récupérer les informations de ce champ.

Cette routine doit être déclarée dans Value (Valeur) selon : /api/run/sparql-query/identifiant/ où identifiant représente le champ contenant la requête copier depuis le yasgui de data.istex.fr

syndication-from

Fait référence à une autre ressource du même jeu de données en liant les valeurs entre elles et non leurs arks. Il affiche ainsi les informations que l’on souhaite via les identifiants de la ressource.

Elle est, en particulier, utilisée avec le format Resources Grid pour représenter sur la page d’accueil les champs paramétrés dans syndication-from.

Elle doit alors être déclarée dans Value (Valeur) selon : /api/run/syndication-from/nC6e/… nC6e représente l’identifiant du champ de la valeur que nous souhaitons voir liée.

exemple l’instance revue de sommaire

Cette ressource récupére les informations d’une autre ressource via son identifiant ISSN déclaré dans une colonne bien spécifique portant l’identifiant nC6e. On reporte donc la valeur à la fin:

/api/run/syndication-from/**nC6e**/0300-4910

syndication

Récupère les champs paramétrés dans Syndication dans la configuration du modèle.

Elle est, en particulier, utilisée avec le format Resources Grid pour représenter sur la page d’accueil les champs paramétrés dans Syndication.

Elle doit alors être déclarée dans Value (Valeur) selon :

/api/run/syndication

exemple

tree-by

Permet de créer des graphiques en forme d’arbres représentant des données hiérarchisées (classification, taxonomies …) et d’afficher le nombre de documents concernés.

Format d’entrée obligatoire : JSON

Les valeurs du champ représenté sont listées dans un ordre précis : du plus générique au plus spécifique :

"categories": {
  "wos": [
    "1 - science",
    "2 - marine & freshwater biology"
  ],
  "scienceMetrix": [
    "1 - natural sciences",
    "2 - biology",
    "3 - marine biology & hydrobiology"
  ],
  "scopus": [
    "1 - Life Sciences",
    "2 - Agricultural and Biological Sciences",
    "3 - Aquatic Science"
  ],
  "inist": [
    "1 - sciences appliquees, technologies et medecines",
    "2 - sciences biologiques et medicales",
    "3 - sciences biologiques fondamentales et appliquees. psychologie"
  ]
},

Crée des paires 2 à 2 entre les concepts spécifiques et plus génériques, et comptabilise le nombre de documents concernés par les concepts plus spécifiques de chaque segment.

Cette routine doit être déclarée dans Value (Valeur) selon : /api/run/tree-by/identifiant/ où identifiant représente les noms des espèces ou les catégories scientifiques (termes les plus spécifiques d’une classification hiérarchique)

Cette routine est destinée à être utilisée avec le format graphique :

  • [HierarchicalGraph]

exemple

2. Les graphes

Les graphes font partie des formats d’affichage, et sont construits à l’aide de routines

 

Graphes disponibles dans Lodex (Des graphes aux routines)

https://docs.google.com/document/d/1Z2Q2AztrYPFg6wxcJycNQbxwwTCrusyXl56EZ7sLJ5I/edit (à utiliser)

 

 

 

Cet article vous a-t-il été utile ? Oui Non

Comment pouvons-nous aider ?