Adiciona vinheta com obras e guia de contribuição.

vignettes/guia-contrib.Rmd

+---
+title: "Guia de Contribuição e Estilo"
+author: "PET Estatística UFPR"
+bibliography: config/bibliography.bib
+csl: config/ABNT_UFPR_2011-Mendeley.csl
+vignette: >
+  %\VignetteIndexEntry{Guia de Contribuição e Estilo}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include=FALSE}
+source("config/_setup.R")
+```
+
+O Guia de Contribuição e Estilo serve para orientar a forma de trabalhar
+que seja eficiente, padronizada, coordenada e segura e produza conteúdo
+de qualidade. Este guia contém orientações de como escrever o código e
+escrever a documentação.
+
+## Estilo de Escrita de Código R
+
+Os números circulados de vermelhos nas imagens abaixo indicam diferenças
+entre os padrões de escrita de código R. Os dois fragmentos de código
+fazem a mesma coisa, funcionam igualmente, porém o primeiro é o padrão
+adotado no labestData.
+
+![](img/style-01.png)
+
+1. Use o operador `<-` e não o operador `=` para atribuir conteúdo aos
+   objetos. Deixe espaço ao redor do operador `<-`. Isso resolve a
+   ambiguidade: `x<-2 ` é `x < -2` ou `x <- 2`?
+2. Use espaço ao redor dos operadores matemáticos: exceto `^` e `/`,
+   todos os demais tem espaços ao redor: `+ - * %% %/% %*%`. Um caso
+   particular é o `-` que não tem espaço quando é o negativo (`-5 * 2`)
+   mas tem quando é o menos (`2 - 5`).
+3. Use espaço ao redor dos operadores lógicos:
+   `== != > >= < <= & && | || %in%`.
+
+![](img/style-02.png)
+
+1. Use espaço para separar o argumento do valor que ele recebe.
+2. Sempre use espaço após a vírgula e nunca use antes dela.
+3. A regra para a vírgula vale dentro de colchetes também. Duas vírgulas
+   não ficam coladas.
+4. Use aspas duplas. Usuários experientes afirmam que a dupla é mais
+   visível por ser um caractere mais cheio. Na linguagem R não existe
+   nenhuma diferença de função entre elas, para outras, como o Shell,
+   existe e deixa de ser uma questão estética mas funcional.
+5. Em algumas linguagens de programação há quem goste do estilo *comma
+   first*. No entanto, além de não haver um argumento forte para, não é
+   esse o padrão adotado pelos programadores de R. Não use *comma
+   first*.
+
+![](img/style-03.png)
+
+1. Acostume-se a usar nomes curtos. A chance de erro de digitação com
+   nomes curtos é menor. Tente abreviações e siglas para definir os seus
+   objetos, evitando nomes que excedam 6 caracteres. O caso de nomes de
+   função em pacote é uma exceção, pois nomes curtos demais podem não
+   ser difícil de recordar ou de adivinhar o significado dele. Quando
+   houver necessidade de nome composto, pode ser usado `.` e o
+   `_`. Existe uma preferência para que nomes de funções em pacotes usem
+   o `_` porque o `.` é usado na construção de funções método.
+2. Use endereços relativos porque isso deixa o código com
+   mais portabilidade.
+3. Evite 1) espaço no nome de diretórios e arquivos, 2) evite caracteres
+   acentuados (não ASCII) e 3) evite letras maiúsculas para diminuir os
+   erros de digitação. No lugar dos espaços recomenda-se usar
+   *underline* ou traço.
+4. Evite ultrapassar 72 caracteres no comprimento das linhas do
+   código. Isso deixa seu código mais vertical e legível, não esconde
+   texto para monitores de pequena resolução, evita quebras de linhas
+   acidentais quando o texto é colado em processadores de texto (me
+   pergunto para que alguém faz isso[^1]) ou se e-mail.
+5. Não abrevie o nome dos argumentos. Você pode até ganhar
+   microssegundos de tempo com isso, mas o seu código fica menos
+   portável (mais sujeito a erro e ambiguidade) além de ser menos
+   compreendido por um usuário não familiar com a linguagem ou com a
+   função que você está usando.
+6. Nunca abrevie para `T` ou `F` os valores lógicos `TRUE` e `FALSE`. Os
+   últimos são palavras reservadas do sistema mas os primeiros são
+   apenas objetos, ou seja, nada impede de fazer `T <- 10` e isso seria
+   desastroso para que abrevia `TRUE` com `T`.
+7. Evite definir objetos ou nomes das variáveis em `data.frames` com
+   maiúsculas. O R é *case sensitive* e as chances de erro de digitação
+   são maiores.
+8. Evite usar `;` e faça quebra de linha para deixar o código mais
+   vertical. Ele é um operador que permite escrever duas instruções na
+   mesma linha mas isso faz crescer horizontalmente, pode ultrapassar as
+   margens.
+
+![](img/style-04.png)
+
+1. Nas construções como `function`, `if`, `for`, `while`, etc, deixe
+   espaço entre o parentese direito e chave esquerda.
+2. O padrão de uso de chaves no R é o [K&R] 1TBS (*the one true brace
+   style*). Nesse padrão de chave, o construtor (`if`, `for`, `while`,
+   etc) antecede a chave que abre e chave que fecha fica sozinha na
+   linha (indentada com o construtor), a menos que esteja acompanhada de
+   um cláusula `else`, de outra chave ou parêntese.
+3. Idem ao 1 e 2.
+4. Deixe espaço entre o nome do construtor e o parêntese que abre. A
+   única exceção é para `function`.
+5. Idem ao 4.
+6. Evite deixar as construções como `function`, `if`, `for`, `while`,
+   sem as chaves mesmo que o corpo seja uma linha curta. As chaves
+   evitam que linhas adicionadas acidentalmente provoquem erros e
+   deixa seu código mais claro.
+7. Use o `return` no final das suas funções porque isso marca melhor o
+   que a função retorna. Usuários não familiares agradecem.
+8. A indentação padrão no R é com 4 espaços (e não com TAB). O RStudio,
+   por exemplo, vem com 2 espaços por padrão. Mude isso no
+   `Global Options > Code > Editing`. Os mais experientes dizem que 4
+   espaços dá mais evidência da hierarquia do código.
+
+![](img/style-05.png)
+
+1. Definitivamente use `library` e não `require`. Apesar do último
+   parecer mais lógico por ser um verbo, `library` é que carrega um
+   pacote. Se o pacote não estiver presente, a `library` retorna um
+   **Error** (!) e a `require` retorna um `FALSE`.
+2. O `~` é um operador como o `-`: tem espaço se existe um objeto que o
+   precede, caso contrário não tem.
+3. Prefira notação científica nos gráficos. Uma grande vantagem do R é
+   permitir anotação matemática nos gráficos. Use sempre que possível,
+   principalmente quando os gráficos vão para uma
+   monografia/disertação/tese ou artigo.
+
+![](img/style-06.png)
+
+1. Para seu próprio benefício, comente o seu código. Os comentários vão
+   te guiar no futuro quando sua memória falhar. Encare o seus
+   comentários como um texto normal e siga as regras do idioma que
+   adotar usar: acentue, comece com maiúscula, termine com ponto.
+2. Quando for o caso, separe o seu código em "seções temáticas". Use
+   algo para destacar isso, como uma linha horizontal. No Emacs é
+   bastante fácil fazer essas linhas horizontal como o mesmo
+   comprimento[^2].
+3. Deixe linhas em branco para separar o código. Não empilhe código que
+   não seja logicamente conectado pois os espaços funcionam como o
+   intervalo entre dois parágrafos de texto.
+4. Use o mesmo número de caracteres para fazer comentários. Todos os
+   editores de R usam um sinal de `#`, que é mais barato. Só o Emacs que
+   usa dois sinais de comentários para o R, lisp e outras linguagens
+   porque no Emacs o número de sinais tem função para indentação. Mas
+   isso é customizável e recomenda-se que você mude para um.
+
+## Regras para Inclusão de Conjuntos de Dados
+
+### Regra para dar nomes aos conjuntos de dados
+
+Para o *labestData* conter diversas obras com rápida e precisa
+identificação dos conjuntos de dados, foi necessário adotar uma regra
+de nomeação. A regra é bem simples. O nome é composto por 3 partes:
+`ObraIndNumer`. `Obra` é a referência a obra, `Ind` é o tipo de elemento
+identificador e `Num` é o número do elemento identificador. São
+exemplos da aplicação dessa regra
+
+  * ZimmermannTb10.20: Obra @zimmermann, Tabela 10.20 (capítulo 10,
+    tabela 20).
+  * BanzattoQd8.4.3: Obra @banzatto, Quadro 8.4.3 (capítulo
+    8, seção 4, tabela 3.)
+  * PaulaEx3.7.20: Obra @paula, Exercício 3.7.20 (capítulo 3, seção 7,
+    exercício 20).
+  * DemetrioEg7.7: Obra @demetrio, Exemplo 7.7 (capítulo 7, exemplo
+    7). Para não confundir exemplo com exercício, usou-se Eg do termo
+    em latin *exempli gratia*.
+  * MingotiAnA1: Obra @mingoti, Anexo A1.
+  * PimentelPg142: Obra @pimentel, Página 142.
+
+A tabela abaixo resume as siglas usadas para cada tipo de referência ao
+conjunto de dados dentro da obra.
+
+| Referência | Abreviação |
+|------------+------------|
+| Tabela     | Tb         |
+| Quadro     | Qd         |
+| Exercício  | Ex         |
+| Exemplo    | Eg         |
+| Apêndice   | Ap         |
+| Anexo      | An         |
+| Página     | Pg         |
+
+A prioridade na hora de atribuir a identificação é a seguinte: Tabela =
+Quadro > Exemplo = Exercício > Apêndice = Anexo > Página. Ou seja, se a
+tabela 5 faz parte do exemplo 3 que está na página 122, o nome do
+dataset terá sufixo Tb5. Note que uma página pode ter mais de uma
+tabela, bem como mais de um exemplo. Além do mais, diferentes edições
+podem preservar com mais facilidade a numeração das tabelas do que a
+localização delas nas mesmas páginas. Sendo assim, um dataset só será
+identificado como sufixo Ex ou Eg se não estiver em Tabela ou Quadro
+numerado e só será identificado pela página se não houver outra
+alternativa.
+
+Dados de arquivos pessoais que não foram usados em uma publicação
+(artigo, trabalho de conclusão de curso, dissertação ou tese), poder ter
+o nome do proprietário, do local de origem, ou outro identificador que
+seja único e descritivo do conjunto de dados.
+
+### Regra para o nome das variáveis
+
+O nome das variáveis não deve conter acentos (ASCII pleno), não pode
+iniciar com número e só admite o *underline* como não alfanumérico (mas
+evite). As variáveis de nome composto e longo devem ser representadas
+por siglas e as de nome simples mas longo, por abreviação. Veja a tabela
+com exemplos de como dar nome para variáveis do conjunto de dados.
+
+| Variável                   | Nome da coluna |
+|----------------------------+----------------|
+| Dias                       | dias           |
+| Peso                       | peso           |
+| Idade                      | idade          |
+| Renda                      | renda          |
+| Escolaridade               | escol          |
+| Cultivar                   | cult           |
+| Variedade                  | varied         |
+| Adubação                   | adub           |
+| Produtividade              | prod           |
+| Temperatura                | temp           |
+| Pressão sanguínea          | ps             |
+| Matéria orgânica           | mo             |
+| Teor de magnésio do solo   | mg             |
+| Diâmetro à altura do peito | dap            |
+| Massa seca de parte aérea  | mspa           |
+
+### Tipo de valor das variáveis
+
+É fundamental que os objetos que armazenem as variáveis declarem o tipo
+correto de valor. São 5 os tipos principais:
+
+  * `numeric`: é o tipo de valor para variáveis contínuas. Normalmente
+    essas variáveis tem unidade de medida e números decimais (e.g. 1.85
+    m, 78.5 kg).
+  * `integer`: é o tipo de valor para variáveis discretas (números
+    inteiros). Variáveis de contagem são desse tipo. São também as
+    variáveis que identificam a repetição ou amostra, normalmente
+    sequências de incremento 1 que começam em 1 ou 0. Quando variáveis
+    contínuas tiverem representação que não tenha casas decimais, elas
+    dever ser declaradas como `integer` para salvar espaço em disco e
+    tornar as contas mais rápidas.
+  * `factor`: é tipo de valor para variáveis categóricas. São rótulos
+    que classificam um conjunto de indivíduos/observações com uma
+    variável qualitativa comum. Como exemplo, tem-se os blocos de um
+    experimento em delineamento de blocos casualizados, as observações
+    do mesmo bairro, os pacientes do mesmo sexo, as parcelas do mesmo
+    local ou extrato, etc.
+      * Os fatores devem ter o rótulo mais descritivo possível, ou seja,
+        se os níveis são Kennebec, Huinkul e Buena Vista (variedades de
+        batatinha) não codifique como 1, 2 e 3. Também não abrevie
+        porque na forma abreviada a correspondência não é
+        imediata. Quando os nomes completos são usados, eles aparecem
+        nos gráficos e nas saídas, o que é bom.
+      * Variáveis como sexo (Masculino, Feminino) podem ser abreviadas
+        por M e F, sem prejuízo ao entendimento, pois a correspondência
+        é imediata (é fácil adivinhar que M e F representa masculino e
+        feminino). Da mesma forma, os níveis resistente e suscetível
+        poder ser abreviados para R e S, e os Estados brasileiros podem
+        ser representados pelas suas siglas.
+      * Nos casos em que os fatores são representados por número
+        inteiros mas são categóricos (como é caso dos blocos do
+        experimento), deve-se usar `factor` ao invés de `integer` para a
+        variável, mesmo que os rótulos continuem a ser os números
+        inteiros. Isso evita erros na interpretação e análise dos
+        dados. Uma opção para os blocos, por exemplo, é usar números
+        romanos, como I, II e III, ao invés de 1, 2 e 3 (use
+        `as.roman(1:n)`). Para fatores como variedade, uma alternativas
+        é usar letras maiúsculas, como A, B e C, ao invés dos números.
+      * Deve ser feita distinção entre fatores nominais (`factor`) e
+        ordinais (`ordered`).
+  * `character`: é o tipo de valor para identificar/descrever
+    indivíduos, como o nome dos alunos em uma classe. Essas variáveis
+    dificilmente representam uma característica preditiva de algo.
+  * `logical`: são para variáveis que assumem dois valores (`TRUE`,
+    `FALSE`). Também podem ser representados pelos valores inteiros 1
+    e 0.
+
+### Dados que não tabelas
+
+Existem casos em que os dados não são uma tabela (várias variáveis, em
+cada coluna uma variável de tipo diferente), ou seja, usar um
+`data.frame` para armazená-los não é adequado. Existem três casos
+principais:
+
+  * Quando os dados são uma amostra aleatória de uma única
+    variável. Nesse caso, os dados devem ser armazenados em um
+    vetor. Ele deve ser um vetor nomeado no caso das observações terem
+    rótulo, como o nome da cidade que corresponde ao valor (veja o dado
+    `precip`).
+  * Quando os dados são uma matriz, ou seja, todos os valores
+    correspondem ao mesmo tipo de valor. É o caso, por exemplo, de uma
+    matriz de distâncias entre cidades. Nesse caso, os dados devem ser
+    armazenados como matriz (`matrix`). Pode-se atribuir nome para as
+    linhas e colunas (`rownames` e `colnames`) para identificar os
+    registros.
+  * Quando os dados são uma amostra aleatória não independente, uma
+    séria temporal. Neste caso, no R, há uma classe de objetos `ts`
+    (*Time-Series*) que armazena os valores da amostra junto com a
+    informação da frequência em que foi observada.
+
+## Regras para Documentação dos Conjuntos de Dados
+
+Os conjuntos de dados devem ter uma documentação que permita
+
+. Existem vários campos da documentação que podem ser usados, no
+entanto, somente 7 serão considerados indispensáveis. Uma lista completa
+com a maioria dos campos está documentada em
+<https://cran.r-project.org/web/packages/roxygen2/roxygen2.pdf>.
+
+Para ilustrar o uso dos campos principais, abaixo tem-se a documentação
+do *data.frame* `RamalhoTb4.7`. Embora os campos sejam autoexplicativos
+por causa do nome, segue breve explicação.
+
+![](img/style-07.png)
+
+`@name`
+: É o campo com o nome do objeto que contém os dados (1).
+
+`@title`
+: É o título que representa o conjunto de dados. O título deve
+  estar apropriado para o conjunto de dados fornecendo uma boa descrição
+  do mesmo. O título deve estar captalizado, ou seja, iniciais
+  maiúsculas, exceto para artigos e preposições. Para que os títulos
+  aparecem na documentação em PDF, deve-se usar `\enc{}{}` (2) para as
+  letras não ASCII, como as vogais acentuadas e o cedilha.
+
+`@description`
+: É o campo para fornecer a descrição detalhada do conjunto de dados,
+  como delineamento ou plano amostral, objetivo do estudo (hipóteses ou
+  teoria), pessoas/organizações envolvidas. A descrição pode conter mais
+  de um parágrafo. Formatação de texto para itálico é feito com
+  `\emph{}` (3), que deve ser usado no nome científico de
+  espécies. Quando for mencionada alguma referência na obra (4) sobre os
+  dados, esta deve ser incluída na descrição e aparecer no campo
+  `@references`.
+
+`@format`
+: Campo que informa sobre a forma e conteúdo do conjunto de
+  dados. Primeiramente deve ser informado o tipo de objeto e suas
+  dimensões (5) e depois fazer a descrição de cada uma das variáveis. A
+  descrição das variáveis deve conter nome, explicação, unidade de
+  medida e tipo de valor. A unidade de medida deve ser escrita com
+  notação de potência ao invés de denominadores (6).
+
+`@keywords`
+: São palavras que classificam o conjunto de dados de acordo, por
+  exemplo, com o tipo de variável resposta, delineamento (7) ou análise
+  recomendada (ex: DIC, DQL, contagem, proporção, ACP, RP). Elas
+  aparecem no índice remissivo no manual em PDF e facilitam na hora de
+  escolher dados para poder praticar.
+
+`@source`
+: Indica a fonte dos dados. Normalmente é a referência
+  bibliográfica (8), a *url* do endereço de origem ou o nome
+  proprietário dos dados (indivíduo, grupo ou instituição). Quando é
+  mencionada outra fonte para os dados, como um artigo, dissertação ou
+  tese, esta referência também precisa ser incluída (9). Para as obras
+  usadas no pacote, é suficiente apenas a chamada da referência (autores
+  e ano).
+
+`@examples`
+: Contém código R que faz análise exploratória dos
+  dados, como gráficos (13) e tabelas (12). Os pacotes necessários para
+  executar o código da sessão devem ser carregados (10), bem como os
+  próprios dados (11). Depois da documentação, um `NULL` deve estar
+  presente (14).
+
+## Referências Bibliográficas
+
+<!------------------------------------------- -->
+
+[**labestData**]: https://gitlab.c3sl.ufpr.br/pet-estatistica/labestData
+[^1]: Processador de texto é diferente de editor de texto. O MS Word e o LibreOffice Writer são processadores enquanto que o Emacs e o Geany são editores.
+[K&R]: https://en.wikipedia.org/wiki/Indent_style#K.26R_style
+[^2]: Faça `C 7 C 1 -` (ctrol+7 ctrol+1 traço) para fazer 71 traços.

vignettes/obras.Rmd

+---
+title: "Obras Contidas no labestData"
+author: "PET Estatística UFPR"
+bibliography: config/bibliography.bib
+csl: config/ABNT_UFPR_2011-Mendeley.csl
+vignette: >
+  %\VignetteIndexEntry{Obras Contidas no labestData}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+bib <- gsub(x = grep(x = readLines("config/bibliography.bib"),
+                     pattern = "^@",
+                     value = TRUE),
+            pattern = "^.*\\{(.*),.*", replacement = "  * @\\1")
+```
+
+O pacote *labestData* contém conjuntos de dados de `r length(bib)` obras
+de diversas áreas da Estatística como: modelo regressão, estatística
+experimental, modelos lineares generalizados, controle estatístico da
+qualidade, e outros. A lista abaixo contém a referência de cada uma
+dessas obras.
+
+```{r, echo = FALSE, results = "asis"}
+cat(bib, sep = "\n")
+```
+
+## Referências Bibliográficas