galaxy-tool-wrapping

Galaxy 工具封装专家

关于开发 Galaxy 工具封装的专业知识。在帮助用户创建、测试、调试或改进 Galaxy 工具 XML 封装时使用此技能。

前置条件： 此技能依赖 galaxy-automation 技能来获取 Planemo 测试和工作流执行模式。

何时使用此技能

• 从头创建新的 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

请参阅 reference.md，了解完整的 .shed.yml 文档，包括所有可用类别和最佳实践。

关键组件

命令块：

• 使用 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. 为大型输出文件做好规划 - 创建测试前，检查预期输出大小。如果超过 1MB，请使用基于断言的测试（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 中。

为映射工具添加索引支持（BWA-MEM2 模式）

为映射工具添加预构建索引支持（遵循 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. 更新 reference 宏，以检测索引或 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. 在 reference 条件中接受索引格式

<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>

将 DatatypesCustomConf 添加到 .lint_skip。

6. Directory 数据集的测试数据

• 在本地构建索引：在 test-data/test-cache/ 中运行 tool index -p reference genome.fa
• 通过 Galaxy MCP 或 planemo serve 生成 BAM 输出
• 为索引测试使用专用输出文件（例如 tool-mem-index-test.bam）

使用 format_source 实现动态输出格式

当输出格式应与输入格式一致时（例如，抽样后的 reads）：

<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 工具（profile 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 - 全面的 Galaxy 工具封装指南，包含 IUC 最佳实践

  • 仓库结构标准
  • .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/