Com fer una pàgina web amb Rmarkdown i GitHub pages

R és un llenguatge de programació/scripting amb el qual es poden fer infinitat de coses: tractament i visualització de dades, anàlisis estadístiques, anàlisis de dades òmiques i altres tipus de dades biològiques (ep, això és interessant per a nosaltres, biotecnòlegs!) i, si ens endinsem a la fusió d’R amb Markdown (Rmarkdown) fins i tot currículums vitae, pàgines web i blogs.

Doncs avui ens interessa publicar una pàgina web o blog propi mitjançant Rmarkdown i el que s’anomena GitHub pages. Sí, ja sabem que podem fer una pàgina web de manera més senzilla (o no) i amb una interfície gràfica més fàcil d’utilitzar mitjançant WordPress o altres plataformes web, però sempre és útil saber com fer-ho des d’altres plataformes, ja sigui fent servir HTML, CSS i PHP o fent servir Rmarkdown per a crear arxius HTML de la nostra pàgina.

A més, si utilitzem Rmarkdown, podrem publicar fragments de codi i anàlisis que fem en el nostre dia a dia i que ens pot interessar donar a conèixer a altres persones, cosa que és una mica menys senzill mitjançant plataformes que no siguin Rmarkdown. Per exemple, aquesta publicació està feta a partir d’un fitxer Rmarkdown i publicada a un lloc web que funciona amb WordPress, però per a fer això, he hagut de copiar tot el codi HTML creat a partir del fitxer .Rmd i copiar-lo a una entrada del blog de WordPress, mentre que amb GitHub pages hagués sigut tant senzill com una ordre al terminal del sistema o com carregar el fitxer sencer al repositori de GitHub on tinc tota la meva pàgina web.

Requeriments

Primer de tot, cal recalcar que farà falta tenir determinats requeriments:

  • Tenir R i RStudio instal·lats.
  • Tenir instal·lats tots els paquets d’R necessaris per a crear la nostra web.
  • Tenir un compte de GitHub, de GitLab o de BitBucket. Aquí ensenyarem com dur a terme el procés amb GitHub, però les altres dues opcions són igual de viables i la metodologia no canvia gaire.
  • Conèixer a grans trets com funcionen RStudio i GitHub.
  • Conèixer la sintaxi d’Rmarkdown.

Web o blog?

Una de les coses que necessitarem decidir és si volem una web o un blog… però quina és la diferència entre aquestes dues coses?

La diferència és senzilla:

  • Un lloc web és un conjunt de pàgines dins un mateix domini a les quals podem accedir a través d’internet.
  • Un blog és un lloc web on una d’aquestes pàgines serveix per llistar o enumerar una sèrie de publicacions.

La majoria de pàgines web personals publicades a partir del mètode que explicarem aquí, així com aquelles publicades amb WordPress i altres, consisteixen en blogs o tenen algun blog enllaçat, però no és estrictament necessari crear un blog si no tenim pensat fer publicacions de manera habitual.

Què és GitHub?

Conèixer R i RStudio, així com la sintaxi d’Rmarkdown és una cosa que durem a terme en el nostre primer curs Inicia’t a R, un curs escrit íntegrament en català dedicat als socis de l’ASBTEC. Per tant, això ens ho saltarem i explicarem el que és GitHub i de què es tracta.

GitHub és una plataforma per a l’emmagatzematge de codi que permet la col·laboració entre desenvolupadors i el que s’anomena control de versió, que no és res més que un conjunt d’eines de desenvolupament de software que ens ajuden a veure els canvis que hem dut a terme en un codi concret al llarg del temps.

Per a fer-ho més simple, podríem dir que GitHub (així com les altres plataformes) és una mena de xarxa social on els usuaris creen repositoris de codi (el que serien les publicacions) que van actualitzant a mesura que milloren o canvien aquest codi.

Per a crear un compte, simplement hem d’anar a https://github.com i clicar a Sign up, senzill oi? Una vegada tinguem el compte creat, podrem configurar el nostre perfil i crear els repositoris que volguem, mitjançant la icona de dalt a la dreta.

Nosaltres generarem tots els fitxers HTML mitjançant Rmarkdown i publicarem la nostra pàgina de manera gratuïta a GitHub pages mitjançant un repositori de nom especial (usuari.github.io), on usuari és el nom que li hem donat al nostre usuari de GitHub.

Aquí teniu una guia ràpida de com utilitzar GitHub.

Passos a seguir

Un cop tinguem R i RStudio instal·lats, els passos a seguir (dins d’RStudio) per a crear i publicar la nostra pàgina web són els següents:

  1. Instal·lar totes les dependències (paquets) necessàries.
  2. Crear un projecte d’R mitjançant una plantilla (template) adient per a crear pàgines web.
  3. Generar tots els fitxers HTML que configuraran cada pàgina del nostre lloc web i generar els fitxers CSS (opcional) per donar format al nostre lloc web.
  4. Configurar l’organització del lloc web utilitzant, per exemple, un fitxer anomenat _site.yaml.
  5. Crear el compte de GitHub (si no el tenim) i el repositori usuari.github.io, el qual ha de ser públic.
  6. Carregar (fer commit i push) de tota la carpeta on tenim els fitxers de la pàgina web al repositori usuari.github.io.
  7. Configurar el repositori per a habilitar les GitHub pages i dir-li a GitHub on ha de buscar els documents HTML.

Pas 1. Instal·lar les dependències

