运行 Nextflow

本页面介绍了如何使用 Nextflow 在 Google Cloud 上运行流水线。

本教程中使用的流水线是 RNA-Seq 流水线的概念验证，用于展示 Nextflow 在 Google Cloud 上的使用情况。

注意：您有责任遵守 Nextflow 许可协议和 RNAseq-NF 流水线许可协议的条款。

目标

完成本教程后，您将了解如何执行以下任务：

• 在 Cloud Shell 中安装 Nextflow。
• 配置 Nextflow 流水线。
• 在 Google Cloud 上使用 Nextflow 运行流水线。

费用

本教程使用 Google Cloud 的计费组件，包括：

• Compute Engine
• Cloud Storage

请使用价格计算器根据您的预计使用情况来估算费用。Google Cloud 新用户可能有资格申请免费试用。

准备工作

1. 登录您的 Google 帐号。

   如果您还没有 Google 帐号，请注册新帐号。

2. 在 Google Cloud Console 的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到项目选择器页面

3. 确保您的 Cloud 项目已启用结算功能。 了解如何确认您的项目是否已启用结算功能。

4. 启用 Cloud Life Sciences, Compute Engine, and Cloud Storage API。

   启用 API

创建 Cloud Storage 存储分区

按照存储分区命名指南创建一个具有唯一名称的存储分区，您将在本教程中使用该存储分区来存储临时工作和输出文件。如存储分区命名准则中所述，为了实现 DNS 兼容性，本教程不适用于包含下划线（_）的存储分区名称。

控制台

1. 在 Cloud Console 中打开 Cloud Storage 浏览器：

   转到 Cloud Storage 浏览器

2. 点击创建存储分区。

3. 在存储分区名称文本框中，输入存储分区的唯一名称，然后点击创建。

gcloud

1. 打开 Cloud Shell：

   转到 Cloud Shell

2. 运行以下命令以创建存储分区，其中将 BUCKET 替换为存储分区的唯一名称。

   gsutil mb gs://BUCKET
   

创建服务帐号并添加角色

如需创建服务帐号并添加相关 IAM 角色，请完成以下步骤：

控制台

使用 Cloud Console 创建服务帐号：

1. 在 Cloud Console 中，转到服务帐号页面。

   转到“服务帐号”页面

2. 点击创建服务帐号。

3. 在服务帐号名称字段中，输入 nextflow-service-account，然后点击创建。

4. 在向此服务帐号授予对项目的访问权限部分中，从选择角色下拉列表中选择以下角色：

   • Cloud Life Sciences Workflows Runner
   • 服务帐号用户
   • Service Usage Consumer
   • Storage Object Admin

5. 点击继续，然后点击完成。

6. 在“服务帐号”页面中，找到您创建的服务帐号。在同一行中，点击更多，然后点击创建密钥。

7. 在出现的为“nextflow-service-account”创建私钥窗口中，完成以下步骤：

   1. 在密钥类型下，选择 JSON。
   2. 点击创建。

   包含密钥的 JSON 文件就会下载到您的计算机。

gcloud

使用 Cloud Shell 完成以下步骤：

1. 打开 Cloud Shell。

   转到 Cloud Shell

2. 设置要在创建服务帐号时使用的变量，将 PROJECT_ID 替换为您的项目 ID。

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

3. 创建服务帐号。

   gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME}
   

4. 该服务帐号需要以下 Identity and Access Management 角色：

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

   通过在 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
   

为应用提供凭据

您可以将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含服务帐号密钥的 JSON 文件的文件路径，以此向应用代码或命令提供身份验证凭据。

以下步骤展示了如何设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。

控制台

1. 打开 Cloud Shell。

   转到 Cloud Shell

2. 从 Cloud Shell 的更多菜单中，选择上传文件，然后选择刚创建的 JSON 密钥文件。此步骤会将文件上传到 Cloud Shell 实例的主目录中。

3. 确认已上传的文件在当前目录中并通过运行以下命令确认文件名：

   ls
   

4. 设置凭据，将 KEY-FILENAME.json 替换为密钥文件的名称。

   export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/KEY-FILENAME.json
   

gcloud

使用 Cloud Shell 完成以下步骤：

1. 打开 Cloud Shell。

   转到 Cloud Shell

2. 将私钥文件设置为 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}
   

在 Cloud Shell 中安装和配置 Nextflow

为避免在您的计算机上安装任何软件，请使用 Cloud Shell 继续运行本教程中的所有终端命令。

1. 如果尚未打开，请打开 Cloud Shell。

   转到 Cloud Shell

2. 运行以下命令以安装 Nextflow：

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

   如果安装成功，系统会显示以下消息：

       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
   

3. 运行以下命令以克隆示例流水线代码库。该代码库包括要运行的流水线以及流水线使用的样本数据。

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

