In pet-estatistica/labestData: Biblioteca de Dados para Aprendizado de Estatística

source("config/_setup.R")
opts_chunk$set(eval = FALSE)

Esse documento descreve o roteiro de trabalho no labestData, desde a instalação do software até os passos para inclusão das contribuições. Os primeiros 4 itens precisam ser feitos apenas uma vez por máquina, as milestones e issues são feitos uma vez por obra, enquanto que os demais procedimentos tem uma peridiodicidade semanal.

Instalação e Configuração do Git

O Git é um sistema de controle de versão. Para instalar o Git no Linux, execute no terminal as instruções abaixo.

# Instalar no Linux (Ubuntu e Mint).
sudo apt-get install git git-core git-man git-gui git-doc \
     ssh openssh-server openssh-client gitk meld -y

Para instalar no Windows, baixe o *.exe disponível no endereço https://git-scm.com/download/win.

Após instalar, é necessário configurar sua conta com as suas informações pessoais: nome e e-mail. Execute no terminal do Linux (se Linux) ou no Git-bash (se Windows), as intruções abaixo substituindo os campos entre aspas pelas suas informações.

# Configura informações pessoais.
git config --global user.name "Seu Nome Aqui"
git config --global user.email "[e-mail]"

# Mostra as configurações feitas.
git config --list

Essas instruções escrevem um arquivo oculto na home do usuário chamado .gitconfig. Você pode abrir e editar esse arquivo se quiser, inclusive para incluir atalhos (aliases) de comandos, mas tenha cuidado para não comprometê-lo com erros. Veja um exemplo de arquivo .gitconfig.

Comunição do Cliente com o GitLab

Depois de instalar o Git é necessário estabelecer comunição com o servidor do serviço GitLab para que um conteúdo (arquivos) seja transferido entre cliente (computador do usuário) e servidor (computador que hospeda o GitLab). A autenticação entre as máquinas é baseada em chaves. Para gerar um par de chaves, execute as instruções abaixo no terminal ou git-bash, substituindo o e-mail pelo seu. O prompt vai pedir para que você forneça uma passphrase mas você pode apenas pressionar ENTER.

ssh-keygen -t rsa -C "[e-mail]"

No output do terminal será informado o endereço do par de arquivos gerados: id_rsa e id_rsa.pub. Esse par é único. Abra o arquivo id_rsa.pub em um editor de texto e copie o seu conteúdo sem modificá-lo. Entre em https://gitlab.c3sl.ufpr.br/profile/keys, cole o conteúdo no campo key e dê um título no campo title. Recomenda-se que o título informe o computador que contem as chaves (e.g. PC-casa, notebook, PC-PET). Clique em Add key para concluir.

Para finalizar, teste se a autenticação está sendo feita. Execute no terminal ou git-bash a instrução abaixo.

# Testa a comunição entre cliente (você) e servidor (GitLab).
ssh -T [e-mail]

Se for retornado um Welcome, então o procedimento foi realizado com sucesso. Importante: sempre que você executar o comando que gera as chaves, novas chaves serão geradas e você terá que substituir as chaves cadastradas anteriormente (a menos que você gere em outro diretório ou faça backup).

Instalar os Pacotes devtools e roxygen2

O desenvolvimento do pacote labestData é baseado no uso do pacote devtools com a documentação escrita no formato roxygen2.

Para instalar esses pacotes, execute em uma sessão R os códigos abaixo.

install.packages(c("devtools", "roxygen2"), dependencies = TRUE)

O devtools tem dependências do sistema operacional. Se a sua instalação no Linux não der certo, leia o output no console que, normamente, é indicado lá o que não foi encontrado. Em geral, basta instalar as "libs" abaixo.

sudo apt-get install libcurl4-openssl-dev libssl-dev

Depois de instalar, tente carregar os dois pacotes.

library(devtools)
library(roxygen2)

Clonar o Repositório do LabestData

Para trabalhar no labestData você precisa ter uma cópia do repositório. Abre o terminal ou git-bash em um diretório para fazer uma cópia do labestData dentro dele. O comando cd (change directory) muda de diretórios. Além disso, você pode clicar com o botão direito do mouse no espaço em branco do navegador de arquivos (Nautilus ou Windows Explorer) e clicar em Open in Terminal ou Open gih-bash here para abri-los no diretório exibido pelo navegador de arquivos.

Para clonar o repositório, execute a instrução abaixo.

