create-workflow

Nextflow ワークフローライター

Nextflow Registry の検証済みモジュールを組み合わせて、完全な Nextflow ワークフローを作成します。

モジュールは名前空間（例：nf-core/fastqc）の下で公開されており、これらのスキルでは任意の名前空間のモジュールを組み合わせます。

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

Registry のモジュールには 2 種類あります（nextflow module view では Kind: として表示されます）。

• プロセスモジュール — 1 つのツール。例：nf-core/star/align
• ワークフローモジュール — 複数のモジュールを連結する再利用可能なサブワークフロー。例：nf-core/fastq_align_star（STAR アライメント + samtools sort/index/stats）

単一モジュールを実行／テストするだけのために、ラッパーワークフローを絶対に作成しないでください。

❌ 誤り - 1 つのモジュールを実行するワークフローを作成する：

// DO NOT DO THIS - not even when a module run fails!
include { FASTQC } from 'nf-core/fastqc'
workflow { FASTQC(Channel.fromPath('data/*.fq.gz')) }

✅ 正しい - run-module スキルを使用する：

Skill(skill="run-module")

run-module スキル：

• nextflow module search/view を使用して、適切な入力やパラメーターを検索・取得します
• nextflow module run <namespace>/<module> でモジュールを直接実行します
• ラッパーワークフローは不要です

⚠️ 引数が不足してモジュールの実行に失敗した場合：

• 修正方法としてラッパーワークフローを作成しないでください
• 代わりに nextflow module view <module> を実行して、正しいパラメーターを確認してください
• コマンドライン引数を修正して、直接再実行してください

複数の検証済みモジュールを組み合わせる場合に限り、ステップ 4 でワークフローを作成してください。

ワークフロー作成の 4 ステップ

新しいワークフローを作成する際は、必ず次の手順に従ってください。

ステップ 1：モジュールを特定し、計画を提案する

1. 各処理ステップに対応する Registry モジュールを nextflow module search <term> で検索します
2. 一連のステップをすでにカバーしているワークフローモジュールを探します。 nextflow module search では上位に表示されることが少ないため、kind=Workflow フィルターを指定して Registry 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"]]'
   

   計画内の一連のステップに合致するワークフローモジュールがある場合、同じプロセスモジュールを手動で接続する代わりに、そのワークフローモジュールを使用します。
3. nextflow module view <name> を使用して各モジュールの入力／出力を確認します（ワークフローモジュールの場合は、呼び出し順の take: 入力と emit: 出力を確認します）
4. ユーザーに計画を提示し、次の内容を含めます：
   • 特定したモジュールの一覧。それぞれがプロセスモジュールかワークフローモジュールかを明記します
   • 処理の順序（どのモジュールを最初に、次に実行するかなど）
   • モジュール間のデータフロー（出力 → 入力）

ここで停止し、ユーザーの承認を待ってください。

ステップ 2：ユーザーの承認

• ユーザーが提案した計画を確認して承認するまで待ちます
• 質問や変更の要望に対応します
• ユーザーが明示的に同意してから先に進みます

ステップ 3：モジュールを 1 つずつ検証する（必須）

このステップを絶対に省略しないでください。 ユーザーの承認後：

1. 検証に適したテストデータを決定します
2. 計画内の各モジュールについて、順番に次を実施します：
   • インストールしてテストデータで実行する：Skill(skill="run-module") を呼び出します
   • 出力を検証する — 期待されるデータが生成されたことを確認します
   • 現在のモジュールが成功してから、次のモジュールに進みます
   • 型指定されていないワークフローモジュール（nf-core の大半）は、nextflow module run で「型指定されていないため直接実行できない」というエラーになります。これは想定どおりであり、修正すべき失敗ではありません。そのモジュール用のラッパーワークフローを作成せず、ユーザーへの確認も求めないでください。検証ログに「ステップ 4 で検証」と記録して、次に進みます。ステップ 4 のエンドツーエンド実行で検証されます。
3. すべてのモジュール実行コマンドとその出力を、.modules-validation- というプレフィックスを付けたデバッグファイルに記録します
4. コマンドが失敗した場合は、別の方法を試す前に停止し、使用したコマンドと生成された出力をユーザーに提示します

注：run-module スキルは検出、設定、実行に nextflow module コマンドを使用します。モジュールはその場でインストールされます。

すべてのモジュールを個別に検証するまで、ステップ 4 に進まないでください。

