Organiza trabajos mediante la ejecución de canalizaciones de Nextflow en Batch

En este instructivo, se explica cómo ejecutar una canalización de Nextflow en Batch. Específicamente, en este instructivo, se ejecuta la canalización de ciencias de la vida de muestra rnaseq-nf de Nextflow, que cuantifica las características genómicas a partir de datos de lecturas cortas con RNA-Seq.

Este instructivo está dirigido a los usuarios de Batch que desean usar Nextflow con Batch.

Nextflow es un software de código abierto para organizar flujos de trabajo bioinformáticos.

Nota: En este instructivo, se proporcionan instrucciones para trabajar con esta app: Nextflow, versión 23.04.1. Es posible que las instrucciones no representen las versiones más recientes de la aplicación. Para obtener más información, consulta la documentación: Nextflow.

Objetivos

Si completas este instructivo, aprenderás a hacer lo siguiente:

• Instala Nextflow en Cloud Shell.
• Crear un bucket de Cloud Storage
• Configurar una canalización de Nextflow.
• Ejecutar una canalización de muestra con Nextflow en Batch
• Visualiza los resultados de la canalización.
• Para evitar incurrir en cargos adicionales, realiza una de las siguientes acciones:
  • Borra un proyecto.
  • Borra recursos individuales.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• Batch
• 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 cumplan con los requisitos para acceder a una prueba gratuita.

Los recursos creados en este instructivo suelen costar menos de un dólar, suponiendo que completas todos los pasos, incluida la limpieza, de manera oportuna.

Antes de comenzar

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.

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

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.

• Crea un proyecto de Google Cloud :

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Habilita las APIs de Batch, Cloud Storage, Compute Engine y Logging:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

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.

• Crea un proyecto de Google Cloud :

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Habilita las APIs de Batch, Cloud Storage, Compute Engine y Logging:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

1. Asegúrate de que tu proyecto tenga una red de nube privada virtual (VPC) con una configuración de red válida para este instructivo.

   Nota: No es necesario que realices ninguna acción en este paso, a menos que tu organización inhabilite la creación de redes de default habilitando la restricción de política compute.skipDefaultNetworkCreation o que tu proyecto haya modificado su red de default.

   En este instructivo, se supone que usas la red de default. De forma predeterminada,los recursos de Google Cloud usan la reddefault, que proporciona el acceso a la red necesario para este instructivo.

   Objetivo: De manera opcional, si deseas que un trabajo por lotes para una canalización de Nextflow use una red diferente, puedes modificar el archivo nextflow.config en este instructivo para definir también la red y la subred del trabajo con los campos google.batch.network y google.batch.subnetwork de Nextflow, respectivamente. Sin embargo, también debes asegurarte de que la red y la subred estén configuradas correctamente para tu carga de trabajo. Para obtener más información, consulta la descripción general de las redes por lotes.

2. Asegúrate de que tu proyecto tenga al menos una cuenta de servicio con los permisos necesarios para ejecutar el trabajo por lotes en este instructivo.

   De forma predeterminada, los trabajos usan la cuenta de servicio predeterminada de Compute Engine, que recibe automáticamente el rol de IAM de Editor (roles/editor) y ya tiene todos los permisos necesarios para este instructivo.

   Nota: No se requiere ninguna acción para este paso, a menos que tu organización inhabilite los permisos automáticos para las cuentas de servicio predeterminadas habilitando la restricción de política iam.automaticIamGrantsForDefaultServiceAccounts, tu proyecto haya modificado su cuenta de servicio predeterminada de Compute Engine o quieras usar una cuenta de servicio diferente.

   Para garantizar que la cuenta de servicio del trabajo tenga los permisos necesarios para permitir que el agente de servicio de Batch cree recursos para los trabajos de Batch y acceda a ellos, pídele a tu administrador que le otorgue los siguientes roles de IAM a la cuenta de servicio del trabajo:

   Importante: Debes otorgar estos roles a la cuenta de servicio del trabajo, no a tu cuenta de usuario. Si no se otorgan los roles a la principal correcta, es posible que se produzcan errores de permisos.
   • Informante del agente por lotes (roles/batch.agentReporter) en el proyecto
   • Administrador de almacenamiento (roles/storage.admin) en el proyecto
   • (Recomendado) Permite que los trabajos generen registros en Cloud Logging: Escritor de registros (roles/logging.logWriter) en el proyecto

   Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

   Es posible que tu administrador también pueda otorgar a la cuenta de servicio del trabajo los permisos necesarios a través de roles personalizados o de otros roles predefinidos.

