run-module

Nextflow モジュールを実行する

Nextflow Registry のモジュールを、nextflow module コマンドを使ってネイティブに実行します。すべてが自己完結しており、外部ツールや MCP は必要ありません。モジュールは実行時にオンザフライでインストールされます。

モジュールは名前空間（例：nf-core/fastqc）の下で公開されており、nextflow module コマンドはどの名前空間でも使用できます。

Nextflow 26.04 以降が必要です（nextflow module コマンドを使用するため）。ワークフローモジュールには Nextflow 26.10 以降が必要です。

プロセスモジュールとワークフローモジュール

モジュールには 種類 があり、nextflow module search と nextflow module view では Kind: として表示されます。

種類	内容	例
Process	1 つのツールをラップする単一のプロセス	nf-core/star/align
Workflow	複数のモジュールを連結する名前付きワークフロー（サブワークフロー）。依存関係も一緒にインストールされます	nf-core/fastq_align_star（STAR + samtools sort/index/stats）

どちらの種類も、同じ方法で検索、表示、実行、インクルードできます。違いについては、ワークフローモジュールを見つけるとワークフローモジュールを実行するで説明します。

⛔ ラッパーワークフローを絶対に作成しないでください

引数の不足やパラメーターの誤りが原因でモジュールが失敗した場合：

❌ 誤り - ラッパーワークフローを作成する：

// NEVER DO THIS - even if the module fails!
include { FASTQC } from 'nf-core/fastqc'
workflow { FASTQC(Channel.fromPath('*.fq.gz')) }

✅ 正しい - nextflow module view を使用して正しいパラメーターを確認する：

nextflow module view nf-core/fastqc

モジュールの実行に失敗した場合：

1. nextflow module view <module> を実行してコマンドテンプレートを取得します
2. テンプレートに基づいて引数を修正します
3. nextflow module run <module> ... で再実行します

引数不足を「修正」するために、ラッパーワークフローを絶対に作成しないでください。

ステップ 1：モジュールを検索する

自然言語の用語を指定して nextflow module search を使用します。モジュール名、説明、機能に基づいて類似検索を行います。

nextflow module search "quality control"
nextflow module search "alignment"
nextflow module search "variant calling"
nextflow module search "BAM statistics"

ワークフローモジュールを見つける

nextflow module search ではワークフローモジュールの順位がプロセスモジュールより低いため、検索結果に表示されることはほとんどありません。タスクが複数のステップにまたがる場合（例：「STAR でアラインメントしてから、ソートしてインデックスを作成」）、kind=Workflow フィルターを使ってレジストリー API も検索してください。

curl -s "https://registry.nextflow.io/api/v1/modules?query=align%20reads%20STAR&kind=Workflow&limit=10" \
  | python3 -c 'import json,sys; [print(r["name"], "-", r["description"]) for r in json.load(sys.stdin)["results"]]'

query 内の空白は %20 として URL エンコードしてください。その後、一致したモジュールを nextflow module view で確認します。

ステップ 2：モジュール情報と実行テンプレートを取得する

モジュールを特定したら、詳細情報とコマンドテンプレートを取得します。

nextflow module view nf-core/fastqc

モジュールの種類、説明、入力、パラメーター、正確な実行コマンドテンプレートが返されます。このテンプレートを実行コマンドの基礎として使用してください。

ワークフローモジュールの場合、入力はワークフローの take: 宣言（呼び出し順）で、出力は emit: 宣言です。

ステップ 3：テンプレートの値を置き換えて実行する

テンプレート内のプレースホルダーをユーザーが指定した具体的な値（ファイルパス、パラメーター）に置き換えてから実行します。明示的なインストールは不要です。モジュールはオンザフライで取得されます。

nextflow module run nf-core/fastqc \
  --input "/path/to/sample.fq.gz" \
  --outdir results

Wave + Conda によるコンテナーのプロビジョニング

モジュールの実行には、基盤となるツールのコンテナーが必要です。nextflow.config を設定して Wave + Conda を使用すると、各モジュールの Conda パッケージからコンテナーがオンザフライでプロビジョニングされます。

wave.enabled = true
wave.strategy = 'conda,container'
docker.enabled = true

これにより、コンテナーイメージを手動でビルドまたはプルする必要がなくなります。Wave がモジュールに宣言された Conda 依存関係からコンテナーをプロビジョニングします。

ワークフローモジュールの実行

ワークフローモジュールは、同じ nextflow module run コマンドで実行しますが、次の違いがあります。

• 型付きである必要があります。 型付きの take: 入力を持つワークフローモジュールのみ、直接実行できます。ほとんどの nf-core ワークフローモジュールは型なしのため、次のエラーが発生します。

  Workflow `FASTQ_ALIGN_STAR` cannot be executed directly because it is not typed
  

  nextflow module view は型なしのワークフローモジュールについても使用テンプレートを出力するため、このエラーが見分ける手掛かりになります。実行に失敗していても、モジュールとその依存関係はすでに ./modules/ にインストールされています。これは引数の不足の問題ではなく、ラッパーワークフローを書く理由にもなりません。create-workflow のステップ 3 から呼び出された場合は、そのスキルの指示に従ってください（ステップ 4 に進みます）。それ以外の場合は、ワークフローモジュール単体では実行できないことをユーザーに伝えて停止し、次の選択肢を提示してください。
  • 構成プロセスモジュールを nextflow module run でひとつずつ実行する方法です。これらは ./modules/<namespace>/<name>/meta.yml の requires.modules に記載されています。リストにあるワークフローモジュールを展開する場合は、そのモジュール内の meta.yml を確認してください。または、
  • create-workflow スキルを使って、パイプライン内で実行する方法です。
