Nextflow の実行

このページでは、Google Cloud で Nextflow パイプラインを実行する方法について説明します。

このチュートリアルで使用するパイプラインは、Google Cloud での Nextflow の使用を示すことを目的とした RNA-Seq パイプラインの概念実証として記しています。

目標

このチュートリアルを完了すると、以下のことが行えます。

  • Cloud Shell に Nextflow をインストールします。
  • Nextflow パイプラインを構成する。
  • Google Cloud で Nextflow を使用してパイプラインを実行する。

料金

このチュートリアルでは、Google Cloud の課金対象となる以下のコンポーネントを使用します。

  • Compute Engine
  • Cloud Storage

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを出すことができます。新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

始める前に

  1. Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
  2. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

    プロジェクト セレクタに移動

  3. Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトに対して課金が有効になっていることを確認する方法を学習する

  4. Cloud Life Sciences, Compute Engine, and Cloud Storage API を有効にします。

    API を有効にする

Cloud Storage バケットの作成

バケットの命名ガイドラインのガイダンスに従って、一意の名前のバケットを作成します。バケットには、このチュートリアル全体を通して一時的な作業ファイルと出力ファイルが保存されます。DNS の互換性を維持するため、このチュートリアルではアンダースコア(_)を含むバケット名は使用できません。

Console

  1. Cloud Console の Cloud Storage [ブラウザ] ページに移動します。

    [ブラウザ] に移動

  2. [バケットを作成] をクリックします。

  3. [バケットの作成] ページで、ユーザーのバケット情報を入力します。

  4. [作成] をクリックします。

gsutil

  1. Cloud Shell を開きます。

    Cloud Shell に移動

  2. gsutil mb コマンドを使用します。

    gsutil mb gs://BUCKET_NAME
    

    BUCKET_NAME は、命名要件に従って、バケットに付ける名前に置き換えます。例: my-bucket

    リクエストが成功すると、コマンドから次のメッセージが返されます。

    Creating gs://BUCKET_NAME/...
    

サービス アカウントを作成してロールを追加する

次の手順に従って、サービス アカウントを作成し、Identity and Access Management の役割を追加します。

  • Cloud Life Sciences ワークフロー実行者
  • サービス アカウント ユーザー
  • Service Usage ユーザー
  • ストレージのオブジェクト管理者

Console

Cloud Console を使用してサービス アカウントを作成します。

  1. Cloud Console で、[サービス アカウント] ページに移動します。

    [サービス アカウント] ページに移動

  2. [サービス アカウントを作成] をクリックします。

  3. [サービス アカウント名] フィールドに「nextflow-service-account」と入力し、[作成] をクリックします。

  4. [このサービス アカウントにプロジェクトへのアクセスを許可する] セクションで、[ロールを選択] プルダウン リストから次の役割を追加します。

    • Cloud Life Sciences ワークフロー実行者
    • サービス アカウント ユーザー
    • Service Usage ユーザー
    • ストレージのオブジェクト管理者
  5. [続行] をクリックし、[完了] をクリックします。

  6. [サービス アカウント] ページで、作成したサービス アカウントを見つけます。サービス アカウントの行で、をクリックし、[キーを管理] をクリックします。

  7. [キー] ページで [キーを追加] をクリックし、[新しいキーを作成] をクリックします。

  8. [キーのタイプ] には [JSON] を選択し、[作成] をクリックします。

    キーを含む 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. サービス アカウントには、次の IAM ロールが必要です。

    • 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 環境変数の設定方法を説明します。

Console

  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. Cloud Shell の [その他] メニューから [ファイルをアップロード] を選択し、作成した JSON キーファイルを選択します。ファイルが Cloud Shell インスタンスのホーム ディレクトリにアップロードされます。

  3. アップロードしたファイルが現在のディレクトリにあることを確認し、次のコマンドを実行してファイル名を確認します。

    ls
    

  4. 秘密鍵ファイルを 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 VM を起動するリージョンを指定します。Compute Engine の使用可能なリージョンとゾーンをご覧ください。
      • BUCKET は、前に作成したバケット名に置き換えます。
      • WORK_DIRは、ロギングと出力に使用するフォルダの名前に置き換えます。まだバケットに存在しない新しいディレクトリ名を使用してください。
      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 バケットに保存します。

各タスクと中間ファイルの個別の出力ファイルを確認するには、次の手順を行います。

Console

  1. Cloud Storage Console で、Storage ブラウザページを開きます。

    Cloud Storage ブラウザに移動

  2. BUCKET に移動し、nextflow.config ファイルで指定されている WORK_DIR を参照します。

  3. パイプラインで実行されていたタスクごとにフォルダがあります。

  4. フォルダには、実行されたコマンド、出力ファイル、ワークフロー中に使用された一時ファイルが含まれます。

gcloud

  1. Cloud Shell で出力ファイルを表示するには、まず Cloud Shell を開きます。

    Cloud Shell に移動

  2. 次のコマンドを実行して、Cloud Storage バケットの出力を一覧表示します。 BUCKETWORK_DIRnextflow.config ファイルで指定された変数に更新します。

    gsutil ls gs://BUCKET/WORK_DIR
    
  3. 出力には、実行された各タスクのフォルダが表示されます。後続のサブディレクトリのコンテンツの一覧表示を続行し、パイプラインによって作成されたすべてのファイルを表示します。 前のコマンドで一覧表示されたタスクフォルダの 1 つを TASK_FOLDER に更新します。

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

パイプラインで作成された中間ファイルを表示し、保存するファイルを選択するか、それらを削除して Cloud Storage に関連する費用を削減できます。ファイルを削除するには、Cloud Storage バケット内の中間ファイルの削除をご覧ください。

トラブルシューティング

  • パイプラインの実行中に問題が発生した場合は、Cloud Life Sciences API のトラブルシューティングをご覧ください。

  • パイプラインが失敗した場合は、.command.err.command.log.command.out など、Cloud Storage の各フォルダにあるログファイルを見ることで、各タスクのログを確認できます。

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

Nextflow パイプライン チュートリアルが終了したら、Google Cloud で作成したリソースをクリーンアップして、今後割り当ての消費や課金が発生しないようにします。次のセクションで、リソースを削除または無効にする方法を説明します。

Cloud Storage バケット内の中間ファイルの削除

パイプラインを実行すると、中間ファイルが gs://BUCKET/WORK_DIR に保存されます。ワークフローの完了後にファイルを削除すると、Cloud Storage の料金を削減できます。

ディレクトリで使用されている容量を表示するには、次のコマンドを実行します。

gsutil du -sh gs://BUCKET/WORK_DIR

WORK_DIR からファイルを削除するには、次の手順を行います。

Console

  1. Cloud Storage Console で、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/**
    

プロジェクトの削除

課金をなくす最も簡単な方法は、チュートリアル用に作成したプロジェクトを削除することです。

プロジェクトを削除するには:

  1. Cloud Console で [リソースの管理] ページに移動します。

    [リソースの管理] に移動

  2. プロジェクト リストで、削除するプロジェクトを選択し、[削除] をクリックします。
  3. ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。

次のステップ

次のページでは、Nextflow の使用に関する詳細な背景情報、ドキュメント、サポートを提供しています。