RDocumentation: punteggio e ranking

Una delle funzionalità principali di RDocumentation.org è la ricerca. Fin dall’inizio, volevamo una barra di ricerca super semplice che trovasse ciò che cerchi, senza moduli complessi che chiedano nome del pacchetto, nome della funzione, versioni o altro. Solo una semplice barra di ricerca.

Nel blog tecnico di oggi, metteremo in evidenza le tecnologie e le tecniche che usiamo per offrire risultati pertinenti e significativi agli utenti.

Elasticsearch

RDocumentation.org utilizza Elasticsearch per indicizzare e cercare in tutti i pacchetti e gli argomenti R.

Elasticsearch è un motore di ricerca open-source, scalabile, distribuito e di livello enterprise.

Elasticsearch è perfetto per interrogare la documentazione perché non usa dati SQL convenzionali, ma memorizza i documenti in una struttura dati simile a JSON. Ogni documento è solo un insieme di coppie chiave-valore con tipi di dati semplici (stringhe, numeri, liste, date, …). La sua natura distribuita rende Elasticsearch estremamente veloce.

Un cluster Elasticsearch può avere più indici e ogni indice può avere più tipi di documento. Un tipo di documento descrive semplicemente come dovrebbe essere la struttura del documento. Per saperne di più sui tipi di Elasticsearch, puoi visitare la guida su elastic.co.

RDocumentation.org usa tre tipi diversi: package_version, topic e package. I primi due sono i principali; parleremo di package più avanti.

Poiché RDocumentation.org è open-source, puoi vedere i mapping di Elasticsearch nel nostro repo su GitHub.

Tipo package_version

Il tipo package_version è come una traduzione del file DESCRIPTION di un pacchetto; include i campi principali che si trovano lì: package_name, version, title, description, release_date, license, url, copyright, created_at, updated_at, latest_version, maintainer e collaborators. I campi maintainer e collaborators sono estratti dal campo Authors nel file DESCRIPTION

Tipo topic

I documenti topic sono analizzati dai file Rd, il formato standard della documentazione in R. Il tipo topic ha le seguenti chiavi: name, title, description, usage, details, value, references, note, author, seealso, examples, created_at, updated_at, sections, aliases e keywords.

Punteggio in Elasticsearch

Prima di calcolare qualsiasi punteggio, Elasticsearch prova innanzitutto a ridurre l’insieme dei candidati verificando se il documento corrisponde davvero alla query. In pratica, una query è una parola (o un insieme di parole). In base alle impostazioni della query, Elasticsearch cerca una corrispondenza in determinati campi di determinati tipi.

Tuttavia, una corrispondenza non implica necessariamente che il documento sia rilevante; la stessa parola può avere significati diversi in contesti diversi. In base alle impostazioni della query, possiamo filtrare per tipo e campo e includere più informazioni contestuali. Queste informazioni migliorano la pertinenza ed è qui che entra in gioco il punteggio.

Elasticsearch utilizza Lucene sotto il cofano, quindi il punteggio si basa sulla Practical Scoring Function di Lucene, che combina modelli come TF-IDF, Vector Space Model e Boolean Model per attribuire un punteggio al documento.

Se vuoi approfondire come quella funzione è usata in Elasticsearch, puoi consultare questa sezione della guida di elastic.co.

Un modo per migliorare la pertinenza è applicare un boost ad alcuni campi. Per esempio, nella ricerca completa di RDocumentation.org, diamo naturalmente più peso a campi come package_name e title per i pacchetti e aliases e name per i topic.

Dare più peso ai documenti popolari

Un altro modo efficace per migliorare la pertinenza è aumentare il punteggio dei documenti in base alla loro popolarità. L’idea è che, se un pacchetto è più popolare, è più probabile che l’utente lo stia cercando. Mostrare prima i pacchetti più popolari aumenterà la probabilità di mostrare ciò che l’utente sta effettivamente cercando.

Usare i download come misura della popolarità

Ci sono diversi modi per misurare la popolarità. Potremmo usare misure dirette come voti o classifiche assegnate dagli utenti (come le valutazioni sui prodotti Amazon), o misure indirette come il numero di articoli venduti o il numero di visualizzazioni (per i video di YouTube).

