Mini curso: Quarto y GitHub Pages

III Jornadas de Ingeniería Estadística 2024
11 y 12 de Noviembre 2024, Auditorio DMCC
Universidad de Santiago de Chile 		Logo JIE

Francisco Plaza Vega
francisco.plaza.v@usach.cl

USACH

Introducción

¿Qué es la Investigación Reproducible?

Es la práctica de conducir estudios científicos o basados en datos de tal manera que permita a otros replicar o reproducir los resultados usando los mismos datos, códigos y metodologías.

Etapas de una Investigación Reproducible

Ciencia Abierta

Espectro de Reproducibilidad

Qué necesitaremos?

Repositorio

Enlaces importantes

Sofware necesarios

Descripción
Lenguaje de programación para análisis de datos y estadística.
Entorno de desarrollo integrado para R, ideal para análisis de datos y desarrollo reproducible.
Herramienta para crear documentos reproducibles, reportes y páginas web de alta calidad.
Sistema de control de versiones (Git) y plataforma para compartir proyectos (GitHub). Incluye GitHub Desktop.

Quarto

Rmarkdown & Quarto

El paquete rmarkdown provee un marco de escritura para investigaciones cuantitativas, que combina códigos, resultados y texto. Los documento R Markdown son completamente reproducibles y permiten generar archivos en distintos formatos: PDF, Word, Presentaciones y más. Quarto es la nueva generación de esta herramienta para incluir distintos lenguajes.

Algunos ejemplos

Quarto posee una galería de ejemplos bastante completa como para comenzar a investigar y visualizar en distintos tipos de documentos.

Quarto

Los archivos Quarto fueron diseñados para ser usados de tres maneras:

  1. Para comunicar a los tomadores de decisiones, quienes quieren centrarse en las conclusiones, no en el código detrás del análisis.

  2. Para colaborar con otros investigadores, quienes están interesados en las conclusiones y el cómo se llego a ellas (i.e. el código)

  3. Como un ambiente para hacer análisis, como un notebook donde se puede capturar el trabajo realizado junto a notas de este.

Primeros pasos

  1. Entrar a Quarto.org
  2. Descargar Quarto para tu sistema operativo
  3. Ingresar a RStudio y crear documento .qmd

Flujo documento Quarto

  • qmd: archivo de origen
  • knitr: Herramienta que interpreta y ejecuta códigos y lo traduce en texto markdown
  • md: texto escrito en lenguaje markdown
  • pandoc: Herramienta que convierte archivos .md en distintos formatos

Anatomía de un documento Quarto

  1. Encabezado en formato YAML
  2. Texto en formato Quarto
  3. Bloques de código (R, Python, Julia, Observable)

YAML

YAML es un formato de serialización de datos que puede ser leído fácilmente. Su uso es amplio, desde Acciones en GitHub hasta Quarto

Un ejemplo de YAML que define un ambiente computacional podría ser:

# Define the operating system as Linux
os: linux

# Use the xenial distribution of Linux
dist: xenial

# Use the programming language Python
language: python

# Use version of Python 3.2
python: 3.2

YAML nos será de particular interés para la creación de documentos y presentaciones reproducibles, utilizando quarto.

Herramientas

El contenido del documento puede estar escrito utilizando diferentes formatos, entre ellos:

  • Quarto
  • HTML
  • LaTeX
  • CSS

Creación de documento básico

  1. Abrir RStudio
  2. File > New File > Quarto Document
  3. Definir características del documento

Sintáxis

Formato de Texto

Sintáxis Markdown Salida 
*italics*, **bold**, ***bold italics***
 italics, bold, bold italics 
superscript^2^ / subscript~2~
 superscript2 / subscript2 
~~strikethrough~~
 strikethrough 
`verbatim code`
 verbatim code

Encabezados

Sintáxis Markdown Salida 
# Header 1

Header 1

 
## Header 2

Header 2

 
### Header 3

Header 3

 
#### Header 4

Header 4

 
##### Header 5
Header 5
 
###### Header 6
Header 6

Listas

Sintáxis Markdown Salida 
* Lista no ordenada
    + sub-item 1
    + sub-item 2
        - sub-sub-item 1
  • Lista no ordenada
    • sub-item 1
    • sub-item 2
      • sub-sub-item 1
 