# Clona o repositório do labestData.
git clone [e-mail]:pet-estatistica/labestData.git

Agora com a cópia, você pode explorar o projeto e fazer contribuições ao mesmo. Os comandos Git abaixo vão fazer um tour pelo labestData.

# Mostra o diretório atual.
pwd

# Move para o diretório recém clonado do labestData.
cd labestData/

# Mostra o estado do repositório.
git status

# Exibe todos os ramos presentes. Com asterisco é o ramo atual.
# Sem argumentos equivale a -l (local), -r (remotes), -a (all).
git branch
git branch -l
git branch -r
git branch -a

# Mostra o log (histórico) do projeto. Pressione q para sair.
git log
git log --oneline

# Abre a aplicação gitk para navegar no projeto.
gitk

Criar Milestone

Toda obra no labestData é uma milestone. A tradução literal é pedra de milha. A milestone na realidade é a definição de uma meta. Uma milestone é um coletivo de issues. Issue é um assunto ou tópico. No projeto labestData, issue é a definição do trabalho de uma semana. Portanto, uma milestone é uma obra, e os issues dessa milestone são fragmentos dessa obra que serão trabalhados em uma semana.

Para criar uma milestone, acesse https://gitlab.c3sl.ufpr.br/pet-estatistica/labestData/milestones e clique em New Milestone. Preencha o campo descrição com detalhes da obra, como título, autores, ano, editora. Visite as milestones já criadas para ver exemplos.

Criar Issues

Dentro da milestone recém criada, clique em New Issue para criar os issues. Na descrição dos issues indique com detalhes o trabalho a ser feito naquele issue. Por exemplo, indique a tabela/página dos conjuntos de dados a serem incluídos com esse issue. Ao criar o issue escolha uma label condizente com o tema da obra.

Cada issue deve ter conteúdo programado para uma semana de desenvolvimento. Pela experiência adquirida, isso equivale à 2 tabelas grandes (maior que meia página) ou 5 tabelas médias (até 10 linhas) ou 8 tabelas pequenas (como tabelas de contigência). Lembre-se, o custo maior de tempo está muitas vezes na documentação do conjunto de dados do que na digitação dos mesmos.

O ideal é que toda a obra seja fragmentada em issues dentro da milestone no início do período de desenvolvimento do projeto. Isso é fundamental para o planejamento individual e coletivo dos desenvolvedores do projeto.

Você pode nagegar pelos issues do projeto em https://gitlab.c3sl.ufpr.br/pet-estatistica/labestData/issues. É possível aplicar filtros para o autor, milestone ou label. Perceba que todas as issues tem um número único. Esse número será usado como parte do nome dos branches de desenvolvimento.

Criar Ramo para Desenvolvimento

Agora que a obra já possui milestone e issues com seus respectividos números, vamos criar ramos para inclusão das contribuições previstas no issue.

O branch de desenvolvimento é autor numerado, ou seja, composto pelo nome do autor e número do issue (e.g. walmes159). Esse ramo é sempre extraído do branch baby, que tem apenas o conteúdo mínimo necessário. Antes, no entanto, é recomendado incorporar possíveis atualizações no baby. Os comandos abaixo ilustram isso.

# Muda para o ramo baby.
git checkout baby

# Atualiza para incorporar possíveis atualizações feitas.
git pull origin baby

# Cria um ramo a partir do baby.
git checkout -b seunome123

# Mostra o ramo atual. Deve estar com asterisco o seunome123.
git branch

O ciclo de vida dos ramos de desenvolvimento (ou demanda) é de uma semana. Ao final de cada semana eles são incorporados ao ramo devel e depois são removidos. Só existem três ramos permanentes: baby, devel e master.

Adicionar Contribuições

