galaxy-tool-wrapping

Galaxy ツールラッパーのエキスパート

Galaxy ツールラッパーの開発に関する専門知識です。Galaxy ツール XML ラッパーの作成、テスト、デバッグ、改善をユーザーが行う際に、このスキルを使用してください。

前提条件： このスキルは、Planemo のテストとワークフロー実行のパターンに関する galaxy-automation スキルに依存します。

このスキルを使用する場面

• Galaxy ツールラッパーをゼロから新規作成する
• コマンドラインツールを Galaxy ラッパーに変換する
• Tool Shed への登録用に .shed.yml ファイルを生成する
• XML の構文エラーや検証エラーをデバッグする
• ツール向けの Planemo テストを作成する
• 条件付きパラメーターやデータ型を実装する
• ツールの依存関係（conda、コンテナ）を処理する
• ツールコレクションやスイートを作成する
• ツールのパフォーマンスとリソース割り当てを最適化する
• Galaxy のデータ型と形式を理解する
• 適切なエラー処理を実装する

コアコンセプト

Galaxy ツール XML の構造

Galaxy ツールラッパーは、以下の要素で構成されます。

• id、name、version を持つ <tool> ルート要素
• ツールの簡単な説明である <description>
• 依存関係（conda パッケージ、コンテナ）を指定する <requirements>
• 実際にコマンドラインを実行する <command>
• パラメーター定義である <inputs>
• 出力ファイルの仕様である <outputs>
• 自動テストである <tests>
• reStructuredText 形式のドキュメントである <help>
• DOI 参照である <citations>

Tool Shed メタデータ（.shed.yml）

Galaxy Tool Shed へのツール公開に必要です。

name: tool_name                  # Match directory name, underscores only
owner: iuc                       # Usually 'iuc' for IUC tools
description: One-line tool description
homepage_url: https://github.com/tool/repo
long_description: |
  Multi-line detailed description.
  Can include features, use cases, and tool suite contents.
remote_repository_url: https://github.com/galaxyproject/tools-iuc/tree/main/tools/tool_name
type: unrestricted
categories:
- Assembly                       # Choose 1-3 relevant categories
- Genomics

利用可能なすべてのカテゴリとベストプラクティスを含む、.shed.yml の包括的なドキュメントについては reference.md を参照してください。

主な構成要素

コマンドブロック：

• Cheetah テンプレートを使用します：$variable_name または ${variable_name}
• 条件分岐：#if $param then... #end if
• ループ構文：#for $item in $collection... #end for
• 複雑なコマンドには CDATA セクションを使用します

Cheetah テンプレートのベストプラクティス：

conda パッケージでのパス処理の問題を回避する方法：

<command detect_errors="exit_code"><![CDATA[
    ## Add trailing slash if script concatenates paths without separator
    tool_command
        -o 'output_dir/'  ## Quoted with trailing slash

    ## Script does: output_dir + 'file.txt' → 'output_dir/file.txt' ✓
    ## Without slash: output_dir + 'file.txt' → 'output_dirfile.txt' ✗
]]></command>

Cheetah で引用符を使用する場面：

• ユーザー入力は必ず引用符で囲みます：'$input_file'
• 特殊文字を含むリテラル文字列は引用符で囲みます：'output_dir/'
• 単純な参照には変数をそのまま使用します：$variable

入力パラメーター：

• type、name、label を指定する <param> 要素
• 型：text、integer、float、boolean、select、data、data_collection
• 任意パラメーターと必須パラメーター
• バリデーターとサニタイザー
• 条件付きパラメーター表示

出力：

• 出力ファイル用の <data> 要素
• label と name による動的な出力名の指定
• 形式の判定と変換
• 条件付き出力用のフィルター
• 複数の出力用のコレクション

テスト：

• 入力パラメーターとファイル
• 期待される出力ファイルまたはアサーション
• テストデータの配置場所と構成
• 大きなファイルの処理を含む詳細なテスト戦略については testing.md を参照してください

ベストプラクティス

1. 必ずテストを含める - テストがないと Planemo は合格しません
2. セマンティックバージョニングを使用する - 変更時にはツールのバージョンを更新します
3. 依存関係を正確に指定する - conda パッケージのバージョンを固定します
4. わかりやすいヘルプテキストを追加する - すべてのパラメーターを説明します
5. エラーを適切に処理する - 終了コードを確認し、入力を検証します
6. コレクションを使用する - 関連する複数のファイルを扱う場合に使用します
7. IUC 標準に従う - intergalactic utilities commission に貢献する場合
8. 大きな出力ファイルに備える - テストを作成する前に、出力の予想サイズを確認します。1 MB を超える場合は、ファイル全体の比較ではなく、アサーションベースのテスト（has_size、has_line）を使用します（testing.md を参照）

よく使う Planemo コマンド

# Test tool locally
planemo test tool.xml

# Serve tool in local Galaxy
planemo serve tool.xml

# Lint tool for best practices
planemo lint tool.xml

# Upload tool to ToolShed
planemo shed_update --shed_target toolshed