Els paquets que haurem d’instal·lar són paquets dedicats a la creació de pàgines web i blogs. D’aquests n’hi ha molts, encara que nosaltres ens basarem en el paquet rmarkdown:

  • rmarkdown: paquet senzill que ens aporta diverses utilitats del llenguatge Rmarkdown i que ens permet utilitzar una plantilla senzilla per a la creació de pàgines web (però no blogs). Podeu trobar més informació sobre aquest paquet a https://rmarkdown.rstudio.com/lesson-1.html i instal·lar-lo mitjançant l’ordre install.packages("rmarkdown").
  • distill: paquet que ens permet utilitzar més plantilles per a fer una web o un blog, així com funcions que ens permetran crear publicacions i/o pàgines pel nostre lloc web de manera molt senzilla, ja que la seva estructura és molt similar a les webs creades amb el paquet rmarkdown, amb molts avantatges i alguns inconvenients. Podeu trobar més informació sobre aquest paquet a https://rstudio.github.io/distill/ i instal·lar-lo mitjançant l’ordre install.packages("distill").
  • blogdown: paquet especialitzat en la creació de blogs, que ens permet tenir una flexibilitat a l’hora de configurar la nostra web i que disposa de diversos temes per a donar un format visual diferent al blog que crearem. És una mica més complicat d’utilitzar, però podeu trobar-ne més informació a https://bookdown.org/yihui/blogdown/ i instal·lar-lo mitjançant l’ordre install.packages('blogdown').

Altres paquets per a la creació de llocs web no personals (llibres, paquets d’R, projectes en general), els quals us seran més útils si us dediqueu a la (bio)informàtica, (bio)estadística, etc:

  • bookdown: aquest paquet està dissenyat per a la creació de llibres, però el format dels llibres també pot ser en línea com una pàgina web. Més informació a https://bookdown.org/yihui/bookdown/.
  • pkgedown: paquet dissenyat per a la creació de llocs web destinats a la documentació de paquets. Més informació a https://pkgdown.r-lib.org/.
  • workflowr: paquet dissenyat per a la creació de llocs web (ja siguin locals o publicats a internet) destinats organitzar les anàlisis i les dades d’un projecte, així com facilitar la seva reproducibilitat i la col·laboració. Més informació a https://jdblischak.github.io/workflowr/.

Les altres dependències dependran del codi que volguem executar a les nostres pàgines o publicacions del lloc web. A continuació teniu alguns paquets útils, encara que no els explicarem:

  • knitr: paquet amb funcions que ens permetran incloure imatges (ex. include_graphics()), donar format de taula a matrius o data frames (ex. kable()), entre moltes altres, quelcom interessant a l’hora de fer CVs, etc. Més informació aquí.
  • tidyverse: conjunt de paquets que fan molt senzills el tractament i modificació d’estructures de dades (matrius, data frames, mitjançant el paquet dplyr) així com la visualització de gràfics (mitjançant ggplot2), etc.

Pas 2. Crear un projecte d’R

Figura 1. Passos necessaris per a crear un projecte d'R.Figura 1. Passos necessaris per a crear un projecte d'R.Figura 1. Passos necessaris per a crear un projecte d'R.Figura 1. Passos necessaris per a crear un projecte d'R.

Figura 1. Passos necessaris per a crear un projecte d’R.

Una vegada tinguem les dependències instal·lades (bàsicament el paquet rmarkdown o el que desitgem), crearem un projecte d’R seguint els següents passos:

  1. Anem a la icona de dalt a la dreta i cliquem a New Project… (Figura 1, panell superior esquerra).
  2. A finestra que se’ns obra a continuació (Figura 1, panell superior dret), indiquem New Directory, si volem crear el projecte en una nova carpeta (aconsellable), o Existing Directory, si volem crear el projecte a un directori ja existent (millor si està buit).
  3. Seguidament se’ns obra una nova finestra (Figura 1, panell inferior esquerra) on hem d’indicar el tipus de projecte que volem. El més senzill és indicar Simple R Markdown Website (que és el que explicarem), encara que si volem fer un blog amb distill podem clicar a Distill Blog i si volem utilitzar blogdown podem clicar Website using blogdown.
  4. Finalment, a la següent finestra (Figura 1, panell inferior dret), hem d’indicar el directori on volem crear el nostre projecte i clicar a Create Project.

Un cop haguem fet això es crearà la carpeta corresponent al nostre projecte juntament amb diversos fitxers:

  • _site.yml: arxiu que ens permetrà l’organització dels fitxers generats per a la nostra web. És obligatori disposar d’aquest arxiu.
  • index.Rmd: arxiu .Rmd que ens servirà per a crear l’arxiu index.html que serà la pàgina inicial (Home) del nostre lloc web. És obligatori disposar d’aquest arxiu.
  • about.Rmd: arxiu .Rmd que ens servirà per a crear l’arxiu index.html que, per defecte és la pàgina About del nostre lloc web. Aquest arxiu no és obligatori, ja que depèn només ens serveix per a crear una pàgina extra al nostra lloc web.

Pas 3. Generar els fitxers HTML

Per a generar els fitxers HTML que configuraran les pàgines del lloc web podem fer-ho de diverses maneres.

  • Escriure els fitxers HTML directament, cosa que no és recomanable pels que no dominen aquest llenguatge i que és força tediosa.
  • Crear documents R Markdown i renderitzar-los a HTML. Aquesta és l’opció més senzilla i en la que ens centrarem:
    • Un cop tinguem tots els fitxers R Markdown creats i el fitxer _site.yml configurat, per a construir la pàgina podem anar a la pestanya Build de dalt a la dreta i clicar a Build Website (Figura 2).
    • Podem crear tants fitxers R Markdown com volguem i renderitzar-los a HTML, però per a què apareixin a la pàgina web hem de posar-los al fitxer _site.yml.
    • Als fitxers R Markdown, normalment hi tenim una capçalera YAML (al principi del document entre dos blocs de tres guions ---), amb diverses opcions. En aquest cas només cal indicar el title, ja que les opcions com output… les indicarem al fitxer _site.yml.