*   item 2

    Continuación (4 spaces)

  • item 2

    Continuación (4 spaces)

 
1. Lista ordenada
2. item 2
    i) sub-item 1
         A.  sub-sub-item 1
  1. Lista ordenada
  2. item 2
    1. sub-item 1
      1. sub-sub-item 1

Listas

Sintáxis Markdown Salida 
(@)  Una lista cuyos números

continuan después

(@)  de una interrupción
  1. Una lista cuyos números

continuan después

  1. de una interrupción
 
::: {}
1. Una lista
:::

::: {}
1. Seguida de otra lista
:::
  1. Una lista
  1. Seguida de otra lista
 
término
: definición
término

definición

Tablas

Sintáxis Markdown

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Salida

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

Código y cálculos

Al igual que RMarkdown, Quarto permite ejecutar código y compilarlo dentro del documento

library(ggplot2)
library(gganimate)
library(gapminder)

ggplot(gapminder, aes(gdpPercap, lifeExp, size = pop, colour = country)) +
  geom_point(alpha = 0.7, show.legend = FALSE) +
  scale_colour_manual(values = country_colors) +
  scale_size(range = c(2, 12)) +
  scale_x_log10() +
  facet_wrap(~continent) +
  # Here comes the gganimate specific bits
  labs(title = 'Año: {frame_time}', x = 'GDP per capita', y = 'Expectativa de vida') +
  transition_time(year) +
  ease_aes('linear')

Las opciones de ejecución que tienen los códigos

Opción Descripción
eval Evalúa el bloque de código (si es false, solo muestra el código en la salida).
echo Incluye el código fuente en la salida.
output Incluye los resultados de ejecutar el código en la salida (true, false, o asis para indicar que la salida es raw markdown sin los contenedores estándar de Quarto).
warning Incluye advertencias en la salida.
error Incluye errores en la salida (nota: esto implica que los errores al ejecutar el código no detendrán el procesamiento del documento).
include Control global para prevenir cualquier salida (código o resultados) de ser incluida (por ejemplo, include: false suprime toda salida del bloque de código).

Código de fuente

Usamos ``` para delimitar bloques de código:


```
código

