Motivação

Como já dizia John M. Chambers quando criou a linguagem S (predecessora do R), o objetivo da linguagem é

“… to turn ideas into software, quickly and faithfully.”

e transformar usuários em programadores de maneira rápida e conveniente.

Se você já explorou um pouco mais do que o potencial básico do R, certamente já criou sua própria função (ou várias funções) para fazer alguma tarefa específica. A ideia é que se você tiver que realizar uma tarefa muitas vezes, então deve criar uma função para fazer isso.

A criação de um pacote do R pode ter duas motivações principais:

• Agrupar e manter uma série de funções criadas por você e que são basicamente de uso próprio ou rotineiro.
• Compartilhar funções de novos métodos e/ou implementações que você tenha criado e queira disponibilizar para outras pessoas usarem.

Não raramente, um pacote de uso pessoal acaba se tornando útil para outras pessoas e o autor disponibiliza para uso geral. O importante é então saber como transformar suas funções em um pacote. E mais importante ainda é saber como fazer isso se preocupando apenas com as funções, ao invés de se preocupar com todo o processo de criação do pacote.

A criação de um pacote no R pode ser feita de duas formas:

• Tradicional: usando os comandos padrões do R para criação de pacotes, como R CMD build para criar e R CMD check para conferir o pacote, ambos executados através de um terminal e não de uma sessão do R.
• Moderna: usando o pacote devtools, que possui funções para criar e conferir o pacote (inclusive para testar e documentar as funções) de dentro de uma sessão do R.

A maneira tradicional de criar pacotes no R é um pouco mais trabalhosa, pois cada vez que você quiser checar se seu pacote está funcionando, é necessário ir para um terminal e rodar os comandos por fora do R. Além disso, se você quiser testar seu pacote após a instalação, será necessário instalar de fato o pacote e carregá-lo com library(). O grande problema é que durante o desenvolvimento de um pacote, esses passos geralmente são repetidos muitas vezes, o que torna todo o processo muito demorado.

O pacote devtools facilita todo esse processo, pois você pode construir, checar, documentar (e conferir a documentação) de dentro da própria sessão do R que você está desenvolvendo o pacote. Além disso esse pacote também permite que, com uma função, você simule a instalação do seu pacote na mesma sessão R, evitando ter que instalar e desinstalar para testes todas as vezes.

Um outro aspecto fundamental de todo pacote é a sua documentação. Da maneira tradicional, é necessário criar os arquivos .Rd e escrever usando uma linguagem muito parecida com o LaTeX. Toda vez que você quiser editar a documentação é necessário abrir esses arquivos e modificá-los nesse formato. Para facilitar ainda mais a vida dos programadores, existe o pacote roxygen2, que possibilita escrever a documentação dentro da própria função .R, integrando código e documentação em um único arquivo, e facilitando a edição das páginas de ajuda.

O pacote roxygen2 pode ser utilizado também na abordagem tradicional de criação de pacotes, eliminando uma etapa trabalhosa que é a de criar os arquivos de documentação. No entanto, podemos usar todo o potencial do devtools e do roxygen2 juntos, e nos preocuparmos apenas com o design das funções e não com todo o processo de criação do pacote em si.

Estrutura de um pacote

Basicamente um pacote do R é uma convenção para organizar e padronizar a distribuição de funções extras do R. Todo pacote é composto obrigatoriamente por apenas dois diretórios e dois arquivos de meta dados:

• R/: um diretório contendo as funções em arquivos *.R (ex.: foo.R).
• man/: um diretório contendo a documentação (páginas de ajuda) de cada função do diretório acima. Os arquivos de documentação do R terminam com a extensão .Rd (ex.: foo.Rd).
• DESCRIPTION: um arquivo texto contendo as informações sobre o seu pacote: autor, licença, outros pacotes dependentes, …
• NAMESPACE: um arquivo texto que informa quais funções do seu pacote serão exportadas, ou seja, aquelas que estarão disponíveis para o usuário, e quais funções são importadas de outros pacotes dos quais o seu depende.

Outros componentes que não são obrigatórios, mas podem estar presentes no pacote são:

• tests/: um diretório contendo scripts com testes unitários, rodados durante a criação do pacote, para testar se existe algum resultado não esperado sendo retornado por alguma de suas funções.
• vignettes/: um diretório que contém uma ou mais vignettes, que traduzidas literalmente são como “vinhetas”, pequenos (ou mesmo grandes) textos que explicam com mais detalhes como os usuários podem usar as funções de seu pacote.
• data/: um diretório contendo arquivos de dados (normalmente em formato binário e comprimido do R, .rda), que podem ser usados como exemplos para aplicação das funções do pacote.

Caso você queira começar um pacote do início, as opções são: 1) criar todos os componentes (diretórios e arquivos) manualmente e ir alimentando com conteúdo, ou 2) usar a função create() do pacote devtools para criar um “esqueleto” inicial com os arquivos e diretórios fundamentais de um pacote. Portanto:

library(devtools)
create("prrpac", rstudio = FALSE)

Creating package 'prrpac' in '/home/fpmayer/GitHub/prr'

No DESCRIPTION found. Creating with values:

Package: prrpac
Title: What the Package Does (one line, title case)
Version: 0.0.0.9000
Authors@R: person("First", "Last", email = "first.last@example.com", role = c("aut", "cre"))
Description: What the package does (one paragraph).
Depends: R (>= 3.3.0)
License: What license is it under?
Encoding: UTF-8
LazyData: true

Como pode ser observado na saída acima, esse comando cria um diretório chamado meupacote, contendo dois arquivos: DESCRIPTION e NAMESPACE, e um diretório: R/

.
├── DESCRIPTION
├── NAMESPACE
└── R

1 directory, 2 files

Note que na mensagem de criação acima, o arquivo DESCRIPTION já é preenchido com alguns campos padrão, sendo necessário apenas alterá-los com as informações do seu pacote.

Abaixo serão especificados os detalhes para a criação de cada um dos componentes obrigatórios criados acima.

Package: prrpac

Title: What the Package Does (one line, title case)

Version: 0.0.0.9000

Authors@R: person("First", "Last", email = "first.last@example.com", role = c("aut", "cre"))

Description: What the package does (one paragraph)

Depends: R (>= 3.3.0)

License: What license is it under?

LazyData: true

Package: prrpac
Title: Pacote Para Pesquisa Reproduzivel
Version: 0.0.1
Authors@R: c(person("Fernando", "Mayer", email = "fernando.mayer@ufpr.br", role = c("aut", "cre")),
             person("Walmes", "Zeviani", email = "walmes@ufpr.br", role = "ctb"))
Description: Pacote de exemplo para pesquisa reproduzivel com R. Para
             mais informacoes consulte o material.
Depends: R (>= 3.3.0)
License: GPL-3
Encoding: UTF-8
LazyData: true

soma <- function(x, y){
    x + y
}

load_all()

Loading prrpac

#' @title Faz a Soma de Dois Numeros
#' @name soma
#'
#' @description Uma (incrivel) funcao que pega dois numeros e faz a
#'     soma. Utilize este campo para descrever melhor o proposito de
#'     sua funcao e o que ela e capaz de fazer.
#'
#' @param x Um numero
#' @param y Outro numero
#'
#' @details Utilize este campo para escrever detalhes mais tecnicos da
#'     sua funcao (se necessario), ou para detalhar melhor como
#'     utilizar determinados argumentos.
#'
#' @return A soma dos numeros \code{x} e \code{y}.
#'
#' @author Fernando Mayer
#'
#' @seealso \code{\link[base]{sum}}, \code{\link[base]{+}}
#'
#' @examples
#' soma(2, 2)
#'
#' x <- 3
#' y <- 4
#' soma(x = x, y = y)
#'
#' @export
soma <- function(x, y){
    x + y
}

document()

Updating prrpac documentation

Loading prrpac

