IPBLN Bioinformatics Report

El proceso de análisis de Single-Cell RNA-Seq (scRNA-Seq) llevado a cabo en este estudio se sustenta en una arquitectura de dos fases computacionales diferenciadas. Esta separación permite manejar eficientemente la enorme carga computacional inicial y, posteriormente, aplicar algoritmos estadísticos interactivos de alta resolución.

En primer lugar, se utiliza el pipeline oficial Cell Ranger (desarrollado por 10x Genomics) para el procesamiento primario de las lecturas crudas, garantizando la correcta demultiplexación y alineamiento frente al genoma de referencia. En segundo lugar, el análisis downstream (secundario y terciario) se ejecuta íntegramente en el lenguaje de programación R, apoyado fuertemente en el paquete Seurat, el estándar actual de la industria para el análisis de célula única.

En los siguientes apartados se describen con detalle estas dos etapas metodológicas, los tipos de resultados que generan y, en el caso del análisis con R, se adjuntan los scripts utilizados para garantizar la trazabilidad y reproducibilidad total del experimento.

Cell Ranger constituye el estándar computacional oficial diseñado por 10x Genomics para procesar los datos de su tecnología microfluídica Chromium. En este proyecto, el procesamiento inicial (upstream) se ejecutó de manera automatizada en infraestructuras de alto rendimiento (HPC), actuando como el puente directo entre la señal bruta del secuenciador y las matrices matemáticas de expresión celular.

Un prerrequisito crítico e ineludible para el éxito de esta fase es la disponibilidad de una arquitectura genómica de alta resolución. El proceso depende absolutamente de dos archivos estructurados aportados o consensuados con el investigador: la secuencia del genoma completo (en formato .fasta) y su anotación transcripcional (en formato .gtf o .gff). Esta anotación actúa como el “mapa de coordenadas” biológico; su calidad y grado de actualización dictan de forma directa qué porcentaje de lecturas genómicas se traducirán en genes detectables y cuánta información se perderá en regiones intergénicas no anotadas.

Las etapas algorítmicas clave que ejecuta esta herramienta se dividen en:

1. Construcción de la Referencia (mkref) ⇒ Indexación computacional de los archivos .fasta y .gtf proporcionados, creando un entorno de mapeo optimizado y filtrado (ej. restringiendo la cuantificación a genes codificantes o biotipos de interés).
2. Demultiplexación (mkfastq) ⇒ Transformación de los archivos binarios crudos (Base Call Files o BCL) emitidos por el secuenciador Illumina en secuencias de texto legibles (archivos FASTQ), separando matemáticamente las muestras del proyecto en base a sus índices moleculares.
3. Alineamiento y Cuantificación (count) ⇒ Mapeo de los millones de lecturas de los FASTQ contra el genoma de referencia empleando el algoritmo STAR aligner. En este paso ultracomplejo se realiza la corrección de errores de los códigos de barras celulares (Cell Barcodes, que identifican a qué célula pertenece cada lectura) y el colapso de los identificadores moleculares únicos (UMIs, para eliminar duplicados exactos de la PCR).
4. Generación de Matrices Topológicas ⇒ Tras el conteo de moléculas reales, se construyen las matrices de expresión de característica-código de barras (Feature-Barcode matrices). Se exportan tanto en formato optimizado de alta compresión .h5 (HDF5) como en formato abierto MEX (Market Exchange Format).
5. Control de Calidad Primario ⇒ Emisión automática de reportes HTML (Web Summaries) que auditan la salud de la secuenciación, detallando métricas de éxito vitales como la fracción de lecturas válidas en células, la profundidad de saturación y la mediana de genes capturados por cada gota lipídica.

Dado que Cell Ranger es un pipeline secuencial cerrado y altamente calibrado por el fabricante, las matrices matemáticas purificadas en esta etapa constituyen el “bloque de arcilla” inamovible sobre el que se esculpirá todo el análisis biológico posterior en R/Seurat. A continuación, se muestra de forma esquemática este flujo de obtención de datos:

Una vez obtenidas las matrices de conteo (.h5) desde Cell Ranger, el análisis downstream se trasladó al ecosistema de R. La herramienta principal utilizada para el procesado de célula única es Seurat, complementada con librerías accesorias para la visualización, anotación y cálculo estadístico.

El análisis mediante scripts personalizados en R abarca las siguientes fases críticas:

• Filtrado y QC Celular: Eliminación de células de baja calidad (alto porcentaje mitocondrial) o posibles dobletes (exceso de genes detectados).
• Normalización e Integración: Estandarización de la expresión génica y aplicación de algoritmos de integración matemática para corregir posibles efectos de lote (batch effects) o desbalances en el número de células capturadas entre condiciones (downsampling).
• Reducción de Dimensionalidad y Clustering: Cálculo de componentes principales (PCA), proyección en mapas no lineales (UMAP) y agrupación ciega mediante algoritmos de grafos compartidos (SNN).
• Anotación: Cruce de perfiles de expresión con bases de datos públicas (Tabula Muris, HPCA) y curación experta manual basada en marcadores canónicos.
• Expresión Diferencial: Contrastes estadísticos pareados o por condición clínica (e.g., WT vs KO) dentro de cada subpoblación celular anotada.

Para garantizar reproducibilidad y permitir la inspección técnica del código por parte de otros bioinformáticos, a continuación se proporciona acceso directo a los scripts analíticos principales desarrollados para este experimento, así como a las funciones auxiliares empleadas a lo largo del flujo.

Los scripts ejecutables que contienen el flujo secuencial principal (procesamiento, clustering, anotación y DEGs) se ubican en el directorio:

/workspace/data/05-INT-24-scRNASeq_Timo_Mdelgado_organized/scripts/01_main

A continuación, se listan los archivos contenidos en dicho directorio:

• analisys_edu.R
• analisys_gon.R

Explorar los archivos de la carpeta “01_main” aquí

Una vez mostrados dichos archivos, se pasa a mostrar su código fuente uno por uno. Puede revisarlos cómodamente desde esta misma ventana o descargarlos para su ejecución.

Script auxiliar: analisys_edu.R

Script auxiliar: analisys_gon.R

Además de los flujos principales, el análisis se apoya en funciones complejas predefinidas y modulares (como la generación de gráficos o cálculos estadísticos repetitivos). Estos archivos se agrupan en el directorio en el siguiente directorio:

/workspace/data/05-INT-24-scRNASeq_Timo_Mdelgado_organized/scripts/02_functions

• scRNASeq.R

Explorar los archivos de la carpeta “02_functions” aquí

Una vez mostrados dichos archivos, se pasa a mostrar su código fuente uno por uno (en el caso de que hubiera varios). Puede revisarlos cómodamente desde esta misma ventana o descargarlos para su ejecución.

Script principal: scRNASeq.R

Una vez completadas todas las etapas del flujo de análisis de Single-Cell RNA-Seq mediante con las herramientas anteriormente vistas, los resultados se organizan en una estructura de directorios que sirve como base para la generación de este informe automatizado. Esta organización incluye archivos intermedios, resultados finales y metadatos asociados a cada módulo del pipeline, garantizando la trazabilidad y la reproducibilidad del análisis completo.

Esta sección, al igual que el resto de la pestaña de metodología, tiene un propósito puramente técnico y está pensada como referencia interna para el usuario que generó el informe. Su objetivo es permitir comprender cómo se estructuran los datos de salida del proyecto, de modo que sea posible revisar rápidamente la organización de resultados sin necesidad de volver al entorno de análisis original.

A continuación se muestra la ruta del directorio principal donde se encuentran los datos y resultados generados para este proyecto:

/workspace/data/05-INT-24-scRNASeq_Timo_Mdelgado_organized

A continuación se muestra la estructura completa de dicho directorio. Esta representación permite visualizar los archivos y subcarpetas generados durante el análisis de Single-Cell RNA-Seq y que se emplearon como base para la construcción de este informe:

Explorar los archivos de la carpeta “05-INT-24-scRNASeq_Timo_Mdelgado_organized” aquí

