Taller Flujo de Investigación Reproducible con Github, VSCode y Quarto

Escuela de invierno ELSOC, 01 de agosto de 2025

---

Laboratorio de Investigación Social Abierta - COES

Módulo 1: Github y VSCode

Kevin Carrasco & Ismael Aguayo

Escuela de invierno ELSOC, 01 de agosto de 2025

---

Laboratorio de Investigación Social Abierta - COES

Antes de comenzar

• Instalar Visual Studio Code

• Instalar Git

• Crear cuenta en github.com

• Dejar su nombre de usuario de Github en el chat

Contenidos Módulo 1

1. Introducción al flujo de investigación reproducible
2. Escritura en texto plano (VS Code)
3. Repositorios (Github)

El Laboratorio de Investigación Social Abierta (LISA) tiene por objetivo ofrecer herramientas y orientaciones para la apertura científica de las distintas etapas de los proyectos de investigación en ciencias sociales.

https://lisacoes.netlify.app/

Ciencia abierta

Investigación reproducible

¿Cómo organizamos el trabajo de investigación (en el momento del análisis y escritura)?

Reproducibilidad

• Es la posibilidad de regenerar de manera independiente los resultados usando los materiales originales de una investigación ya publicada.

• En términos simples: obtener los mismos resultados de una investigación utilizando los mismos datos.

¿Qué porcentaje de los estudios publicados son reproducibles?

Alrededor de un 40%! dependiendo de la disciplina

¿Hay crisis de reproducibilidad?

Fuente: Baker (2016) 1,500 scientists lift the lid on reproducibility - Nature

¿y en la práctica cómo afecta la reproducibilidad?

Breznau, et. al, (2023) coordinó una investigación con 161 investigadores de 73 equipos de investigación.

Los equipos informaron tanto hallazgos numéricos como conclusiones sustanciales muy diversas

Flujos de investigación reproducible

• Texto plano
• Carpetas y archivos
• Autocontenido
• Abierto

Ejemplo con procesador de texto tradicional

Ejemplo con procesador de texto tradicional

Algunas limitaciones

• Barrera de pago/licencia para acceder a contenidos (propiedad)

• Difícil versionamiento y llevar registro de quién hizo qué cambio, barrera a la reproducibilidad y colaboración

• No permite un documento enteramente reproducible que combine texto y código de análisis (en caso de utilizarlo)

Propuesta: escritura libre y abierta

• Independiente de programa comercial

• Independiente de plataformas específicas

• Permite combinar texto y análisis en un mismo documento

• Foco en los contenidos en lugar del formato

• Permite distintas opciones de formato final

Visual Studio Code

• Editor de código fuente desarrollado por Microsoft para Windows, Linux, macOS y Web. Incluye soporte para la depuración, control integrado de Git, resaltado de sintaxis, finalización inteligente de código, fragmentos y refactorización de código.

• Personalizable, por lo que los usuarios pueden cambiar el tema del editor, los atajos de teclado y las preferencias.

• software gratuito y de código abierto,​ aunque la descarga oficial está bajo software privativo e incluye características personalizadas por Microsoft.

Así se ve VSC

Protocolo de flujo de investigación reproducible

Alternativas

A. ad-hoc

• cada investigador define numero de archivos, nombres, carpetas y organización

• explicar al resto cómo se organiza

• documentar en un archivo cómo se organiza

–> reproducibilidad y transparencia LIMITADA

B. Protocolo reproducible

• estructura de carpetas y archivos interconectados que refieren a reglas conocidas (estándares)

• autocontenido: toda la información necesaria para la reproducibilidad se encuentra en la carpeta raíz o directorio de trabajo.

Propuesta: Protocolo IPO

Estructura IPO

Mayores detalles y plantilla de carpetas:

• https://lisacoes.netlify.app/ipo-repro/

• https://github.com/lisa-coes/ipo

Repositorios y apertura

La escritura en texto simple (como Markdown o Quarto) permite implementar un sistema de control de versiones, además de herramientas de respaldo, colaboración y comunicación

