RDocumentation: Scoring und Ranking

Eine der Kernfunktionen von RDocumentation.org ist die Suche. Von Anfang an wollten wir eine super einfache Suchleiste, die findet, was du suchst – ohne komplizierte Formulare für Paketnamen, Funktionsnamen, Versionen oder Ähnliches. Einfach eine Suchleiste.

Im heutigen Technical Blog-Beitrag zeigen wir die Technologien und Methoden, mit denen wir unseren Nutzern relevante und aussagekräftige Ergebnisse liefern.

Elasticsearch

RDocumentation.org nutzt Elasticsearch, um alle R-Pakete und -Themen zu indexieren und zu durchsuchen.

\n

Elasticsearch ist eine Open-Source-, skalierbare, verteilte Suchmaschine in Enterprise-Qualität.

\n

Elasticsearch eignet sich ideal für die Abfrage von Dokumentation, weil es nicht auf klassischem SQL basiert, sondern Dokumente in einer JSON-ähnlichen Datenstruktur speichert. Jedes Dokument ist eine Menge aus Key-Value-Paaren mit einfachen Datentypen (Strings, Zahlen, Listen, Datumswerte, …). Durch die verteilte Architektur ist Elasticsearch extrem schnell.

Ein Elasticsearch-Cluster kann mehrere Indizes haben und jeder Index mehrere Dokumenttypen. Ein Dokumenttyp beschreibt, wie die Struktur eines Dokuments aussehen soll. Mehr zu Elasticsearch-Typen findest du in diesem Guide auf elastic.co.

RDocumentation.org verwendet drei Typen: package_version, topic und package. Die ersten beiden sind die wichtigsten; package besprechen wir später.

Da RDocumentation.org Open Source ist, kannst du die Mappings für Elasticsearch in unserem GitHub-Repo einsehen. 

package_version-Typ

Der Typ package_version ist im Grunde eine Übersetzung der DESCRIPTION-Datei eines Pakets und enthält die wichtigsten Felder daraus: package_name, version, title, description, release_date, license, url, copyright, created_at, updated_at, latest_version, maintainer und collaborators. Die Felder maintainer und collaborators werden aus dem Authors-Feld der DESCRIPTION-Datei extrahiert.

topic-Typ

Die Topic-Dokumente werden aus den Rd-Dateien geparst, dem Standardformat für R-Dokumentation. Der topic-Typ enthält die folgenden Keys: name, title, description, usage, details, value, references, note, author, seealso, examples, created_at, updated_at, sections, aliases und keywords.

Scoring in Elasticsearch

Bevor es ans Scoring geht, reduziert Elasticsearch zunächst die Kandidatenmenge, indem geprüft wird, ob ein Dokument überhaupt zur Suchanfrage passt. Eine Query ist im Grunde ein Wort (oder mehrere Wörter). Basierend auf den Query-Einstellungen sucht Elasticsearch in bestimmten Feldern bestimmter Typen nach Übereinstimmungen.

Eine Übereinstimmung bedeutet jedoch nicht automatisch, dass das Dokument relevant ist; dasselbe Wort kann in verschiedenen Kontexten Unterschiedliches bedeuten. Über die Query-Einstellungen können wir nach Typ und Feld filtern und mehr Kontext einbeziehen. Diese Kontextinformationen erhöhen die Relevanz – hier kommt das Scoring ins Spiel.

Elasticsearch setzt unter der Haube auf Lucene, das Scoring basiert also auf Lucenes Practical Scoring Function. Diese vereint Modelle wie TF-IDF, das Vektorraummodell und das Boolesche Modell zu einem Gesamtscore.

Wenn du mehr darüber lernen willst, wie diese Funktion in Elasticsearch eingesetzt wird, schau dir diesen Abschnitt im Guide auf elastic.co an.

Eine Möglichkeit, die Relevanz zu verbessern, ist das gezielte Boosten einzelner Felder. In der Volltextsuche auf RDocumentation.org boosten wir zum Beispiel Felder wie package_name und title bei Paketen sowie aliases und name bei Topics.

Beliebte Dokumente boosten

Eine weitere wirksame Methode zur Relevanzsteigerung ist das Boosten basierend auf Popularität. Die Idee dahinter: Je beliebter ein Paket ist, desto eher sucht jemand genau danach. Wenn wir die populäreren Pakete zuerst anzeigen, steigt die Chance, dass wir genau das zeigen, wonach gesucht wird.

Downloads als Popularitätsmaß

Popularität lässt sich verschieden messen. Möglich sind direkte Kennzahlen wie Bewertungen oder Rankings (wie Produktbewertungen bei Amazon) oder indirekte Kennzahlen wie Verkaufszahlen oder Aufrufe (z. B. bei YouTube-Videos).

