Easy-DRAM2 🧬

Configuración sencilla de DRAM2 para que corra en el HPC de OMICA 🖥️. Facilito.

---

Índice

• Estructura del repositorio
• Prerrequisitos
• Instrucciones
  • Instalación de DRAM2
  • Configuración de SLURM: META_MAG_distill_DRAM2.slurm
  • Configuración de Nextflow: META_nf_DRAM2.config
  • Correr Nextflow/DRAM2

📁 Estructura del repositorio

Este repositorio consiste de los siguientes archivos:

easy-DRAM2/
├── scripts/
│   ├── META_install_DRAM2.sh
│   └── META_MAG_distill_DRAM2.slurm
└── configs/
    ├── META_nf_DRAM2.config
    └── META_omica_slurm.config

Archivo	Descripción
META_install_DRAM2.sh	Script de instalación. Aquí se define WORK_DIR (una sola vez). Se pasa a META_nf_DRAM2.config, copia el fork de DRAM2 a tu home, META_omica_slurm.config a DRAM2, y trait_rules.tsv a WORK_DIR.
META_MAG_distill_DRAM2.slurm	Script que ejecuta el pipeline principal de Nextflow/DRAM2.
META_nf_DRAM2.config	Archivo de configuración de Nextflow. Aquí puedes personalizar los parámetros del pipeline.
META_omica_slurm.config	Archivo con parámetros de SLURM. No recomiendo editarlo; el script de META_install_DRAM2.sh lo copia a donde debe de ir y listo.

📌Prerrequisitos

Para poder correr DRAM2 en el servidor de OMICA, hay unos prerrequisitos que se deben cumplir. El servidor ya los cumple:

• Docker: En el servidor de OMICA, Docker está instalado en los nodos nodo5 y nodo[26-28].
• Nextflow: Se instaló Nextflow en el ambiente de conda DRAMV2.
• Bases de datos de referencia: Al día de hoy, las siguientes bases de datos están descargadas en el servidor OMICA: KEGG, Kofam, Pfam, UniRef, Sulfur, Metals, Methyl, Camper, dbCAN y FeGenie. Puedes elegir las bases de datos a usar en tu flujo.

🚀Instrucciones

🛠️Instalación de DRAM2

El repositorio oficial de DRAM2 tiene una serie de bugs que impiden que el pipeline corra fluidamente con la base de datos de KEGG; para resolverlo, forkié el repo original y lo modifiqué. Mientras aceptan mi pull request, usaremos el fork.

Sitúate dentro de la carpeta en la que desees clonar este repositorio. Clona:

git clone https://github.com/ruben1294/easy-DRAM2.git
cd easy-DRAM2

Corre el script de instalación:

bash scripts/META_install_DRAM2.sh

Este script va a:

1. Clonar el fork de DRAM2 (ruben1294/DRAM, rama dev) en tu home usando Nextflow.
2. Colocar una copia del archivo META_omica_slurm.config dentro del directorio conf/ del pipeline.
3. Copiar el archivo trait_rules.tsv a WORK_DIR. Este archivo se usa para el módulo traits. Esto es necesario porque Docker no tiene acceso al home del usuario en tiempo de ejecución y no puede leer el archivo desde ~/.nextflow/assets/. Sin esta copia, el módulo traits da error.

Ahora debes configurar dos archivos para personalizar tus rutas y parámetros del pipeline. Recomiendo que los modifiques en este orden:

⚙️Configuración de SLURM: META_MAG_distill_DRAM2.slurm

Este script lanza el job maestro y ejecuta el orquestador, que es Nextflow, quien a su vez pasa los subjobs a SLURM. Actualmente, Docker sólo está instalado en los nodos nodo5 y nodo[26-28], sólo ahí se pueden ejecutar los subjobs del pipeline. Por default, el orquestador corre en nodo26 (el nodo5, al ser de los primeros, normalmente está ocupado).

Este es el único archivo donde debes definir WORK_DIR. El script lo exporta como variable de entorno, y META_nf_DRAM2.config lo lee automáticamente con System.getenv('WORK_DIR'). No hace falta editar el config para cambiar la ruta de trabajo.

