Exécuter Nextflow

Cette page explique comment exécuter un pipeline sur Google Cloud à l'aide de Nextflow.

Le pipeline utilisé dans ce tutoriel est une démonstration de faisabilité d'un pipeline RNA-Seq destiné à illustrer l'utilisation de Nextflow sur Google Cloud.

Objectifs

À la fin de ce tutoriel, vous saurez :

Installez Nextflow dans Cloud Shell.
Configurer un pipeline Nextflow
Exécutez un pipeline utilisant Nextflow sur Google Cloud.

Coûts

Ce tutoriel utilise des composants facturables de Google Cloud, dont :

Instance
Cloud Storage.

Utilisez le Simulateur de coût pour générer une estimation des coûts en fonction de votre utilisation prévue. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Avant de commencer

Connectez-vous à votre compte Google.
Si vous n'en possédez pas déjà un, vous devez en créer un.

Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

Accéder à la page de sélection du projet

Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

Activer les API Cloud Life Sciences, Compute Engine, and Cloud Storage.
Activer les API

Créer un bucket Cloud Storage

En suivant les recommandations fournies dans les consignes relatives aux noms des buckets, créez un bucket portant un nom unique pour stocker les fichiers temporaires et les fichiers de sortie utilisés tout au long de ce tutoriel. Comme indiqué dans les consignes concernant les noms de buckets, pour des raisons de compatibilité DNS, ce tutoriel ne fonctionnera pas avec les noms de buckets contenant un trait de soulignement (_).

Console

Dans Cloud Console, ouvrez le navigateur Cloud Storage :

Accéder au navigateur Cloud Storage
Cliquez sur Créer un bucket.
Dans la zone de texte Nom du bucket, saisissez un nom unique pour votre bucket, puis cliquez sur Créer.

gcloud

Ouvrez Cloud Shell.

Accéder à Cloud Shell
Exécutez la commande suivante pour créer un bucket en remplaçant BUCKET par un nom unique pour ce bucket.
```
gsutil mb gs://BUCKET
```

Créer un compte de service et ajouter des rôles

Pour créer un compte de service et ajouter les rôles IAM pertinents, procédez comme suit:

Console

Créez un compte de service à l'aide de Cloud Console :

Dans Cloud Console, accédez à la page Comptes de service.

Accéder à la page Comptes de service
Cliquez sur Créer un compte de service.
Dans le champ Nom du compte de service, saisissez nextflow-service-account, puis cliquez sur Créer.
Dans la section Autoriser ce compte de service à accéder au projet, ajoutez les rôles suivants à partir de la liste déroulante Sélectionner un rôle:
- Exécuteur de workflows Cloud Life Sciences
- Utilisateur du compte de service
- Consommateur Service Usage
- Administrateur des objets de l'espace de stockage
Cliquez sur Continuer, puis sur OK.
Sur la page Comptes de service, recherchez le compte de service que vous avez créé. Sur la ligne du compte de service, cliquez sur le bouton , puis cliquez sur Gérer les clés.
Sur la page Clés, cliquez sur Ajouter une clé, puis sur Créer une clé.
Sélectionnez JSON pour le type de clé, puis cliquez sur Créer.

Un fichier JSON contenant votre clé est téléchargé sur votre ordinateur.

gcloud

Effectuez les étapes suivantes à l'aide de Cloud Shell:

Ouvrez Cloud Shell.

Accéder à Cloud Shell

Définissez les variables à utiliser lors de la création du compte de service, en remplaçant PROJECT_ID par l'ID de votre projet.

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

Créez le compte de service.

gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME}

Le compte de service doit disposer des rôles Identity and Access Management suivants :

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

Attribuez ces rôles en exécutant les commandes suivantes dans Cloud Shell :

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

Fournir des identifiants à l'application

Vous pouvez fournir des identifiants d'authentification au code ou aux commandes de votre application en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur le chemin du fichier JSON contenant votre clé de compte de service.

Les étapes suivantes montrent comment définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS:

Console

Ouvrez Cloud Shell.