Tras visualizar la estructura de forma interactiva, se presenta a continuación un desglose detallado de las carpetas generadas durante el análisis de Single-Cell RNA-Seq para el proyecto 05-INT-24-scRNASeq_Timo_Mdelgado_organized. Esta organización estandarizada está diseñada para mapear directamente el flujo biológico del análisis celular, facilitando la reproducibilidad y la trazabilidad de los resultados.

Esta estructura modular y coherente no solo permite automatizar los pasos clave del análisis bioinformático, sino que también garantiza trazabilidad, reproducibilidad y facilidad de interpretación. Además, contribuye a una mejor documentación del flujo de trabajo, lo cual es especialmente útil en entornos colaborativos o proyectos de largo recorrido.

Una vez obtenidos los datos procesados mediante el análisis bioinformático y mostrada la estructura del directorio en el cuál se encuentran los resultados generados a partir de todo el proceso de análisis, el siguiente paso consiste en la generación automatizada del informe final. Esta sección tiene como objetivo documentar de manera clara y reproducible todo el proceso mediante el cual se construye el informe, detallando la organización de los archivos de ejecución, la integración de herramientas y la configuración utilizada.

En particular, se abordarán los siguientes aspectos:

• 3.1. Estructura del directorio de ejecución ⇒ Se mostrará la ubicación y organización de los archivos y carpetas desde los cuales se ejecuta el pipeline, incluyendo los scripts de Nextflow y los archivos asociados de Quarto. Esto permite al usuario técnico entender dónde se encuentran los datos, resultados intermedios y archivos de configuración necesarios para generar el informe.
• 3.2. Integración de Nextflow y Quarto ⇒ Se explicará cómo se ha utilizado Nextflow para automatizar la ejecución de Quarto y la generación del informe final, describiendo el rol de los scripts principales (main.nf) y cómo se coordinan las distintas etapas del pipeline.
• 3.3. Configuración del archivo _quarto.yml y params.yml ⇒ Se mostrarán los archivos de configuración que permiten reproducir el informe exacto, incluyendo rutas de entrada, parámetros de análisis y opciones de visualización. Esta documentación asegura que cualquier usuario técnico pueda regenerar el informe con los mismos resultados en el futuro, garantizando trazabilidad y reproducibilidad.

El propósito de esta sección es proporcionar un registro técnico completo del flujo de trabajo utilizado para generar el informe, de manera que cualquier persona que vuelva a consultar el proyecto pueda entender de forma clara cómo se ensamblaron los datos, qué herramientas se utilizaron y cómo se configuró todo el entorno de ejecución.

En esta subsección se describe la estructura de archivos y carpetas desde la cual se ejecuta el pipeline de metagenómica que genera el informe automatizado. Esta información es fundamental para entender cómo se organizan los datos de entrada, los resultados intermedios y los archivos de configuración de Quarto y Nextflow.

La ruta raíz desde la cual se ejecuta este pipeline es:

/workspace/GenoScribe/02-pipelines/01-transcriptomics/02-sc-rna-seq

A continuación se presenta la estructura completa del directorio correspondiente a este proyecto. Es importante destacar que los elementos listados (tanto archivos como subcarpetas) no representan enlaces interactivos, sino que se muestran únicamente para ilustrar la organización interna de los contenidos. Esta representación permite al lector comprender de manera clara y visual cómo se distribuyen los distintos componentes del proyecto, facilitando la navegación conceptual del directorio sin necesidad de acceder directamente a cada archivo.

Explorar los archivos de la carpeta “02-sc-rna-seq” aquí

A continuación se detalla la organización principal del directorio raíz del pipeline (01-bulk-rna-seq). Esta descripción está pensada como referencia técnica: indica qué hace cada archivo o carpeta, dónde se guardan los datos generados y cómo se conectan las piezas para producir el report final.

Una vez comentada la estructura general del directorio de ejecución, se puede señalar que el pipeline está organizado de manera modular para asegurar la reproducibilidad, la trazabilidad de los resultados y la claridad en la generación del informe. Los archivos .qmd representan las pestañas y subsecciones del informe, mientras que Nextflow se encarga de consolidar los resultados previos, generar reportes adicionales cuando es necesario y coordinar la ejecución de Quarto para producir el documento final.

