galaxy-tool-wrapping

v2026.09.24
delphine-l/claude_global00

Expert in Galaxy tool wrapper development, XML schemas, Planemo testing, and best practices for creating Galaxy tools

GitHub
安装命令
npx skhub add delphine-l/galaxy-tool-wrapping
Markdown
SKILL.md

Galaxy Tool Wrapping Expert

Expert knowledge for developing Galaxy tool wrappers. Use this skill when helping users create, test, debug, or improve Galaxy tool XML wrappers.

Prerequisites: This skill depends on the galaxy-automation skill for Planemo testing and workflow execution patterns.

When to Use This Skill

  • Creating new Galaxy tool wrappers from scratch
  • Converting command-line tools to Galaxy wrappers
  • Generating .shed.yml files for Tool Shed submission
  • Debugging XML syntax and validation errors
  • Writing Planemo tests for tools
  • Implementing conditional parameters and data types
  • Handling tool dependencies (conda, containers)
  • Creating tool collections and suites
  • Optimizing tool performance and resource allocation
  • Understanding Galaxy datatypes and formats
  • Implementing proper error handling

Core Concepts

Galaxy Tool XML Structure

A Galaxy tool wrapper consists of:

  • <tool> root element with id, name, and version
  • <description> brief tool description
  • <requirements> for dependencies (conda packages, containers)
  • <command> the actual command-line execution
  • <inputs> parameter definitions
  • <outputs> output file specifications
  • <tests> automated tests
  • <help> documentation in reStructuredText
  • <citations> DOI references

Tool Shed Metadata (.shed.yml)

Required for publishing tools to the 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

See reference.md for comprehensive .shed.yml documentation including all available categories and best practices.

Key Components

Command Block:

  • Use Cheetah templating: $variable_name or ${variable_name}
  • Conditional logic: #if $param then... #end if
  • Loop constructs: #for $item in $collection... #end for
  • CDATA sections for complex commands

Cheetah Template Best Practices:

Working around path handling issues in conda packages:

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

When to use quotes in Cheetah:

  • Always quote user inputs: '$input_file'
  • Quote literal strings with special chars: 'output_dir/'
  • Use bare variables for simple references: $variable

Input Parameters:

  • <param> elements with type, name, label
  • Types: text, integer, float, boolean, select, data, data_collection
  • Optional vs required parameters
  • Validators and sanitizers
  • Conditional parameter display

Outputs:

  • <data> elements for output files
  • Dynamic output naming with label and name
  • Format discovery and conversion
  • Filters for conditional outputs
  • Collections for multiple outputs

Tests:

  • Input parameters and files
  • Expected output files or assertions
  • Test data location and organization
  • See testing.md for detailed testing strategies including large file handling

Best Practices

  1. Always include tests - Planemo won't pass without them
  2. Use semantic versioning - Increment tool version on changes
  3. Specify exact dependencies - Pin conda package versions
  4. Add clear help text - Document all parameters
  5. Handle errors gracefully - Check exit codes, validate inputs
  6. Use collections - For multiple related files
  7. Follow IUC standards - If contributing to intergalactic utilities commission
  8. Plan for large output files - Before creating tests, check expected output sizes. If over 1MB, use assertion-based tests (has_size, has_line) instead of full file comparison (see testing.md)

Common Planemo Commands

# 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 Routing with Symlinks

When a tool writes output to a filename it constructs internally (not $output), use symlinks in the command block to route the file to Galaxy's output variable.

Pattern: Symlink before command execution

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

Pattern: Prefix-based output naming

Some tools use --out-prefix where the output filename is prefix + input_filename. The tool constructs the filename internally, so you must predict it and symlink:

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

Key points:

  • Symlink is created before running the tool -- the tool writes through it
  • Must match the exact filename the tool will produce
  • For prefix mode: output = prefix + getFileName(input), so mangle the input name to match

