nextflow

Nextflow

概要

Nextflow は、再現性があり、移植可能で、スケーラブルなデータパイプラインを構築するためのワークフロー言語およびランタイムです。バイオインフォマティクス分野で広く使われていますが、データ量の多いあらゆる計算に利用できます。nf-core は、Nextflow 上で本番環境向けの Nextflow パイプライン、再利用可能なモジュール、nf-core ツール群をコミュニティで整備しています。

主な考え方：

• データフロープログラミング：パイプラインは、チャネルで接続された process タスクで構成されます。Nextflow はデータ依存関係から実行順序と並列性を推定するため、明示的なスケジューラーを記述する必要はありません。
• 一度書けば、どこでも実行可能：同じパイプラインを、コードではなく設定／プロファイルを変更することで、ローカル、HPC（SLURM、SGE、LSF、PBS）、クラウド（AWS Batch、Google Batch、Azure Batch、Kubernetes）で実行できます。
• 再現性：タスクごとのコンテナ（Docker/Singularity/Apptainer/Conda/Wave）＋-resume によるキャッシュ＋固定されたパイプラインのリビジョン。
• DSL2 は最新の必須構文です。モジュール化された process／workflow／include 定義を使用します。

このスキルでは、既存のパイプラインの実行と、独自のパイプラインの開発（Nextflow 言語＋nf-core の規約、nf-test によるテスト、設定、デプロイ）の両方を扱います。

このスキルを使う場面

ユーザーが次のことを希望する場合に、このスキルを使います：

• nf-core または独自の Nextflow パイプラインを実行する、または失敗した実行や再開中の実行をデバッグする。
• .nf スクリプト、nextflow.config、プロファイル、nextflow_schema.json を作成または変更する。
• nf-core 形式のモジュール／サブワークフロー（main.nf、meta.yml、tests/、nf-test）を作成またはテストする。
• エグゼキューター、コンテナ、リソースを設定する、または HPC やクラウドへスケールする。
• 再現可能な科学／バイオインフォマティクスのワークフローを構築する（「Nextflow」という名前が出ていない場合も含む）。
• プロセス、チャネル、演算子、take／emit、publishDir、ext.args、メタマップを理解する。

セットアップ

Nextflow には Bash と Java 17 以降（17～25 をサポート）が必要です。java -version で確認してください。

# Install Nextflow (self-contained launcher)
curl -s https://get.nextflow.io | bash      # creates ./nextflow
sudo mv nextflow /usr/local/bin/             # put on PATH
nextflow info                                # verify

# Or via conda/bioconda (also gets a managed Java)
conda create -n nf -c bioconda -c conda-forge nextflow nf-core

# nf-core tools (Python) for creating/linting/running nf-core assets
uv pip install nf-core            # or: conda install -c bioconda nf-core
nf-core --version

再現性のため、エンジンのバージョンを固定してください：export NXF_VER=24.10.0（必要な場合のみ [edge] リリースを使用してください）。エアギャップ環境／HPC については、references/running-pipelines.md（オフラインモード）と references/configuration.md を参照してください。

2 つの作業モード

ユーザーがどちらの作業を行うのか判断してください。選択によってすべてが変わります：

目標	まずはこちら
既存のパイプライン（nf-core または提供された .nf）を実行する	references/running-pipelines.md
新しいパイプライン／モジュール／サブワークフローを開発する	references/language.md + references/developing.md
設定／スケールする（HPC、クラウド、コンテナ、リソース）	references/configuration.md + references/containers.md
モジュール／パイプラインをテストする	references/testing.md

クイックスタート

nf-core パイプラインを実行する

まず、必ず付属の test プロファイルでスモークテストを実施してください。小さなデータを使用するため、環境が正しく動作することを確認できます。

# 1. Confirm setup works (downloads pipeline + tiny test data)
nextflow run nf-core/rnaseq -profile test,docker --outdir results

# 2. Real run: pin a revision (-r), pick a container engine, pass inputs
nextflow run nf-core/rnaseq -r 3.14.0 \
  -profile docker \
  --input samplesheet.csv \
  --genome GRCh38 \
  --outdir results \
  -resume

• -profile（ハイフン 1 つ）は付属の設定プロファイルを選択します。カンマ区切りで組み合わせて指定します（例：test,docker）。コンテナ／インフラのプロファイル（docker、singularity、conda）は相互に排他的です。1 つ選んでください。
• --input、--genome、--outdir（ハイフン 2 つ）はパイプラインのパラメーターです。nf-core パイプラインでは、個別のファイルではなく CSV サンプルシートを指定します。
• -resume は前回の実行結果をキャッシュから再利用します。-r <version> は再現性のためにリリースを固定します。

対話形式でスキーマ検証を行いながらコマンドと -params-file を作成するには、nf-core pipelines launch <name> を使用してください。詳しくは references/running-pipelines.md を参照してください。

