In curso-r/mcUFSCar2015:

Criação de pacotes

Baseado no livro r-pkgs do Hadley

Vantagens {.build}

• Economia de tempo para tarefas futuras.
• Forma de organização pré-estabelecida.
• Contribuir e aproveitar contribuições da comunidade.

Filosofia {.build}

• Tudo que pode ser automatizado, deve ser automatizado.
• Utilização do pacote devtools como base para criação de pacotes.
• Um pacote não precisa estar no CRAN para ser útil.
• Trabalhar menos com os detalhes (estrutura, etc.) e mais com funcionalidades (funções úteis, etc).
• Se for necessário trabalhar com coisas mais complexas, ler Writing R extensions.

Pré-requisitos

• Pacotes devtools, roxygen2, testthat, knitr
• R e RStudio atualizados (recomenda-se preview version do RStudio)

Configurações recomendáveis

• Instalar versão dev do devtools

devtools::install_github('hadley/devtools')

• No Windows, instalar o Rtools
• No Mac, instalar o XCode
• No linux, instalar o pacote de desenvolvimento r-base-dev. No Ubuntu, basta digitar

sudo apt-get install r-base-dev

• Verifique se está tudo certo digitando devtools::has_devel().

Workflow sugerido para criar um pacote

• Criar repositório no github.
• Clonar em um diretório.
• Abrir um terminal ou RStudio.
• Entrar no diretório clonado (no R, setwd(), em um terminal linux, cd, etc).
• Com o R, rodar devtools::setup().

Caso não queira deixar seu pacote no github

• Clicar em "Novo projeto" -> "R package" do RStudio

Estrutura {.build}

Essa é a estrutura mínima para criar um pacote.

• Tudo dentro de uma pasta
• DESCRIPTION: Metadados do pacote.
• NAMESPACE: Trata das interações do seu pacote com outros pacotes.
• R/: Pasta onde fica os códigos em R
• man/: Pasta onde fica a documentação
• xxx.Rproj: Seu projeto (não é necessário).

Arquivo DESCRIPTION

• Versões (>= 0.3), devtools::numeric_version()
• Depends (versões de R).
• Authors@R
• Licensas
• Definir Imports, Suggests, e usar o ::.
• devtools::use_package('xxxxxx')

Código R {.build}

• Todo o código em R fica aqui
• Tudo é baseado em funções.
  • Crie objetos, principalmente funções,
  • não use coisas como View()
• Melhor workflow:
  • Editar R -> Ctrl+Shift+L -> Teste no console -> Editar R -> ...

Código R {.build}

• Organizando funções:
  • dividir arquivos por temas,
  • manter padrão de títulos e conteúdos
• Não use library(), require() nem source(), setwd(), etc.
  • Ao invés disso, coloque dependências na documentação.

Documentação dos objetos

• Facilmente construído
  • colocando headers nas funções do R e
  • usando devtools::document()
• Começar com #'
• workflow: Adicionar documentação em roxygen -> chamar devtools::document() -> visualizar documentação com ? -> Adicionar documentação em roxygen -> ...
• Tags com @tag (ex: @param).
• Textos:
  • Primeira sentença é o título.
  • Segundo parágrafo é uma descrição.
  • Os outos parágrafos vão para Details.

Vignettes

• Útil para dar uma explicação geral de um pacote
• Facilmente construído usando RMarkdown
• Geralmente usado para pacotes mais complexos

Testes

• Pacote testthat, do Hadley.
• devtools::use_testthat()
• Defina o que você quer testar (função e parâmetros), e o que você espera de resultado
• workflow: mude códigos -> devtools::test() -> repita.

library(stringr)
context("String Length")
test_that("str_length is a number of characters", {
  expect_equal(str_length('a'), 1)
  expect_equal(str_length('ab'), 2)
  expect_equal(str_length('abc'), 3)
})

Namespace

• Pode ser necessário se preocupar com isso se você quiser colocar seu pacote no CRAN.
• imports e exports.
• Search path, load e attach.
• requireNamespace() dá load e não attach.
• Geralmente também é criado usando devtools::document() e roxygen2.
• Use @export para fazer sua função ficar disponível para o usuário via ::
• Use @importFrom pkg fun para importar funções no NAMESPACE (não recomendável)
• Use Depends se você quiser dar attach de um pacote e usar suas funções (no DESCRIPTION).

Dados externos {.build}

• Quatro maneiras de incluir dados no pacote.
  • Binários (.RData) na pasta data/. Utilizar devtools::use_data().
  • Dados utilizados internamente pelas funções em R/sysdata.rda.
  • Dados em texto (csv, excel, etc), na pasta inst/extdata.
  • Dados que não são utilizados pelo pacote em data-raw. Utilizar devtools::use_data_raw().
• Documentar dados é semelhante a documentar funções, adicionando @format e @source.
• Não é necessário usar @export.

Código compilado (C, C++, etc)

• Usar o pacote RCpp
• Programar em C e C++ foge do escopo do curso
• Usando o RStudio e abrindo um novo arquivo, é possível visualizar um template.
• Usar Ctrl+Shift+B ao invés de devtools::load_all()

Git e GitHub

• Versionamento
• Colaboração
• Funciona como um website para seu pacote

curso-r/mcUFSCar2015 documentation built on May 14, 2019, 12:51 p.m.