galaxy-workflow-development

Galaxy ワークフロー開発エキスパート

Intergalactic Workflow Commission（IWC）の標準に基づく、Galaxy ワークフローの開発、テスト、ベストプラクティスのエキスパートです。

主な知識

Galaxy ワークフロー形式（.ga ファイル）

Galaxy ワークフローは、.ga 拡張子を持つ JSON ファイルで、次の内容を含みます。

必須のトップレベルメタデータ

{
    "a_galaxy_workflow": "true",
    "annotation": "Detailed description of workflow purpose and functionality",
    "creator": [
        {
            "class": "Person",
            "identifier": "https://orcid.org/0000-0002-xxxx-xxxx",
            "name": "Author Name"
        },
        {
            "class": "Organization",
            "name": "IWC",
            "url": "https://github.com/galaxyproject/iwc"
        }
    ],
    "format-version": "0.1",
    "license": "MIT",
    "release": "0.1.1",
    "name": "Human-Readable Workflow Name",
    "tags": ["domain-tag", "method-tag"],
    "uuid": "unique-identifier",
    "version": 1
}

ワークフローステップの構造

ステップには連番が付けられ、次の項目を定義します。

1. 入力データセット

   • type: "data_input" - 単一ファイルの入力
   • type: "data_collection_input" - ファイルのコレクション
   • 説明的な annotation と label が必要です

2. 入力パラメーター

   • type: "parameter_input"
   • タイプ：text、boolean、integer、float、color
   • ユーザーが設定できる項目に使用します

3. ツールステップ

   • type: "tool"
   • tool_id と content_id は Galaxy ToolShed を参照します
   • tool_shed_repository には owner、name、changeset_revision を含めます
   • input_connections は前のステップの出力に接続します
   • tool_state にはパラメーター値を含めます（JSON エンコード済み）

4. ワークフロー出力

   • workflow_outputs 配列で指定します
   • 各出力には label（人が読める名前）を設定します
   • hide: true を指定すると、中間出力を非表示にできます

高度な機能

• コメント：ドキュメント用の type: "text" ステップ
• フレーム：色分けされたボックスによる視覚的なグループ化
• レポート：Galaxy レポート構文を使用した、埋め込み Markdown テンプレート
• ジョブ後アクション：出力の名前変更、タグ付け、非表示
• 条件付き実行：条件付きステップ用の when フィールド
• パラメーターツール：compose_text_param、map_param_value、pick_value、param_value_from_file

条件ロジックの制限事項

Galaxy のパラメーターツールには、比較機能に制限があります。

• Map parameter value：ルックアップテーブルを使って、離散値を別の値にマッピングします。範囲比較（例：「X より大きい場合」）はできません。
• Calculate numeric parameter value：算術式を評価しますが、出力は数値であり、when 条件に使う Galaxy のブール値ではありません。
• 数値の比較（例：「ゲノムサイズは 10Gb より大きいか？」）には、パラメーターファイルに対して awk ステップを使用します：awk '{if ($1 >= 10000000000) print "true"; else print "false"}'。その後、テキスト出力を map_param_value または pick_value に渡して、条件分岐を制御します。
• 空／空でない値をブール値として扱う：空のマッピングと unmapped: {"on_unmapped": "input"} を設定した map_param_value ステップは、入力値をそのまま渡します。output_param_type: boolean の場合、結果は空文字列なら False、空でない値なら True となります。明示的なマッピングを記述せずに、任意のフィルターパラメーターに対する when ゲートとして使用できます。

主なルール

命名規則（厳守）

• フォルダー／ファイル名：小文字のみ、ハイフンのみを使用（アンダースコアや空白は使用しない）
• ワークフロー名（.ga 内）：人が読める名前にし、空白や大文字を使用できます
• 入力／出力ラベル：人が読める説明的な名前にし、技術的な略語は使用しません
• 複合形容詞：単数形を使用します（例：「short-reads sequencing」ではなく「short-read sequencing」）

ワークフロー設計の原則

1. 汎用ワークフロー：サンプル名をハードコードせず、ユーザーが設定できる値にはパラメーター入力を使用します
2. 明確な命名：説明的なラベルを付け、注釈で想定される形式を説明します
3. 充実した注釈：ワークフロー、ステップ、パラメーターに詳細な注釈を付けます
4. 完全なメタデータ：ORCID を含む作成者情報、IWC 組織、MIT ライセンス、セマンティックバージョニングを含めます
5. 固定されたツールバージョン：正確なバージョンと changeset_revision を指定し、CHANGELOG に記載します

