6  Fluxo de trabalho: scripts e projetos

Este capítulo irá te apresentar duas ferramentas essenciais para organizar seu código: scripts e projetos.

6.1 Scripts

Até agora você usou o console para executar códigos. O console é um ótimo lugar para começar, mas com o tempo você perceberá que ele vai ficando apertado à medida que criamos gráficos mais complexos com ggplot2 e pipelines mais longas com dplyr. Para ter mais espaço para trabalhar, use o editor de scripts. Abra-o clicando no menu Arquivo, selecionando Novo Arquivo e depois R script, ou usando o atalho de teclado Cmd/Ctrl + Shift + N. Agora você verá quatro painéis, como na Figura 6.1. O editor de scripts é um ótimo lugar para experimentar com seu código. Quando você quiser mudar algo, não precisa reescrever tudo, pode apenas editar o script e executá-lo novamente. E uma vez que você tenha escrito um código que funcione e faça o que você quer, pode salvá-lo como um arquivo de script para retornar a ele facilmente mais tarde.

Figura 6.1: Abrir o editor de script adiciona um novo painel no canto superior esquerdo da interface de usuário do RStudio.

6.1.1 Rodando código

O editor de scripts é um excelente lugar para construir gráficos complexos com ggplot2 ou sequências longas de manipulações com dplyr. O segredo para usar o editor de scripts de forma eficaz é memorizar um dos atalhos de teclado mais importantes: Cmd/Ctrl + Enter. Isso executa o trecho de código atual no console. Por exemplo, veja o código abaixo.

library(dplyr)
library(dados)

nao_cancelado <- voos %>% 
  filter(!is.na(atraso_saida)█, !is.na(atraso_chegada))

nao_cancelado %>% 
  group_by(ano, mes, dia) %>% 
  summarize(media = mean(atraso_saida))

Se o seu cursor estiver em █, pressionar Cmd/Ctrl + Enter executará o comando completo que gera nao_cancelado. Também moverá o cursor para a declaração seguinte (começando com nao_cancelado |>). Isso torna fácil percorrer o script completo pressionando repetidamente Cmd/Ctrl + Enter.

Em vez de executar seu código expressão por expressão, você também pode executar o script completo em um único passo com Cmd/Ctrl + Shift + S. Fazer isso regularmente é uma ótima maneira de garantir que você capturou todas as partes importantes do seu código no script.

Recomendamos que você sempre comece seu script carregando os pacotes de que precisa. Dessa forma, se você compartilhar seu código com outras pessoas, elas poderão ver facilmente quais pacotes precisam instalar. Observe, no entanto, que você nunca deve incluir install.packages() em um script que compartilha. É imprudente passar adiante um script que fará alterações no computador de alguém considerando que a pessoa pode não estar atenta ao que está fazendo!

Ao trabalhar nos próximos capítulos, recomendamos fortemente que você comece no editor de scripts e pratique seus atalhos de teclado. Com o tempo, enviar código para o console dessa maneira se tornará tão natural que você nem pensará sobre isso.

6.1.2 Diagnosticando problemas no código

No editor de scripts, o RStudio destacará erros de sintaxe com uma linha ondulada vermelha e um X na barra lateral:

Para saber mais sobre o problema, passe o mouse sobre o X:

O RStudio também informará sobre problemas em potencial:

6.1.3 Salvando e nomeando

O RStudio salva automaticamente o conteúdo do editor de scripts quando você sai e recarrega automaticamente quando você reabre. Contudo, é altamente recomendável evitar os nomes como Untitled1, Untitled2, Untitled3, etc, que são o padrão para arquivos não nomeados. Salve seus scripts e atribua a eles nomes que façam sentido.

Pode ser tentador nomear seus arquivos codigo.R ou meuscript.R, mas você deve pensar um pouco mais antes de escolher um nome para seu arquivo. Três princípios importantes para nomear arquivos são os seguintes:

1. Os nomes dos arquivos devem ser legíveis por máquina: evite espaços, símbolos e caracteres especiais. Não confie na sensibilidade a maiúsculas e minúsculas para distinguir arquivos.
2. Os nomes dos arquivos devem ser legíveis por humanos: use nomes de arquivos para descrever o que está no arquivo.
3. Os nomes dos arquivos devem se dar bem com a ordenação padrão: comece os nomes dos arquivos com números para que a ordenação alfabética os coloque na ordem em que são usados.