Essa parte consiste basicamente em criar 4 arquivos para cada conjunto de dados: data-raw/*.txt, data/*.rda, R/*.R e man/*.Rd. Considerando que o nome do conjunto de dados seja dados, por simplicidade, teríamos então a seguinte estrutura.

labestData/
|-- DESCRIPTION
|-- NAMESPACE
|-- data-raw/
|   `-- dados.txt               1. Digitar os dados e criar arquivo txt.
|-- data/
|   `-- dados.rda               2. Gerar rda com use_data(dados).
|-- R/
|   `-- dados.R                 3. Gerar esqueleto com roxy_data(dados)
`-- man/                           e preencher.
    `-- dados.Rd                4. Gerar documentação com document().

Algumas funções foram criadas para auxiliar no desenvolvimento do labestData, como a roxy_data(). Elas estão disponíveis no snippet 46 do GitLab: https://gitlab.c3sl.ufpr.br/snippets/46. Recomenda-se que você tenha um script com os códigos para trabalhar no labestData e que carrege as funções no snippet ao iniciar sua sessão R. O repositório não versiona arquivos com nome roteiro.R, portanto considere nomear seu script dessa forma.

# Abre no navegador o snippet 46.
browseURL("https://gitlab.c3sl.ufpr.br/snippets/46/")

# Carrega as funções do definidas no snippet 46.
source("https://gitlab.c3sl.ufpr.br/snippets/46/raw")

Arquivo txt

Existem várias maneiras de gerar o arquivo *.txt e destacamos três: digitar na planilha e exportar pela planilha, digitar na planilha e exportar pelo R, digitar no R e exportar pelo R.

Digitar na planilha e exportar pela planilha : Consiste em digitar os dados em uma planilha eletrônica, copiar a região com os dados, criar um arquivo txt vazio em data-raw/ e colar o conteúdo copiado da planilha dentro. As colunas serão separadas por tabulação.

Digitar na planilha e exportar com o R : Digitar os dados na planilha eletrônica, copiar a região com os dados, carregar pelo R com read.table("clipboard", header = TRUE, sep = "\t"). Depois escrever em data-raw/ com a função write2txt(dados) (disponível no snippet 46).

Digitar no R e exportar com o R : Digitar os dados com o R usando scan() ou edit() e exportar com a função write2txt(dados). Essa opção é bastante vantajosa quando você tem dados com estrutura regular, como os de experimentos planejados. Você pode criar as estruturas com expand.grid() e então só digitar a variável resposta.

Arquivo rda

O arquivo rda pode ser gerado com a função use_data() do pacote devtools.

# Gera o arquivo dados.rda no diretório data/.
use_data(dados)

Depois de criar o arquivo rda, você deve remover esse objeto do da memória e carregar o labestData com load_all(). Esse é momento de experimentar o conjunto de dados para ver se ele não contém erros.

# Remove o objeto "dados" da memória.
rm("dados")

# Carrega os objetos do labestData. Isso vai carregar o dados.
load_all()

# Objetos do labestData.
ls("package:labestData")

# Mostra a estrutura do objeto.
str(dados)

Arquivo R

O arquivo R vai conter a documentação do conjunto de dados escrito no formato definido pelo pacote roxygen2. Esse formato será transcrito para o formato oficial de documentação R, cuja extensão de arquivo é Rd (R documentation), e se assemelha aos textos LaTeX.

Para gerar o arquivo R com uma documentação prévia, execute a função roxy_data() definida no snippet.

# Cria o arquivo dados.R no diretório R/.
roxy_data(dados)

A função roxy_data() criará o arquivo R com parte da documentação preenchida. Abra o arquivo e complete com as informações restantes.

Arquivo Rd

O arquivo Rd é gerado automaticamente, a partir do arquivo R, pela função document() do devtools. A função check_man() verifica se existe problemas com a documentação gerada, como campos mal formados, inexistentes ou falta de chaves em algum ambiente.

# Gera a documentação dados.Rd em man/.
document()

# Verifica se a documentação não contém erros.
check_man()

Resumo com Comandos

# Carrega as funções do definidas no snippet 46.
source("https://gitlab.c3sl.ufpr.br/snippets/46/raw")

# Carregar os dados no txt (opção 1).
dados <- read.table("data-raw/dados.txt", header = TRUE, sep = "\t")

# Carregar os dados da área de transferência (opção 2).
dados <- read.table("clipboard", header = TRUE, sep = "\t")

# IMPORTANT: Use esses dados para ver se estão corretos.

library(devtools)

# Cria o txt no diretório data-raw/.
write2txt(dados)

# Criar o rda no diretório data/.
use_data(dados)

# Remover ele do workspace.
rm("dados")

# Carregar o labestData em desenvolvimento.
load_all()

# Exibe o nome dos objetos do pacote.
ls("package:labestData")

# Mostra estrutura dos dodos.
str(dados)

# Cria o arquivo com a documentação parcialmente preenchido.
roxy_data(dados)

# Abrir o arquivo R gerado no diretório R/ e editar.

# Gera o arquivo Rd no diretório man/.
document()

# Busca por erros na documentação gerada.
check_man()

# Mostra o diretório em forma de árvore.
dirtree("../")

Verificar

Depois de adicionados os 4 arquivos referentes ao conjunto de dados, é necessário fazer uma verificação integral do pacote. Caso erros tenham sido introduzidos, nessa fase serão indenficados para serem corrigidos antes de serem enviados para o repositório remoto. Procure sempre subir para o repositório remoto contribuições estáveis.

# Verificação integral. Gera manual mas não as vinhetas. Resultados
# ficam em diretório ao lado do atual.
check(manual = TRUE, vignettes = FALSE, check_dir = "../")

# Cria o arquivo comprimido (zip, tar.gz) para distribuição do pacote.
build(manual = TRUE, vignettes = TRUE)

Orientações de uso do Git

O recurso mais utilizado por desenvolvedores do labestData e que é permanente no projeto é o commit. Por isso, é importante fazer o commit de forma correta para tirarmos ainda mais vantagem desse incrível recurso. Algumas diretrizes para fazer commits são dadas na página oficial do Git. Destacaremos as mais relevantes para o labestData.

Faça commits de mudanças completas : Apenas faça commits de arquivos para unidades completas de algo. Por exemplo, não faça commit de um texto com frases incompletas, não faça commit de uma função cujo código não foi terminado de escrever.

Faça commits pensando que vai precisar revertê-los : Antes de fazer um commit, imagine que vai precisar revertê-lo, voltar para o instante antes de fazê-lo. Existe um jeito melhor de agrupar mudanças que seja melhor para o caso de precisar retroceder? Se sim, faça o agrupamento de mudanças para um commit com isso em mente.

Use uma mensagem curta e apropriada : Prefira mensagens curtas e acertivas. Elas devem em poucas palavras permitir se lembrar ou advinhar o que foi feito. Normalmente, mensagens que relatam o porquê das modificações são assim. Se um commit precisar de uma mensagem longa demais, então é porque ele agrupa modificações divisíveis.

Use o tempo verbal como se fosse um comando : Recomenda-se usar o tempo verbal no presente da segunda pessoa (ele/ela): faz, corrige, remove, muda, fatora, rescreve, transfere, copia, acrescenta, modifica.

Adote o idioma plenamente : Adotar o idioma plenamente, com palavras acentuadas e sinais de pontuação facilita bastante quando for necessário fazer buscas nos textos das mensagens, pois só existe um jeito certo para a grafia das palavras.

Fazer Merge Request

Para fazer merge request visite: https://gitlab.c3sl.ufpr.br/pet-estatistica/labestData/merge_requests. Clique no botão New Merge Request para criar um novo MR. Detalhe no campo descrição todas as contribuições enviadas com o ramo que você submeteu para a avaliação, informe também qual o issue esse ramo refere-se com #NumeroIssue isso garante que as atualizações feitas no MR também serão reportadas no issue correspondente. Escolha dentre os mergers do projeto aquele que foi designado para você.

Quando o seu MR não for aceito, o merger vai deixar descrição das correções a serem feitas na página do seu MR. Todo MR tem um número correspondente, como os issues. Quando fizer as correções por ele apontadas, comente na página do MR que o ramo está pronto para incorporação novamente.

Finalizar o trabalho

Após aceito o MR, ou seja, suas contribuições tiverem sido incorporadas ao ramo devel, deve-se fechar o issue que originou o MR. Caso tenha colocado na descrição do MR a indicação do issue com #NumeroIssue, apenas vá até o issue (https://gitlab.c3sl.ufpr.br/pet-estatistica/labestData/issues/NumeroIssue) e clique em Close issue, caso contrário indique como comentário do issue qual MR que incorpora as contribuições por ele indicadas, faça isso com !NumeroMR. Com o issue finalizado, deve-se então remover o ramo criado para desenvolvimento do trabalho, faça isso com

# Atualiza todos os ramos conforme versão remota
git pull

# Mude para o ramo baby
git checkout baby

# Remova o ramo de desenvolvimento local
git branch -d seunome123

# Remova o ramo de desenvolvimento do GitLab
git push origin :seunome123

Certifique-se de que o ramo de desenvolvimento do issue foi realmente incorporado ao devel para então realizar esses procedimentos. Feito isso retorna-se à seção Criar ramo para Desenvolvimento realizando todo o roteiro descrito semanalmente até que se finalize todas as issues compreendidas na Milestone correspondente.

pet-estatistica/labestData documentation built on May 25, 2019, 12:47 a.m.