テストの必須事項

• テストファイルの命名：workflow-name.ga -> workflow-name-tests.yml
• ワークフローごとに最低 1 件のテストケースを用意します
• 100 KB 未満のファイルは test-data/ に配置し、100 KB 以上のファイルは SHA-1 ハッシュとともに Zenodo に配置します
• 可能な限り厳密なアサーションを使用し、完全なファイル比較を優先します
• .ga ファイルには必ず workflow_lint を使用します（ツール XML 用の lint は使用しません）

Planemo コマンド（クイックリファレンス）

# Lint workflow — argument is the workflow DIRECTORY (planemo walks it for .ga files)
# NOT the .ga filename. Passing a file fails with "ValueError: Directory not found".
planemo workflow_lint --iwc .

# Test on live instance (PREFERRED)
planemo test --fail_fast \
  --galaxy_url https://usegalaxy.org \
  --galaxy_user_key "$API_KEY" \
  workflow.ga

# Test locally (slower, use only when needed)
planemo test workflow.ga

# Re-test against an existing successful invocation (FAST — seconds, not minutes)
# Use this whenever ONLY the test YAML was edited and the workflow itself
# already ran successfully. Skip the full planemo test re-run.
planemo workflow_test_on_invocation \
  --galaxy_url https://usegalaxy.org \
  --galaxy_user_key "$API_KEY" \
  --test_index 1 \
  workflow-tests.yml <INVOCATION_ID>

重要：ローカルの Galaxy よりも、稼働中の Galaxy インスタンスでのテストを常に優先してください。

注：-v／--verbose は planemo レベルのフラグであり、サブコマンドの前に指定する必要があります。planemo -v test ... のように指定してください。planemo test -v ... と指定すると、「Invalid value for 'TOOL_PATH'」というエラーが発生します。

判断基準 — 使用する planemo コマンド：

• ワークフローのロジック（.ga）を変更した場合 → planemo test（全体を再実行。10～30 分以上）
• tests YAML のアサーションのみを変更し、最近の実行が成功している場合 → planemo workflow_test_on_invocation <invocation_id>（キャッシュされた実行出力を使って tests YAML を数秒で再検証し、再計算は行いません）

前回の planemo test の出力から実行 ID を抽出します。最上位の実行パネル（サブワークフローのネストされたパネルではなく、外側のパネル）の進行状況バーにある Invocation <ID> を探してください。MCP を使った失敗のデバッグを含む workflow_test_on_invocation の詳しい使用方法については、testing-guide.md を参照してください。

よくある問題（クイックリファレンス）

問題	解決策
テストで「output not found」と表示される	出力ラベルが完全に一致しているか確認します（大文字と小文字を区別します）
リポジトリ内のテストファイルが大きい	Zenodo にアップロードし、ハッシュ付きの URL で参照します
ワークフローに汎用性がない	ハードコードされた値をパラメーター入力に置き換えます
ツールの更新でワークフローが壊れる	changeset_revision で正確なバージョンを固定します
ローカルではテストに通るが、CI では失敗する	CVMFS で参照データを利用できるか確認します
再エクスポートした .ga で release／annotation／tags が失われる	Galaxy の「Download workflow」は最上位の annotation、release、tags を消去し、ORCID 識別子を短縮する場合もあります。再エクスポートのたびに IWC メタデータを再適用してください。コミット前にメタデータを再設定するスクリプトの作成も検討してください。
Planemo test で古いエラーメッセージが返り続ける	Galaxy に古いワークフローが保存されています。再実行する前に DELETE /api/workflows/<id> で削除してください。詳しくは testing-guide.md の「Troubleshooting」を参照してください。
Lint 警告が出る	planemo workflow_lint --iwc . を実行し、各警告に対処します
workflow_lint で Directory not found と表示される	.ga ファイル名ではなく、ワークフローのディレクトリ（.）を渡してください。lint コマンドには、ワークフローファイルを検索するパスを指定します
planemo-autoupdate ブランチにプッシュできない	GitHub の Web UI で編集するか、自分のフォークにプッシュします
ツールのバージョンを戻しても効果がない	Galaxy の設定で use_cached_job を無効にします

バージョンの更新

ワークフローを更新する場合：

1. .ga ファイルの release フィールドを更新します
2. CHANGELOG.md にエントリーを追加します
3. 必要に応じてテストを更新します
4. 内容がわかるコミットメッセージでコミットします