Por exemplo, suponha que você tenha os seguintes arquivos em uma pasta de projeto.

modelo alternativo.R
codigo para analise exploratoria.r
relatoriofinal.qmd
RelatorioFinal.qmd
fig 1.png
Figura_02.png
primeira_tentativa_modelo.R
executar-primeiro.r
temporario.txt

Existem vários problemas aqui: é difícil encontrar qual arquivo executar primeiro, os nomes dos arquivos contêm espaços, existem dois arquivos com o mesmo nome, um com caixa alta na primeira letra e outro sem (relatoriofinal vs. RelatorioFinal¹), e alguns nomes não descrevem seu conteúdo (executar-primeiro e temporario).

Aqui está uma maneira melhor de nomear e organizar o mesmo conjunto de arquivos:

01-carregar-dados.R
02-analise-exploratoria.R
03-modelo-abordagem-1.R
04-modelo-abordagem-2.R
fig-01.png
fig-02.png
relatorio-2022-03-20.qmd
relatorio-2022-04-02.qmd
notas-rascunho-relatorio.txt

Numerar os scripts principais torna óbvio a ordem em que devem ser executados e um esquema de nomenclatura consistente facilita a visualização do que varia. Além disso, as figuras são rotuladas de maneira semelhante, os relatórios são distinguidos por datas incluídas nos nomes dos arquivos, e temporario é renomeado para notas-rascunho-relatorio para descrever melhor seu conteúdo. Se você tem muitos arquivos em um diretório, é recomendado levar a organização um passo adiante e colocar diferentes tipos de arquivos (scripts, figuras, etc.) em diretórios diferentes.

6.2 Projetos

Um dia, você precisará sair do R, fazer outra coisa e voltar para a sua análise mais tarde. Um dia, você estará trabalhando em várias análises simultaneamente e vai querer mantê-las separadas. Um dia, você precisará trazer dados do mundo externo para o R e enviar resultados numéricos e figuras do R para o mundo externo.

Para lidar com essas situações da vida real, você precisa tomar duas decisões:

1. Qual é a fonte da verdade? O que você vai salvar como seu registro final do que aconteceu?

2. Onde é o lar da sua análise?

6.2.1 Qual é a fonte da verdade?

Como iniciante, é aceitável confiar no seu Ambiente (Environment) atual para guardar todos os objetos que você criou durante sua análise. No entanto, para facilitar o trabalho em projetos maiores ou colaborar com outros, sua fonte da verdade deveriam ser os scripts R. Com seus scripts R (e seus arquivos de dados), você pode recriar o ambiente (Environment). Com apenas o seu ambiente, é muito mais difícil recriar seus scripts R: você terá que digitar novamente muito código de memória (inevitavelmente cometendo erros ao longo do caminho) ou terá que cuidadosamente extrair seu histórico R.

Para ajudar a manter seus scripts R como a fonte da verdade para sua análise, recomendamos fortemente que você instrua o RStudio a não preservar seu espaço de trabalho (workspace) entre as sessões. Você pode fazer isso executando usethis::use_blank_slate()² ou imitando as opções mostradas na Figura 6.2. Isso causará alguma dor a curto prazo, porque agora, quando você reiniciar o RStudio, ele não se lembrará do código que você executou na última vez, nem os objetos que você criou ou os conjuntos de dados que você leu estarão disponíveis para uso. Mas essa dor a curto prazo poupa-lhe agonia a longo prazo, pois força você a capturar todos os procedimentos importantes em seu código. Não há nada pior do que descobrir três meses depois que você só armazenou os resultados de um cálculo importante em seu ambiente, não o próprio cálculo em seu código.

Figura 6.2: Copie estas opções nas suas opções do RStudio para sempre iniciar sua sessão do RStudio com um ambiente (Environment) limpo.

Existe um ótimo par de atalhos de teclado que trabalham juntos para garantir que você tenha capturado as partes importantes do seu código no editor:

1. Pressione Cmd/Ctrl + Shift + 0/F10 para reiniciar o R.
2. Pressione Cmd/Ctrl + Shift + S para executar novamente o script atual.

