1 Notas editoriais e técnicas

Nesta página descrevemos a abordagem filosófica, o estilo e as decisões editoriais específicas tomadas durante a criação deste manual.

1.1 Abordagem e estilo

O público em potencial para este livro é grande. Ele será certamente utilizado por pessoas muito novas no R, e também por usuários experientes do R que procuram as melhores práticas e dicas. Portanto, deve ser ao mesmo tempo acessível e sucinto. Portanto, a nossa abordagem foi fornecer o suficiente no texto para que alguém muito novo no R possa aplicar o código e seguir o que o código está fazendo.

Alguns outros pontos:

Este é um livro de referência de códigos, acompanhado de exemplos relativamente breves - não um livro de texto completo sobre R ou sobre ciência de dados
Este é um manual de R para utilização no âmbito da epidemiologia aplicada - não um manual sobre os métodos ou a ciência da epidemiologia aplicada
Este destina-se a ser um documento “vivo” - os pacotes R que são ideais para uma determinada tarefa tendem a mudar frequentemente, e estamos abertos a discussão sobre qual pacote deveríamos enfatizar neste manual

Pacotes do R

São tantas escolhas

Um dos aspectos mais desafiadores da aprendizagem de R é saber qual o pacote R utilizar para uma dada tarefa. É uma ocorrência comum esforçar-se demais em uma tarefa e só mais tarde perceber - ei, há um pacote R que faz tudo isso numa única linha de código!

Neste manual, tentamos oferecer-lhe pelo menos duas formas de completar cada tarefa: um método experimentado e validado (provavelmente em R base ou tidyverse) e um pacote especial R que tenha sido construído para esse fim. Queremos que tenham algumas opções caso não consigam fazer o download de um determinado pacote ou que este não funcione.

Ao escolher os pacotes a utilizar, nós demos prioridade aos pacotes R e às abordagens que foram testados e aprovados pela comunidade. Também minimizamos o número de pacotes utilizados numa sessão de trabalho típica, e escolhemos aqueles que são estáveis (não mudam com muita frequência), e que cumprem a tarefa de forma simples e limpa

Este manual dá, de modo geral, prioridade aos pacotes e funções R do tidyverse. Tidyverse é uma colecção de pacotes de R concebidos para a ciência de dados que partilham gramática e estruturas de dados em comum. Todos os pacotes do tidyverse podem ser instalados ou carregados através do pacote tidyverse. Leia mais em tidyverse website.

Quando aplicável, também oferecemos opções de código usando o R base - os pacotes e funções que já vêm com R na sua instalação. Isto porque reconhecemos que parte do público deste livro podem não ter Internet estável para realizar o download de pacotes extra.

Explicitando os pacotes de origem de cada função

Geralmente é frustrante quando, nos tutoriais de R, uma função é mostrada em código, mas não se sabe de que pacote ela é! Tentamos evitar esta situação.

No texto narrativo, os nomes dos pacotes são escritos a negrito (por exemplo dplyr) e as funções são escritas desta forma: mutate(). Esforçamo-nos por ser explícitos sobre de que pacote vem uma função, seja referenciando o pacote em texto próximo ou especificando o pacote explicitamente no código: dplyr::mutate(). Pode parecer redundante, mas estamos fazendo isso de propósito.

Veja a página em Introdução ao R para saber mais sobre pacotes e funções.

Estilo do código

No manual, nós utilizamos frequentemente “novas linhas”, fazendo o nosso código parecer “longo”. Fazemos isso por algumas razões:

Dessa forma podemos escrever comentários explicativos com `#’, colocando-os posicionados de forma adjacente a cada pequena parte do código
Geralmente, o código mais longo (vertical) é mais fácil de ler
É mais fácil de ler em uma tela estreita (não é necessária rolagem lateral)
A partir das indentações, pode ser mais fácil saber que argumentos pertencem a que função

Como resultado, código que poderia ser escrito desta forma:

linelist %>% 
  group_by(hospital) %>%  # agrupe as linhas por hospital
  slice_max(date, n = 1, with_ties = F) # se houver um empate (de data), pegue a primeira linha

…é escrito assim:

linelist %>% 
  group_by(hospital) %>% # agrupe as linhas por hospital
  slice_max(
    date,                # mantenha a linha que contem o valor máximo de data para cada grupo k
    n = 1,               # mantenha unicamente a linha com o valor mais alto
    with_ties = F)       # se houver um empate (de data), pegue a primeira linha

O código R não é geralmente afetado por novas linhas ou indentações. Ao escrever o código, se você iniciar uma nova linha após uma vírgula, ele aplicará padrões de recuo automáticamente.

Também utilizamos muitos espaços (por exemplo n = 1 em vez de n=1) porque é mais fácil de ler. Seja gentil com as pessoas que lêem o seu código!

Nomenclatura

Neste manual, referimos geralmente “colunas” e “linhas” em vez de “variáveis” e “observações”. Como explicado neste manual em “tidy data”, a maioria dos conjuntos de dados estatísticos epidemiológicos consistem estruturalmente em linhas, colunas e valores.

As variáveis contêm os valores que medem o mesmo atributo subjacente (como grupo etário, resultado, ou data de início). Observações contêm todos os valores medidos na mesma unidade (por exemplo, uma pessoa, local, ou amostra de laboratório). Portanto, estes aspectos podem ser mais difíceis de definir de forma tangível.

Em conjuntos de dados “arrumados” (tidy), cada coluna é uma variável, cada linha é uma observação, e cada célula é um valor único. No entanto, alguns conjuntos de dados que encontrarem podem não seguir esse modelo - um conjunto de dados de formato “largo” pode ter uma variável dividida em várias colunas (ver um exemplo na página Pivoteando Dados). Da mesma forma, uma única observação pode estar divididas em várias linhas.

A maior parte deste manual trata da gestão e transformação de dados, e por isso, se referir às estruturas concretas de dados (linhas e colunas) é mais relevante do que se referir às observações e às variáveis de forma mais abstractas. As exceções ocorrem principalmente em páginas sobre análise de dados, onde se verá mais referências a variáveis e observações.

Notas

Aqui estão os tipos de notas que você poderá encontrar neste manual:

NOTA: Isso é uma nota
DICA: Isso é uma dica.
CUIDADO: Esta é uma nota de precaução.
PERIGO: Isso é uma advertência.

1.2 Decisões editoriais

Abaixo, relacionamos decisões editoriais significativas em torno da escolha do pacote e da função. Se discordar ou quiser oferecer uma nova ferramenta para consideração, por favor, junte-se/ inicie uma conversa na nossa página Github.

Tabela de pacote, função, e outras decisões editoriais*

Assunto	POssibilidades	Escolha	Breve justificativa
Abordagem geral para escrita do código	tidyverse, data.table, base	tidyverse, com uma página sobre data.table, e menções a alternativas em R base para leitores sem internet	A facilidade de leitura proporcionada pelo tidyverse, elém da sua universalidade e maior utilização para ensino.
Carregamento de pacotes	`library()`,`install.packages()`, `require()`, pacman	pacman	Encurta e simplifica o código para a maioria dos casos de instalação/carregamento de vários pacotes
Importar e Exportar	rio, muitos outros pacotes	rio	Fácil para muitos tipos de arquivo
Agrupamento para estatísticas resumo	dplyr `group_by()`, stats `aggregate()`	dplyr `group_by()`	Compatível com a ênfase em tidyverse
Pivotamento (	tidyr (funções de pivotamento), reshape2 (melt/cast), tidyr (spread/gather)	tidyr (funções de pivotamento)	reshape2 está em desuso, tidyr usa funções de pivotamento desde a versão v1.0.0
Limpar nome das colunas	linelist, janitor	janitor	Consolidação de pacotes enfatizada
Epiweeks	lubridate, aweek, tsibble, zoo	lubridate de modo geral, os outros em casos específicos	A flexibilidade, consistência e perspectiva de manutenção do pacote lubridate
Rótulos/Legendas do ggplot	`labs()`, `ggtitle()`/`ylab()`/`xlab()`	`labs()`	todos os rótulos em um lugar, simplicidade
Converter para fator	`factor()`, forcats	forcats	suas várias funções tembém convertem para o formato de fator em um memso comando
Curvas epidêmicas	incidence, ggplot2, EpiCurve	incidence2 para rapidez, ggplot2 para detalhamento	fiabilidade
Concatenação	`paste()`, `paste0()`, `str_glue()`, `glue()`	`str_glue()`	Funções com sintaxe mais simples do que as funções paste; está contido stringr

1.3 Principais revisões

Data	Principais mudanças
10 Maio 2021	Lançamento da versão 1.0.0

1.4 Informação da sessão (R, RStudio, pacotes)

Abaixo estão as informações sobre as versões dos pacotes R, RStudio, e R utilizados durante esta elaboração deste Manual.

sessioninfo::session_info()

─ Session info ───────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.3.2 (2023-10-31 ucrt)
 os       Windows 11 x64 (build 22621)
 system   x86_64, mingw32
 ui       RTerm
 language (EN)
 collate  English_United States.utf8
 ctype    English_United States.utf8
 tz       Europe/Stockholm
 date     2024-06-19
 pandoc   3.1.11 @ C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/ (via rmarkdown)

─ Packages ───────────────────────────────────────────────────────────────────
 package     * version date (UTC) lib source
 cli           3.6.2   2023-12-11 [2] CRAN (R 4.3.2)
 digest        0.6.35  2024-03-11 [1] CRAN (R 4.3.3)
 evaluate      0.23    2023-11-01 [2] CRAN (R 4.3.2)
 fastmap       1.1.1   2023-02-24 [2] CRAN (R 4.3.2)
 htmltools     0.5.8   2024-03-25 [1] CRAN (R 4.3.3)
 htmlwidgets   1.6.4   2023-12-06 [2] CRAN (R 4.3.2)
 jsonlite      1.8.8   2023-12-04 [2] CRAN (R 4.3.2)
 knitr         1.45    2023-10-30 [2] CRAN (R 4.3.2)
 rlang         1.1.3   2024-01-10 [2] CRAN (R 4.3.2)
 rmarkdown     2.26    2024-03-05 [1] CRAN (R 4.3.3)
 rstudioapi    0.15.0  2023-07-07 [2] CRAN (R 4.3.2)
 sessioninfo   1.2.2   2021-12-06 [2] CRAN (R 4.3.2)
 xfun          0.43    2024-03-25 [1] CRAN (R 4.3.3)

 [1] C:/Users/ngulu864/AppData/Local/R/win-library/4.3
 [2] C:/Program Files/R/R-4.3.2/library

──────────────────────────────────────────────────────────────────────────────