# Test with conda
planemo test --conda_auto_init --conda_auto_install tool.xml

# Lint with skips (for tools with custom datatypes or shared boolean conditionals)
planemo lint --skip ConditionalParamTypeBool,DatatypesCustomConf .

# Note: .lint_skip file is used by IUC CI, not by local planemo lint.
# For local linting, use the --skip flag explicitly.

シンボリックリンクによる出力のルーティング

ツールが内部で生成したファイル名（$output ではない）に出力を書き込む場合は、コマンドブロック内でシンボリックリンクを使用して、そのファイルを Galaxy の出力変数にルーティングします。

パターン：コマンド実行前にシンボリックリンクを作成する

<command detect_errors="exit_code"><![CDATA[
    ## Create symlink so tool output lands where Galaxy expects it
    ln -s '$output_variable' 'expected_tool_output_name' &&
    tool_command --input '$input' -o 'expected_tool_output_name'
]]></command>

パターン：プレフィックスベースの出力ファイル名

一部のツールでは --out-prefix を使用します。この場合、出力ファイル名は prefix + input_filename になります。 ツールは内部でファイル名を生成するため、生成される名前を予測してシンボリックリンクを作成する必要があります。

<command><![CDATA[
    #set $mangled_input = re.sub(r"[^\w\-\s]", "_", str($input.element_identifier)) + "." + str($input.ext)
    ln -s '$input' '$mangled_input' &&
    ln -s '$output_var' 'myprefix${mangled_input}' &&
    tool_command --input-reads '$mangled_input' -p myprefix
]]></command>

重要なポイント：

• シンボリックリンクはツールの実行前に作成します。ツールはそのリンク経由で書き込みます
• ツールが生成するファイル名と完全に一致させる必要があります
• プレフィックスモードの場合、出力は prefix + getFileName(input) となるため、一致するように入力名を加工します

Galaxy へのカスタムデータ型の追加

シンプルなディレクトリベースのインデックス形式（例：bwa_index）を追加するには：

1. config/datatypes_conf.xml.sample に登録する — 類似の型の近くに追加します：

   <datatype extension="bwa_index" display_in_upload="true" type="galaxy.datatypes.data:Directory" subclass="true"/>
   

2. test/functional/tools/sample_datatypes_conf.xml に登録する — 同じ行に追加します

シンプルなディレクトリベースのインデックス形式では、カスタム Python クラスやスニファーは必要ありません。 参考 PR：galaxyproject/galaxy#19694（最初の例として bwa_mem2_index を追加）。

既知の制限事項： planemo test（--galaxy_root の有無を問わず）では、class="Directory" のテストデータセットが正しくステージングされません。__DATA_FETCH__ によるテストデータのアップロード中に、extra_files_path が設定されません。これはすべての Directory サブクラスのデータ型（例：bwa_mem2_index、bwa_index）に影響します。これらのテストは IUC CI では成功しますが、ローカルでは失敗します。テストを成功させるには、新しいデータ型を Galaxy コアの datatypes_conf.xml.sample にも追加する必要があります。

Mapper ツールへのインデックスサポートの追加（BWA-MEM2 パターン）

Mapper にビルド済みインデックスのサポートを追加するには（実績のある BWA-MEM2 のパターンに従います）：

1. インデックス作成ツールを作成する（tool-idx.xml）

<tool id="tool_idx" name="Tool indexer" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" profile="@PROFILE_VERSION@">
    <command><![CDATA[
mkdir '$index.extra_files_path' &&
cd '$index.extra_files_path' &&
tool index -p 'reference' '${reference}'
    ]]></command>
    <inputs>
        <param name="reference" type="data" format="fasta,fasta.gz" label="Select a genome to index"/>
    </inputs>
    <outputs>
        <data name="index" format="tool_index"/>  
    </outputs>
</tool>

2. インデックスと FASTA を判別するよう、参照マクロを更新する

<token name="@set_reference_fasta_filename@"><![CDATA[
#if str($reference_source.reference_source_selector) == "history":
    #if $reference_source.ref_file.is_of_type("tool_index"):
        #set $reference_fasta_filename = $reference_source.ref_file.extra_files_path + "/reference"
    #else
        #set $reference_fasta_filename = "localref." + $reference_source.ref_file.extension
        ln -s '${reference_source.ref_file}' '${reference_fasta_filename}' &&
        tool index '${reference_fasta_filename}' &&
    #end if
#else:
    #set $reference_fasta_filename = str($reference_source.ref_file.fields.path)
#end if
]]></token>

3. 参照条件分岐でインデックス形式を受け入れる

<param name="ref_file" type="data" format="fasta,fasta.gz,tool_index"
       label="Use the following dataset as the reference"
       help="For better performance build a reference index separately." />

4. 下位互換性のため、既存のパラメーターを維持する

インデックスサポートを追加する際は、index_a（アルゴリズムの選択）のようなパラメーターを保持してください。インデックスが指定された場合は無視されますが、ワークフローとの互換性を維持できます。

5. ツールディレクトリに datatypes_conf.xml を含める

