diff --git a/vignettes/guia-contrib.Rmd b/vignettes/guia-contrib.Rmd new file mode 100644 index 0000000000000000000000000000000000000000..2461a3200360e6639703d2d8addfb0664c0596d8 --- /dev/null +++ b/vignettes/guia-contrib.Rmd @@ -0,0 +1,375 @@ +--- +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. + + + +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%`. + + + +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*. + + + +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. + + + +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. + + + +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. + + + +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. + + + +`@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. diff --git a/vignettes/img/crop-07.png b/vignettes/img/crop-07.png new file mode 100644 index 0000000000000000000000000000000000000000..d1be8868e60fcc30be2d34a3aa5581de00b3eda9 Binary files /dev/null and b/vignettes/img/crop-07.png differ diff --git a/vignettes/img/style-01.png b/vignettes/img/style-01.png new file mode 100644 index 0000000000000000000000000000000000000000..0b901abe0bb55cd5a56d029180aa9a6969d8fa0d Binary files /dev/null and b/vignettes/img/style-01.png differ diff --git a/vignettes/img/style-02.png b/vignettes/img/style-02.png new file mode 100644 index 0000000000000000000000000000000000000000..32e954ba60e2cb21dc6f0afd84acc9f455b8e4fd Binary files /dev/null and b/vignettes/img/style-02.png differ diff --git a/vignettes/img/style-03.png b/vignettes/img/style-03.png new file mode 100644 index 0000000000000000000000000000000000000000..ddd56d84129bee07878a8105257147e74a064151 Binary files /dev/null and b/vignettes/img/style-03.png differ diff --git a/vignettes/img/style-04.png b/vignettes/img/style-04.png new file mode 100644 index 0000000000000000000000000000000000000000..9772e6f7a9d6a477cb61998632148acbd032a3e2 Binary files /dev/null and b/vignettes/img/style-04.png differ diff --git a/vignettes/img/style-05.png b/vignettes/img/style-05.png new file mode 100644 index 0000000000000000000000000000000000000000..738b9c6056e3f5b20168b842c567efdb8805b4db Binary files /dev/null and b/vignettes/img/style-05.png differ diff --git a/vignettes/img/style-06.png b/vignettes/img/style-06.png new file mode 100644 index 0000000000000000000000000000000000000000..56eb2e596ac282d606f5a67663acaf76933e5e19 Binary files /dev/null and b/vignettes/img/style-06.png differ diff --git a/vignettes/img/style-07.png b/vignettes/img/style-07.png new file mode 100644 index 0000000000000000000000000000000000000000..be6d95696e58448443c1f89bed776e77cce7b374 Binary files /dev/null and b/vignettes/img/style-07.png differ diff --git a/vignettes/obras.Rmd b/vignettes/obras.Rmd new file mode 100644 index 0000000000000000000000000000000000000000..a38bc373c2378cb52659e9b499ca7688e7ef69e6 --- /dev/null +++ b/vignettes/obras.Rmd @@ -0,0 +1,29 @@ +--- +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