最小限のパイプラインを書く

#!/usr/bin/env nextflow

process SAYHELLO {
    tag "$greeting"
    publishDir "results", mode: 'copy'

    input:
    val greeting

    output:
    path "${greeting}.txt"

    script:
    """
    echo '$greeting world' > ${greeting}.txt
    """
}

workflow {
    channel.of('hello', 'bonjour', 'hola') | SAYHELLO
}

nextflow run main.nf            # add -resume on reruns

言語全体（プロセス、チャネル、演算子、take／main／emit を使う DSL2 ワークフロー、モジュール）については、references/language.md を参照してください。

主な概念の概要

• プロセス：スクリプト（デフォルトでは Bash）を実行する作業単位です。input:、output:、省略可能な directives（リソース、コンテナ、publishDir、tag、errorStrategy）、および script:／shell:／exec: ブロックを宣言します。各タスクは、独立した専用の作業ディレクトリ（work/xx/yy…）で実行されます。
• チャネル：プロセスをつなぐ非同期キューです。キューチャネルは消費されるストリームで、バリューチャネルは再利用可能な単一の値を保持します。channel.of、channel.fromPath、channel.fromFilePairs、channel.value などのファクトリーで作成します。
• オペレーター：チャネルを変換・結合します。map、filter、collect、groupTuple、join、combine、mix、flatten、branch、multiMap、splitCsv、view、set があります。
• ワークフロー：プロセスを組み合わせます。DSL2 のワークフローでは、take:（入力）、main:（ロジック）、emit:（名前付き出力）を宣言し、サブワークフローとして include できます。名前のない workflow {} がエントリーポイントです。
• モジュール：include { NAME } from './path' でプロセスやワークフローを公開する .nf ファイルです（as によるエイリアスに対応しています）。
• 設定：nextflow.config では、params、process ディレクティブ、executor、コンテナエンジン、名前付き profiles を設定します。セレクター withName:／withLabel: で特定のプロセスを指定できます。references/configuration.md を参照してください。
• meta map（nf-core）：入力／出力タプル内のファイルとともにメタデータマップ（[ id:'sample1', single_end:false ]）を引き回す規約です。これにより、パイプライン全体でサンプルのラベルを維持します。references/developing.md を参照してください。

nf-core tools CLI

nf-core tools（v3 以降）では、サブコマンドが pipelines、modules、subworkflows の下にまとめられています。（nf-core lint のような単独形式も引き続き動作しますが、警告が表示されるため、グループ形式の使用を推奨します。）

コマンド	目的
nf-core pipelines list	nf-core パイプラインを一覧表示／検索します（--json、キーワード）
nf-core pipelines create	nf-core テンプレートから新しいパイプラインのひな形を作成します
nf-core pipelines launch <name>	スキーマに基づく対話形式の実行コマンドと params ファイルを生成します
nf-core pipelines download <name>	オフライン／HPC での利用に向けて、パイプラインとコンテナをダウンロードします
nf-core pipelines lint	nf-core 標準に照らしてパイプラインをリントします（リポジトリのルートで実行）
nf-core pipelines schema build	Web GUI で nextflow_schema.json を作成／編集します
nf-core pipelines create-params-file <name>	説明付きの YAML params ファイルを生成します
nf-core pipelines bump-version / sync	バージョンを更新／テンプレートの更新と同期します
nf-core modules list/info/install/update/remove	nf-core/modules のモジュールを管理します
nf-core modules create / lint / test	モジュールを作成、リントし、nf-test を実行します
nf-core modules patch / bump-versions	インストール済みモジュールにパッチを適用／ツールのバージョンを更新します
nf-core subworkflows install/create/lint/test	サブワークフローの同様のライフサイクルを管理します

コマンド、フラグ、使用例の完全なリファレンス：references/nf-core-tools.md。

必須の nextflow CLI

コマンド	目的
nextflow run <pipeline> -profile <p> --outdir <dir>	パイプラインを実行します（パス、.nf、または user/repo）
-resume	前回の実行結果をキャッシュから再利用します
-r <rev>	特定の git リビジョン／タグ／ブランチを実行します
-params-file params.yml	YAML／JSON からパラメーターを指定します
-c custom.config	追加の設定ファイルを適用します
-with-report -with-trace -with-timeline -with-dag flow.html	実行レポート、トレース、タイムライン、DAG を出力します
-stub-run	stub: ブロックのみを実行します（ドライラン用の配線確認）
nextflow log	過去の実行を確認します
nextflow clean -f -before <run>	古い work/ データを削除します
nextflow pull / drop / list / info <repo>	キャッシュされたリモートパイプラインを管理します

設定、エグゼキューター、キャッシュの内部動作、トレースの詳細：references/configuration.md。

ベストプラクティス（効果の高い習慣）

