RDocumentation : scoring et classement

L’une des fonctionnalités clés de RDocumentation.org est sa recherche. Dès le départ, nous voulions une barre de recherche ultra simple qui trouve ce que vous cherchez, sans formulaire complexe demandant un nom de package, une fonction, une version ou autre. Juste une barre de recherche, tout simplement.

Dans l’article technique du jour, nous mettons en lumière les technologies et techniques utilisées pour fournir des résultats pertinents et utiles à nos utilisateurs.

Elasticsearch

RDocumentation.org utilise Elasticsearch pour indexer et rechercher dans tous les packages et sujets R.

\n

Elasticsearch est un moteur de recherche open source, évolutif, distribué et de niveau entreprise.

\n

Elasticsearch est idéal pour interroger de la documentation, car il n’utilise pas des données SQL conventionnelles : il stocke plutôt des documents dans une structure de type JSON. Chaque document n’est qu’un ensemble de paires clé-valeur avec des types simples (chaînes, nombres, listes, dates, …). Sa nature distribuée rend Elasticsearch extrêmement rapide.

Un cluster Elasticsearch peut contenir plusieurs index, et chaque index plusieurs types de documents. Un type de document décrit simplement la structure attendue du document. Pour en savoir plus sur les types Elasticsearch, consultez le guide sur elastic.co.

RDocumentation.org utilise trois types : package_version, topic et package. Les deux premiers sont les principaux ; nous reviendrons sur package plus tard.

Comme RDocumentation.org est open source, vous pouvez consulter les mappings Elasticsearch dans notre repo GitHub.

Type package_version

Le type package_version correspond en quelque sorte à une traduction du fichier DESCRIPTION d’un package ; il reprend les champs principaux que l’on y trouve : package_name, version, title, description, release_date, license, url, copyright, created_at, updated_at, latest_version, maintainer et collaborators. Les champs maintainer et collaborators sont extraits du champ Authors du fichier DESCRIPTION.

Type topic

Les documents de type topic sont analysés à partir des fichiers Rd, le format standard de la documentation en R. Le type topic comprend les clés suivantes : name, title, description, usage, details, value, references, note, author, seealso, examples, created_at, updated_at, sections, aliases et keywords.

Le scoring dans Elasticsearch

Avant tout calcul de score, Elasticsearch tente d’abord de réduire l’ensemble des candidats en vérifiant si le document correspond réellement à la requête. En substance, une requête est un mot (ou un ensemble de mots). Selon les paramètres de la requête, Elasticsearch recherche une correspondance dans certains champs de certains types.

Cependant, une correspondance ne signifie pas forcément que le document est pertinent : un même mot peut avoir des sens différents selon le contexte. En fonction des paramètres de la requête, nous pouvons filtrer par type et par champ, et inclure davantage d’informations contextuelles. Ces informations améliorent la pertinence, et c’est là que le scoring intervient.

Elasticsearch s’appuie sur Lucene, de sorte que le score est basé sur la fonction de scoring pratique de Lucene, qui combine des modèles comme le TF‑IDF, le modèle vectoriel et le modèle booléen pour attribuer un score au document.

Pour en savoir plus sur l’utilisation de cette fonction dans Elasticsearch, consultez cette section du guide elastic.co.

Une façon d’améliorer la pertinence consiste à appliquer un boost à certains champs. Par exemple, dans la recherche globale de RDocumentation.org, nous renforçons naturellement des champs comme package_name et title pour les packages, et aliases et name pour les topics.

Booster les documents populaires

Autre levier efficace : booster les documents en fonction de leur popularité. L’idée, c’est que si un package est plus populaire, l’utilisateur a plus de chances de le rechercher. Afficher d’abord les packages les plus populaires augmente la probabilité de montrer ce que l’utilisateur cherche vraiment.

Utiliser les téléchargements comme mesure de popularité

Il existe plusieurs manières de mesurer la popularité. On peut utiliser des mesures directes comme des votes ou des notes attribuées par les utilisateurs (comme les évaluations de produits sur Amazon), ou des mesures indirectes comme le nombre d’articles vendus ou le nombre de vues (pour des vidéos YouTube).