ToolShed へのインストールと lint 検証に必要です：

<?xml version="1.0"?>
<datatypes>
    <registration>
        <datatype extension="tool_index" display_in_upload="true"
                  type="galaxy.datatypes.data:Directory" subclass="true"/>
    </registration>
</datatypes>

.lint_skip に DatatypesCustomConf を追加します。

6. Directory データセット用のテストデータ

• test-data/test-cache/ でインデックスをローカルにビルドします：tool index -p reference genome.fa
• Galaxy MCP または planemo serve 経由で BAM 出力を生成します
• インデックスのテストには専用の出力ファイルを使用します（例：tool-mem-index-test.bam）

動的な出力形式に format_source を使用する

出力形式を入力形式と一致させる場合（例：サブサンプリングしたリード）：

<data name="subsampled_outfile" format_source="input_reads" label="Subsampled reads">
    <filter>output_options["output_type"]["type_selector"] == "subsampled_reads"</filter>
</data>

出力が常に入力と同じ形式になる場合は、change_format よりこちらが適しています。 ユーザーが出力形式を明示的に選択する場合は、change_format を使用します。

テスト構文：条件分岐ラッパーを使用する

最新の Galaxy ツール（プロファイル 20.01 以降）では、テストパラメーターを対応する <conditional> ブロックで囲む必要があります。フラット形式のパラメーターを使うと、TestsCaseValidation 警告が発生します：

誤り（フラット形式 — 検証警告が発生します）：

<param name="reference_source_selector" value="history"/>
<param name="ref_file" ftype="fasta" value="genome.fa"/>
<param name="fastq_input_selector" value="paired"/>

正しい（条件分岐ラッパーを使用）：

<conditional name="reference_source">
    <param name="reference_source_selector" value="history"/>
    <param name="ref_file" ftype="fasta" value="genome.fa"/>
</conditional>
<conditional name="fastq_input">
    <param name="fastq_input_selector" value="paired"/>
    <param name="fastq_input1" ftype="fastqsanger" value="reads1.fq"/>
</conditional>

XML テンプレートの例

<tool id="tool_id" name="Tool Name" version="1.0.0">
    <description>Brief description</description>

    <requirements>
        <requirement type="package" version="1.0">package_name</requirement>
    </requirements>

    <command detect_errors="exit_code"><![CDATA[
        tool_command
            --input '$input'
            --output '$output'
            #if $optional_param
                --param '$optional_param'
            #end if
    ]]></command>

    <inputs>
        <param name="input" type="data" format="txt" label="Input file"/>
        <param name="optional_param" type="text" optional="true" label="Optional parameter"/>
    </inputs>

    <outputs>
        <data name="output" format="txt" label="${tool.name} on ${on_string}"/>
    </outputs>

    <tests>
        <test>
            <param name="input" value="test_input.txt"/>
            <output name="output" file="expected_output.txt"/>
        </test>
    </tests>

    <help><![CDATA[
**What it does**

Describe what the tool does.

**Inputs**

- Input file: description

**Outputs**

- Output file: description
    ]]></help>

    <citations>
        <citation type="doi">10.1234/example.doi</citation>
    </citations>
</tool>

ドキュメント

このスキルには、詳細なリファレンスドキュメントが含まれています。

• reference.md - IUC のベストプラクティスに沿った、Galaxy ツールの包括的なラッピングガイド

  • リポジトリ構造の標準
  • .shed.yml の設定
  • XML 構造の完全なリファレンス
  • 高度な機能とパターン

• testing.md - テスト戦略とアサーションパターン

  • 期待されるテスト出力の再生成
  • 大きなテストファイル（1MB 超、CI の上限）への対応
  • サイズ、チェックサム、コンテンツのサンプリングに関するアサーション
  • 大きなテストファイルを置き換えるワークフロー

• troubleshooting.md - 実践的なトラブルシューティングガイド

  • tool_test_output.json の読み取り
  • 一般的な終了コードとその意味
  • よくある XML および実行時の問題
  • ツールテストの失敗のデバッグ
  • テスト失敗の診断と修正

• dependency-debugging.md - 依存関係の競合の解決

  • 診断での planemo mull の使用
  • Conda ソルバーエラーの解釈
  • macOS でのテストに関する考慮事項
  • バージョン競合のワークフロー

これらのファイルでは、上記の主要な概念を補完する、詳細な技術情報を説明しています。

関連スキル

• galaxy-automation - BioBlend と Planemo の基礎（依存関係）
• galaxy-workflow-development - これらのツールを使用するワークフローの構築
• conda-recipe - ツールの依存関係向け Conda パッケージの作成
• bioinformatics-fundamentals - ツールで使用されるファイル形式とデータ型の理解

リソース

• Galaxy ツール開発: https://docs.galaxyproject.org/en/latest/dev/
• Planemo ドキュメント: https://planemo.readthedocs.io/
• IUC 標準: https://galaxy-iuc-standards.readthedocs.io/
• Galaxy トレーニング: https://training.galaxyproject.org/