# =============================================
# CONFIGURA TUS RUTAS AQUÍ (una sola vez):
# =============================================
export WORK_DIR="/LUSTRE/bioinformatica_data/metagenomica"
export OUT_DIR="${WORK_DIR}"  # Directorio de salida del pipeline
export DB_DIR="/LUSTRE/bioinformatica_data/BD/metagenomica/DRAM_v2_DB_012026"
# =============================================

Modifica el job-name y el tiempo a reservar a tu gusto:

#SBATCH --job-name=MAG_distill_DRAM2
#SBATCH --time=160:00:00

Nextflow usa pocos recursos. Por esta razón, recomiendo dejar los valores de nodes, ntasks, cpus-per-task y mem intactos:

#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=2
#SBATCH --mem=2G

Ahora, modifica las rutas a los logs de output y error para que se guarden donde desees:

#SBATCH --output=/LUSTRE/bioinformatica_data/metagenomica/DRAM2_%j.out
#SBATCH --error=/LUSTRE/bioinformatica_data/metagenomica/DRAM2_%j.err

Si quieres usar un archivo .env con rutas definidas, coloca la ruta del archivo y descomenta la sección con el encabezado Configuration Section:

#log_info "Loading configuration..."
#CONFIG_FILE="/LUSTRE/bioinformatica_data/metagenomica/config.env"
#if [[ ! -f "$CONFIG_FILE" ]]; then
#    log_error "Configuration file not found: $CONFIG_FILE"
#    exit 1
#fi
#source "$CONFIG_FILE"
#log_info "Configuration file sourced successfully"

Configura las siguientes rutas:

export OUT_DIR="/LUSTRE/bioinformatica_data/metagenomica" # Directorio de salida (donde se colocarán las salidas del pipeline)
export RAW_DIR="/LUSTRE/bioinformatica_data/metagenomica" # Directorio donde están los MAGs a procesar
export QUALITY_DIR="/LUSTRE/bioinformatica_data/metagenomica" # Directorio donde están los resultados de calidad
export TAXONOMY_DIR="/LUSTRE/bioinformatica_data/metagenomica" # Directorio donde están los resultados de la clasificación taxonómica

Eso es todo lo que tienes que hacer en este archivo.

⚠️ Importante: la etiqueta -resume sirve para que DRAM2 guarde una caché de tu pipeline. Si llegaras a cancelar el job maestro (el del orquestador), o si el pipeline falla por un error, puedes relanzar el script más adelante, y DRAM2 reanudará el pipeline en donde se quedó. La caché se guarda en:

~/.nextflow/assets/ruben1294/DRAM/work

Si quieres que el script corra todo desde cero, simplemente borra la carpeta work, esto borra la caché del pipeline. Puedes hacerlo sin preocupaciones.

⚙️Configuración de Nextflow: META_nf_DRAM2.config

Aquí es donde puedes configurar el pipeline para que corra los módulos que desees, que use las bases de datos de referencia que desees, etcétera. Te recomiendo modificar sólo lo que menciono a continuación.

Ruta de trabajo (WORK_DIR)

WORK_DIR se define en META_MAG_distill_DRAM2.slurm (ver más abajo) y se pasa a Nextflow como variable de entorno. El config lo lee con System.getenv('WORK_DIR'). No es necesario editarlo aquí. Todas las demás rutas (MAGs de entrada, taxonomía, calidad, etc.) están en función de WORK_DIR.

Bases de datos

La ruta a las bases de datos de referencia se define aquí:

DB_DIR = "/LUSTRE/bioinformatica_data/BD/metagenomica/DRAM_v2_DB_012026"

Módulos

El pipeline de DRAM2 se divide en módulos. Puedes encender o apagar los que desees correr. Ya tenemos una copia de la base de datos de KEGG, por lo que todos los módulos están activos por defecto:

rename    = true
annotate  = true
summarize = true
visualize = true
traits    = true
qc        = true

Esto es lo que hace cada módulo:

• rename: agrega el nombre del MAG en el encabezado de cada contig, antes del ID actual y sucedido por un guión bajo (_).
• annotate: asigna funciones biológicas a los genes predichos, usando como referencia las bases de datos que más adelante definas.
• summarize: el "destilado" del metabolismo. Resume las anotaciones del módulo de annotate en rutas metabólicas, módulos funcionales, etcétera, por MAG.
• visualize: genera gráficos con los resultados de summarize.
• traits: intenta extraer rasgos biológicos a partir de las anotaciones. Existen varias hojas llamadas "distill sheets", con una serie de reglas para definir los traits de cada MAG.
• qc: usa barrnap y tRNAscan-SE para identificar rDNAs y tRNAs, respectivamente.
• call: usa Prodigal para predecir marcos abiertos de lectura, genes y secuencias proteicas.

