Blogdown Tutorial (in Portuguese)
Para começo de conversa, você deve estar se perguntando: “Mas por que diabos eu faria um site utilizando o R? Tenho tantas opções na internet! Além disso, já passo mal só por rodar minhas análises, quem dirá fazendo um site!”
Bom… se você pensou dessa forma, já lhe adianto que fazer um site por meio do Rstudio não é tão difícil quanto parece, sobretudo se você já está familiarizado com a linguagem R. Neste tutorial básico, vou te mostrar como o R pode te ajudar a reproduzir suas ideias, publicações, gráficos, vídeos etc, de maneira rápida, prática e intuitiva.
Vamos lá!
Um estudo publicado recentemente na Nature questinou se estamos vivendo uma crise na reprodutibilidade científica ( Baker 2016). Para mais da metade dos 1576 pesquisadores entrevistados, a resposta foi sim.
Mas afinal, o que seria isso?
Na prática, o termo reprodutibilidade científica se refere ao processo de utilização de um mesmo conjunto de dados, mesmas análises, códigos e funções utilizadas por outro pesquisador, a fim de alcançar os mesmos resultados obtidos por esse. De acordo com o artigo, cerca de 70% dos cientistas falharam em tentar reproduzir o experimento de outros pesquisadores, e mais da metade falhou em reproduzir o próprio experimento.
E por que isso é importante?
A prática de uma pesquisa reproduzível acelera o avanço científico, nos faz ganhar tempo e economizar dinheiro, torna os resultados mais confiáveis e robustos e facilita a colaboração entre pesquisadores. Uma das boas práticas na reprodutibilidade científica está na organização, transparência e disponibilização dos dados e códigos utilizados no estudo. É sempre importante disponibiliar os dados, scripts e funções utilizadas na pesquisa para que outros pesquisadores possam entender prontamente como aquele estudo foi feito, aprimorar ideias existentes e gerar novas hipóteses.
Se você já utiliza o Rstudio e possui versões mais atualizadas, certamente já se deparou com algumas abas como: “Rmarkdown”, “Shiny web app”, “R presentation”, “Version control”, dentre outras. Muitas dstas ferramentas aumentam a nossa capacidade de fazer uma pesquisa reproduzível.
O vídeo abaixo, por exemplo, destaca brevemente a importância do R Markdown e do GitHub nesse processo:
Como pudemos ver, utilizando essas ferramentas temos maior controle dos documentos, excluímos a necessidade de copiar e colar figuras e tabelas, reduzimos as chances de erro e tornamos todo o processo de criação e publicação de documentos mais fluido. Não pretendo entrar em detalhes neste tutorial, mas com o R Markdown, por exemplo, é possível escrever um documento (como este que você está lendo), sua tese, artigo, incluir figuras e/ou tabelas utilizando apenas o código gerado para fazer a figura, direto no documento. Com o shiny é possível fazer mapas, gráficos interativos, ferramentas para análise de dados e disponibilizar online; R presentation você pode fazer seus slides; o “Version control”, quando integrado ao GitHub, cria um repositório online dos seus dados, scripts, funções, nos permite ver todas as edições feitas no documento. Além dessas ferramentas, recentemente, foi lançado o pacote “blogdown”, tornando possível que qualquer pessoa possa fazer seu próprio site por meio do Rstudio.
E como o blogdown pode auxiliar na reprodutibilidade científica?
Bom… como o blogdown é escrito em Rmarkdown, todo material feito no R pode ser diretamente disponibilizado online, por meio do site/blog. Diante das ferramentas existentes, ao meu ver, o blogdown é a cereja do bolo que faltava para finalizar a prática de uma pesquisa reproduzível dentro do Rstudio. Portanto, atualmente você pode (1) fazer suas análises no Rstudio e gerar as tabelas e figuras; (2) escrever seu artigo ou tese em R Markdown e plotar suas tabelas e figuras direto no documento; (3) fazer os slides para apresentar seus resultados com o R Presentation; (4) salvar isso tudo em um repositório online, onde você e seus colaboradores têm o controle de tudo que foi modificado no texto - com o GitHub; e (5) disponibilizar todo esse material na internet por meio do seu site - Blogdown.
Bom… Chega de enrolação. Bora botar a mão na massa
Antes de começarmos, você precisa fazer uma conta no GitHub e integrá-lo ao R. O GitHub é necessário para quando formos upar nosso site na web. Aqui temos um tutorial bem detalhado de como funciona o GitHub e de como integrá-lo ao Rstudio.
Após integrar o git ao R, vamos fazer um novo projeto dentro do Rstudio para gerar nosso site.
Se a sua conta do GitHub já estiver integrada ao Rstudio, deve aparecer assim:
Próximo passo é escolher em que pasta local e em que repositório no GitHub o seu projeto vai ficar.
Para isso, criamos um novo repositório no GitHub:
Escolhemos o nome do repositório:
Copiamos o endereço:
E, por fim, colamos esse endereço no Rstudio
Pronto. Projeto criado no computador e vinculado ao GitHub. Tudo que for acrescetado, alterado ou deletado teremos o controle quando olharmos no git - vou mostrar logo mais como jogar as alterações feitas no Rstudio para o GitHub.
Bom… agora podemos instalar o blogdown
## Basicamente existem duas maneiras de se instalar pacotes no R
## A primeira é a mais comum, por meio do CRAN
install.packages("blogdown")
## A segunda, é por meio do GitHub. Instalando pacotes por meio dessa opção nos garante sempre a versão mais atualizada do pacote.
if (!requireNamespace("devtools")) install.packages("devtools")
devtools::install_github("rstudio/blogdown")O próximo passo é instalar o hugo.
blogdown::install_hugo()O Hugo é uma plataforma utilizada para gerar sites, com muitas opções de layouts. Sugiro que dê uma olhada nos diferentes tipos disponíveis e escolha o que melhor atende às suas necessidades: https://gohugo.io/
Feito isso, agora a gente pode criar o nosso site.
blogdown::new_site(theme = "gcushen/hugo-academic")Note que estou utilizando o tema “Academic”. Caso queira utilizar outro tema, basta ir lá na página hugo e selecionar o tema que mais lhe agrada (theme = “nome do tema”). Caso queira utilizar o default do pacote basta digitar:
blogdown::new_site()Após criar o site, sempre que quisermos carregá-lo no Rstudio, utilizamos a função:
blogdown::serve_site()Ok… até aqui a gente conseguiu gerar o default do nosso site e nele a gente encontra o modelo de quem o criou, com alguns exemplos, cores, fontes, enfim, toda uma estrutura pré-estabelecida. Agora a ideia é alterar esse modelo.
No Rstudio temos a aba “Files”. Nesta, nós podemos visualizar todos os arquivos presentes no site. As três principais pastas são: content, public e static (imagem abaixo). Além destas, temos o arquivo “config.toml”. Vamos mexer nele agora e depois voltamos para as pastas.
No arquivo “config.toml”, temos a maioria dos códigos utilizados para gerar o layout inicial do site. No Academic, por exemplo, a gente pode alterar o estilo, fonte, dados pessoais, foto do perfil, mídias sociais etc. O arquivo “config.toml” é auto explicativo, basta dar uma lida nele que você saberá o que deve mudar para começar a deixar o site do seu jeito. Para mudanças mais profundas na estrutura do site, temos que criar ou utilizar um arquivo “.css” já pronto. Neste site, estou utilizando o “blue.css”, criado pela Alisson Hill.
Na pasta content, encontramos as postagens feitas no site, desde sua apresentação inicial, projetos, publicações ou posts. Lá você pode acrescentar, remover ou consertar algo que foi escrito em qualquer seção publicada no site.
Na pasta static, temos as imagens que estão no site. Caso queira incluir uma imagem em algum post, é importante que esta imagem esteja salva dentro da pasta static. Mais pra frente vou explicar como incluir imagens ou gráficos dentro de um post.
Por fim, a pasta public está integrada às demais pastas e contém todos os arquivos que estão disponíveis no site. Portanto, tudo que for alterarado nas outras pastas será salvo automaticamente na public.
Como criar um novo post?
Para criar um novo post, basta clicar em addins -> newpost
ou
blogdown::new_post()
Sugiro que crie o post utilizando a extensão .Rmd. Essa extensão nos permite utilizar gráficos, tabelas e códigos gerados no R. Saber o básico do R Markdown pode te salvar algum tempo quando estiver postando algo no blogdown. No help (cheatsheets) do Rstudio é possível encontrar um mini tutorial sobre R Markdown. Sugiro que dê uma olhada para entender melhor algumas funções básicas.
Até aqui, a gente viu como criar o site, modificar o seu conteúdo e como criar novas postagens. Agora vamos salvar isso tudo localmente e aprender como salvar no GitHub.
Como nosso projeto já está vinculado ao GitHub, passar nossas alterações para lá é muito simples, basta utilizarmos o seguinte caminho: “Tools”, “Version control”, “Commit…”.
Na aba “commit” a gente pode ver todas as alterações que foram feitas em todos os arquivos
Por fim, para mandar as alterações para o GitHub, basta seguir estes três passos: “selecionar os arquivos”, “commit” e “push”.
Note que é importante incluir algum texto na janela “commit” que indique quais foram as mudanças mais importantes feitas no documento. Por ex. “deletei tal arquivo”, “acrescentei texto a tal seção e consertei alguns erros em tal tópico”. Futuramente, você pode rastrear todas as suas alterações olhando os “commit’s” no GitHub.
Importante: Precisamos fazer esse mesmo processo todas as vezes que alterarmos algo no documento e formos salvar no GitHub. Se não clicarmos no “Push”, os arquivos não serão atualizados no GitHub.
Como incluir imagens, figuras e vídeos nas postagens?
Como já foi dito, o blogdown aceita a extensão .Rmd, portanto, muitas das funções utilizadas para criar novas postagens são funções utilizadas em documentos do R Markdown.
Para incluir imagens, basta salvar a imagem dentro da pasta “static/img”, depois digitar:
Para incluir um gráfico feito no R, precisamos apenas escrever os comandos do gráfico desejado:
library(ggplot2)
## Warning: package 'ggplot2' was built under R version 4.0.2
ggplot(mtcars, aes(x=hp, y=mpg)) +
geom_point(size=3) +
geom_smooth(method="lm")
## `geom_smooth()` using formula 'y ~ x'
Podemos também incluir um gráfico interativo:
library(plotly)
## Warning: package 'plotly' was built under R version 4.0.2
library(ggplot2)
ggiris<-qplot(Petal.Width, Sepal.Length, data = iris, color = Species)
ggplotly(ggiris)
Para incluir um gif basta incluir o endereço do gif:
Para incluir um vídeo do youtube utilizamos a função:
blogdown::shortcode("youtube", "DNS7i2m4sB0")
#Note que basta apenas inserir o id do vídeo, aquele conjunto de letras e números após o "watch?v="Agora, finalmente, vamos colocar nosso site no ar.
Para isso vamos utilizar o netlify, como sugerido no livro do blogdown.
No netlify escolhemos a opção GitHub, depois “New site from Git”
Agora a gente escolhe o repositório do GitHub onde nosso projeto está vinculado.
Por fim, escolhemos o “public directory” como “public” e geramos o site:
Pronto! Se tudo estiver correto, o site estará no ar. Para isso, salve tudo no GitHub (utilizando commit + push) e execute o comando abaixo:
blogdown::build_site()Essa ação (salvar no GitHub e “build_site()”) deve ser repetida todas as vezes que acrescentar ou excluir algo do site.
Note que o netlify gera nomes aleatórios para o site. O meu por ex. veio “masseur-harry-45572.netlify.com”. Para trocar o nome do site basta ir em “settings”, “change site name”.
Atualização: Caso use o netlify para hospedar seu site, atualmente é importante incluir o arquivo netlify.toml na pasta inicial do seu projeto:
[build]
publish = "public"
command = "hugo"
[context.production.environment]
HUGO_VERSION = "0.54.0" # if older, use format: 0.53 (no trailing zero)
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"
[context.branch-deploy.environment]
HUGO_VERSION = "0.54.0" # if older, use format: 0.53 (no trailing zero)
[context.deploy-preview.environment]
HUGO_VERSION = "0.54.0"
Informação retirada de: https://alison.rbind.io/post/2019-02-19-hugo-netlify-toml/
Além disso, caso tenha feito o site há algum tempo e queira atualizá-lo, lembre-se de ir até o seu perfil no netlify e atualizar o link do repositório - faça isso mesmo que o repositório não tenha mudado. Basta ir em “build settings” e “edit settings”.
Links úteis
Have fun!
Diego P.F. Trindade
PhD Student
My research interests include theoretical ecology, global change ecology and biodiversity change across space and time.