Dentro de resources/01-essential/03-scripts/02-quarto se mantienen dos versiones de las plantillas: 01-full-version, que incluye la pestaña de metodología y todas las secciones detalladas de análisis, y 02-compact-version, que omite la pestaña de metodología y ofrece una versión más compacta del informe. Cada archivo .qmd corresponde a una pestaña o subsección específica.

Nextflow utiliza los resultados existentes del análisis metagenómico (control de calidad, abundancias y predicciones funcionales) almacenados en resources/02-nextflow-results/01-project-data/{nombre_del_proyecto} y realiza operaciones adicionales como la preparación de datos estadísticos en 02-analisis-estadistico. Asimismo, genera los archivos de configuración que Quarto requiere, incluyendo params.yml y, mediante yaml_generator.py, _quarto.yml con los parámetros y rutas específicos del proyecto, para asegurar que la renderización del informe sea reproducible y consistente.

v Para generar el informe, Nextflow invoca quarto render sobre los .qmd y los archivos de parámetros correspondientes, produciendo el HTML final en report/. Los scripts auxiliares en la raíz del proyecto, como run_pipeline_shell.sh, run_pipeline_shiny.sh y run_cleaning_dir.sh, permiten ejecutar el pipeline desde la terminal, mediante interfaz gráfica o limpiar caches y directorios temporales respectivamente.

Para reproducir un informe exacto, se requiere disponer de la copia completa de los resultados en resources/02-nextflow-results/01-project-data/{nombre_del_proyecto}, así como de los archivos params.yml y _quarto.yml generados durante la ejecución. Esta estructura modular facilita la localización de los archivos necesarios y asegura que cualquier usuario pueda reconstruir el informe de manera consistente.

Para detalles adicionales y pasos exactos de ejecución, se recomienda consultar la guía oficial del proyecto en GitHub: GenoScribe: Guía completa para el pipeline Transcriptómico de Single-Cell RNA-Seq.

La integración entre Nextflow y Quarto constituye la base técnica que permite generar de forma automatizada el informe final a partir de los resultados del análisis previo. Este enfoque busca asegurar reproducibilidad, modularidad y trazabilidad, evitando la dependencia de pasos manuales y reduciendo el riesgo de inconsistencias entre los resultados y la documentación generada. A diferencia de un pipeline clásico, en este caso Nextflow no ejecuta los procesos analíticos de pipelines precedentes como podría ser el de Cell Ranger o R, sino que consume sus resultados ya generados, realiza operaciones intermedias necesarias (copias estructuradas, generación de reportes auxiliares, preparación de parámetros) y finalmente invoca Quarto para la construcción del informe.

El esquema general es el siguiente:

1. Se define un conjunto de parámetros y rutas base mediante nextflow.config.
2. Nextflow inicia el pipeline, copia los archivos esenciales del proyecto a una estructura de trabajo reproducible, y ejecuta procesos auxiliares como MultiQC sobre los reportes de control de calidad.
3. Se generan o actualizan los archivos de configuración que Quarto utilizará (params.yml y _quarto.yml).
4. Finalmente, se invoca quarto render para ensamblar el informe HTML final de manera completamente automatizada.

El archivo de configuración nextflow.config, ubicado en /workspace/GenoScribe/02-pipelines/01-transcriptomics/02-sc-rna-seq/nextflow.config, es el punto de partida de esta integración. Define las variables globales del pipeline, incluyendo:

• outdir → Ruta de salida estándar donde se almacenarán los resultados y el informe final.
• project_path → Ubicación del proyecto, que contiene la estructura de directorios generada previamente mediante el correspondiente análisis bioinformático.
• report_version → Define la versión del informe a generar (full o compact), lo cual condiciona las pestañas y contenidos que Quarto renderizará.

Una vez comentado esto, podemos visualizar dicho archivo mediante el siguiente iframe, así como explorarlo de forma más detallada en una página completa o descargarlo (hay que abrir el informe mediante un servidor para que esta acción funcione, como ya se ha mencionado).

