Creando paquetes en R

1

Lo primero que necesitaremos es una carpeta que almacenará todo, lo ideal es que esta carpeta se llame como el paquete, en este caso le llamaremos amazonReviews.

Una vez hecho esto, crearemos un proyecto de R en ese directorio.

Adicionalemte necesitamos un par de paquetes que nos harán la vida más fácil, estos son: devtools, usethis y here (este último no es tan necesario).

2

Ahora tenemos que hacerle saber a R que crearemos un paquete, para ello corremos en la consola la siguiente función:

usethis::create_package(here::here())

# usethis::create_package(getwd()) # en el caso de no haber instalado el paquete here

Al hacerlo nos saldrá una pregunta en la consola que nos pedirá decidir si debemos sobreescribir el archivo RProj que había sido creado en el paso 1, decimos que sí.

Notemos que una vez hecho lo anterior se habrá habilitado un pestaña llamada Build en el recuadro del Environment y además se habrán creado automáticamente algunos archivos en el directorio del proyecto:

archivos creados automáticamente

3

Ahora lo que haremos será llenar el archivo DESCRIPTION con el título del paquete, nuestra información en la sección Authors@R y la descripción.

N.B. Por ahora no modificaremos el campo License, ya llegará el momento.

Package: amazonReviews
Title: Scrapes amazon reviews
Version: 0.0.0.9000
Authors@R: 
    person(given = "David",
           family = "Mateos",
           role = c("aut", "cre"),
           email = "davidmateosmo@gmail.com")
Description: Provides a couple of functions to scrape reviews from Amazon MX and visualise them in wordclouds.
License: `use_mit_license()`, `use_gpl3_license()` or friends to
    pick a license
Encoding: UTF-8
LazyData: true
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.0

4

Ahora toca el turno de las funciones.

Tenemos que ir llenando el paquete con nuestras funciones, para ello solo debemos crear un nuevo script y pegar nuestra función.

Antes de guardarla tenemos que modificar un poco este script, empezaremos por documentarla a la R. Esta parte será bastante sencilla pues usaremos a nuestro favor una característica de devtools que convierte cierto tipo de comentarios a la documentación estándar de R (acá usamos la magia de un paquete llamado roxygen2).

Estos comentarios especiales son precedidos por los caractéres #':

#' Scrapes Amazon MX reviews
#'
#' @param id The product id, you can get it from the amazon URL
#' @param pages Number of pages to scrape data from
#' @export

get_reviews <- function(id, pages){
  
  webpage <- paste0("https://www.amazon.com.mx/product-reviews/", id)
  session <- bow(webpage, force = TRUE)
  
  reviews_list <- list()
  
  for (i in 1:pages) {
    reviews_list[[i]] <- scrape(session, query = list(pageNumber=i)) %>% 
      html_nodes("[class='a-size-base review-text review-text-content']") %>% 
      html_text()
  }
  
  reviews <- unlist(reviews_list)
  
  return(reviews)
}

Notemos los comentarios con los indicadores @param y @export, éstos le dicen a R cómo tratar esas partes de la documentación, e.g. @param le indica a R que estamos explicando un parámetro de la función y pondrá esta información en un lugar específico de la documentación.

Por otro lado @export le dice a R que le debe permitir al usuario usar esa función, este parámetro es importantísimo y casi siempre lo usaremos.

5

Ahora nos encargaremos de las dependencias de la función, como mencionamos al inicio, nuestras funciones usan otras funciones de otros paquetes de R por lo que hay que hacer que R sepa cuáles son y de qué paquetes.

Esta función en particular (get_reviews) usa funciones de dos paquetes, a saber polite y rvest, para avisarle a R sobre esto debemos correr la siguiente función:

usethis::use_package("polite")

# √ Setting active project to 'C:/Users/David Alberto MMO/Documents/Workshops/Rpackages/amazonReviews'
# √ Adding 'polite' to Imports field in DESCRIPTION
# * Refer to functions with `polite::fun()`


