Ejecutar Nextflow

En esta página, se explica cómo ejecutar una canalización de Nextflow en Google Cloud.

La canalización utilizada en este instructivo es una prueba de concepto de una canalización de RNA-Seq destinada a mostrar la utilización de Nextflow en Google Cloud.

Nota: Tienes la responsabilidad de cumplir con las condiciones del Contrato de Licencia de Nextflow y del Contrato de Licencia de la canalización de RNAseq-NF.

Objetivos

Después de completar el instructivo, sabrás cómo realizar las siguientes actividades:

• Instalar Nextflow en Cloud Shell.
• Configurar una canalización de Nextflow.
• Ejecutar una canalización con Nextflow en Google Cloud.

Costos

En este instructivo, se usan los siguientes componentes facturables de Google Cloud:

• Compute Engine
• Cloud Storage

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud califiquen para obtener una prueba gratuita.

Antes de comenzar

1. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

2. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

3. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información sobre cómo verificar si la facturación está habilitada en un proyecto.

4. Habilita las API de Cloud Life Sciences, Compute Engine, and Cloud Storage.

   Habilita las API

5. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

6. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información sobre cómo verificar si la facturación está habilitada en un proyecto.

7. Habilita las API de Cloud Life Sciences, Compute Engine, and Cloud Storage.

   Habilita las API

Cree un bucket de Cloud Storage

Crea un depósito con un nombre único según las instrucciones de los lineamientos para asignar nombres a depósitos. El bucket almacena archivos de trabajo y de salida temporales a lo largo de este instructivo. Para la compatibilidad de DNS, este instructivo no funciona con nombres de depósitos que contengan un guion bajo (_).

Console

1. En Console, ve a la página Navegador de Cloud Storage:

   Ir al navegador

2. Haz clic en Crear bucket.

3. En la página Crear un bucket, ingresa la información de tu bucket.

4. Haga clic en Crear.

gsutil

1. Abre Cloud Shell:

   Ir a Cloud Shell

2. Usa el comando gsutil mb:

   gsutil mb gs://BUCKET_NAME
   

   Reemplaza BUCKET_NAME por el nombre que deseas asignar a tu bucket, sujeto a los requisitos de nomenclatura. Por ejemplo, my-bucket.

   Si la solicitud se realiza correctamente, el comando mostrará el siguiente mensaje:

   Creating gs://BUCKET_NAME/...
   

Crea una cuenta de servicio y agrega funciones

Completa los siguientes pasos para crear una cuenta de servicio y agregar las siguientes funciones de administración de identidades y accesos:

• Ejecutor de flujos de trabajo de Cloud Life Sciences
• Service Account User
• Consumidor de Service Usage

• Administrador de objetos de almacenamiento

Console

Crea una cuenta de servicio con la consola:

1. En la consola, ve a la página Cuentas de servicio.

   Ir a la página Cuentas de servicio

2. Haga clic en Crear cuenta de servicio.

3. En el campo Nombre de la cuenta de servicio, ingresa nextflow-service-account y haz clic en Crear.

4. En la sección Otorga a esta cuenta de servicio acceso al proyecto, agrega las siguientes funciones de la lista desplegable Selecciona una función:

   • Ejecutor de flujos de trabajo de Cloud Life Sciences
   • Service Account User
   • Consumidor de Service Usage
   • Administrador de objetos de almacenamiento

5. Haz clic en Continuar y, luego, en Listo.

6. En la página Cuentas de servicio, busca la cuenta de servicio que creaste. En la fila de la cuenta de servicio, haz clic en el botón Más y, luego, en Administrar claves.

7. En la página Claves, haz clic en Agregar clave y, luego, en Crear clave nueva.

8. Selecciona JSON para el Tipo de clave y haz clic en Crear.

   Se descargará a tu computadora un archivo JSON con la clave.

gcloud

Completa los siguientes pasos con Cloud Shell:

1. Abra Cloud Shell.

   Ir a Cloud Shell