Updating roxygen version in  /home/fpmayer/GitHub/prr/prrpac/DESCRIPTION 
Writing NAMESPACE
Writing soma.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/soma.R
\name{soma}
\alias{soma}
\title{Faz a Soma de Dois Numeros}
\usage{
soma(x, y)
}
\arguments{
\item{x}{Um numero}

\item{y}{Outro numero}
}
\value{
A soma dos numeros \code{x} e \code{y}.
}
\description{
Uma (incrivel) funcao que pega dois numeros e faz a
    soma. Utilize este campo para descrever melhor o proposito de
    sua funcao e o que ela e capaz de fazer.
}
\details{
Utilize este campo para escrever detalhes mais tecnicos da
    sua funcao (se necessario), ou para detalhar melhor como
    utilizar determinados argumentos.
}
\examples{
soma(2, 2)

x <- 3
y <- 4
soma(x = x, y = y)

}
\author{
Fernando Mayer
}
\seealso{
\code{\link[base]{sum}}, \code{\link[base]{+}}
}

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/soma.R

check_man()

Updating prrpac documentation

Loading prrpac

Checking documentation

# Generated by roxygen2: fake comment so roxygen2 overwrites silently.
exportPattern("^[^\\.]")

# Generated by roxygen2: do not edit by hand

export(soma)

#' @title Faz um Grafico Personalizado
#' @name meuxy
#'
#' @description Uma (incrivel) funcao para fazer um xyplot
#'     personalizado. Usando o pacote lattice.
#'
#' @param x Uma formula do lattice
#' @param ... Outros argumentos passados para a funcao
#'     \code{\link[lattice]{xyplot}}
#'
#' @details Utilize este campo para escrever detalhes mais tecnicos da
#'     sua funcao (se necessario), ou para detalhar melhor como
#'     utilizar determinados argumentos.
#'
#' @return Um grafico xyplot do lattice com \code{pch = 4} e \code{col =
#'     1}.
#'
#' @author Fernando Mayer
#'
#' @seealso \code{\link[lattice]{xyplot}}
#'
#' @examples
#' meuxy(1:10 ~ 1:10)
#'
#' @importFrom lattice xyplot
#'
#' @export
meuxy <- function(x, ...){
    xyplot(x, pch = 4, col = 1, ...)
}

document()

Updating prrpac documentation

Loading prrpac

Writing NAMESPACE
Writing meuxy.Rd

# Generated by roxygen2: do not edit by hand

export(meuxy)
export(soma)
importFrom(lattice,xyplot)

importFrom(lattice,xyplot)

#' @importFrom lattice xyplot

meuxy <- function(x, ...){
    lattice::xyplot(x, pch = 4, col = 1, ...)
}

#' @import lattice

use_package("lattice")

* Adding lattice to Imports

Next: 

Refer to functions with lattice::fun()

Package: prrpac
Title: Pacote Para Pesquisa Reproduzivel
Version: 0.0.1
Authors@R: c(person("Fernando", "Mayer", email = "fernando.mayer@ufpr.br", role = c("aut", "cre")),
             person("Walmes", "Zeviani", email = "walmes@ufpr.br", role = "ctb"))
Description: Pacote de exemplo para pesquisa reproduzivel com R. Para
    mais informacoes consulte o material.
Depends:
    R (>= 3.3.0)
License: GPL-3
Encoding: UTF-8
LazyData: true
RoxygenNote: 5.0.1
Imports: lattice

Construindo o pacote

A última etapa é finalmente construir o pacote, ou seja, gerar um arquivo fonte (ou binário) que pode ser distribuído para os usuários instalarem.

Antes de construir o pacote, podemos rodar uma série de checagens para conferir se todos os componentes do pacote estão funcionando como seria o esperado. Essa checagem é feita com o comando R CMD check depois de construir o pacote. No entanto, como estamos usando o devtools, podemos simplificar e utilizar a função check() para realizar a mesma checagem automaticamente, de dentro de uma sessão do R, e deixar para construir o pacote só no final quando tudo estiver funcionando.

Rodando a função check():

check()

Updating prrpac documentation

Loading prrpac

Setting env vars ----------------------------------------------------------

CFLAGS  : -Wall -pedantic
CXXFLAGS: -Wall -pedantic

Building prrpac -----------------------------------------------------------