Accéder à Cloud Shell
Dans le menu Plus de Cloud Shell, sélectionnez Importer un fichier, puis le fichier de clé JSON que vous venez de créer. Cette étape importe le fichier dans le répertoire d'accueil de votre instance Cloud Shell.
Vérifiez que le fichier importé se trouve dans votre répertoire actuel et confirmez le nom du fichier en exécutant la commande suivante :
```
ls
```
Définissez les identifiants en remplaçant KEY-FILENAME.json par le nom de votre fichier de clé.
```
export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/KEY-FILENAME.json
```

gcloud

Effectuez les étapes suivantes à l'aide de Cloud Shell:

Ouvrez Cloud Shell.

Accéder à Cloud Shell

Définissez le fichier de clé privée sur la variable d'environnement 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}

Installer et configurer Nextflow dans Cloud Shell

Pour éviter d'avoir à installer des logiciels sur votre ordinateur, continuez à exécuter toutes les commandes de terminal de ce tutoriel à partir de Cloud Shell.

Si ce n'est pas déjà fait, ouvrez Cloud Shell.

Accéder à Cloud Shell

Exécutez les commandes suivantes pour installer Nextflow :

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

Si l'installation se termine correctement, le message suivant s'affiche :

    N E X T F L O W
version 20.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

Exécutez la commande suivante pour cloner l'exemple de dépôt de pipeline. Le dépôt inclut le pipeline à exécuter et les exemples de données qu'il utilise.
```
git clone https://github.com/nextflow-io/rnaseq-nf.git
```
Pour configurer Nextflow, procédez comme suit :
1. Accédez au dossier rnaseq-nf.
```
cd rnaseq-nf
git checkout v2.0
```
2. À l'aide de l'éditeur de texte de votre choix, modifiez le fichier nommé nextflow.config et apportez les modifications suivantes à la section intitulée gls :
  - Ajoutez la ligne google.project si elle n'est pas présente.
  - Remplacez PROJECT_ID par l'ID du projet.
  - Si vous le souhaitez, modifiez la valeur de google.location. Il doit s'agir de l'un des emplacements de l'API Cloud Life Sciences actuellement disponibles.
  - Si vous le souhaitez, modifiez la valeur de google.region qui spécifie la région dans laquelle les VM Compute Engine seront lancées. Consultez la page Régions et zones de Compute Engine disponibles.
  - Remplacez BUCKET par le nom du bucket créé ci-dessus.
  - Remplacez WORK_DIR par le nom d'un dossier à utiliser pour la journalisation et la sortie. Utilisez un nom de répertoire qui n'existe pas encore dans votre bucket.
  - Remarque : L'emplacement de la variable workDir doit contenir au moins un sous-répertoire. N'utilisez pas juste le nom du bucket.