2. Configura las variables que se usarán en la creación de la cuenta de servicio y reemplaza PROJECT_ID con el ID de tu proyecto.

   export PROJECT=PROJECT_ID
   export SERVICE_ACCOUNT_NAME=nextflow-service-account
   export SERVICE_ACCOUNT_ADDRESS=${SERVICE_ACCOUNT_NAME}@${PROJECT}.iam.gserviceaccount.com
   

3. Cree la cuenta de servicio.

   gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME}
   

4. La cuenta de servicio necesita las siguientes funciones de IAM:

   • roles/lifesciences.workflowsRunner
   • roles/iam.serviceAccountUser
   • roles/serviceusage.serviceUsageConsumer
   • roles/storage.objectAdmin

   Ejecuta los siguientes comandos en Cloud Shell para otorgar estas funciones:

   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/lifesciences.workflowsRunner
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/iam.serviceAccountUser
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/serviceusage.serviceUsageConsumer
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/storage.objectAdmin
   

Proporciona credenciales para tu aplicación

Puedes proporcionar credenciales de autenticación al código o a los comandos de tu aplicación. Para ello, configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta del archivo JSON que contiene la clave de tu cuenta de servicio.

En los siguientes pasos se muestra cómo configurar la variable de entorno GOOGLE_APPLICATION_CREDENTIALS:

Console

1. Abra Cloud Shell.

   Ir a Cloud Shell

2. En el menú Más de Cloud Shell, selecciona Subir archivo y, luego, el archivo de claves JSON que creaste. El archivo se sube al directorio principal de la instancia de Cloud Shell.

3. Confirma que el archivo subido esté en tu directorio actual y confirma el nombre del archivo mediante la ejecución del siguiente comando:

   ls
   

4. Configura las credenciales y reemplaza KEY_FILENAME.json por el nombre de tu archivo de claves.

   export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/KEY_FILENAME.json
   

gcloud

Completa los siguientes pasos con Cloud Shell:

1. Abra Cloud Shell.

   Ir a Cloud Shell

2. En el menú Más de Cloud Shell, selecciona Subir archivo y, luego, el archivo de claves JSON que creaste. El archivo se sube al directorio principal de la instancia de Cloud Shell.

3. Confirma que el archivo subido esté en tu directorio actual y confirma el nombre del archivo mediante la ejecución del siguiente comando:

   ls
   

4. Establece el archivo de claves privadas en la variable de entorno GOOGLE_APPLICATION_CREDENTIALS:

   export SERVICE_ACCOUNT_KEY=${SERVICE_ACCOUNT_NAME}-private-key.json
   gcloud iam service-accounts keys create \
     --iam-account=${SERVICE_ACCOUNT_ADDRESS} \
     --key-file-type=json ${SERVICE_ACCOUNT_KEY}
   export SERVICE_ACCOUNT_KEY_FILE=${PWD}/${SERVICE_ACCOUNT_KEY}
   export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/${SERVICE_ACCOUNT_KEY}
   

Instala y configura Nextflow en Cloud Shell

Para evitar tener que instalar software en tu máquina, continúa ejecutando todos los comandos de terminal en este instructivo desde Cloud Shell.

1. Si aún no está abierto, abre Cloud Shell.

   Ir a Cloud Shell

2. Instala Nextflow mediante la ejecución de los siguientes comandos:

   export NXF_VER=21.10.0
   export NXF_MODE=google
   curl https://get.nextflow.io | bash
   

   Si la instalación se completa correctamente, se muestra el siguiente mensaje:

       N E X T F L O W
   version 21.10.0 build 5430
   created 01-11-2020 15:14 UTC (10:14 EDT)
   cite doi:10.1038/nbt.3820
   http://nextflow.io
   
   Nextflow installation completed. Please note:
   ‐ the executable file `nextflow` has been created in the folder: DIRECTORY
   ‐ you may complete the installation by moving it to a directory in your $PATH
   