'/usr/local/lib64/R/bin/R' --no-site-file --no-environ --no-save  \
  --no-restore --quiet CMD build '/home/fpmayer/GitHub/prr/prrpac'  \
  --no-resave-data --no-manual 

Setting env vars ----------------------------------------------------------

_R_CHECK_CRAN_INCOMING_USE_ASPELL_: TRUE
_R_CHECK_CRAN_INCOMING_           : FALSE
_R_CHECK_FORCE_SUGGESTS_          : FALSE

Checking prrpac -----------------------------------------------------------

'/usr/local/lib64/R/bin/R' --no-site-file --no-environ --no-save  \
  --no-restore --quiet CMD check '/tmp/RtmpBGUn4C/prrpac_0.0.1.tar.gz'  \
  --as-cran --timings --no-manual 

R CMD check results

0 errors | 0 warnings | 0 notes

* checking for file ‘/home/fpmayer/GitHub/prr/prrpac/DESCRIPTION’ ... OK
* preparing ‘prrpac’:
* checking DESCRIPTION meta-information ... OK
* checking for LF line-endings in source and make files
* checking for empty or unneeded directories
* building ‘prrpac_0.0.1.tar.gz’
* using log directory ‘/tmp/RtmpXTZjUO/prrpac.Rcheck’
* using R version 3.3.0 (2016-05-03)
* using platform: x86_64-pc-linux-gnu (64-bit)
* using session charset: UTF-8
* using options ‘--no-manual --as-cran’
* checking for file ‘prrpac/DESCRIPTION’ ... OK
* this is package ‘prrpac’ version ‘0.0.1’
* package encoding: UTF-8
* checking package namespace information ... OK
* checking package dependencies ... OK
* checking if this is a source package ... OK
* checking if there is a namespace ... OK
* checking for executable files ... OK
* checking for hidden files and directories ... OK
* checking for portable file names ... OK
* checking for sufficient/correct file permissions ... OK
* checking whether package ‘prrpac’ can be installed ... OK
* checking installed package size ... OK
* checking package directory ... OK
* checking DESCRIPTION meta-information ... OK
* checking top-level files ... OK
* checking for left-over files ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking R files for non-ASCII characters ... OK
* checking R files for syntax errors ... OK
* checking whether the package can be loaded ... OK
* checking whether the package can be loaded with stated dependencies ... OK
* checking whether the package can be unloaded cleanly ... OK
* checking whether the namespace can be loaded with stated dependencies ... OK
* checking whether the namespace can be unloaded cleanly ... OK
* checking loading without being on the library search path ... OK
* checking dependencies in R code ... OK
* checking S3 generic/method consistency ... OK
* checking replacement functions ... OK
* checking foreign function calls ... OK
* checking R code for possible problems ... OK
* checking Rd files ... OK
* checking Rd metadata ... OK
* checking Rd line widths ... OK
* checking Rd cross-references ... OK
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... OK
* checking Rd \usage sections ... OK
* checking Rd contents ... OK
* checking for unstated dependencies in examples ... OK
* checking examples ... OK
* DONE
Status: OK

Note que esta checagem é bem completa, e se o status final for OK, então o pacote está funcionando e pronto para ser instalado. Se nesta checagem aparecer no final algum NOTE, significa que o pacote funciona mas algumas coisas precisam ser arrumadas. Se houverem ERRORs, o processo de checagem é parado e não é possível instalar o seu pacote até que no seja arrumado.

Finalmente para construir o pacote, usaremos a função build() do pacote devtools:

build()

'/usr/local/lib64/R/bin/R' --no-site-file --no-environ --no-save  \
  --no-restore --quiet CMD build '/home/fpmayer/GitHub/prr/prrpac'  \
  --no-resave-data --no-manual 

* checking for file ‘/home/fpmayer/GitHub/prr/prrpac/DESCRIPTION’ ... OK
* preparing ‘prrpac’:
* checking DESCRIPTION meta-information ... OK
* checking for LF line-endings in source and make files
* checking for empty or unneeded directories
* building ‘prrpac_0.0.1.tar.gz’
[1] "/home/fpmayer/GitHub/prr/prrpac_0.0.1.tar.gz"

