Una de las funciones clave de RDocumentation.org es su buscador. Desde el principio queríamos una barra de búsqueda súper sencilla que encontrara lo que buscas, sin formularios complejos que pidan el nombre del paquete, la función, versiones ni nada más. Solo una barra de búsqueda simple.
En la entrada técnica de hoy, vamos a destacar las tecnologías y técnicas que usamos para ofrecer resultados relevantes y útiles a nuestros usuarios.
Elasticsearch
RDocumentation.org utiliza Elasticsearch para indexar y buscar en todos los paquetes y temas de R.
Elasticsearch es un motor de búsqueda de código abierto, escalable, distribuido y de nivel empresarial.
Elasticsearch es perfecto para consultar documentación porque no trabaja con datos SQL convencionales, sino que almacena documentos en una estructura similar a JSON. Cada documento es un conjunto de pares clave-valor con tipos de datos simples (cadenas, números, listas, fechas, …). Su naturaleza distribuida hace que Elasticsearch pueda ser extremadamente rápido.
Un clúster de Elasticsearch puede tener varios índices y cada índice puede incluir múltiples tipos de documento. Un tipo de documento describe cómo debe ser la estructura del documento. Para saber más sobre los tipos en Elasticsearch, puedes visitar la guía en elastic.co.
RDocumentation.org usa tres tipos distintos: package_version, topic y package. Los dos primeros son los principales; hablaremos de package después.
Como RDocumentation.org es de código abierto, puedes ver los mapeos de Elasticsearch en nuestro repositorio de GitHub.
Tipo package_version
El tipo package_version es como una traducción del archivo DESCRIPTION de un paquete: incluye los campos principales que aparecen ahí; package_name, version, title, description, release_date, license, url, copyright, created_at, updated_at, latest_version, maintainer y collaborators. Los campos maintainer y collaborators se extraen del campo Authors del archivo DESCRIPTION
Tipo topic
Los documentos de tipo topic se obtienen a partir de los archivos Rd, el formato estándar de documentación en R. El tipo topic incluye las siguientes claves: name, title, description, usage, details, value, references, note, author, seealso, examples, created_at, updated_at, sections, aliases y keywords.
Puntuación en Elasticsearch
Antes de calcular ninguna puntuación, Elasticsearch primero intenta reducir el conjunto de candidatos comprobando si el documento realmente coincide con la consulta. En esencia, una consulta es una palabra (o un conjunto de palabras). Según la configuración de la consulta, Elasticsearch busca una coincidencia en ciertos campos de ciertos tipos.
Sin embargo, una coincidencia no implica necesariamente que el documento sea relevante; la misma palabra puede tener significados distintos según el contexto. En función de la configuración de la consulta, podemos filtrar por tipo y campo, e incluir más información contextual. Esa información contextual mejora la relevancia, y aquí es donde entra en juego la puntuación.
Elasticsearch utiliza Lucene por debajo, así que la puntuación se basa en la función práctica de puntuación de Lucene, que combina modelos como el TF-IDF, el modelo de espacio vectorial y el modelo booleano para puntuar el documento.
Si quieres profundizar en cómo usa Elasticsearch esa función, puedes consultar esta sección de la guía de elastic.co.
Una forma de mejorar la relevancia es aplicar un refuerzo a ciertos campos. Por ejemplo, en la búsqueda completa de RDocumentation.org, reforzamos de forma natural campos como package_name y title para paquetes y aliases y name para temas.
Impulsar los documentos populares
Otra manera eficaz de mejorar la relevancia es impulsar los documentos según su popularidad. La idea es que, si un paquete es más popular, es más probable que el usuario lo esté buscando. Mostrar primero los paquetes más populares aumenta la probabilidad de que mostremos justo lo que el usuario necesita.
Usar las descargas como medida de popularidad
Hay varias formas de medir la popularidad. Podemos usar medidas directas como votos o valoraciones que dan los usuarios (como las reseñas en productos de Amazon), o medidas indirectas como el número de artículos vendidos o el número de visualizaciones (en el caso de vídeos de YouTube).
En RDocumentation.org optamos por lo segundo. En concreto, usamos el número de descargas como medida de popularidad. Las medidas indirectas suelen ser más fáciles de recopilar porque no requieren intervención activa del usuario.
Ventana temporal
Un problema al usar el número de descargas es que los paquetes antiguos acumulan naturalmente más descargas totales que los nuevos. Eso no significa que sean más populares; simplemente llevan más tiempo disponibles. ¿Y si un paquete fue muy popular hace años, pero ahora ha quedado obsoleto y la comunidad ya no lo usa activamente?
Para resolverlo, solo tenemos en cuenta el número de descargas del último mes. Así evitamos inflar artificialmente la puntuación de popularidad de paquetes antiguos y los obsoletos desaparecerán pronto.
Descargas directas vs indirectas
Otro problema surge con las dependencias inversas. Los paquetes de R suelen depender de un amplio abanico de otros paquetes. Los que tienen muchas dependencias inversas se descargarán mucho más que el resto. Sin embargo, estos paquetes suelen ser de bajo nivel y no los usa directamente el usuario final. Debemos evitar dar demasiado peso a su número de descargas.
Por ejemplo, toma Rcpp. Más del 70 % de todos los paquetes en CRAN, la red completa de archivos de R, dependen de este paquete, lo que obviamente lo convierte en el paquete más descargado de R. Sin embargo, pocos usuarios de R lo utilizarán directamente ni buscarán su documentación.
Para solucionarlo, necesitábamos separar las descargas directas (las que se producen porque un usuario las solicita) de las descargas indirectas (las que se producen porque se descargó un paquete dependiente). Para distinguir las descargas directas e indirectas a partir de los registros de CRAN, usamos la misma heurística descrita en el paquete cran.stats de Arun Srinivasan.
Ahora contamos con una métrica de popularidad significativa: el número de descargas directas en el último mes. Elasticsearch ofrece una forma sencilla de inyectar esta información adicional; para más detalles, consulta este artículo en elastic.co.
La puntuación se modifica así:
new_score = old_score * log(1 + number of direct downloads in the last month)
Usamos una función log() para suavizar el valor de number of downloads, porque cada descarga adicional pesa menos; la diferencia entre 0 y 1.000 descargas debe impactar más en una puntuación de popularidad que la diferencia entre 100.000 y 101.000.
Este reescalado mejora la relevancia general de los resultados de búsqueda que ofrece RDocumentation.org y, como resultado, los usuarios pueden centrarse en leer documentación en lugar de buscarla.
Si quieres ver más detalles sobre cómo está implementada la consulta de Elasticsearch, echa un vistazo al proyecto RDocumentation en GitHub. La consulta está en el SearchController.
Si quieres saber más sobre cómo está implementado RDocumentation.org, consulta nuestros repos:
- RDocumentation-app: la aplicación web que ejecuta rdocumentation.org.
- RDocumentation-elasticsearch: configuración y feeders del servidor de Elasticsearch que da servicio a rdocumentation.org.
- RDocumentation: paquete de R para integrar rdocumentation.org en tu flujo de trabajo en R
- RDocumentation-lambda-worker: canalización en AWS Lambda para analizar la documentación de paquetes para rdocumentation.org
Sobre RDocumentation
RDocumentation agrega la ayuda de paquetes de R desde CRAN, BioConductor y GitHub, las tres fuentes más habituales de documentación actual de R. Pero RDocumentation.org va más allá de simplemente agregar esta información: pone toda esta documentación a tu alcance mediante el paquete RDocumentation. Este paquete sustituye las funciones básicas de ayuda del paquete utils y te da acceso a RDocumentation.org directamente desde tu IDE de RStudio. Consulta los paquetes de R más nuevos y populares, busca en la documentación y publica ejemplos de la comunidad.