```

Podemos agregar un lenguaje para destacar el código:


``` python
1 + 1
```

´´´ r
1 + 1
´´´

Pandoc ofrece 140 distintos lenguajes para destacar código.

Guía de referencia

Para una lista exhaustiva de las opciones de formato que tienen los documentos .qmd visitar https://quarto.org/docs/guide/.

Formatos de salida: Documentos

Los formatos de salida más utilizados para documentos creados con Quarto son:

Para cambiar entre estos formatos, basta especificiar la salida deseada en el YAML. Otros formatos posibles:

Formatos de salida: Presentaciones

En Quarto tenemos 3 opciones para presentaciones:

En donde RevealJS es el formato que nos entrega más herramientas. (Esta presentación fue hecha utilizando RevealJS en Quarto)

Templates

Template para este tutorial

Páginas web con Quarto

También se puede crear un website desde la terminal, siguiendo:

quarto create-project mi-pagina-web --type website

Lo anterior generará una estructura de carpetas como la siguiente:

mi-pagina-web/
├── _quarto.yml
├── index.qmd
└── about.qmd
  • _quarto.yml: Archivo de configuración del proyecto.
  • index.qmd: Archivo principal del sitio web.
  • about.qmd: Página adicional para el sitio.

Archivo _quarto.yml

El archivo _quarto.yml define configuraciones para personalizar el sitio web:

project:
  type: website
  title: "Página Web con Quarto"
  author: "Nombre"
  description: "sitio web creado con Quarto"
  
website:
  navbar:
    right:
      - text: "Inicio"
        href: index.qmd
      - text: "Acerca de"
        href: about.qmd

format:
  html:
    theme: cosmo
    toc: true
    toc-location: left
  • title: El título del sitio.
  • navbar: Barra de navegación con enlaces.
  • theme: Se puede cambiar el tema (e.g., cosmo, flatly, darkly).

Contenido en index.qmd

Abrir el archivo index.qmd y añadimos el siguiente contenido:

---
title: "Mi Página Web"
---

# ¡Hola, Mundo!

Esta es una página web simple creada con Quarto en las III Jornadas de Ingeniería en Estadística.

## Sección 1: Introducción

Quarto te permite crear documentos y sitios web de forma rápida y sencilla.

## Sección 2: Características

- Código reproducible
- Fácil de publicar en GitHub Pages
- Compatible con múltiples lenguajes

Luego renderizar el documento

Contenido en about.qmd

---
title: "Jornadas"
about:
  template: jolla
  image: profile.jpg
  links:
    - icon: twitter
      text: twitter
      href: https://twitter.com
    - icon: github
      text: Github
      href: https://github.com
---

Las III Jornadas de Ingeniería Estadística son un evento que se efectúa desde hace tres años en el Departamento de Matemática y Ciencia de la Computación, en la Universidad de Santiago.

## Fecha y lugar de realización

Auditorio del Departamento de Matemática y Ciencia de la Computación, Universidad de Santiago | 11 y 12 de noviembre de 2024


Templates

Quarto incluye 5 templates para este tipo de página: jolla, trestles, solana, marquee, broadside.

Github

Control de versiones

Git

Sistema de control de versiones distribuido que se utiliza para el seguimiento de cambios en archivos de desarrollo software.

Motivación para utilizar control de versiones

  • Es primordial para seguir la procedencia de la información.

  • Crea versiones históricas que nos permiten entender que cambios fueron realizados.

  • Facilita el manejo de distintas versiones de archivos.

  • Permite seguir y combinar cambios realizados por distintas personas.

Flujo de trabajo

El control de versiones es un enfoque sistemático para registrar los cambios realizados en un archivo o conjunto de archivos a lo largo del tiempo.

Un flujo de trabajo típico para usar control de versiones es:

  1. Crear archivos
  2. Trabajar sobre estos archivos
  3. Crear un snapshot del estado del archivo (también llamado versión)
  4. Documentar que cambios fueron realizados en el historial de la versión del archivo

Elementos de Git

  • Repositorio: Lugar donde se almacenan todos los archivos, carpetas e historial del proyecto.

  • Commit: Registro de los cambios realizados en los archivos del proyecto en un momento específico.

  • Ramas (o “Branches”): Espacios de trabajo independientes del desarrollo principal.

  • Fusiones (o “Merges”): Representa la acción de incorporar los cambios de una Rama (Branch) a otra.

  • Repositorios remotos: Copias del repositorio almacenadas en un servidor central o en otros equipos.

Repositorio

El Repositorio de un proyecto corresponde al almacén de datos que contiene todos los archivos, carpetas y el historial de cambios del proyecto.

Un repositorio de Git puede estar:

  • Estar ubicado localmente en la computadora de un desarrollador.

  • De forma remota en un servidor.

Ramas (Branches)

Supongamos que quiero agregar o probar algo nuevo en un archivo antes de que se vea reflejado en archivo principal. ¿Cómo puedo mantener un registro de esto?

Sub-ramas (Sub-Branches)

Repositorio usando Github Desktop

Antes de continuar

Asegurarse de haber descargado e instalado:

Crear un Nuevo Repositorio

Para crear un repositorio local:

  1. Hacer clic en File > New Repository.

  2. Completar la información que se muestra a continuación:

    • Name: mi-pagina-web
    • Description: “Repositorio para mi sitio web con Quarto”
    • Local Path: Elige una carpeta en tu computadora donde se almacenará el repositorio.
    • Git Ignore Template: Selecciona None.
    • License: Seleccionar algún tipo de licencia o None (se puede modificar más adelante).

  3. Hacer clic en Create Repository.

  4. Ahora que el repositorio está creado, se puede modificar y crear archivos.

Push & Pull

Configurar GitHub Pages

  1. Crear un repositorio llamado nombre-usuario.github.io. Donde nombre-usuario sea tu nombre de usuario de GitHub.
  2. Ir a Settings > Pages.
  3. Seleccionar la rama main y la carpeta / (root), o alguna otra carpeta que sea definida para guardar los archivos del sitio web.
  4. Guardar los cambios.
  5. Luego puedes clonar el repositorio a alguna carpeta local y comenzar a trabajar. Debe contener algún archivo index.html para funcionar

El sitio web debería estar disponible en: https://usuario.github.io/mi-pagina-web

Guía de referencia

Guía de referencia para Github Pages

Para modificar la carpeta de salida del sitio web

En el archivo _quarto.yml:

project:
  type: website
  output-dir: docs

Muchas gracias!