3. Asegúrate de tener los permisos necesarios para este instructivo.

   Nota: Si creaste el proyecto que planeas usar para este instructivo, no es necesario que realices ninguna acción en este paso. Como creador del proyecto, se te otorga automáticamente el rol de IAM de propietario (roles/owner), que ya tiene todos los permisos necesarios para este instructivo.

   Si quieres obtener los permisos que necesitas para completar este instructivo, pídele a tu administrador que te otorgue los siguientes roles de IAM:

   • Editor de trabajos por lotes (roles/batch.jobsEditor) en el proyecto
   • Usuario de la cuenta de servicio (roles/iam.serviceAccountUser) en la cuenta de servicio del trabajo
   • Administrador de objetos de almacenamiento (roles/storage.objectAdmin) en el proyecto

4. Instala Nextflow:

   curl -s -L https://github.com/nextflow-io/nextflow/releases/download/v23.04.1/nextflow | bash
   

   El resultado debería ser similar al siguiente ejemplo:

   N E X T F L O W
   version 23.04.1 build 5866
   created 15-04-2023 06:51 UTC
   cite doi:10.1038/nbt.3820
   http://nextflow.io
   
   Nextflow installation completed. Please note:
   - the executable file `nextflow` has been created in the folder: ...
   - you may complete the installation by moving it to a directory in your $PATH
   

Cree un bucket de Cloud Storage

Para crear un bucket de Cloud Storage en el que se almacenen los archivos de salida y de trabajo temporales de la canalización de Nextflow, usa la consola Google Cloud o la línea de comandos.

Console

Para crear un bucket de Cloud Storage con la Google Cloud consola, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página Buckets.

   Ir a Buckets

2. Haz clic en Crear.

3. En la página Crear un bucket, ingresa un nombre único a nivel global para tu bucket.

4. Haz clic en Crear.

5. En la ventana Se impedirá el acceso público, haz clic en Confirmar.

gcloud

Para crear un bucket de Cloud Storage con Google Cloud CLI, usa el comando gcloud storage buckets create.

gcloud storage buckets create gs://BUCKET_NAME

Reemplaza BUCKET_NAME por un nombre único a nivel global para tu bucket.

Si la solicitud se realiza de forma correcta, el resultado debe ser similar al siguiente:

Creating gs://BUCKET_NAME/...
   ```

Configura Nextflow

Para configurar la canalización de Nextflow para que se ejecute en Batch, sigue estos pasos en la línea de comandos:

1. Clona el repositorio de la canalización de muestra:

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

2. Ve a la carpeta rnaseq-nf:

   cd rnaseq-nf
   

3. Abre el archivo nextflow.config:

   nano nextflow.config
   

   El archivo debe contener la siguiente sección google-batch:

   'google-batch' {
       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-batch'
       process.container = 'docker.io/nextflow/rnaseq-nf:v1.3.1'
       /*
        * replace with your own bucket!
        */
       workDir = 'gs://BUCKET_NAME/WORK_DIRECTORY'
       google.region  = 'REGION'
   }
   

4. En la sección google-batch, haz lo siguiente:

   1. Reemplaza BUCKET_NAME por el nombre del bucket de Cloud Storage que creaste en los pasos anteriores.

   2. Reemplaza WORK_DIRECTORY por el nombre de una carpeta nueva que la canalización pueda usar para almacenar registros y resultados.

      Por ejemplo, ingresa workDir.

   3. Reemplaza REGION por la región que se usará.

      Por ejemplo, ingresa us-central1.

   4. Después del campo google.region, agrega los siguientes campos:

      1. Agrega el campo google.project:

         google.project = 'PROJECT_ID'
         

         Reemplaza PROJECT_ID por el ID del proyecto Google Cloud actual.

      2. Si no usas la cuenta de servicio predeterminada de Compute Engine como la cuenta de servicio del trabajo, agrega el campo google.batch.serviceAccountEmail:

         google.batch.serviceAccountEmail = 'SERVICE_ACCOUNT_EMAIL'
         

         Reemplaza SERVICE_ACCOUNT_EMAIL por la dirección de correo electrónico de la cuenta de servicio del trabajo que preparaste para este instructivo.

      Objetivo: Para obtener información sobre todos los campos que puedes especificar para configurar el trabajo por lotes de una canalización de Nextflow, consulta la documentación de Nextflow sobre el alcance de la configuración por lotes.

5. Para guardar los cambios, haz lo siguiente:

   1. Presiona Control+S.

   2. Ingresa Y.

   3. Presiona Enter.

Ejecuta la canalización

Ejecuta la canalización de muestra de Nextflow con la línea de comandos:

../nextflow run nextflow-io/rnaseq-nf -profile google-batch

La canalización ejecuta un conjunto de datos pequeño con la configuración que proporcionaste en los pasos anteriores. Esta operación puede tardar hasta 10 minutos en completarse.

Una vez que finalice la ejecución de la canalización, el resultado debería ser similar al siguiente:

N E X T F L O W  ~  version 23.04.1
Launching `https://github.com/nextflow-io/rnaseq-nf` [crazy_curry] DSL2 - revision: 88b8ef803a [master]
 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