usethis::use_package("rvest")

# √ Adding 'rvest' to Imports field in DESCRIPTION
# * Refer to functions with `rvest::fun()`

Notemos que R nos avisa cómo debemos usar la funciones de cada paquete, esto es, en lugar de solo usar la función debemos seguir la estructura: nombredepaquete::función, así que debemos modificar la función para que siga esta regla:

#' Scrapes Amazon MX reviews
#'
#' @param id The product id, you can get it from the amazon URL
#' @param pages Number of pages to scrape data from
#' @export

get_reviews <- function(id, pages){
  
  webpage <- paste0("https://www.amazon.com.mx/product-reviews/", id)
  session <- polite::bow(webpage, force = TRUE)
  
  reviews_list <- list()
  
  for (i in 1:pages) {
    reviews_list[[i]] <- polite::scrape(session, query = list(pageNumber=i)) %>% 
      rvest::html_nodes("[class='a-size-base review-text review-text-content']") %>% 
      rvest::html_text()
  }
  
  reviews <- unlist(reviews_list)
  
  return(reviews)
}

Una vez hechas estas modificaciones procedemos a guardar el script con el nombre de la función.

Ahora bien, para saber que todo se ha hecho correctamente iremos a la pestaña Build y daremos click en el botón check o bien, corremos la siguiente función:

devtools::check()

Al final veremos algo como lo siguiente:

> checking DESCRIPTION meta-information ... WARNING
  Non-standard license specification:
    `use_mit_license()`, `use_gpl3_license()` or friends to pick a
    license
  Standardizable: FALSE

> checking R code for possible problems ... NOTE
  get_reviews: no visible global function definition for '%>%'
  Undefined global functions or variables:
    %>%

0 errors v | 1 warning x | 1 note x

Esta retroalimentación que R nos da nos ayudará a saber si estamos siguiendo todas las reglas correctamente o si debemos modificar algo, en este caso hay cosas que resolver.

Por un lado tenemos un WARNING que nos indica que la licencia no es correcta, ignoremos esto pues pronto nos encargaremos de ello. Por otro lado, generamos un NOTE que nos indica que no definimos una función que estamos usando, esta es %>%.

Particularmente, cuando hagamos paquetes que usen el increíble pipe de magrittr debemos correr la siguiente función:

usethis::use_pipe()

Hacemos el check nuevamente y ese NOTE habrá desaparecido (aunque sigue presente el warning).

Ahora tenemos que correr la siguiente función para transformar nuestros comentarios tipo roxygen2 a la documentación estándar de R:

devtools::document()

6

Lo que sigue es repetir los pasos 4 y 5 con cada una de las funciones restantes, haciendo check constantemente para asegurarnos que vamos por buen camino.

7

Con todas las funciones configuradas, estamos aun paso de tener nuestro paquete listo.

Ahora sí, hay que encargarnos de la licencia, ésta nos servirá para proteger nuestro trabajo y hacerle saber a las demás personas cómo puede usarlo.

Tenemos 7 licencias posibles, las cuales recomiendo revisar a detalle para saber cual es la que mejor aplica a tu proyecto:

• CC0: dedicated to public domain. Appropriate for data packages.
• MIT: simple and permissive.
• Apache 2.0: provides patent protection.
• GPL v3: requires sharing of improvements.
• AGPL v3: requires sharing of improvements.
• LGPL v3: requires sharing of improvements.
• CCBY 4.0: Free to share and adapt, must give appropriate credit. Appropriate for data packages.

En este ejemplo usaremos la licencia MIT:

usethis::use_mit_license("David Mateos") # En lugar de mi nombre deberás poner el tuyo ;D

Damos Check una vez más y debemos ver lo siguiente:

-- R CMD check results --------------------------- amazonReviews 0.0.0.9000 ----
Duration: 18.7s

0 errors v | 0 warnings v | 0 notes v

R CMD check succeeded

Eso significa que todo funciona a la perfección.