• チャネル入力にはサンプルシートを使用します。 Channel<...> 入力は、CSV、JSON、または YAML 形式のサンプルシートのパスを受け取り、各行がチャネル項目になります。Value<...> 入力は単一の値（例：ファイルパス）を受け取ります。
• 出力は公開されません。 出力される各項目について、その作業ディレクトリのパスが報告されます。--outdir には何もコピーされません。

コマンドリファレンス

コマンド	説明
nextflow module search <term>	名前、説明、機能に基づく類似検索
nextflow module view <name>	モジュールの詳細情報と実行方法
nextflow module run <name> [options]	モジュールを実行（その場でインストール）
nextflow module list	インストール済みモジュールをバージョンと種類とともに一覧表示

例

シングルエンド FASTQ の品質管理

# 1. Search
nextflow module search "quality control"

# 2. Get the template
nextflow module view nf-core/fastqc

# 3. Run with concrete values
nextflow module run nf-core/fastqc \
  --input "data/sample.fq.gz" \
  --outdir results_fastqc

ペアエンドアライメント

# 1. Search
nextflow module search "bwa alignment"

# 2. Get the template
nextflow module view nf-core/bwa/mem

# 3. Run with concrete values
nextflow module run nf-core/bwa/mem \
  --input "data/reads_1.fq.gz,data/reads_2.fq.gz" \
  --reference "data/genome.fa" \
  --outdir results_bwa

ワークフロー全体：検索 → 情報確認 → 実行

1. モジュールを検索します。

   nextflow module search "quality control for FASTQ"
   

2. 情報と実行テンプレートを取得します。

   nextflow module view nf-core/fastqc
   

3. テンプレートのプレースホルダーを、ユーザーのデータに基づく実際の値に置き換えます。

4. モジュールを実行します。

   nextflow module run nf-core/fastqc \
     --input "data/sample.fq.gz" \
     --outdir results
   

5. 出力を処理します。標準出力を読み取り、主な結果を要約して、次に行うべきことをユーザーに提案します。

重要なルール

1. 最初に検索する — 適切なモジュールを見つけるには、必ず nextflow module search を使用します。
2. テンプレートを取得する — モジュールの実行前に、必ず nextflow module view を実行します。
3. テンプレートの値を置き換える — すべてのプレースホルダーを、ユーザーのデータに基づく具体的な値に置き換えます。
4. ラッパーワークフローを書かない — 実行に失敗した場合は、nextflow module view を使って正しい引数を確認します。
5. パラメーターを推測しない — 必ず情報テンプレートから取得します。
6. 最初にワイルドカードを展開する — ls data/*.fq を実行し、結果をカンマ区切りにします。
7. 複数ファイルの入力は引用符で囲む — --input "file1,file2,file3"
8. 可能な場合は絶対パスを使用する
9. 標準出力の結果を必ず処理する — 実行に成功したら、概要を示し、次に行うべきことを提案します。
10. 種類を確認する — nextflow module view は Kind: Process または Kind: Workflow を報告します。複数のステップがあるタスクでは、レジストリ API の kind=Workflow フィルターを使ってワークフローモジュールも探します。
11. 型なしのワークフローモジュールは直接実行できません — 「型付けされていないため直接実行できません」というエラーが出た場合は停止し、ワークフローモジュールの実行 にある代替案を提示します。ラッパーワークフローは決して書かないでください。

モジュールの実行に失敗した場合

ラッパーワークフローを書かないでください。 代わりに、次の手順に従います。

1. nextflow module view nf-core/<module> を実行します。
2. テンプレートとコマンドを比較し、相違点を確認します。
3. 正しい引数で nextflow module run コマンドを修正します。
4. 修正したコマンドを再実行します。

ステップ 4：実行結果を処理する（必須）

nextflow module run コマンドは、出力を標準出力に表示します。モジュールの実行後、必ず次のことを行ってください。

1. 実行コマンドの標準出力を確認する
2. 結果をユーザーに明確に要約して提示する — 重要な指標、ステータス、警告やエラーを強調してください
3. 次のステップを推測する — 出力と実行したモジュールに基づいて、ユーザーが次に行いたいことを提案してください。例：
   • fastqc の後：「品質スコアは良好です。bwa/mem でアライメントに進みますか？」
   • bwa/mem の後：「アライメントが完了しました。samtools/sort で BAM をソートするか、samtools/stats で統計を取得しますか？」
   • fastp の後：「トリミングが完了しました。トリミング済みリードをアライメントしますか？」

次のステップの提案は、必ずユーザーへの質問として提示してください。

モジュールまたはユーザーから特に求められた場合を除き、ワークディレクトリ内の出力ファイルを一覧表示したり調べたりしないでください。これはデフォルトで行わないでください。