diff --git a/vignettes/_output.yaml b/vignettes/_output.yaml new file mode 100644 index 0000000000000000000000000000000000000000..53b4884f85589657b49bc6b9397ef770c2b87e9b --- /dev/null +++ b/vignettes/_output.yaml @@ -0,0 +1,12 @@ +html_document: + fig_width: 6 + fig_height: 6 + toc: true + toc_dep: 3 + css: config/_style.css + fig_caption: yes + highlight: default + includes: + in_header: config/_MathJax.html + before_body: config/_before_body.html + after_body: config/_after_body.html diff --git a/vignettes/config/ABNT_UFPR_2011-Mendeley.csl b/vignettes/config/ABNT_UFPR_2011-Mendeley.csl new file mode 100644 index 0000000000000000000000000000000000000000..746a0cde45cef6fc6abc2c488bc8fd4e522f3eea --- /dev/null +++ b/vignettes/config/ABNT_UFPR_2011-Mendeley.csl @@ -0,0 +1,235 @@ +<?xml version="1.0" encoding="utf-8"?> +<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0"> + <info> + <title>ABNT (UFPR)</title> + <id>http://www.zotero.org/styles/ABNT</id> + <link href="http://www.zotero.org/styles/ABNT" rel="self"/> + <author> + <name>Iuri Gavronski</name> + <email>iuri at ufrgs dot br</email> + </author> + <contributor> + <name>Eduardo Bettoni</name> + <email>webtur @ ufpr dot br</email> + </contributor> + <category citation-format="author-date"/> + <category field="generic-base"/> + <updated>2010-11-15T12:42:52+00:00</updated> + <summary>The Brazilian standard style</summary> + </info> + <macro name="container-contributors"> + <choose> + <if type="chapter paper-conference" match="any"> + <text value="In:" suffix=" "/> + <names variable="editor translator" delimiter=", " suffix="; "> + <name initialize-with=". " delimiter="; "/> + <label form="short" prefix=" (" text-case="capitalize-first" suffix=".)" strip-periods="true"/> + </names> + </if> + </choose> + </macro> + <macro name="secondary-contributors"> + <choose> + <if type="chapter paper-conference" match="none"> + <names variable="editor translator" delimiter=", " prefix=" (" suffix=")"> + <name and="symbol" initialize-with=". " delimiter=", "/> + <label form="short" prefix=", " text-case="capitalize-first" suffix="." strip-periods="true"/> + </names> + </if> + </choose> + </macro> + <macro name="author"> + <names variable="author"> + <name name-as-sort-order="all" sort-separator=", " initialize-with=". " delimiter="; " delimiter-precedes-last="always"> + <name-part name="family" text-case="uppercase"/> + <name-part name="given" text-case="uppercase"/> + </name> + <label form="short" prefix=" (" suffix=".)" text-case="uppercase" strip-periods="true"/> + <substitute> + <names variable="editor"/> + <names variable="translator"/> + <text macro="title"/> + </substitute> + </names> + </macro> + <macro name="author-short"> + <names variable="author"> + <name form="short" name-as-sort-order="all" sort-separator=", " initialize-with=". " delimiter="; " delimiter-precedes-last="always"> + <name-part name="family" text-case="uppercase"/> + <name-part name="given" text-case="uppercase"/> + </name> + <substitute> + <names variable="editor"/> + <names variable="translator"/> + <choose> + <if type="bill book graphic legal_case motion_picture report song" match="any"> + <text variable="title" form="short" font-weight="bold"/> + </if> + <else> + <text variable="title" form="short" quotes="true"/> + </else> + </choose> + </substitute> + </names> + </macro> + <macro name="access"> + <text variable="URL" prefix="Disponível em: <" suffix=">. "/> + <date variable="accessed" prefix="Acesso em: "> + <date-part name="day" suffix="/"/> + <date-part name="month" form="numeric" suffix="/"/> + <date-part name="year"/> + </date> + </macro> + <macro name="title"> + <choose> + <if type="bill book graphic legal_case motion_picture report song thesis" match="any"> + <text variable="title" font-weight="bold"/> + </if> + <else> + <text variable="title" suffix=". "/> + </else> + </choose> + </macro> + <macro name="container-title"> + <choose> + <if type="paper-conference" match="any"> + <text variable="container-title" suffix=". "/> + <text value=" Anais... " font-weight="bold"/> + </if> + <else> + <text variable="container-title" font-weight="bold"/> + </else> + </choose> + </macro> + <macro name="publisher"> + <text variable="genre" suffix=", "/> + <group delimiter=": "> + <text variable="publisher-place"/> + <text variable="publisher"/> + </group> + </macro> + <macro name="event"> + <text variable="event"/> + <text variable="event-place" prefix=", "/> + </macro> + <macro name="issued"> + <group prefix=" " suffix="." text-case="lowercase"> + <choose> + <if type="bill book graphic legal_case motion_picture report song article-journal chapter paper-conference" match="none"> + <date variable="issued"> + <date-part prefix=" " suffix="." name="day"/> + <date-part prefix=" " suffix=". " name="month" form="short" strip-periods="true"/> + </date> + </if> + </choose> + <date variable="issued"> + <date-part name="year"/> + </date> + </group> + </macro> + <macro name="issued-year"> + <date variable="issued"> + <date-part name="year"/> + </date> + </macro> + <macro name="edition"> + <choose> + <if type="bill book graphic legal_case motion_picture report song chapter paper-conference" match="any"> + <choose> + <if is-numeric="edition"> + <group delimiter=" "> + <number variable="edition" form="ordinal"/> + <text term="edition" form="short" suffix="." strip-periods="true"/> + </group> + </if> + <else> + <text variable="edition" suffix=" ed."/> + </else> + </choose> + </if> + </choose> + </macro> + <macro name="locators"> + <choose> + <if type="article-journal article-magazine article-newspaper" match="any"> + <group prefix=", " delimiter=", "> + <group> + <text variable="volume" prefix="v. "/> + <text variable="issue" prefix=", n. " suffix=""/> + </group> + <text variable="page" prefix="p. "/> + </group> + </if> + <else-if type="bill book graphic legal_case motion_picture report song chapter paper-conference" match="any"> + <group prefix=". " suffix="" delimiter=", "> + <text macro="edition"/> + <group> + <text variable="volume" prefix="v. "/> + </group> + <group> + <text variable="page" prefix="p."/> + </group> + </group> + </else-if> + </choose> + </macro> + <macro name="citation-locator"> + <group> + <label variable="locator" form="short"/> + <text variable="locator" prefix=" "/> + </group> + </macro> + <citation et-al-min="3" et-al-use-first="1" et-al-subsequent-min="3" et-al-subsequent-use-first="1" disambiguate-add-year-suffix="true" disambiguate-add-names="true" disambiguate-add-givenname="true" collapse="year"> + <sort> + <key variable="issued"/> + <key macro="author"/> + </sort> + <layout prefix="(" suffix=")" delimiter="; "> + <group delimiter=", "> + <text suffix="" macro="author-short"/> + <text macro="issued-year"/> + <text macro="citation-locator"/> + </group> + </layout> + </citation> + <bibliography hanging-indent="false" et-al-min="6" et-al-use-first="3" entry-spacing="0"> + <sort> + <key macro="author"/> + <key variable="issued"/> + </sort> + <layout suffix="."> + <choose> + <if type="bill book graphic legal_case motion_picture report song" match="any"> + <group> + <text macro="author" suffix=". "/> + <text macro="title" suffix=". "/> + <text macro="edition" suffix=". "/> + <text macro="publisher" suffix=", "/> + <text macro="issued-year"/> + </group> + </if> + <else-if type="webpage"> + <group> + <text macro="author" suffix="."/> + <text macro="title" prefix=" "/> + <text macro="access"/> + </group> + </else-if> + <else> + <text macro="author" suffix="."/> + <text macro="title" prefix=" "/> + <text macro="container-contributors"/> + <text macro="secondary-contributors"/> + <text macro="container-title"/> + <text variable="collection-title" prefix=", " suffix="."/> + <text macro="locators"/> + <text macro="issued" prefix=","/> + <group delimiter=". " prefix=". "> + <text macro="publisher"/> + <text macro="access"/> + </group> + </else> + </choose> + </layout> + </bibliography> +</style> diff --git a/vignettes/config/_MathJax.html b/vignettes/config/_MathJax.html new file mode 100644 index 0000000000000000000000000000000000000000..e7e537aea476322edbc18e67913fbec599b26b1a --- /dev/null +++ b/vignettes/config/_MathJax.html @@ -0,0 +1,9 @@ +<script type="text/x-mathjax-config"> + MathJax.Hub.Config({ + "HTML-CSS": { + scale: 85, + /* preferredFont: "STIX" /* padrão do MathJax */ + availableFonts: ["TeX"], /* */ + } + }); +</script> diff --git a/vignettes/config/_after_body.html b/vignettes/config/_after_body.html new file mode 100644 index 0000000000000000000000000000000000000000..09f93f49b47dbc33681ad8e5d269a49e6eaacf09 --- /dev/null +++ b/vignettes/config/_after_body.html @@ -0,0 +1,30 @@ +<style type="text/css"> +hr.footer { + border-top: 1px solid black; + margin-top: 20px; + margin-bottom: 2px; +} +table.footer { + margin-bottom: 10px; +} +</style> + +<hr class="footer"/> +<center> + <table class="footer" width="100%"> + <tr> + <td> + <a href="http://www.pet.est.ufpr.br/"> + PET Estatística UFPR + </a> + </td> + </tr> + <tr> + <td> + <em> + pet.estatistica.ufpr@gmail.com + </em> + </td> + </tr> + </table> +</center> diff --git a/vignettes/config/_before_body.html b/vignettes/config/_before_body.html new file mode 100644 index 0000000000000000000000000000000000000000..280a71dca4969ee0943a3f1f80a1912de3874499 --- /dev/null +++ b/vignettes/config/_before_body.html @@ -0,0 +1,29 @@ +<style type="text/css"> +div.header { + margin-top: 20px; + border-bottom: 1px solid #BCBCBC; +} +table.header { + margin-top: 10px; +} +</style> + +<table class="header" width="100%" align="center"> + <tr> + <td align="left" valign="bottom" width="90px"> + <img src="img/labestData.png" width="100%" /> + </td> + <td align="left" valign="top"> + <div class="header"> + <h4 style="font-size: 20px; margin: 10px"> + <em>labestData</em> - Biblioteca de Dados para Aprendizado de Estatística + </h4> + <h5 style="margin: 0px 0px 10px 10px"> + <a href="https://github.com/pet-estatistica/labestData"> + <code>github.com/pet-estatistica/labestData</code> + </a> + </h5> + </div> + </td> + </tr> +</table> diff --git a/vignettes/config/_setup.R b/vignettes/config/_setup.R new file mode 100644 index 0000000000000000000000000000000000000000..105acf497b8a21252aefe4044e79226e0d40f711 --- /dev/null +++ b/vignettes/config/_setup.R @@ -0,0 +1,29 @@ +library(knitr) +opts_chunk$set(cache = FALSE, + tidy = FALSE, + fig.width = 6, + fig.height = 6, + fig.align = "center", + dpi = 100, + dev = "png", + dev.args = list(family = "Palatino")) +options(width = 68) + +library(latticeExtra) +mycol <- c("#E41A1C", "#377EB8", "#4DAF4A", + "#984EA3", "#FF7F00", "#FFFF33") + +# Trellis graphical style. +ps <- list(box.rectangle = list(col = 1, fill = c("gray70")), + box.umbrella = list(col = 1, lty = 1), + dot.symbol = list(col = 1, pch = 19), + dot.line = list(col = "gray50", lty = 3), + plot.symbol = list(col = 1, cex = 0.8), + plot.line = list(col = 1), + plot.polygon = list(col = "gray95"), + superpose.line = list(col = mycol, lty = 1), + superpose.symbol = list(col = mycol, pch = 1), + superpose.polygon = list(col = mycol), + strip.background = list(col = c("gray80", "gray50"))) +trellis.par.set(ps) +# show.settings() diff --git a/vignettes/config/_style.css b/vignettes/config/_style.css new file mode 100644 index 0000000000000000000000000000000000000000..6d51c09b2de55a140967c26ce136c5a1a7efab99 --- /dev/null +++ b/vignettes/config/_style.css @@ -0,0 +1,67 @@ +body, td, caption { + font-family: "Palatino Linotype", "Book Antiqua", Palatino, serif; + background-color: white; + font-size: 16px; + text-align: justify; +} + +body { + width: 800px; + margin: auto; +} + +tt, code, pre { + font-family: "Inconsolata", "Andale Mono", monospace; +} + +pre code { + font-size: 14px; +} + +/* R input */ +pre, code { + border-radius: 3px; + background-color: #EDEDED; + color: #333; +} + +/* R output */ +pre:not([class]) code { + background-color: #D4D4D4; +} + +pre:not([class]), code { + background-color: #D4D4D4; +} + +img { + max-width: 100% !important; + display: block; + margin: auto; +} + +#header { + text-align: center; + margin: 20px 0px 20px 0px; +} + +#TOC { + /* border-bottom: 1px solid red; */ + margin: 0px 0px 20px 0px; +} + +#TOC li { + list-style: outside none url; +} + +blockquote { + font-size: 17.5px; + width: 90%; + border-left: none; + margin: auto; +} + +blockquote > blockquote > p { + color: "red"; + text-align: right; +} diff --git a/vignettes/config/bibliography.bib b/vignettes/config/bibliography.bib new file mode 100644 index 0000000000000000000000000000000000000000..0cc52bda50b70dbdeaa77c0942606ee9b94dce93 --- /dev/null +++ b/vignettes/config/bibliography.bib @@ -0,0 +1,158 @@ +% This file was created with JabRef 2.10b2. +% Encoding: UTF-8 + +@Book{banzatto, + Title = {Experimentação Agrícola}, + Author = {Banzatto, D. A. and Kronka, S. D.}, + Publisher = {Funep}, + Year = {2013}, + Address = {Jaboticabal, SP}, + Edition = {4}, +} + +@Book{barbin, + Title = {Planejamento e Análise Estatística de Experimentos Agronômicos}, + Author = {Barbin, D.}, + Publisher = {Mecenas}, + Year = {2013}, + Address = {Londrina, PR}, + Edition = {2}, +} + +@Book{dias, + Title = {Biometria Experimental}, + Author = {Barros, W. S. and Dias, L. A. S.}, + Publisher = {Editora UFV}, + Year = {2009}, + Address = {Viçosa, MG}, +} + +@Book{charnet, + Title = {Análise de Modelos de Regressão Linear com Aplicações}, + Author = {Charnet, R. and de Luna Freire, C.A. and Charnet, E.M.R. and Bonvino, H.}, + Publisher = {Editora Unicamp}, + Year = {2008}, + Address = {Campinas, SP}, + Edition = {2}, +} + +@Book{epprecht, + Title = {Controle Estatístico de Qualidade}, + Author = {Costa, A. F. B. and Epprecht, E. K. and Carpinetti, L.}, + Publisher = {Atlas}, + Year = {2010}, + Address = {São Paulo, SP}, + Edition = {2}, +} + +@Misc{costa, + Title = {Técnicas Experimentais aplicadas às Ciências Agrárias}, + Author = {Costa, J. R.}, + HowPublished = {Seropédica, RJ: Embrapa Agrobiologia (Documentos 163)}, + Year = {2003}, + Url = {http://www.ica.ufmg.br/mestrado_doutorado/images/stories/arquivos_mestrado/experimentao%20agrcola.pdf} +} + +@Misc{demetrio, + Title = {Modelos de Regressão}, + Author = {Demétrio, C. G. B. and Zocchi, S. S.}, + HowPublished = {Piracicaba, SP. ESALQ (apostila)}, + Year = {2011}, + Url = {http://www.lce.esalq.usp.br/arquivos/aulas/2011/LCE5801/Apostila.pdf} +} + +@Misc{faria, + Title = {Notas de aulas expandidas: Metodologia e Estatística Experimental}, + Author = {Faria, J. C.}, + HowPublished = {Ilhéus, BA. UESC (apostila)}, + Year = {2009}, + Url = {http://nbcgib.uesc.br/lec/download/faria/apostilas/CET076_12ed_1pf.pdf} +} + +@Book{ferreira, + Title = {Estatística Multivariada}, + Author = {Ferreira, D. F.}, + Publisher = {Editora UFLA}, + Year = {2011}, + Address = {Lavras, MG}, + Edition = {2}, +} + +@Book{manly, + Title = {Métodos Estatísticos Multivariados: uma introdução}, + Author = {Manly, B. F.}, + Publisher = {Bookman}, + Year = {2005}, + Address = {Porto Alegre}, +} + +@Book{mingoti, + Title = {Análise de dados através de métodos de estatística multivariada: uma abordagem aplicada}, + Author = {Mingoti, S. A.}, + Publisher = {Editora UFMG}, + Year = {2005}, + Address = {Belo Horizonte, MG}, +} + +@Misc{paula, + Title = {Modelos de regressão: com apoio computacional}, + Author = {Paula, G. A.}, + HowPublished = {São Paulo, SP. IME-USP (apostila)}, + Year = {2004}, + Url = {https://www.ime.usp.br/~giapaula/texto_2013.pdf} +} + +@Book{pimentel, + Title = {Curso de Estatística Experimental}, + Author = {{Pimentel-Gomes}, F.}, + Publisher = {FEALQ}, + Year = {2009}, + Address = {Piracicaba, SP}, + Edition = {15}, + +} + +@Book{ramalho, + Title = {Experimentação em Genética e Melhoramento de Plantas}, + Author = {Ramalho, M. A. P. and Ferreira, D. F. and Oliveira, A. C.}, + Publisher = {Editora UFLA}, + Year = {2005}, + Address = {Lavras, MG}, + Edition = {2}, +} + +@Book{ramos, + Title = {Controle Estatístico da Qualidade}, + Author = {Ramos, E. M. L. S. and Almeida, S. S, and Araújo, A. R.}, + Publisher = {Bookman}, + Year = {2013}, + Address = {Porto Alegre, RS}, + Edition = {1}, +} + +@Book{storck, + Title = {Experimentação Vegetal}, + Author = {Storck, L. and Garcia, B. C. and Lopes, S. J. and Estefanel, V.}, + Publisher = {Editora UFSM}, + Year = {2011}, + Address = {Santa Maria, RS}, + Edition = {3}, +} + +@Book{vieira, + Title = {Estatística Experimental}, + Author = {Vieira, S.}, + Publisher = {Atlas}, + Year = {1999}, + Address = {São Paulo, SP}, + Edition = {2}, +} + +@Book{zimmermann, + Title = {Estatística Aplicada à Pesquisa Agrícola}, + Author = {Zimmermann, F. J.}, + Publisher = {Embrapa Arroz e Feijão}, + Year = {2004}, + Address = {Santo Antônio de Goiás, GO}, + Edition = {1}, +} diff --git a/vignettes/guia-contrib.Rmd b/vignettes/guia-contrib.Rmd new file mode 100644 index 0000000000000000000000000000000000000000..c0b8d7ff758d3ed177df78850fa11dd7d4ff95d3 --- /dev/null +++ b/vignettes/guia-contrib.Rmd @@ -0,0 +1,423 @@ +--- +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). + +## Fluxo de Trabalho + +O fluxograma abaixo resumo em linhas gerais o fluxo de trabalho do +*labestData*. O fluxo é composto de 3 partes: 1) a da esquerda resume +ações feitas no gitlab ou entre gitlab e repositório local; 2) a do meio +são ações usando o R com o pacote *devtools*; e 3) são as ações usando o +Git. + + + +A primeira coisa é ler o Guia de Contribuição, que é este documento. Em +seguida, catalogar toda a obra criando uma +[*milestone*](https://gitlab.c3sl.ufpr.br/pet-estatistica/labestData/milestones) +para ela. Dentro da *milestone* devem ser criados *issues*. Cada *issue* +deve ter o conteúdo para uma semana de desenvolvimento. + +O desenvolvimento começa com a criação de um ramo para inclusão das +contribuições. Cada *issue* no gitlab é numerado e para uma fácil +indentificação, o padrão é criar ramos autor numerados: `jhenifer33`, +`alessandra90`, `walmes160`. O ramo de desenvolvimento deve ser tirado +do ramo *baby*. Antes, no entanto, atualize o ramo *baby*. + +Com o Git no ramo de desenvolvimento, o trabalho de inclusão do conjunto +de dados começa com a criação do arquivo texto `txt` no diretório +`data-raw/`. O arquivo deve ser um TSV (*tab separeted values*) com +valores separados por tabulação e a primeira linha como cabeçalho. Você +tem a opção de fazer *commits* quando convier. Carregue os dados em uma +sessão R e gere o binário `rda` no diretório `data/`. Em seguida, +carrege o pacote e experimente os dados que acabou de incluir para +eliminar qualquer eventual erro. Escreva a documentação do conjunto de +dados no diretório `R/`. Use a função `roxy_data()` definida em +<https://gitlab.c3sl.ufpr.br/snippets/46>. Por fim, gere e verifique se +a transcrição para o formato `Rd` aconteceu sem erros. + +Agora que todos os arquivos foram criados (`txt`, `rda`, `R` e `Rd`), é +necessário fazer uma verificação completa no pacote. Se problemas +forem indentificados nessa fase, deve procurar fazer a correção antes de +subir. Se não houveram erros, então faça o empacotamento para gerar o +`tar.gz` do pacote. Por fim, suba para o repositório remoto no gitlab. + +Na interface do gitlab, faça um *merge request* (requisição de fusão) +para o *merger* designado à você. Se o MR for aceito, ponto positivo, +você pode fechar o *issue* pois o completou e remover o ramo que já não +é mais necessário. Caso contrário, providencie as correções indicadas +pelo *merger* e, quando prontas, notifique-o novamente no mesmo MR. + +O Projeto só termina quando todas as obras tiverem sido concluídas. + +## 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/labestData.png b/vignettes/img/labestData.png new file mode 100644 index 0000000000000000000000000000000000000000..97f3fbea90d50eb6c70f658ffc4e7bb5ff1e11f1 Binary files /dev/null and b/vignettes/img/labestData.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/img/workflow-labestData.png b/vignettes/img/workflow-labestData.png new file mode 100644 index 0000000000000000000000000000000000000000..dba0b59622c4408cbb05a3224ea3cdda42c90999 Binary files /dev/null and b/vignettes/img/workflow-labestData.png differ diff --git a/vignettes/obras.Rmd b/vignettes/obras.Rmd new file mode 100644 index 0000000000000000000000000000000000000000..f4b9101cb85f4df8f18c4dcbea4b0cc80718a14c --- /dev/null +++ b/vignettes/obras.Rmd @@ -0,0 +1,38 @@ +--- +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} +rl <- readLines("config/bibliography.bib") +bib <- gsub(x = grep(x = rl, + 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 em formato bibtex + +```{r, echo = FALSE, results = "asis"} +cat("```tex\n") +cat(rl, sep = "\n") +cat("```\n") +``` + +## Referências Bibliográficas