Step 4: 最終ワークフローを構成する

すべてのモジュールが正常に実行された後に限り、次の手順を実行します。

1. Wave と Conda を使用して nextflow.config を設定します。

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

2. 検証済みのすべてのステップを組み合わせたワークフロースクリプトを、Nextflow 管理モジュールを使用して記述します（./ プレフィックスは付けません。Nextflow が Nextflow Registry から自動的にダウンロードしてインストールします）。

   include { MODULE_A } from 'nf-core/module_a'
   include { MODULE_B } from 'nf-core/module_b'
   
   workflow {
       MODULE_A(input_ch)
       MODULE_B(MODULE_A.out.results)
   }
   

   ワークフローモジュールでは同じ include 構文（include { FASTQ_ALIGN_STAR } from 'nf-core/fastq_align_star'）を使用し、nextflow module view に記載されている take: の順序に従い、位置引数で呼び出します。型指定のないワークフローモジュールでは、nextflow module view にある入力の説明はおおよそのものです。インストール済みの modules/<namespace>/<name>/main.nf を読み、各入力がどのプロセスに渡されるかを確認して、そのプロセスが想定するチャネルの形式（例：[meta, index] のタプル）を作成します。初回実行時、Nextflow は各モジュールを依存関係とともに、ネストされた modules/ ディレクトリ内の modules/<namespace>/<name>/ にインストールします。パイプラインとともに modules/ ディレクトリをコミットしてください。

3. 同じテストデータを使ってワークフロー全体を実行し、エンドツーエンドで検証します。これは、Step 3 でスキップした型指定のないワークフローモジュールを検証する手順です。

重要なガイドライン

コマンドの実行

• 適切な場合は -resume フラグを使用して、キャッシュ済みの結果を活用します
• 相対パスではなく、絶対パスを使用します

ファイルの取り扱い

• 複数のファイルを指定する場合は、カンマで区切り、二重引用符で囲みます：--input "file1.fq,file2.fq"
• 実行前に、ワイルドカードやグロブは必ずカンマ区切りのファイルリストに展開します
• stdout に出力されるタスク ID を参照して、作業ディレクトリ内の出力ファイルを探します

モジュールの include 構文

• include { MOD } from 'nf-core/module' — Nextflow 管理モジュール（デフォルト）。Nextflow が Nextflow Registry から自動的にダウンロードしてインストールします。常にこの形式を優先してください。（ここでの nf-core は名前空間です。使用するモジュールの実際の名前空間に置き換えてください。）
• include { MOD } from './modules/nf-core/module/main.nf' — ローカルファイルパス。作業ディレクトリを基準に解決されます。ローカルで変更したモジュールを参照する場合にのみ使用してください。

モジュールの選択

• 既存のワークフローモジュールが、すでに連携しているプロセスモジュールを個別に配線するよりも優先してください
• ワークフローモジュールはレジストリ API の kind=Workflow フィルターを使って探します（Step 1 を参照）。nextflow module search ではほとんど見つかりません
• 単一モジュールのテストにラッパーワークフローを作成しないでください。代わりに Skill(skill="run-module") を使用します
• nextflow module search でモジュールを探し、nextflow module view で詳細を確認します

デバッグ手順

1. stdout のタスク ID を使って、タスクの作業ディレクトリを確認します
2. .command.log、.command.err、.command.out ファイルを調べます
3. 入力ファイルが存在し、アクセス可能であることを確認します
4. リソース要件（メモリ、CPU）が利用可能なリソースと一致していることを確認します

スキルへの委譲（重要）

モジュール固有のタスクは、Skill ツールを使って専門スキルに委譲してください。

タスク	呼び出すスキル
モジュールのインストール／実行／テスト	Skill(skill="run-module")

委譲するタイミング

• Step 3（モジュールの検証）：各モジュールの検証には run-module スキルを使用します

例：Step 3 の検証

計画に含まれる各モジュールについて：

1. Invoke: Skill(skill="run-module") → install, run with test data, and verify outputs
2. Only proceed to next module after success

これらのスキルには、それぞれのタスクに関する詳しい手順が含まれており、一貫した実行パターンを確保できます。

クイックリファレンス

Step 1: Identify process + workflow modules → Propose plan to user
Step 2: Wait for user agreement
Step 3: Validate ALL modules ONE BY ONE with test data (untyped workflow modules: defer to Step 4)
Step 4: Compose final workflow (only after Step 3 succeeds)