Sur RDocumentation.org, nous avons choisi la seconde option. Plus précisément, nous utilisons le nombre de téléchargements comme indicateur de popularité. Les mesures indirectes sont généralement plus faciles à collecter, car elles ne requièrent pas d’action explicite de l’utilisateur.

Fenêtrage temporel

Un problème apparaît avec le nombre total de téléchargements : les anciens packages auront naturellement cumulé plus de téléchargements que les plus récents. Cela ne signifie pas qu’ils sont plus populaires ; ils existent simplement depuis plus longtemps. Et si un package était très populaire il y a des années, mais est devenu obsolète et n’est plus vraiment utilisé par la communauté ?

Pour résoudre ce problème, nous ne prenons en compte que le nombre de téléchargements du dernier mois. Ainsi, le score de popularité des anciens packages n’est pas artificiellement gonflé, et les packages obsolètes disparaissent rapidement.

Téléchargements directs vs indirects

Un autre problème vient des dépendances inverses. Les packages R dépendent généralement d’un large éventail d’autres packages. Les packages avec beaucoup de dépendances inverses seront bien plus téléchargés que les autres. Or, ces packages sont souvent plus bas niveau et ne sont pas utilisés directement par l’utilisateur final. Il faut éviter d’accorder trop de poids à leur nombre de téléchargements.

Prenez par exemple Rcpp. Plus de 70 % des packages sur CRAN, le dépôt complet des packages R, en dépendent, ce qui en fait évidemment le package R le plus téléchargé. Pourtant, relativement peu d’utilisateurs R l’emploient directement ou recherchent sa documentation.

Pour résoudre ce point, nous avons séparé les téléchargements directs (déclenchés par une demande explicite de l’utilisateur) et les téléchargements indirects (déclenchés par le téléchargement d’un package dépendant). Pour distinguer téléchargements directs et indirects dans les journaux CRAN, nous utilisons la même heuristique que celle décrite dans le package cran.stats d’Arun Srinivasan.

Nous disposons désormais d’un indicateur de popularité pertinent : le nombre de téléchargements directs sur le dernier mois. Elasticsearch offre un moyen simple d’injecter cette information supplémentaire ; pour plus de détails, consultez cet article sur elastic.co.

Le score est modifié comme suit :

new_score = old_score * log(1 + number of direct downloads in the last month)\n

Nous utilisons une fonction log() pour lisser la valeur du nombre de téléchargements, car chaque téléchargement supplémentaire pèse moins ; la différence entre 0 et 1 000 téléchargements doit avoir plus d’impact sur un score de popularité que la différence entre 100 000 et 101 000 téléchargements.

Ce re‑scoring améliore la pertinence globale des résultats de recherche présentés par RDocumentation.org et, en conséquence, les utilisateurs peuvent se concentrer sur la lecture de la documentation plutôt que sur sa recherche.

Si vous souhaitez en savoir plus sur l’implémentation exacte de la requête Elasticsearch, consultez le projet RDocumentation sur GitHub. La requête elle‑même se trouve dans le SearchController.

Pour en savoir plus sur la mise en œuvre de RDocumentation.org, parcourez nos dépôts :

\n
• RDocumentation-app : l’application web qui fait tourner rdocumentation.org.
\n
• RDocumentation-elasticsearch : configuration et feeders du serveur Elasticsearch qui alimente rdocumentation.org.
\n
• RDocumentation : package R pour intégrer rdocumentation.org dans votre flux de travail R
\n
• RDocumentation-lambda-worker : pipeline AWS Lambda pour analyser la documentation des packages pour rdocumentation.org
\n

À propos de RDocumentation 

RDocumentation agrège l’aide des packages R depuis CRAN, BioConductor et GitHub – les trois sources les plus courantes de documentation R à jour. RDocumentation.org ne se contente pas d’agréger ces informations : via le package RDocumentation, il met toute cette documentation à portée de main. Le package RDocumentation remplace les fonctions d’aide de base du package utils et vous donne accès à RDocumentation.org directement depuis votre IDE RStudio. Consultez les packages R les plus récents et les plus populaires, parcourez la documentation et publiez des exemples issus de la communauté.