• 必ず最初に test でテストする：実データを扱う前に -profile test,docker（または singularity／conda）を指定します。高速に実行でき、環境の問題も検出できます。
• すべてのバージョンを固定する：パイプラインのリビジョン（-r）、NXF_VER、ツールのバージョン（コンテナ）を固定します。公開する科学研究で latest を実行してはいけません。
• -resume を使用し、キャッシュの仕組みを理解する：入力、スクリプト、コンテナが変更されるとタスクは再実行されます。references/configuration.md のキャッシュのデバッグに関する説明を参照してください。
• ハードコードしたパスではなく、設定／params-file でパラメーター化する：params とプロファイルは nextflow.config に記述します。
• プロセスごとにコンテナまたは Conda 環境を1つ使用する：ホストにインストールされたツールに依存してはいけません。
• nf-core の開発では：新しいモジュールを作成する前に既存のモジュール（nf-core modules install）を再利用します。ツールのフラグはハードコードせず、ext.args を通じて渡します。必ず stub: ブロックと nf-test のテストを含めます。コミット前に nf-core pipelines lint と prettier を実行します。
• リソースを適切な規模に調整する：process_low/medium/high ラベルと、task.attempt に応じて動的にスケールする errorStrategy 'retry' を使用し、巨大なリソース要求を1つ指定するのは避けます。
• 将来との互換性を考慮した構文を書く：Nextflow 26.04 では厳格構文パーサーがデフォルトになります。小文字の channel.of(...)、明示的なクロージャーパラメーター（{ v -> ... }）、すべての変数での def、emit: で名前を付けた出力を優先します。nextflow lint で確認してください。

リファレンスファイル

詳しい情報が必要な場合は、該当するファイルを読んでください。それぞれ単独で参照できます。

• references/language.md — DSL2 言語：プロセス、ディレクティブ、チャネル、演算子、ワークフロー（take／emit）、モジュール、動的リソース、エラー処理。
• references/configuration.md — nextflow.config、スコープ、profiles、withName／withLabel セレクター、エグゼキューター（local／SLURM／クラウド）、キャッシュ／-resume の内部動作、トレース／レポート、nextflow CLI。
• references/containers.md — Docker、Singularity／Apptainer、Podman、Conda、Wave コンテナ。エンジンの選択と有効化、よくある注意点。
• references/running-pipelines.md — nf-core パイプラインの検索と実行、サンプルシート、params ファイル、参照ゲノム（iGenomes）、オフライン実行、組織内設定、Seqera Platform。
• references/nf-core-tools.md — nf-core CLI の完全なリファレンス（パイプライン／モジュール／サブワークフロー）、フラグ、ワークフロー。
• references/developing.md — nf-core パイプラインとモジュールの作成：テンプレートの構成、モジュールの main.nf／meta.yml、メタマップ、ext.args／modules.config、サブワークフロー、リソースラベル、リンティング、Harshil のスタイルへの準拠。
• references/testing.md — モジュール／サブワークフロー／パイプライン向け nf-test：テスト構造、アサーション、スナップショット、タグ、テストの実行、CI。

公式ドキュメント：Nextflow https://www.nextflow.io/docs/latest/ · nf-core https://nf-co.re/docs/ · トレーニング https://training.nextflow.io/

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を特定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値を推測せず、ユーザーに尋ねてください。
3. まず小規模に実行します。 パイプラインを小さなサブセット（1サンプル、1染色体、数千個の細胞）で実行します。
4. 上記の手順と参照情報を使って、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC指標、サンプルの識別情報、ゲノムビルドの整合性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の不確実性を明記します。

発生したこと	対応方法
入力間でゲノムビルドまたは識別子が一致しない	中断し、続行する前に調整します（liftover、IDマッピング）。
インストール済みのバージョンに、この手順に記載された関数、フラグ、またはエンドポイントがない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜対応してユーザーに伝えます。APIを捏造してはいけません。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに尋ねるか、実行前に仮定を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えます。
• 統計的な裏付けを超えて生物学的意義を解釈してはいけません。多重検定補正について報告します。
• ここに記載されたバージョン固有の情報は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する、共有GPUまたはクラウドのクォータを消費する、個人データまたは患者データに触れる、あるいは取り消せない操作を行う前に、ユーザーに確認します。

関連スキル

• pacsomatic：BAM入力を使用した、nf-core/pacsomaticの腫瘍・正常ペアワークフロー向けオペレーターツールキットです。
• bulk-rnaseq：バルクRNA-seqのエンドツーエンドオーケストレーターです。未処理のFASTQリードから、QCとトリミング（FastQC、fastp/Trim Galore）、アライメント、定量化まで処理します…
• latchbio-integration：Python SDK、CLI、Latch DataとRegistry、Nextflow、Snakemaを使用して、Latch上のバイオインフォマティクスワークフローを構築、登録、デバッグ、運用します…