3. Ejecuta el siguiente comando para clonar el repositorio de la canalización de muestra. El repositorio incluye la canalización que se ejecutará y los datos de muestra que usa la canalización.

   git clone https://github.com/nextflow-io/rnaseq-nf.git
   

4. Completa los siguientes pasos para configurar Nextflow:

   1. Cambia a la carpeta rnaseq-nf.

      cd rnaseq-nf
      git checkout v2.0
      

   2. Con el editor de texto que elijas, edita el archivo llamado nextflow.config y realiza las siguientes actualizaciones en la sección gls:

      • Agrega la línea google.project si no está presente.
      • Reemplaza PROJECT_ID por el ID del proyecto.
      • Si lo deseas, cambia el valor de google.location. Debes ser una de las ubicaciones disponibles de Cloud Life Sciences API.
      • Si lo deseas, cambia el valor de google.region, que especifica la región en la que se inician las VM de Compute Engine. Consulta Regiones y zonas disponibles de Compute Engine.
      • Reemplaza BUCKET por el nombre del depósito que creaste antes.
      • Reemplaza WORK_DIR por el nombre de una carpeta que se usará para el registro y el resultado. Usa un nombre de directorio nuevo que aún no exista en tu bucket.
      Nota: La ubicación de la variable workDir debe contener al menos 1 subdirectorio. No uses solo el nombre del depósito.

      gls {
         params.transcriptome = 'gs://rnaseq-nf/data/ggal/transcript.fa'
         params.reads = 'gs://rnaseq-nf/data/ggal/gut_{1,2}.fq'
         params.multiqc = 'gs://rnaseq-nf/multiqc'
         process.executor = 'google-lifesciences'
         process.container = 'nextflow/rnaseq-nf:latest'
         workDir = 'gs://BUCKET/WORK_DIR'
         google.location = 'europe-west2'
         google.region  = 'europe-west1'
         google.project = 'PROJECT_ID'
      }
      

   3. Vuelve a cambiar a la carpeta anterior.

      cd ..
      

Ejecuta la canalización con Nextflow

Ejecuta la canalización con Nextflow. Después de iniciar la canalización, esta sigue ejecutándose en segundo plano hasta que se complete. La canalización puede tardar hasta 10 minutos en completarse.

./nextflow run rnaseq-nf/main.nf -profile gls

Cuando finalice la canalización, se mostrará el siguiente mensaje:

N E X T F L O W  ~  version 21.10.0
Launching `rnaseq-nf/main.nf` [suspicious_mestorf] - revision: ef908c0bfd
R N A S E Q - N F   P I P E L I N E
 ===================================
 transcriptome: gs://rnaseq-nf/data/ggal/transcript.fa
 reads        : gs://rnaseq-nf/data/ggal/gut_{1,2}.fq
 outdir       : results
executor >  google-lifesciences (4)
[db/2af640] process > RNASEQ:INDEX (transcript)     [100%] 1 of 1 ✔
[a6/927725] process > RNASEQ:FASTQC (FASTQC on gut) [100%] 1 of 1 ✔
[59/438177] process > RNASEQ:QUANT (gut)            [100%] 1 of 1 ✔
[9a/9743b9] process > MULTIQC                       [100%] 1 of 1 ✔
Done! Open the following report in your browser --> results/multiqc_report.html
Completed at: DATE TIME
Duration    : 10m
CPU hours   : 0.2
Succeeded   : 4

Visualiza el resultado de la canalización de Nextflow

Una vez finalizada la canalización, puedes verificar el resultado y los registros, errores, comandos ejecutados y archivos temporales.

La canalización guarda el archivo de salida final, results/qc_report.html, en el bucket de Cloud Storage que especificaste en el archivo nextflow.config.

Para verificar los archivos de salida individuales de cada tarea y los archivos intermedios, completa los siguientes pasos:

Console

1. En Cloud Storage Console, abre la página del navegador de Storage:

   Ir al navegador de Cloud Storage