El archivo main.nf, ubicado en /workspace/GenoScribe/02-pipelines/01-transcriptomics/02-sc-rna-seq/main.nf, constituye el núcleo del pipeline y orquesta los diferentes procesos necesarios para la preparación del informe. Entre las etapas más relevantes que gestiona este script se incluyen:

• Copia estructurada de archivos del proyecto ⇒ Se seleccionan únicamente los elementos esenciales (sin archivos de gran tamaño como FASTQ o BAM) para trasladarlos a resources/02-nextflow-results/01-project-data/. Esto garantiza que Quarto trabaje sobre una estructura consolidada y ligera.
• Preparación de parámetros para Quarto ⇒ A partir de las variables definidas en nextflow.config, se generan los archivos params.yml y _quarto.yml (este último, mediante yaml_generator.py), los cuales actúan como interfaz entre el pipeline y Quarto.
• Renderizado del informe ⇒ Cuando todos los procesos previos han finalizado satisfactoriamente, se invoca quarto render para construir el informe HTML en la carpeta report/. Esto asegura que el informe se genere siempre con datos completos y parámetros consistentes.

De igual modo, podemos visualizar este archivo mediante el siguiente iframe, así como explorarlo de forma más detallada en una página completa o descargándolo.

Este diseño modular permite ampliar o modificar el pipeline fácilmente sin comprometer su reproducibilidad. Al separar claramente las etapas de preparación de datos y la generación del informe, se facilita la trazabilidad de cada componente y se asegura que cualquier informe pueda ser reconstruido en el futuro a partir de los mismos parámetros y estructura de resultados.

Una vez ejecutado el pipeline de Nextflow, se generan los archivos de configuración _quarto.yml y params.yml. Estos archivos constituyen la interfaz entre el pipeline y Quarto, permitiendo que el último paso del flujo de trabajo ejecute quarto render y construya el informe HTML final a partir de los datos y parámetros proporcionados.

El archivo params.yml contiene todos los parámetros específicos de la ejecución, incluyendo rutas de archivos, opciones de visualización, marcador analizado, versión del informe y metadatos relevantes del proyecto. Por su parte, _quarto.yml establece la estructura del informe, definiendo las plantillas, pestañas, secciones a renderizar y rutas internas, mediante la ejecución del script yaml_generator.py. Juntos, estos archivos permiten que la generación del informe sea completamente automatizada, consistente y reproducible.

A continuación se puede visualizar params.yml mediante un iframe, explorar su contenido de manera interactiva, o abrirlo en una página completa y descargarlo si se desea:

Una vez comprendido el contenido de params.yml, se puede observar _quarto.yml, que actúa como guía estructural para Quarto, indicando qué plantillas y secciones deben incluirse y cómo deben organizarse dentro del informe. Este archivo es esencial para que quarto render genere un documento final coherente con los datos del proyecto.

Esta arquitectura garantiza que cualquier informe pueda ser reproducido en el futuro de manera exacta, siempre que se disponga de los mismos resultados consolidados en resources/02-nextflow-results/01-project-data/nombre_del_proyecto y de los archivos params.yml y _quarto.yml generados por el pipeline. La separación clara entre la preparación de datos y la generación del informe asegura trazabilidad, modularidad y consistencia en los reportes finales.

Esta sección final cierra la pestaña de metodología, dirigida principalmente a usuarios interesados en comprender en detalle cómo se ha generado el informe, qué datos se han utilizado y cómo se ha estructurado la integración entre Nextflow y Quarto. La información aquí proporcionada permite acceder a recursos adicionales, consultar la documentación técnica y localizar los repositorios de código para revisar o reutilizar los scripts empleados.

De manera similar a las tarjetas de inicio, se presentan a continuación algunas tarjetas informativas que facilitan el acceso rápido a los recursos clave relacionados con este proyecto:

Para cualquier duda adicional o consultas de soporte, se puede recurrir a los datos de contacto que se muestran en la pestaña de inicio del informe, donde se incluyen enlaces a la Unidad de Bioinformática del CSIC y al correo de soporte.