```
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. Revenez au dossier précédent.
```
cd ..
```

Exécuter le pipeline à l'aide de Nextflow

Exécutez le pipeline avec Nextflow. Une fois le pipeline démarré, il continue à s'exécuter en arrière-plan jusqu'à la fin de l'opération. Le pipeline peut prendre jusqu'à 10 minutes.

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

Une fois l'exécution du pipeline terminée, le message suivant s'affiche :

N E X T F L O W  ~  version 20.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

Afficher le résultat du pipeline Nextflow

Une fois que l'exécution du pipeline se conclut, vous pouvez vérifier le résultat ainsi que les journaux, les erreurs, les commandes exécutées et les fichiers temporaires.

Le pipeline enregistre le fichier de sortie final (results/qc_report.html) dans le bucket Cloud Storage que vous avez spécifié dans le fichier nextflow.config.

Pour vérifier les fichiers de sortie individuels de chaque tâche et fichiers intermédiaires, procédez comme suit :

Console

Dans la console Cloud Storage, ouvrez la page du navigateur de Cloud Storage :

Accéder au navigateur Cloud Storage
Accédez au BUCKET et à l'élément WORK_DIR spécifié dans le fichier nextflow.config.
Il existe un dossier pour chacune des tâches distinctes exécutées dans le pipeline.
Le dossier contient les commandes exécutées, les fichiers de sortie et les fichiers temporaires utilisés au cours du processus.

gcloud

Pour afficher les fichiers de sortie dans Cloud Shell, commencez par ouvrir Cloud Shell :

Accéder à Cloud Shell
Exécutez la commande suivante pour répertorier les résultats dans votre bucket Cloud Storage. Mettez à jour BUCKET et WORK_DIR vers les variables spécifiées dans le fichier nextflow.config.
```
gsutil ls gs://BUCKET/WORK_DIR
```
La sortie de la commande affiche un dossier pour chacune des tâches exécutées. Pour afficher tous les fichiers créés par le pipeline, continuez à répertorier le contenu des sous-répertoires suivants. Mettez à jour TASK_FOLDER pour qu'il soit l'un des dossiers de tâches répertoriés dans la commande ci-dessus.
```
gsutil ls gs://BUCKET/WORK_DIR/FOLDER/TASK_FOLDER
```

Vous pouvez afficher les fichiers intermédiaires créés par le pipeline et sélectionner ceux que vous souhaitez conserver, ou les supprimer pour réduire les coûts associés à Cloud Storage. Pour supprimer les fichiers, consultez la section Supprimer des fichiers intermédiaires du bucket Cloud Storage ci-après.

Dépannage

Si vous rencontrez des problèmes lors de l'exécution du pipeline, consultez la page Dépannage de l'API Cloud Life Sciences.
Si votre pipeline échoue, vous pouvez vérifier les journaux de chaque tâche en consultant les fichiers journaux figurant dans chacun des dossiers de Cloud Storage, tels que .command.err, .command.log, .command.out, etc.

Nettoyer

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et les ressources individuelles.

Une fois que vous avez terminé le tutoriel sur l'exécution du pipeline des bonnes pratiques GATK, vous pouvez procéder au nettoyage des ressources que vous avez créées sur Google Cloud afin qu'elles ne soient plus comptabilisées dans votre quota et qu'elles ne vous soient plus facturées. Dans les sections suivantes, nous allons voir comment supprimer ou désactiver ces ressources.

Supprimer des fichiers intermédiaires du bucket Cloud Storage

Lorsque vous exécutez le pipeline, celui-ci stocke les fichiers intermédiaires dans le répertoire gs://BUCKET/WORK_DIR. Vous pouvez supprimer ces fichiers une fois le workflow terminé afin de réduire les frais générés par Cloud Storage.

Pour afficher la quantité d'espace utilisée dans le répertoire, exécutez la commande suivante :

gsutil du -sh gs://BUCKET/WORK_DIR

Pour supprimer des fichiers du répertoire de travail, procédez comme suit :

Console

Dans la console Cloud Storage, ouvrez la page du navigateur de Cloud Storage :

Accéder au navigateur Cloud Storage
Accédez au BUCKET et à l'élément WORK_DIR spécifié dans le fichier nextflow.config.
Parcourez les sous-dossiers et supprimez les fichiers ou répertoires que vous ne souhaitez pas conserver. Pour supprimer tous les fichiers, supprimez tout le répertoire WORK_DIR.

gcloud

Ouvrez Cloud Shell et exécutez la commande suivante :

Accéder à Cloud Shell
Pour supprimer tous les fichiers intermédiaires du répertoire WORK_DIR, exécutez la commande suivante :
```
gsutil -m rm gs://BUCKET/WORK_DIR/**
```

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

Attention : La suppression d'un projet aura les effets suivants :

Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour ce tutoriel et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs tutoriels et guides de démarrage rapide, vous pouvez constater que réutiliser des projets peut vous aider à éviter de dépasser les limites de quotas des projets.

Dans Cloud Console, accédez à la page Gérer les ressources.
Accéder à la page Gérer les ressources
Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Étape suivante

Le site de Nextflow, le dépôt GitHub Nextflow et la documentation de Nextflow fournissent des informations de contexte, une documentation et une assistance pour l'utilisation de Nextflow.