Adding Custom Datatypes to Galaxy

To add a simple directory-based index format (e.g., bwa_index):

  1. Register in config/datatypes_conf.xml.sample — add near similar types: 
    <datatype extension="bwa_index" display_in_upload="true" type="galaxy.datatypes.data:Directory" subclass="true"/>
  2. Register in test/functional/tools/sample_datatypes_conf.xml — same line

No custom Python class or sniffer is needed for simple directory-based index formats. Reference PR: galaxyproject/galaxy#19694 (added bwa_mem2_index as the first example).

Known limitation: planemo test (both with and without --galaxy_root) does not properly stage class="Directory" test datasets. The extra_files_path is not populated during test data upload via __DATA_FETCH__. This affects all Directory-subclass datatypes (e.g., bwa_mem2_index, bwa_index). These tests pass in IUC CI but fail locally. The new datatype must also be added to Galaxy core datatypes_conf.xml.sample before tests can pass.

Adding Index Support to Mapper Tools (BWA-MEM2 Pattern)

To add pre-built index support to a mapper (following BWA-MEM2's proven pattern):

1. Create the indexer tool (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"/>  <!-- Directory subclass datatype -->
    </outputs>
</tool>

2. Update the reference macro to detect index vs 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. Accept index format in the reference conditional

<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. Keep existing parameters for backward compatibility

When adding index support, preserve parameters like index_a (algorithm selection). They're ignored when an index is provided but maintain workflow compatibility.

5. Include datatypes_conf.xml in tool directory

Required for ToolShed installation and lint validation:

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

Add DatatypesCustomConf to .lint_skip.

6. Test data for Directory datasets

  • Build index locally: tool index -p reference genome.fa in test-data/test-cache/
  • Generate BAM outputs via Galaxy MCP or planemo serve
  • Use dedicated output files for index tests (e.g., tool-mem-index-test.bam)

Using format_source for dynamic output formats

When output format should match the input format (e.g., subsampled reads):

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

This is preferable to change_format when the output is always the same format as input. Use change_format when the user explicitly selects the output format.

Test Syntax: Use Conditional Wrappers

Modern Galaxy tools (profile 20.01+) require test params to be wrapped in their <conditional> blocks. Flat-style params cause TestsCaseValidation warnings:

Wrong (flat style — triggers validation warnings):

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

Correct (conditional wrappers):

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

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

Supporting Documentation

This skill includes detailed reference documentation:

  • reference.md - Comprehensive Galaxy tool wrapping guide with IUC best practices

    • Repository structure standards
    • .shed.yml configuration
    • Complete XML structure reference
    • Advanced features and patterns

  • testing.md - Testing strategies and assertion patterns

    • Regenerating expected test outputs
    • Handling large test files (>1MB CI limit)
    • Size, checksum, and content sampling assertions
    • Workflow for replacing large test files

  • troubleshooting.md - Practical troubleshooting guide

    • Reading tool_test_output.json
    • Common exit codes and their meanings
    • Common XML and runtime issues
    • Debugging tool test failures
    • Test failure diagnosis and fixes

  • dependency-debugging.md - Dependency conflict resolution

    • Using planemo mull for diagnosis
    • Conda solver error interpretation
    • macOS testing considerations
    • Version conflict workflows

These files provide deep technical details that complement the core concepts above.

Related Skills

  • galaxy-automation - BioBlend & Planemo foundation (dependency)
  • galaxy-workflow-development - Building workflows that use these tools
  • conda-recipe - Creating conda packages for tool dependencies
  • bioinformatics-fundamentals - Understanding file formats and data types used in tools

Resources

发现
标签

此技能尚未发布标签。

版本
最新版本元数据

版本

v2026.09.24

发布时间

2026年9月24日

分类

未分类

许可证

未指定

源路径

skills/galaxy/tool-wrapping

默认分支

main

最新提交

71c292e

Tree SHA

3c1a52e