El origen: Abriendo un sistema operativo

• Linus Torvalds, 1991 (21 años)

• Crea sistema operativo libre (Linux) y lo abre a la colaboración. Postea:

  • “I’m doing a (free) operating system (just a hobby, won’t be big and professional…”

• TED talk

Git

• es una especie de memoria o registro local que guarda información sobre:

  • quién hizo un cambio
  • cuándo lo hizo
  • qué hizo

• mantiene la información de todos los cambios en la historia de la carpeta / repositorio local

• se puede sincronizar con un repositorio remoto (ej. Github)

Git/github

• actualmente, Git / Github posee más de 100 millones de repositorios

• mayor fuente de código en el mundo

• ha transitado desde el mundo de desarrollo de software hacia distintos ámbitos de trabajo colaborativo y abierto

• entorno de trabajo que favorece la ciencia abierta

Git no es un registro de versiones de archivos específicos, sino de una carpeta completa

Guarda “fotos” de momentos específicos de la carpeta, y esta foto se saca mediante un commit

Commits

• El commit es el procedimiento fundamental del control de versiones

• Git no registra cualquier cambio que se “guarda”, sino los que se “comprometen” (commit).

• En un commit

  • se seleccionan los archivos cuyo cambio se desea registrar (stage)
  • se registra lo que se está comprometiendo en el cambio (mensaje de commit)

¿Cuándo hacer un commit?

• según conveniencia

• sugerencias:

  • que sea un momento que requiera registro (momento de foto)

  • no para cambios menores

  • no esperar muchos cambios distintos que puedan hacer perder el sentido del commit

Módulo 2: Documentos y presentaciones en Quarto

Tomás Urzúa & Juan Carlos Castillo

Escuela de invierno ELSOC, 01 de agosto de 2025

---

Laboratorio de Investigación Social Abierta - COES

Parte 1: Documentos en Quarto

¿Qué es Quarto?

• Quarto es un sistema moderno de creación de documentos dinámicos, informes, presentaciones, libros, sitios web y más, a partir de archivos de texto plano y por medio del conversor universal de documentos Pandoc.

• Evolución de los sistemas de autoría como Jupyter, R Markdown, todo dentro del mismo documento.

Características Principales

• Multiplataforma

• Basado en Markdown

• Soporte para múltiples lenguajes

• Multitud de formatos de salida

• Soporte para publicación científica

• Integración entornos de desarrollo (RStudio, VSC, etc)

• Extensible

Instalación en VSC

• Requisitos: Quarto CLI y Visual Studio Code (VSC)

• Instalación de Quarto: https://quarto.org/docs/get-started/

• Verificación de instalación:

  quarto check

• Extensión “Quarto” para Visual Studio Code

Estructura de un documento

• Archivo .qmd

• Encabezado YAML:

  title: "Mi documento"
  author: "Juan Castillo"
  date: today
  format: html

• Cuerpo:

  • Markdown para secciones, énfasis, listas, etc.
  • Bloques de código
  • Bibliografía

Ejemplo

---
title: "Tutorial Quarto"
author: "JC"
date: "2025-08-01"
format: html
lang: es
---

# Bienvenidos a este tutorial de **Quarto**.

Quarto está especialmente diseñado para elaborar documentos
científicos y técnicos reproducibles

• Para renderizar:
  • Desde el terminal: quarto render archivo.qmd
  • VSC: Ctrl+Shift+P -> quarto preview

Base de escritura: Markdown

• Encabezados: #, ##, ###
• Listas:
  • Viñetas: - o *
  • Numeradas: 1., 2.
• Énfasis: *cursiva*, **negrita**
• Código en línea: `código`
• Enlaces: [texto](url)

Ejemplo

---
title: "Tutorial Quarto"
author: "JC"
date: "2025-08-01"
format: html
lang: es
---

# Bienvenidos a este tutorial de **Quarto**.

Quarto está especialmente diseñado para elaborar documentos
científicos y técnicos reproducibles

## Este es un subtítulo

Ahora vamos a ensayar **negritas** y _cursivas_

### Y un título de tercer orden

Y una lista

- con viñetas
- ...
- ...

Y otra numerada:

1. punto 1
2. punto 2
3. ...

## Links e imágenes

[Este es un link a Github](https://github.com/)  

![Imagen online](https://upload.wikimedia.org/wikipedia/commons/thumb/3/33/Gutenberg.jpg/330px-Gutenberg.jpg)

Personalización visual del HTML

• Temas: cosmo, flatly, lux, darkly, etc.

• Opciones comunes en YAML:

  toc: true
  number-sections: true
  code-fold: true

• Personalización con CSS externo:

  css: estilos.css

Ejemplo

---
title: "Tutorial Quarto"
author: "JC"
date: "2025-08-01"
format: html
lang: es
toc: true
number-sections: true
theme: darkly
css: estilos.css
---

# Bienvenidos a este tutorial de **Quarto**.

Quarto está especialmente diseñado para elaborar documentos
científicos y técnicos reproducibles

## Este es un subtítulo

Ahora vamos a ensayar **negritas** y _cursivas_

### Y un título de tercer orden

Y una lista

- con viñetas
- ...
- ...

Y otra numerada:

1. punto 1
2. punto 2
3. ...

Extensiones

• Integración con R
• Referencias bibliográficas
• Renderizado a pdf, word
• Sitios web
• Presentaciones

Recursos

• Recursos para seguir aprendiendo:
  • https://quarto.org
• Creación de documentos científicos con Quarto

Parte 2: Presentaciones en Quarto

¿Por qué usar Quarto para presentaciones?

• Permite controlar las versiones (Git)

• Facilita la difusión (GitHub Pages)

• Utiliza texto plano y todos los recursos de Quarto

• Permite combinar texto y código

YAML

• Contiene las características que tendrá la presentación al momento de ser renderizada

• Las especificaciones afectarán todo el documento

• Veamos un ejemplo con el YAML de esta presentación

Ejemplo

---
format:
  revealjs:
    theme: 
          - taller-elsoc.scss 
    transition: slide
    transition-speed: slow
editor: source
---

Sacar la transición y renderizar la presentación sin ella

Slides

• Cada slide se define a partir de un ‘#’

• Se pueden generar subtítulos dentro de una slide añadiendo ‘#’ antes de un texto

Slide con un ‘#’

Subtítulo con 2 ‘#’

Subtítulo con 3 ‘#’

Subtítulo con 4 ‘#’

Texto sin ‘#’

Orden de la información

• La información puede ser presentada de distintas maneras

• Puede verse todo el texto de inmediato

• Todo a un mismo lado

• Y sin ninguna variante

Orden de la presentación

• La información puede ser presentada de distintas maneras

• Puede verse secuencialmente

• Separando el texto en columnas

• Y variando el estilo

Orden de la presentación

• 1
• 2
• 3

• La información puede ser presentada de distintas maneras

• Puede ser separada en casillas

• Idealmente para comparar

Diseño de la presentación

• Las presentaciones (y todos los documentos .qmd) son completamente personalizables

• Se pueden realizar cambios en partes específicas de la presentación así como a nivel global

Cambiar el color de las letras de una slide, del background y por último jugar con el tema y scss {style=“color: #212529;”} {data-background-color=“#212529”} {.incremental .highlight-last style=“font-size: 45px”}

Palabras de cierre

• Quarto es ideal para generar documentos divulgativos, sobre todo aquellos que mezclan texto y código

• Los documentos son completamente personalizables

• Es una plataforma libre, por lo que no es necesario pagar licencias ni piratear softwares

• El conocimiento se vuelve más accesible y transparente

Recursos para seguir aprendiendo

• Presentaciones Quarto y más documentación

• Videos explicativos esenciales para aprender viendo

• Foro de Posit para mantenerse actualizado y resolver dudas

• Página LISA y más sobre Ciencia Abierta

Repositorio

https://github.com/lisa-coes/taller-vsc-github

Muchas gracias!