Nós usamos coletivamente este padrão centenas de vezes por semana.

Alternativamente, se você não usa atalhos de teclado, você pode ir para Sessão > Reiniciar R e então destacar e executar novamente o seu script atual.

RStudio server

Se você está usando o RStudio server, sua sessão R nunca é reiniciada por padrão. Quando você fecha a aba do seu RStudio server, pode parecer que você está fechando o R, mas o servidor na verdade continua rodando em segundo plano. Na próxima vez que você retornar, você estará exatamente no mesmo lugar que deixou. Isso torna ainda mais importante reiniciar regularmente o R para que você esteja começando com um ambiente limpo.

6.2.2 Onde é o “lar” da sua análise?

O R tem um poderoso conceito de diretório de trabalho. Este é o local onde o R procura por arquivos que você pede para carregar, e onde ele colocará quaisquer arquivos que você pedir para salvar. O RStudio mostra o seu diretório de trabalho atual no topo do console:

E você pode imprimir isso em código R executando getwd():

getwd()
#> [1] "/Users/hadley/Documents/r4ds"

Nesta sessão R, o diretório de trabalho atual (pense nele como “casa”) está na pasta Documentos do Hadley, em uma subpasta chamada r4ds. Este código retornará um resultado diferente quando você executá-lo, porque a estrutura de diretórios do seu computador é diferente da do Hadley!

Como um usuário iniciante de R, está tudo bem em deixar o seu diretório de trabalho ser o seu diretório inicial, diretório de documentos, ou qualquer outro diretório estranho no seu computador. Mas você já leu sete capítulos deste livro, e você não é mais um iniciante. Muito em breve, você deve evoluir para organizar seus projetos em diretórios e, ao trabalhar em um projeto, definir o diretório de trabalho do R para o diretório associado.

Você pode definir o diretório de trabalho a partir do próprio R, mas nós não recomendamos isso:

setwd("/caminho/para/meu/ProjetoLegal")

Existe uma maneira melhor; uma maneira que também te coloca no caminho para gerenciar seu trabalho em R como um especialista. Essa maneira é o projeto do RStudio.

6.2.3 Projetos do RStudio

Manter todos os arquivos associados a um determinado projeto (dados de entrada, scripts R, resultados analíticos e figuras) juntos em um diretório é uma prática tão sábia e comum que o RStudio tem suporte integrado para isso através de projetos. Vamos criar um projeto para você usar enquanto trabalha no restante deste livro. Clique em Arquivo > Novo Projeto, e então siga os passos mostrados em Figura 6.3.

Figura 6.3: Para criar um novo projeto: (topo) primeiro clique em Novo Diretório, depois (meio) clique em Novo Projeto, então (abaixo) preencha o nome do diretório (projeto), escolha um bom subdiretório para ser o “lar” do seu projeto, e clique em Criar Projeto.

Nomeie seu projeto como r4ds e pense cuidadosamente sobre qual subdiretório você colocará o projeto. Se você não armazená-lo em algum lugar que faça sentido, será difícil encontrá-lo no futuro!

Uma vez que esse processo esteja completo, você terá um novo projeto RStudio apenas para este livro. Verifique se o “lar” do seu projeto é o diretório de trabalho atual:

getwd()
#> [1] /Users/hadley/Documents/r4ds

Agora insira os seguintes comandos no editor de scripts e salve o arquivo, chamando-o de “diamantes.R”. Em seguida, crie uma nova pasta chamada “dados”. Você pode fazer isso clicando no botão “Nova Pasta” no painel de Arquivos no RStudio. Finalmente, execute o script completo, que salvará um arquivo PNG e CSV no diretório do seu projeto. Não se preocupe com os detalhes, você aprenderá mais tarde no livro.

library(dados)

ggplot(diamante, aes(x = quilate, y = preco)) + 
  geom_hex()
ggsave("diamantes.png")

write_csv(diamante, "dados/diamantes.csv")

Feche o RStudio. Inspecione a pasta associada ao seu projeto - observe o arquivo .Rproj. Dê um duplo clique nesse arquivo para reabrir o projeto. Observe que você volta para onde parou: é o mesmo diretório de trabalho e histórico de comandos, e todos os arquivos em que você estava trabalhando ainda estão abertos. Porque você seguiu nossas instruções acima, você terá, no entanto, um ambiente completamente novo, garantindo que você está começando com uma folha em branco.

