Quando se trabalha com dados, principalmente de forma colaborativa, é muito comum que as análises e seus resultados sejam postos em um relatório a fim de documentar a rotina de trabalho, compartilhar o código desenvolvido e comunicar os resultados obtidos. No R, em particular, isso facilmente pode ser feito por meio de um RMarkdown, um relatório dinâmico poderoso em contar histórias a respeito de dados. Ao proporcionar reprodutibilidade, flexibilidade de formatos e sintaxe bastante simples, propagou-se entre os usuários de R (com larga vantagem, obviamente) e também entre aqueles que não o são – para ser ter uma ideia, é possível usar as linguagens Python, JavaScript e SQL em RMarkdown.

Intuitivamente, o “R” de RMarkdown vem da linguagem de programação R e o “Markdown” está relacionado com a linguagem de marcação do tipo markdown, que por sua vez informa apenas sobre a estrutura (conjunto de marcações) do projeto. Logo, RMarkdown nada mais é do que códigos R (no caso em que a programação é feita com R) incorporados em um arquivo markdown.

Adiante, vamos ver como o RMarkdown funciona em sua forma mais simples, porém sem deixar de dizer como ele deve ser minimamente estruturado.

Partindo do ponto que o R + RStudio já está instalado – caso não, deixamos como sugestão a leitura do post Iniciando na linguagem R -, um arquivo RMarkdown (.Rmd) precisa ser criado. Para isso, vá em File > New File > R Markdown…. A janela New R Markdown será aberta. Nela, já podemos definir qual será o título (em Title), o nome do autor (em Author) e o formato do arquivo (em Default Output Format). Em nosso exemplo, vamos criar um arquivo .Rmd em que o título é Raça das gestantes e puérperas diagnosticadas com SRAG em 2021, os autores são estes que vos falam e HTML é o tipo do arquivo que queremos que seja gerado. É importante dizer que o RMarkdown exporta diferentes formatos para além desses exibidos como default.

Ao clicar em OK, um arquivo .Rmd será aberto no editor de script do RStudio com um roteiro pré-programado. Para não haver confusão, apague tudo o que estiver abaixo do cabeçalho (mais precisamente, tudo o que estiver abaixo do segundo —) e salve o arquivo com o nome que julgar adequado. Ah, caso queira alterar o nome do título e/ou o nome dos autores que foram definidos anteriormente, não tem problema, pode modificá-los normalmente. Inclusive, pode excluir a data e o autor se achar que são informações desnecessárias. O que não pode é deixar o arquivo sem o título e o output, informações indispensáveis para que o RMarkdown funcione. Em nosso caso, vamos apenas remover a data.

Como já deu para notar, é no cabeçalho (também conhecido como YAML) que estão as configurações gerais do documento. A princípio, determinamos somente o título, o nome dos autores e o formato do arquivo de interesse. Mas podem ser definidas muitas outras informações, como índice, seções, tema etc. Na documentação do RMarkdown para HTML é possível ver com detalhes todas essas possibilidades.

Após estabelecido o cabeçalho, é a partir daqui que as marcações de texto do markdown e os chunks começam a ser bastante utilizados. As marcações são sintaxes que vão indicar o que são desde títulos de seções, tópicos e imagens a links, códigos e expressões matemáticas. Por exemplo:

•  o tamanho do título de uma seção é determinado pela quantidade de #, em que quanto menor a quantidade, maior o tamanho da fonte (varia de 1 a 5 hashtags);

•  uma palavra em negrito deve estar entre ** e em itálico, entre _;

•  expressões matemáticas LaTeX podem ser feitas usando a mesma sintaxe LaTeX, desde que estejam entre $;

•  para incluir uma imagem no meio do texto siga o modelo de marcação: ; e

•  para incluir uma palavra/frase redirecionável: [palavra/texto](link).

Quanto aos chunks, eles são blocos de códigos que podem ser adicionados por meio do ícone verde que contém a letra C e um sinal de + (à esquerda do botão Run, na janela de script) ou pelo atalho Ctrl + Alt + I no Linux ou Windows ou Command + Option + I no Mac. Quando renderizados, eles são adicionados ao arquivo markdown (.md) via pacote {knitr}, que executa os códigos dos chunks e gera-os em .md. Em seguida, o pacote {pandoc} converte o arquivo .md para a linguagem de programação (neste caso, o R) e no formato de arquivo (neste caso, HTML) escolhidos. Não se preocupe se os dois pacotes mencionados não estiverem instalados, o R fará questão de avisá-lo sobre esse contratempo. Além disso, nos chunks existem uma série de alternativas que permitem ao usuário controlar a execução e os resultados dos códigos, tais como:

•  echo = FALSE: não exibir o código (TRUE, caso contrário);

•  eval = FALSE: não executar o código (TRUE, caso contrário);

•  message =  FALSE: esconder mensagens geradas pelo código (TRUE, caso contrário);

•  fig.height = 10: estipular a altura de uma figura (valor em polegadas);

•  fig.width = 10: estipular a largura de uma figura (valor em polegadas); e

•  fig.align = ‘ center’ : centralizar uma imagem.

É sugerido ler a seção 2.5 Markdown syntax se a intenção é conhecer o conjunto de sintaxes disponível para RMarkdown e a seção 2.6 R code chunks and inline R code para ver a gama de opções que está a serviço dos chunks.

Vamos ver como isso funciona na prática ao dar continuidade àquele arquivo .Rmd que criamos alguns parágrafos atrás.

Em nosso “mini” relatório, vejam que redigimos um pequeno texto como introdução igualmente como fazemos em editores de texto como o Word e Google Docs, por exemplo. Já para dar início à seção “Os dados”, utilizamos o marcador ###. No entanto, a atenção mesmo fica por conta do chunk, para o qual demos o nome de “dados” – nomear um chunk é muito importante para identificar erros, a propósito. Nesse caso, informamos que o código fosse avaliado e mostrado no relatório e que mensagens e alertas fossem omitidos.

Agora reparem na próxima seção e nos chunks correspondentes.

Aqui, dividimos a seção “Análise” em duas abas, em que numa tem uma tabela cruzada entre raça e classificação e na outra, um gráfico de barras. A forma de fazer isso é muito simples mas o resultado é fantástico! Apenas digite o código HTML {.tabset} ao lado do título da seção. Bom, mas voltando às configurações dos chunks, observem que dessa vez preferimos não apresentar os códigos, além de que o gráfico fosse centralizado.

Terminado o relatório, o que precisamos fazer agora é renderizar nosso arquivo .Rmd para que ele seja convertido em um arquivo HTML, que foi o formato de output que escolhemos lá no início. Fazemos isso ao utilizar o atalho Ctrl + Shift + K no Linux ou Windows ou Command + Shift + K no Mac ou simplesmente clicando no botão Knit (que está acompanhado por um ícone de um novelo de lã azul). Na realidade, é recomendável que a cada chunk construído seja feita a renderização do documento, principalmente se o seu relatório for muito extenso e com muitos chunks. Dessa forma, é possível acompanhar se o resultado está ficando ao seu agrado como também fica mais fácil para identificar possíveis erros.

Após “dar knit” em nosso RMarkdown, o relatório em HTML gerado é o que está na figura abaixo.

Legal, né?

Ainda que de forma simples, mostramos como o RMarkdown pode conectar o documentar, o compartilhar e o comunicar dos dados de maneira prática e sem dar maiores dores de cabeça ao usuário (pois olhem só, propusemos um relatório em HTML sem precisar ter qualquer noção de HTML!). Além do mais, sua flexibilidade em se adequar aos diferentes tipos de linguagem de programação e formato de arquivo consegue agradar aos mais diversos perfis de profissionais, mesmo aqueles com pouca experiência em programação.

A última e grande notícia é que o RMarkdown não se limita a um relatório estático com códigos e respectivos resultados. Com ele, também é possível fazer painéis interativos (geralmente por meio do pacote {flexdashboard}), slides, livros (o livro R Markdown: The Definitive Guide, recomendado mais de uma vez neste post, é todo feito em? RMarkdown!), trabalhos acadêmicos, correio personalizado (encaminhar documentos em PDF automaticamente), artigos, currículos profissionais… No bom sentido da expressão, o que foi mostrado aqui foi só a pontinha do iceberg!

Gostou? Compartilhe! Mas se não gostou, tudo bem, deixe sua crítica e/ou sugestão no nosso e-mail, observatorioobstetricobr@gmail.com, ou lá no nosso Twitter ou Instagram.