Uploading local `bin` scripts folder to gs://example-bucket/workdir/tmp/53/2847f2b832456a88a8e4cd44eec00a/bin
executor >  google-batch (4)
[67/71b856] process > RNASEQ:INDEX (transcript)     [100%] 1 of 1 ✔
[0c/2c79c6] process > RNASEQ:FASTQC (FASTQC on gut) [100%] 1 of 1 ✔
[a9/571723] process > RNASEQ:QUANT (gut)            [100%] 1 of 1 ✔
[9a/1f0dd4] process > MULTIQC                       [100%] 1 of 1 ✔

Done! Open the following report in your browser --> results/multiqc_report.html

Completed at: 20-Apr-2023 15:44:55
Duration    : 10m 13s
CPU hours   : (a few seconds)
Succeeded   : 4

Visualiza los resultados de la canalización

Una vez que finaliza la ejecución de la canalización, esta almacena los archivos de salida, los registros, los errores o los archivos temporales en el archivo results/qc_report.html dentro de la carpeta WORK_DIRECTORY de tu bucket de Cloud Storage.

Para verificar los archivos de salida de la canalización en la carpeta WORK_DIRECTORY de tu bucket de Cloud Storage, puedes usar la consola de Google Cloud o la línea de comandos.

Console

Para verificar los archivos de salida de la canalización con la consola de Google Cloud , sigue estos pasos:

1. En la consola de Google Cloud , ve a la página Buckets.

   Ir a Buckets

2. En la columna Nombre, haz clic en el nombre del bucket que creaste en los pasos anteriores.

3. En la página Detalles del bucket, abre la carpeta WORK_DIRECTORY.

Hay una carpeta para cada tarea independiente que ejecuta el flujo de trabajo. Cada carpeta contiene los comandos que se ejecutaron, los archivos de salida y los archivos temporales que creó la canalización.

gcloud

Para verificar los archivos de salida de la canalización con gcloud CLI, usa el comando gcloud storage ls.

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY

Reemplaza lo siguiente:

• BUCKET_NAME: Es el nombre del bucket que creaste en los pasos anteriores.

• WORK_DIRECTORY: Es el directorio que especificaste en el archivo nextflow.config.

El resultado enumera una carpeta para cada tarea independiente que ejecuta la canalización. Cada carpeta contiene los comandos que se ejecutaron, los archivos de salida y los archivos temporales que creó la canalización.

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.

Borra el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto actual.

Para borrar el proyecto actual, usa la consola de Google Cloud o gcloud CLI.

Console

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

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

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

1. En la Google Cloud 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.

gcloud

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

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

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

Borra un Google Cloud proyecto:

gcloud projects delete PROJECT_ID

Borra los recursos individuales

Si deseas seguir usando el proyecto actual, borra los recursos individuales que se usaron en este instructivo.

Borra el bucket

Si ya no necesitas el bucket que usaste en este instructivo, bórralo.

Borra los archivos de salida del bucket

Una vez que finaliza la ejecución de la canalización, se crean y almacenan archivos de salida en la carpeta WORK_DIRECTORY de tu bucket de Cloud Storage.

Para reducir los cargos de Cloud Storage a la cuenta actual deGoogle Cloud , puedes borrar la carpeta que contiene los archivos de salida de la canalización con la consola de Google Cloud o la línea de comandos.

Console

Para borrar la carpeta WORK_DIRECTORY y todos los archivos de salida de tu bucket de Cloud Storage con la consola deGoogle Cloud , sigue estos pasos:

1. En la consola de Google Cloud , ve a la página Buckets.

   Ir a Buckets

2. En la columna Nombre, haz clic en el nombre del bucket que creaste en los pasos anteriores.

3. En la página Detalles del bucket, selecciona la fila que contiene la carpeta WORK_DIRECTORY y, luego, haz lo siguiente:

   1. Haz clic en Borrar.

   2. Para confirmar, ingresa DELETE y, luego, haz clic en Borrar.

gcloud

Para borrar la carpeta WORK_DIRECTORY y todos los archivos de salida de tu bucket de Cloud Storage con gcloud CLI, usa el comando gcloud storage rm con la marca --recursive.

gcloud storage rm gs://BUCKET_NAME/WORK_DIRECTORY \
      --recursive

Reemplaza lo siguiente:

• BUCKET_NAME: Es el nombre del bucket que especificaste en los pasos anteriores.

• WORK_DIRECTORY: Es el directorio en el que se almacenarán los archivos de salida de la canalización que especificaste en los pasos anteriores.

¿Qué sigue?

• Para obtener más información sobre la implementación de flujos de trabajo de Nextflow, consulta el repositorio de GitHub de Nextflow.

• Para obtener más información sobre los procesos, las secuencias de comandos y las opciones de configuración de Nextflow, consulta la documentación de Nextflow.