2. Ve al BUCKET y navega hasta el WORK_DIR especificado en el archivo nextflow.config.

3. Hay una carpeta para cada una de las tareas separadas que se ejecutaron en la canalización.

4. La carpeta contiene los comandos que se ejecutaron, los archivos de salida y los archivos temporales que se usaron durante el flujo de trabajo.

gcloud

1. Para ver los archivos de salida en Cloud Shell, primero abre Cloud Shell:

   Ir a Cloud Shell

2. Ejecuta el siguiente comando para enumerar los resultados de tu bucket de Cloud Storage. Actualiza BUCKET y WORK_DIR a las variables especificadas en el archivo nextflow.config.

   gsutil ls gs://BUCKET/WORK_DIR
   

3. El resultado muestra una carpeta para cada una de las tareas ejecutadas. Continúa enumerando el contenido de los subdirectorios posteriores para ver todos los archivos que creó la canalización. Actualiza TASK_FOLDER una de las carpetas de tareas que se mostraron en el comando anterior.

   gsutil ls gs://BUCKET/WORK_DIR/FOLDER/TASK_FOLDER
   

Puedes ver los archivos intermedios que creó la canalización y elegir cuáles quieres conservar, o bien quitarlos para reducir los costos asociados con Cloud Storage. Si quieres quitar los archivos, consulta Borra los archivos intermedios en el depósito de Cloud Storage.

Solución de problemas

• Si tienes problemas para ejecutar la canalización, consulta la solución de problemas de la API de Cloud Life Sciences.

• Si tu canalización falla, puedes revisar los registros de cada tarea. Para ello, mira los archivos de registro en cada una de las carpetas de Cloud Storage, como .command.err, .command.log, .command.out, etcétera.

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Una vez que completes el instructivo, puedes limpiar los recursos que creaste para que dejen de usar la cuota y generen cargos. En las siguientes secciones, se describe cómo borrar o desactivar estos recursos.

Borra los archivos intermedios del bucket de Cloud Storage

Cuando ejecutas la canalización, almacena los archivos intermedios en gs://BUCKET/WORK_DIR. Puedes quitar los archivos luego de que se complete el flujo de trabajo para reducir los cargos de Cloud Storage.

Para ver cuánto espacio se usa en el directorio, ejecuta el siguiente comando:

gsutil du -sh gs://BUCKET/WORK_DIR

Para quitar archivos de WORK_DIR, completa los siguientes pasos:

Console

1. En Cloud Storage Console, abre la página del navegador de Storage:

   Ir al navegador de Cloud Storage

2. Ve al BUCKET y navega hasta el WORK_DIR especificado en el archivo nextflow.config.

3. Examina las subcarpetas y borra los archivos o directorios no deseados. Para borrar todos los archivos, borra todo el directorio WORK_DIR.

gcloud

1. Abre Cloud Shell y ejecuta lo siguiente:

   Ir a Cloud Shell

2. Para quitar los archivos intermedios del directorio WORK_DIR, ejecuta el siguiente comando:

   gsutil -m rm gs://BUCKET/WORK_DIR/**
   

Borra el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

Para borrar el proyecto, haga lo siguiente:

Precaución: Borrar un proyecto tiene estas consecuencias:

• Se borra todo en el proyecto. Si utilizaste un proyecto existente para este instructivo, cuando lo borres, también borrarás cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los ID personalizados de proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URL que utilizan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto en lugar de borrar todo el proyecto.

Si planeas explorar varios instructivos y guías de inicio rápido, la reutilización de proyectos puede ayudarte a evitar exceder los límites de las cuotas del proyecto.

1. En la consola, ve a la página Administrar recursos.

   Ir a Administrar recursos

2. En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

¿Qué sigue?

En las siguientes páginas, se proporciona más información general, documentación y asistencia para usar Nextflow:

• Sitio de Nextflow
• Repositorio de GitHub de Nextflow
• Documentación de Nextflow