デプロイパイプライン

PR のマージ後：テスト成功 -> RO-Crate メタデータを生成 -> iwc-workflows にデプロイ -> Dockstore に登録 -> WorkflowHub に登録 -> usegalaxy.* サーバーで使用時に自動インストール

---

エクスポートワークフローの構築

主なルール

1. ワークフローの出力ラベルでは変数の展開を使用できません — ${Species Name} が機能するのは RenameDatasetAction のみで、workflow_outputs[].label では使えません。出力ラベルには静的テキストを使用してください。

2. 任意のデータセット入力には pick_value の中継ステップが必要です — 任意の入力を export_remote などの任意ではないツール入力に直接接続することはできません。フォールバックデータセットを指定した pick_value ステップ（pick_style: first）を経由させ、export ステップに when: $(inputs.when) を指定して実行を制御してください。

3. 入力ボックスの配置でフォームの順序が決まります — Galaxy は入力を左上から右下へ表示します。手動操作が必要な入力（テキストパラメーター、ブール値、任意のデータセット）は左上に配置し、フォームの最初に表示されるようにしてください。タグで絞り込まれた自動入力の項目は、設定漏れを減らせるよう、さらに右下に配置します。

エクスポートワークフロー構造パターン

一般的な VGP エクスポートワークフローは、次の構造に従います。

• パラメーター入力：種名、アセンブリ ID、日付、出力先（directory_uri）
• ブール値入力：条件フラグ（例：「アノテーションをアップロードしますか？」「ファイルを圧縮しますか？」）
• データ入力：上流ワークフローのタグ付きデータセット（自動入力）
• パス作成サブワークフロー：ベースパス（root、tracks/、pretextmap/、alignments/、evaluation/）を作成します
• テキストパラメーターの構成ステップ：サブディレクトリ + Assembly ID + infix + Date + extension から完全なファイルパスを作成します
• 圧縮ステップ（条件付き）：pick_value を介したオプションの fasta 圧縮
• リモートエクスポートステップ：カテゴリ別（メインファイル、評価、条件付きアノテーション）にグループ化されます

---

参考資料

詳細なガイダンスは、このディレクトリ内の次のファイルに分かれています。

• iwc-standards.md - IWC リポジトリの構造、必須ファイル（.dockstore.yml、README、CHANGELOG）、ワークフローのカテゴリ、レビューチェックリスト、IWC 提出の準備（リリース番号、実行時パラメーターの整理）
• testing-guide.md - テストに関する完全なリファレンス：テストファイルの構造、アサーションの種類と構文、Planemo の lint エラー、リモートテスト、テストデータの整理、合成データの生成、ツールの失敗に関するトラブルシューティング、アサーションの調整
• workflow-patterns.md - 一般的なワークフローパターン、.ga ファイルでのツールバージョンの移行、バージョンの確認に使用する ToolShed API、ツール更新の検証、論文の方法セクションの執筆
• galaxy-workflow-viz/ - ドキュメント、README、ランディングページ向けに、Galaxy ブランドの SVG ワークフロー図（ベジェ曲線の接続、ノードカード、終端の配置）を生成します。スタイルの参考資料については、galaxy-workflow-viz/SKILL.md と galaxy-workflow-viz/examples/ を参照してください。

---

関連スキル

• galaxy-tool-wrapping - ワークフローで使用できる Galaxy ツールの作成
• galaxy-automation - ワークフローテストのための BioBlend と Planemo の基礎
• conda-recipe - ワークフローのツール依存関係向け conda パッケージのビルド

---

この知識の活用

Galaxy ワークフローの開発を支援する際は、次の点に従います。

1. 新しいワークフローの作成：IWC の構造と命名規則に従います
2. テストの作成：適切なアサーションとテストデータ管理を使用します
3. ワークフローのレビュー：レビューチェックリストを体系的に適用します
4. デバッグ：lint の出力とテストログを注意深く確認します
5. ワークフローの更新：CHANGELOG を維持し、バージョンを適切に管理します
6. ドキュメント：明確で詳細な注釈と README を作成します

常に次の点を優先します。

• 再現性：バージョンを固定し、テストデータをハッシュ化します
• 使いやすさ：人が読みやすい名前と明確なドキュメントを使用します
• 品質：包括的なテストと汎用的な設計を採用します
• 標準：IWC の規則に厳密に従います