Su RDocumentation.org, abbiamo scelto la seconda opzione. Più precisamente, usiamo il numero di download come misura della popolarità. Le misure indirette sono in genere più facili da raccogliere perché non richiedono l’intervento attivo degli utenti.

Finestra temporale

Un problema che sorge usando il numero di download è che i pacchetti più vecchi avranno naturalmente più download totali rispetto a quelli più nuovi. Questo però non significa che siano più popolari; semplicemente esistono da più tempo. E se un pacchetto fosse stato molto popolare anni fa, ma ora fosse obsoleto e non più usato attivamente dalla community?

Per risolvere questo problema, consideriamo solo il numero di download dell’ultimo mese. In questo modo, il punteggio di popolarità dei pacchetti più datati non viene gonfiato artificialmente e i pacchetti obsoleti spariranno rapidamente.

Download diretti vs indiretti

Un altro problema nasce dalle dipendenze inverse. I pacchetti R dipendono in genere da un’ampia gamma di altri pacchetti. I pacchetti con molte dipendenze inverse verranno scaricati molto di più degli altri. Tuttavia, questi pacchetti sono in genere più di basso livello e non sono usati direttamente dall’utente finale. Dobbiamo fare attenzione a non attribuire troppo peso al loro numero di download.

Per esempio, prendi Rcpp. Oltre il 70 percento di tutti i pacchetti su CRAN, la comprehensive R archive network, dipende da questo pacchetto, il che ovviamente lo rende il pacchetto R più scaricato. Tuttavia, pochi utenti R lo useranno direttamente e cercheranno la sua documentazione.

Per risolvere questo problema, abbiamo dovuto separare i download diretti (download che avvengono perché un utente li richiede) e i download indiretti (download che avvengono perché è stato scaricato un pacchetto dipendente). Per distinguere i download diretti e indiretti dai log di CRAN, usiamo la stessa euristica descritta nel pacchetto cran.stats di Arun Srinivasan.

Ora abbiamo una metrica di popolarità significativa: il numero di download diretti nell’ultimo mese. Elasticsearch offre un modo semplice per inserire queste informazioni aggiuntive; per maggiori dettagli, vedi questo articolo su elastic.co.

Il punteggio viene modificato come segue:

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

Usiamo una funzione log() per attenuare il valore del numero di download, perché ogni download successivo pesa di meno; la differenza tra 0 e 1000 download dovrebbe avere un impatto maggiore su un punteggio di popolarità rispetto alla differenza tra 100.000 e 101.000 download.

Questo ricalcolo migliora la pertinenza complessiva dei risultati di ricerca presentati da RDocumentation.org e, di conseguenza, gli utenti possono concentrarsi sulla lettura della documentazione invece che sulla sua ricerca.

Se vuoi scoprire di più su come è implementata esattamente la query di Elasticsearch, dai un’occhiata al progetto RDocumentation su GitHub. La query si trova in SearchController.

Se vuoi sapere di più su come è implementato RDocumentation.org, consulta i nostri repo:

• RDocumentation-app: L’applicazione web che esegue rdocumentation.org.
• RDocumentation-elasticsearch: Configurazione e feeder del server Elasticsearch che serve rdocumentation.org.
• RDocumentation: Pacchetto R per integrare rdocumentation.org nel tuo flusso di lavoro R
• RDocumentation-lambda-worker: pipeline AWS Lambda per analizzare la documentazione dei pacchetti per rdocumentation.org

Informazioni su RDocumentation 

RDocumentation aggrega la documentazione di supporto per i pacchetti R da CRAN, BioConductor e GitHub, le tre fonti più comuni di documentazione R aggiornata. RDocumentation.org va oltre la semplice aggregazione di queste informazioni, portando tutta questa documentazione a portata di mano tramite il pacchetto RDocumentation. Il pacchetto RDocumentation sovrascrive le funzioni di help di base del pacchetto utils e ti dà accesso a RDocumentation.org direttamente dal tuo IDE RStudio. Cerca i pacchetti R più nuovi e popolari, esplora la documentazione e pubblica esempi della community.