O resultado da chamada dessa função é o arquivo prrpac_0.0.1.tar.gz que contém o código-fonte do seu pacote e está pronto para ser distribuído e instalado no Linux e Mac.

NOTA: no mesmo diretório onde você está desenvolvendo o pacote, você pode ter outros arquivos e diretórios. Por exemplo, algumas pessoas preferem ter um diretório que não irá fazer parte do pacote, mas que serve para guardar scripts de teste, bases de dados, material em desenvolvimento, etc. Nestes casos é necessário especificar que estes arquivos e diretórios devem ser ignorados no processo de checagem (check()) e construção do pacote (build()). Caso algum arquivo ou diretório que não seja comum ao pacote do R, esses comandos retornarão com um erro, e não será possível construir o pacote. Para evitar estes erros e ao mesmo tempo manter esses arquivos e diretórios, liste-os pelo nome no arquivo .Rbuildignore na raíz do pacote. Por exemplo, se você tiver o diretório playground/ e um arquivo chamdo teste.R, coloque no arquivo .Rbuildignore:

teste.R
playground/

Para gerar um arquivo binário (.zip) para instalar no Windows, o processo é mais complicado (como tudo no Windows). Esse arquivo binário só é possível ser gerado de dentro do Windows, o que, em muitos casos, ão está disponível para uso. Uma opção então é utilizar o win-builder, um servidor Windows disponibilizado pelos mantenedores do R para que pessoas sem acesso ao Windows possam gerar arquivos binários de pacotes. O processo consiste em entrar na página e enviar o código-fonte (.tar.gz) por upload. Em alguns minutos você recebe um email com o link para baixar a versão binária do seu pacote para Windows.

Como estamos usando o devtools, podemos apenas utilizar a função build_win(), que irá fazer todo esse processo automaticamente. O link com a versão binária do arquivo será enviado para o email colocado no campo Maintainer no arquivo DESCRIPTION, por isso é importante que seja um email válido.

build_win()

Uma vantagem dessa função é que ela também roda uma checagem para ver se o pacote funcionará adequadamente no Windows.

Workflow

Um workflow típico para a construção de um pacote utilizando devtools e roxygen2 seria:

##======================================================================
## Criando pacote com devtools e roxygen2
##======================================================================

##----------------------------------------------------------------------
## Pacotes necessarios
library(devtools)
library(roxygen2)

##----------------------------------------------------------------------
## 1) Criando a estrutura (esqueleto) do pacote
create("prrpac", rstudio = FALSE)
# irá criar o diretório 'meupacote' com man/, R/ e DESCRIPTION
# Edite o arquivo DESCRIPTION com as informações do seu pacote

##----------------------------------------------------------------------
## 2) Crie funções e carregue com
load_all()
# cada vez que criar ou alterar uma função, use esse comando para
# carregá-las no seu workspace e testá-las. Crie funções em arquivos com
# extensão .R dentro do diretório R/

##----------------------------------------------------------------------
## 3) Documente as funções usando as tags do roxygen2 e use a função
document()
# para gerar os arquivos com extensão .Rd correspondentes no diretório
# man/. Use também a função
check_man()
# para conferir a documentação

##----------------------------------------------------------------------
## 4) Certifique-se de que o arquivo NAMESPACE esteja contendo todas as
## funções do seu pacote a serem exportadas, e todas as funções (ou
## pacotes inteiros) a serem importadas para o seu pacote. Use as tags
## @export para exportar e @import ou @importFrom para importar (na
## documentação roxygen2 de cada função). Rode
document()
# sempre que exportar ou importar uma função, para que o arquivo
# NAMESPACE seja atualizado.

##----------------------------------------------------------------------
## 5) Confira o pacote com
check()
# e construa o pacote final com
build()

Referências

• Estas notas são altamente baseadas em:
  • R packages by Hadley Wickham
  • Package Development Cheat Sheet
  • Introduction to roxygen2
• O material mais completo e definitivo sobre o desenvolvimento de pacotes no R é o Writing R extensions
• Outras fontes de informação importantes:
  • Developing R packages by JT Leek
  • Routinely testing your R package with Travis