4. 要配置 Nextflow，请完成以下步骤：

   1. 切换到 rnaseq-nf 文件夹。

      cd rnaseq-nf
      git checkout v2.0
      

   2. 使用选择的文本编辑器，修改名为 nextflow.config 的文件，并对标记为 gls 的部分进行以下更新：

      • 添加 google.project 行（如果不存在）。
      • 将 PROJECT_ID 替换为您的项目 ID。
      • 如果需要，更改 google.location 的值。该值必须是当前可用的 Cloud Life Sciences API 位置之一。
      • 如果需要，更改 google.region 的值，以指定 Compute Engine 虚拟机的启动区域。请参阅可用的 Compute Engine 地区和区域。
      • 将 BUCKET 替换为上面创建的存储分区名称。
      • 将 WORK_DIR 替换为用于日志记录和输出内容的文件夹的名称。请使用您的存储分区中尚不存在的新目录名称。
      • 注意：workDir 变量位置必须至少包含 1 个子目录。请勿仅使用存储分区名称。

      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. 转到上一个文件夹

      cd ..
      

使用 Nextflow 运行流水线

使用 Nextflow 运行流水线。流水线启动后，它将在后台继续运行，直到完成。流水线最多可能需要 10 分钟才能完成。

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

流水线完成后，系统将显示以下消息：

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

查看 Nextflow 流水线的输出

流水线完成后，您可以检查输出以及所有日志、错误、运行的命令和临时文件。

流水线将最终输出文件 results/qc_report.html 保存到您在 nextflow.config 文件中指定的 Cloud Storage 存储分区。

如需检查每个任务和中间文件中的各个输出文件，请完成以下步骤：

控制台

1. 在 Cloud Storage 控制台中，打开 Storage 浏览器页面：

   转到 Cloud Storage 浏览器

2. 转到 BUCKET 并浏览至 nextflow.config 文件中指定的 WORK_DIR。

3. 在流水线中运行的每个独立任务都有一个文件夹。

4. 该文件夹将包含运行过的命令、输出文件以及曾在工作流中使用的临时文件。

gcloud

1. 如需在 Cloud Shell 中查看输出文件，请先打开 Cloud Shell：

   转到 Cloud Shell

2. 运行以下命令，列出 Cloud Storage 存储分区中的输出。将 BUCKET 和 WORK_DIR 更新为 nextflow.config 文件中指定的变量。

   gsutil ls gs://BUCKET/WORK_DIR
   

3. 输出会为每个运行的任务显示一个文件夹。继续列出后续子目录的内容，以查看该流水线创建的所有文件。将 TASK_FOLDER 更新为通过上方命令列出的任务文件夹之一。

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

您可以查看流水线创建的中间文件，并选择要保留或删除它们以降低 Cloud Storage 相关的成本。如需删除文件，请参阅删除 Cloud Storage 存储分区中的中间文件。

问题排查

• 如果您在运行流水线时遇到问题，请参阅 Cloud Life Sciences API 问题排查。

• 如果流水线发生故障，您可以检查每项任务的日志，即 Cloud Storage 中每个文件夹内的日志文件（如 .command.err、.command.log、.command.out 等）。

清理

为避免因本教程中使用的资源导致您的 Google Cloud 帐号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

学完“运行 GATK 最佳做法流水线”教程之后，您可以清理在 Google Cloud 上创建的资源，以避免占用配额，日后产生费用。以下部分介绍如何删除或关闭这些资源。

删除 Cloud Storage 存储分区中的中间文件

当您运行流水线时，中间文件将存储在 gs://BUCKET/WORK_DIR 中。您可以在工作流完成后移除文件，以减少 Cloud Storage 费用。

如需查看目录中使用的空间量，请运行以下命令：

gsutil du -sh gs://BUCKET/WORK_DIR

如需从工作目录中删除文件，请执行以下操作：

控制台

1. 在 Cloud Storage 控制台中，打开 Storage 浏览器页面：

   转到 Cloud Storage 浏览器

2. 转到 BUCKET 并浏览至 nextflow.config 文件中指定的 WORK_DIR。

3. 浏览子文件夹并删除所有不需要的文件或目录。如需删除所有文件，请删除整个 WORK_DIR。

gcloud

1. 打开 Cloud Shell 并运行以下命令：

   转到 Cloud Shell

2. 如需删除 WORK_DIR 目录中的所有中间文件，请运行以下命令：

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

删除项目

为了避免产生费用，最简单的方法是删除您为本教程创建的项目。

如需删除项目，请执行以下操作：

警告：删除项目会产生以下影响

• 项目中的所有内容都会被删除。如果您将现有项目用于本教程，则在删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

如果您打算浏览多个教程和快速入门，重复使用项目可以帮助您避免超出项目配额上限。

1. 在 Cloud Console 中，转到管理资源页面。

   转到“管理资源”

2. 在项目列表中，选择要删除的项目，然后点击删除。
3. 在对话框中输入项目 ID，然后点击关闭以删除项目。

后续步骤

• Nextflow 网站、Nextflow GitHub 代码库和 Nextflow 文档提供了有关如何使用 Nextflow 的更完整的背景信息、文档和支持。