Opciones de Prodigal

Si quieres usar tus propias salidas de Prodigal, puedes apagar el módulo call y definir la ruta a tus archivos aquí:

input_genes = "$GENES_DIR"

Modifica la ruta input_fasta para que vaya a la carpeta donde están tus MAGs:

input_fasta = "${WORK_DIR}/01_raw_files"

Puedes modificar los parámetros con los que correrá Prodigal:

prodigal_mode = 'single'
prodigal_trans_table = 11
min_contig_len = 1000 // Aquí yo usé 2500, y me funcionó relativamente bien. Obtuve muchos genes predichos.

Bases de datos de referencia

En la parte de Annotation Database Flags, puedes elegir qué base de datos de referencia usar para la anotación funcional de proteínas. Puedes encender o apagar a tu gusto. No obstante, hay un bug conocido con la base de datos de Pfam, por lo que está deshabilitada por ahora:

use_pfam = false // 2026/01/13: Pfam está deshabilitado por ahora debido a un bug.

Reportes de calidad y taxonomía

En la sección de Taxonomy and Bin Quality ingest, puedes definir rutas a tu reporte de taxonomía y de calidad:

taxa = "${WORK_DIR}/03_taxonomy_assigned/classify/summary.tsv"
bin_quality = "${WORK_DIR}/02_mags_quality/quality_report.tsv"

Estos resultados se incorporan al reporte raw-annotations.tsv.

Quality control (rDNAs y tRNAs)

Si tienes apagado el módulo de qc y deseas incluir tus propios resultados de la búsqueda de rDNAs y tRNAs, puedes incluir las rutas a los archivos aquí:

rrnas = null
trnas = null

trait_rules.tsv (fix Docker)

El módulo traits necesita un archivo de reglas (trait_rules.tsv). Docker no tiene acceso al home del usuario en tiempo de ejecución, por lo que el archivo debe estar en una ruta accesible desde el contenedor. El script de instalación lo copia automáticamente a WORK_DIR, y en la configuración se hace referencia a esa copia:

rules_tsv = "${WORK_DIR}/trait_rules.tsv"

No es necesario modificar este parámetro si usas el directorio de trabajo predeterminado.

Opciones de SLURM

En la parte de SLURM options, el único parámetro que recomiendo modificar (si lo deseas), es la partición, si no vas a usar la de 'cicese':

partition = 'cicese'

Si deseas usar más de dos nodos, incluye el nombre del nodo adicional aquí:

slurm_node = 'nodo27,nodo28'

⚠️ Importante: asegúrate de que el nodo nuevo que vayas a incluir acá, no sea el mismo en donde lanzaste el job maestro (el del orquestador). Si es el mismo, se quedará esperando para siempre a que el nodo se libere.

Queue size

El parámetro de queue_size es para definir cuántos subjobs se ejecutarán al mismo tiempo. Aquí es importante mencionar que los subjobs usarán la memoria RAM disponible del nodo repartida entre ellos, por lo que a mayor cantidad de subjobs, menor RAM podrá usar cada uno. A mí me ha funcionado usar un valor conservador (2-3):

queue_size = 3

Esto es todo lo que te sugiero modificar en el archivo.

🚀Correr Nextflow/DRAM2

Una vez que hayas revisado esos parámetros, puedes correr el script de SLURM:

sbatch scripts/META_MAG_distill_DRAM2.slurm

Como habrás notado, el script está diseñado para que coloque las salidas en la carpeta que elijas, pero el comando de Nextflow se debe ejecutar en la carpeta del repositorio. El script hace todo eso, no necesitas hacer nada más.

Debugging

• Dentro de la carpeta de bases de datos de referencia, en la carpeta de la base KEGG, todos los archivos deben llamarse "kegg.*", eso es lo que espera el código. Si esto no se cumple, dará error.
• Para poder correr traits se requieren forzosamente las bases de datos KEGG, FeGenie y Sulfur. Además, los módulos summarize y visualize activan traits automáticamente. Si intentas correr alguno de estos módulos sin una de estas bases de datos, dará error.