Organizando o seu trabalho localmente

Organização - questão de estilo?

“Eu me acho na minha bagunça”, quem já ouviu essa frase, ou já pronunciou? Provavelmente todos nós. Mas o conceito de organização seria mesmo uma questão pessoal? Podemos discutir isso durante horas a fio se estivermos falando do seu quarto, da sua estante ou do seu guarda-roupa, mas quando falamos de ciência, ou seja, uma atividade coletiva, organização não é uma questão pessoal, justamente por ser coletiva. Sempre trabalhamos em conjunto, e isso pode ser com um grupo composto por muitas pessoas que trabalham em um determinado projeto, ou pode ser consigo mesmo, o seu eu do futuro. Desta maneira, é necessário que tudo que foi utilizado para o desenvolvimento do seu projeto científico seja de fácil compreensão para seus colaboradores ou para o seu “eu” do futuro.

Dados necessários para as práticas

Nesta seção vamos utilizar os dados do pacote {palmerpenguins}. Que apesar de estar disponível como pacote, portanto poderia ser lido automáticamente apenas baixando o pacote, vamos importar os dados a partir do nosso computador. Vamos fazer isso pois assim podemos demonstrar boas práticas na leitura de dados, scripts e organização do nosso repositório local de maneira geral. Os dados do pacote já estão no repositório que baixaram. Mais adiante vamos utilizá-lo, mas antes vamos ver esquemas gerais de organização de repositório local

Um esquema geral (mas não absoluto) para organização do diretório local

Nessa seção irei mostrar uma proposta de esquema geral para organização de diretórios. Essa estrutura é baseada nesta proposta do Gustavo Paterno.

Digo que não é absoluto pois modificações nesse esquema podem ser feita para ajustar ao conjunto de dados de cada pessoa. A Ecologia é um campo muito amplo de pesquisa, e nem todos os dados se ajustarão perfeitamente a esta proposta. O mais importante de tudo é que os dados estejam organizados de uma maneira intuitiva e consistente no diretório, como o na figura seguinte.

Um diretório minimamente organizado

Mas, qual a lógica por trás da organização desse diretório? Seguimos a proposta presente na figura seguinte (original pode ser visto aqui).

Nesta proposta os arquivos dentro de um projeto são organizados em 4 pastas que contemplam quase todos os documentos que geramos ou que precisamos quando estamos desenvolvendo um projeto científico.

Um modelo geral de organização do diretório local

Nomeando arquivos

Uma boa regra a ser seguida:

Human + Machine redable

Exemplo:

Nomeando scripts

Pessoalmente eu utilizo o seguinte esquema

número_letra-maiúscula_descrição.R

• número: usado para indicar a sequência de execução dos scripts

• letra maiúscula: Código que indica o que o script faz. Uso a seguinte notação

  • C (Clean) leitura e limpeza/processamento de dados
  • D (Do) análises
  • S (Show) gráficos/figuras

• descrição: uma breve descrição sobre o que o script faz especificamente (e.g. glm)

O README

O README é uma das partes mais importantes do seu diretório, ele é escrito em caixa alta justamente para que a pessoa que esteja acesssando o seu diretório ouça em voz alta Me leia por favor!!.

Neste arquivo de texto você irá encontrar as principais instruções sobre a estrutura do diretório, incluindo os nomes das pessoas que montaram o diretório, além de instruções básicas sobre o que contém em cada pasta. Aqui você pode encontrar dicas de como o README contendo as informações básicas necessárias que ele deve conter e porque. Aqui um template que pode ser adaptado para os seus propósitos. Aqui algumas dicas interessantes em português.

É importante saber que você não irá encontrar o modelo final para o README perfeito. Os detalhes de cada README vão variar dependendo do projeto que está desenvolvendo e a forma como ele deve ser apresentado ao usuário. Por exemplo, se o projeto se trata de um repositório de arquivos e scripts de um manuscrito, e não de um README de um projeto de software, não precisa haver alguns campos de explicação, tais como exemplo de uso ou antigas versões de lançamento. Aqui coloco um checklist adaptado de itens que julgo essenciais para um README informativo. Pense no seu trabalho, adicione ou edite esse checklist de acordo com seus propósitos.

Minha proposta de checklist:

• Uma linha explicando o propósito do repositório
• Autores do repositório
• Ligações e contextualizações necessárias (por exemplo, se o repositório está linkado a um artigo)
• badges (opcional)
• Instruções de instalação (ou download se for um repo)
• Exemplo de utilização claro e executável (se estivermos falando de uma base de dados ou pacote)
• Estrutura de pastas e scripts (o que cada pasta contém, o que cada script faz)
• Status do projeto (finalizado/em andamento)
• Em caso de problema com algo no repositório, como reportar (Usar o GitHub issues é uma boa ideia)
• Licença

Iniciando o README