Da maneira que preferir no seu sistema operacional, pesquise no seu computador por diamantes.png e você encontrará o PNG (sem surpresa) mas também o script que o criou (diamantes.R). Isso é ótimo! Um dia, você vai querer refazer uma figura ou apenas entender de onde ela veio. Se você rigorosamente salvar figuras em arquivos com código R e nunca com o mouse ou a área de transferência, você será capaz de reproduzir trabalhos antigos com facilidade!

6.2.4 Caminhos relativos e absolutos

Uma vez que você está dentro de um projeto, você deve usar apenas caminhos relativos, não caminhos absolutos. Qual é a diferença? Um caminho relativo é relativo ao diretório de trabalho, ou seja, a “casa” do projeto. Quando Hadley escreveu dados/diamantes.csv acima, era um atalho para /Users/hadley/Documents/r4ds/data/diamantes.csv. Mas, importante, se a Mine executasse este código em seu computador, apontaria para /Users/Mine/Documents/r4ds/data/diamantes.csv. É por isso que os caminhos relativos são importantes: eles funcionarão independentemente de onde a pasta do projeto R terminar.

Os caminhos absolutos apontam para o mesmo lugar, independentemente do seu diretório de trabalho. Eles parecem um pouco diferentes dependendo do seu sistema operacional. No Windows, eles começam com uma letra de unidade (por exemplo, C:) ou duas barras invertidas (por exemplo, \\servername) e no Mac/Linux eles começam com uma barra “/” (por exemplo, /users/hadley). Você nunca deve usar caminhos absolutos em seus scripts, porque eles dificultam o compartilhamento: ninguém mais terá exatamente a mesma configuração de diretório que você.

Há outra diferença importante entre os sistemas operacionais: como você separa os componentes do caminho. Mac e Linux usam barras (por exemplo, dados/diamantes.csv) e o Windows usa barras invertidas (por exemplo, dados\diamantes.csv). O R pode trabalhar com qualquer tipo (não importa a plataforma que você está usando atualmente), mas infelizmente, barras invertidas significam algo especial para o R, e para obter uma única barra invertida no caminho, você precisa digitar duas barras invertidas! Isso pode te frustrar, então recomendamos sempre usar o estilo do Linux/Mac com barras normais.

6.3 Exercícios

1. Acesse a conta do Twitter RStudio Tips (em inglês), https://twitter.com/rstudiotips e encontre uma dica que pareça interessante. Pratique usá-la!

2. Quais outros erros comuns o diagnóstico do RStudio irá reportar? Leia (em inglês) https://support.posit.co/hc/en-us/articles/205753617-Code-Diagnostics para descobrir.

6.4 Sumário

Neste capítulo, você aprendeu como organizar seu código R em scripts (arquivos) e projetos (diretórios). Assim como o estilo de código, isso pode parecer trabalho desnecessário no início. Mas à medida que você acumula mais código em vários projetos, você aprenderá a apreciar como uma pequena organização inicial pode economizar muito tempo no futuro.

Em resumo, scripts e projetos fornecem um fluxo de trabalho sólido que te servirá bem no futuro:

• Crie um projeto RStudio para cada projeto de análise de dados.
• Salve seus scripts (com nomes informativos) no projeto, edite-os, execute-os em partes ou como um todo. Reinicie o R frequentemente para garantir que você capturou tudo em seus scripts.
• Use apenas caminhos relativos, nunca caminhos absolutos.

Então tudo que você precisa está em um lugar e claramente separado de todos os outros projetos em que você está trabalhando.

Até agora, trabalhamos com conjuntos de dados incluídos em pacotes R. Isso facilita a prática em dados pré-preparados, mas obviamente seus dados não estarão disponíveis desta forma. Então, no próximo capítulo, você vai aprender como carregar dados do computador para a sua sessão R usando o pacote readr.

---

1. Sem mencionar que você está flertando com o azar ao usar “final” no nome 😆 A tirinha Piled Higher and Deeper tem uma divertida historinha sobre isso.

2. Se você não tem o pacote usethis instalado, você pode instalá-lo com install.packages("usethis").