Bei RDocumentation.org haben wir uns für den indirekten Ansatz entschieden. Konkret nutzen wir die Anzahl der Downloads als Popularitätsindikator. Indirekte Kennzahlen sind meist leichter zu erheben, weil sie keine aktive Nutzereingabe erfordern.

Zeitfenster

Ein Problem bei der Nutzung von Downloadzahlen: Ältere Pakete haben naturgemäß mehr Gesamtdownloads als neuere. Das heißt aber nicht automatisch, dass sie beliebter sind – sie sind nur länger verfügbar. Was, wenn ein Paket früher sehr beliebt war, inzwischen aber veraltet ist und kaum noch aktiv genutzt wird?

Um das zu lösen, berücksichtigen wir nur die Downloads des letzten Monats. So werden ältere Pakete nicht künstlich nach oben gespült und veraltete Pakete verschwinden schnell aus dem Rampenlicht.

Direkte vs. indirekte Downloads

Ein weiteres Problem ergibt sich aus Reverse-Dependencies. R-Pakete hängen typischerweise von vielen anderen Paketen ab. Pakete mit vielen Reverse-Dependencies werden deutlich häufiger heruntergeladen als andere. Diese Pakete sind jedoch meist Low-Level und werden nicht direkt von Endnutzenden verwendet. Wir müssen vermeiden, ihrer Downloadzahl zu viel Gewicht zu geben.

Ein Beispiel ist Rcpp. Über 70 Prozent aller Pakete auf CRAN, dem Comprehensive R Archive Network, hängen von diesem Paket ab – dadurch ist es das am häufigsten heruntergeladene R-Paket. Dennoch werden es relativ wenige R-Nutzende direkt verwenden oder gezielt nach seiner Dokumentation suchen.

Zur Lösung mussten wir direkte Downloads (Downloads, die auf eine explizite Anforderung durch den Nutzer zurückgehen) und indirekte Downloads (Downloads, die erfolgen, weil ein abhängiges Paket installiert wird) trennen. Um direkte und indirekte Downloads in den CRAN-Logs zu unterscheiden, nutzen wir dieselbe Heuristik wie im cran.stats-Paket von Arun Srinivasan.

Damit erhalten wir eine aussagekräftige Popularitätsmetrik: die Anzahl direkter Downloads im letzten Monat. Elasticsearch bietet eine einfache Möglichkeit, diese Zusatzinformation ins Scoring einfließen zu lassen; Details findest du in diesem Artikel auf elastic.co.

Der Score wird wie folgt angepasst:

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

Wir verwenden die Funktion log(), um die Anzahl der Downloads zu glätten. Denn jeder zusätzliche Download wiegt weniger: Der Unterschied zwischen 0 und 1.000 Downloads sollte sich stärker im Popularitätsscore niederschlagen als der zwischen 100.000 und 101.000 Downloads.

Dieses Re-Scoring verbessert die Gesamtqualität der Suchergebnisse auf RDocumentation.org. So kannst du dich aufs Lesen der Dokus konzentrieren – statt auf die Suche danach.

Wenn du genauer wissen willst, wie die Elasticsearch-Query implementiert ist, wirf einen Blick auf das RDocumentation-Projekt auf GitHub. Die Query selbst findest du im SearchController.

Wenn du mehr darüber lernen willst, wie RDocumentation.org aufgebaut ist, schau dir unsere Repos an:

\n
• RDocumentation-app: Die Webanwendung hinter rdocumentation.org.
\n
• RDocumentation-elasticsearch: Konfiguration und Feeder des Elasticsearch-Servers für rdocumentation.org.
\n
• RDocumentation: R-Paket, um rdocumentation.org in deinen R-Workflow zu integrieren
\n
• RDocumentation-lambda-worker: AWS-Lambda-Pipeline zum Parsen der Paketdokumentation für rdocumentation.org
\n

Über RDocumentation 

RDocumentation bündelt Hilfedokumentation für R-Pakete aus CRAN, BioConductor und GitHub – den drei gängigsten Quellen aktueller R-Dokumentation. RDocumentation.org geht aber über das reine Aggregieren hinaus und bringt dir all diese Dokumentation mit dem RDocumentation-Paket direkt an die Hand. Das RDocumentation-Paket überschreibt die grundlegenden Hilfe-Funktionen aus dem utils-Paket und gibt dir Zugriff auf RDocumentation.org direkt in deiner RStudio-IDE. Finde die neuesten und beliebtesten R-Pakete, durchsuche Dokumentation und veröffentliche Community-Beispiele.