Duas opções para montar o arquivo README. Primeira, montar você mesmo. O arquivo pode ser montado em um bloco de notas e deve ser nomeado como README.md. A extensão .md é importante aqui, ela significa que é um arquivo do tipo Markdown. Neste momento é importante saber que o arquivo Markdown é apenas uma linguagem de marcação. Vamos abordar em detalhes como elaborar documentos em Markdown, como este que lê neste momento, mais adiante. Por hora é relevante saber que o README deve ser em markdown pois assim o GitHub idenfica corretamente este documento como sendo o arquivo a ser exibido na página inicial do repositório remoto, como ilustrado na figura abaixo.

Arquivo README correspondente ao repositório deste site

Na realidade, o arquivo fonte tem essa aparência

Arquivo fonte para o README acima mostrado

Mostro como podemos montar um README nesta seção. Por enquanto vamos fazer o mais simples.

1- Abra um editor de texto (recomendo o Atom, mas o editor nativo do seu computador funciona bem também).

2- Digite qualquer título na primeira linha que se inicie com # Meu Título.

3- Salve o arquivo com o nome de README.md em algum local do seu computador. Por enquanto é isso.

Ferramentas para organização do diretório local

Iniciando um projeto com o RStudio

Como vimos na aula teórica, o RStudio possibilita enraizar o projeto, desta forma não precisamos utilizar caminhos absolutos, tornando nossa vida mais fácil e o trabalho mais reprodutível para quem tentar utilizar nosso repositório. Portanto, o primeiro passo vai ser iniciar um novo projeto com o RStudio. Para isso faça o seguinte:

1- Abra o RStudio

2- Em Arquivo, selecione Novo Projeto, como mostrado abaixo

Iniciando um projeto

3- Na janela que se abriu selecione Novo Diretório para iniciar o projeto em um diretório novo

Iniciando um projeto em um novo diretório

4- Escolha o tipo de projeto, neste caso novo projeto (se apenas um projeto, ou um pacote ou um aplicativo shiny)

5- Por fim escolha o nome para o diretório e onde ele vai estar no seu computador

Pronto, uma nova janela do RStudio se abrirá, indicando que seu projeto foi iniciado com sucesso. A partir de agora, para abrir o R e realizar modificações de scripts basta clicar no arquivo .RProject que leva o nome que deu ao diretório.

Pacotes para inicialização automática (alternativa)

Alguns pacotes auxiliam montar automaticamente a organização do seu diretório local, por exemplo essa ferramenta elaborado pelo Carl Boettiger e essa do Francisco Rodriguez-Sanchez.

Vamos explorar um pouco a funcionalidade do pacote {template}. Para tanto precisamos primeiro instalar o pacote que está hospedado no GitHub.

# install.packages("remotes")
remotes::install_github("Pakillo/template")

Em seguida vamos ler o pacote e iniciar um novo projeto

library("template")
new_project(name = "treegrowth", path = "caminho/para/diretório")

O diretório será iniciado no local indicado pelo argumento path na função new_project.

Here

O {here} é o melhor pacote para padronizar caminhos. Sabe aquele erro de leitura dos dados por conta de um / ou \, ou por ter esquecido ou errado na digitação daquele caminho gigantesco para o arquivo desejado? Com o {here} nada disso vai acontecer.

Para demonstrar o uso do pacote here vamos ler os dados palmer-penguins.txt para o R. Lembrando, abra o R a partir do .Rproject dentro do diretório que iniciamos nos passos anteriores

# caso não tenha o here instalado ainda
# install.packages("here")

library(here)

Da forma convencional poderíamos ler esse dado da seguinte forma

data_penguins <- read.csv("/Users/gabrielnakamura/OneDrive/Disciplina_Praticas_ferramentas_gestao_dados/USP_reproducibility_BIE5791/data/data-penguins.csv")

Será que você consegue reproduzir essa simples leitura de dados usando o mesmo código acima? Tente..

Após a tentativa fica claro que não é possível realizar essa leitura de dados. Mas vamos lembrar que temos o projeto que enraiza nossa pasta, então podemos apenas usar o seguinte código

data_penguins <- read.csv("data/data-penguins.csv")

Funcionou? Ou apenas para alguns?

Imagino que pode ter funcionado para todos que tem o computador onde a máquina reconhece / como separador de caminhos, porém, aqueles que precisa de \ para informar a separação dos caminhos não deve ter tido sucesso. Como resolvemos isso?

Aí entra o here. Com o pacote here podemos usar simplesmente o seguinte código

library(here)
data_penguins <- read.csv(here("data", "data-pengins.csv"))

Note que ao invés de usarmos o caminho, usamos dentro da função here o nome das pastas que levam até o arquivo que desejamos abrir, bem como o nome deste arquivo. Garanto que agora isso irá funcionar com todos