Tool Selection Diagram

Tool Selection Diagram Generator

Generate "which tool should I use?" flowchart diagrams for multi-tool Galaxy suites (e.g., MMseqs2, Samtools). Produces PNG images using Galaxy's color palette and Atkinson Hyperlegible font.

When to Use

• Creating a new visual guide for a multi-tool suite
• Updating an existing tool selection diagram after adding/removing tools
• A tool suite has 3+ tools and users frequently ask "which one should I use?"

Quick Reference

JSON Schema

The JSON definition describes a tree: start question -> goals -> (optional criteria) -> tools.

{
  "title": "string (required) — diagram caption, shown at bottom",
  "start_question": "string (required) — root node text, e.g. 'What do you need to do?'",
  "goals": [
    {
      "label": "string (required) — analysis goal name",
      "criteria": [
        {
          "label": "string (required) — decision criterion",
          "tools": [
            {
              "name": "string (required) — Galaxy tool name as shown in UI",
              "description": "string (optional) — short description below node"
            }
          ]
        }
      ],
      "tools": [
        {
          "name": "string (required)",
          "description": "string (optional)"
        }
      ]
    }
  ]
}

Field Details

Each goal uses either criteria (4-tier path) or tools (3-tier path), never both. A single diagram can mix both patterns across different goals.

Workflow

Step 1: Identify tools in the suite

List all tools in the suite. Group them by analysis goal (what the user is trying to accomplish). Each group becomes a goal node.

Step 2: Decide tier structure per goal

For each goal, decide whether users need a decision criterion to choose between tools:

Present the proposed structure to the user for approval before drafting JSON.

Step 3: Draft JSON definition

Use the examples in examples/ as templates:

• simple_example.json — minimal 3-tier (no criteria)
• mmseqs2_tool_selection.json — mixed 3-tier and 4-tier
• samtools_tool_selection.json — large suite, mixed tiers, multi-tool criteria

Step 4: Run the renderer

python3 tool-selection-diagram/scripts/render_tool_diagram.py \
    --input definition.json \
    --output tools/<suite>/static/images/<suite>_tool_selection.png \
    --dpi 150

The script requires Pillow. Install if needed: pip install Pillow.

Step 5: Verify the PNG

Open the PNG and check:

• All tool names match their Galaxy tool names exactly
• No text is clipped or overlapping
• The tree structure matches the intended decision flow
• Descriptions are concise and readable

Step 6: Embed in tool help

Reference the diagram in each tool's <help> section so users see it in Galaxy. See Embedding in Tool Help below.

Tier Structure Guide

The renderer supports mixed-tier diagrams. Each goal independently chooses its path:

A criterion node can have multiple tools beneath it (e.g., "Quick summary" -> flagstat + idxstats).

Color Palette

Colors come from Galaxy's "Paired" colormap (gxy-colors.svg):

Text colors: white on dark backgrounds (Start, Goal), dark navy on light backgrounds (Criterion, Tool).

Common Mistakes

Examples

Simple 3-tier (no criteria)

examples/simple_example.json — 2 goals, 3 tools, direct goal-to-tool paths:

{
  "title": "My Toolkit Selection Guide",
  "start_question": "What do you want to do?",
  "goals": [
    {
      "label": "Analyze data",
      "tools": [
        {"name": "tool-analyze", "description": "Run full analysis"},
        {"name": "tool-summarize", "description": "Quick summary stats"}
      ]
    },
    {
      "label": "Visualize results",
      "tools": [
        {"name": "tool-plot", "description": "Generate charts"}
      ]
    }
  ]
}

Mixed 3-tier and 4-tier

examples/mmseqs2_tool_selection.json — 4 goals, some with criteria (search, cluster, taxonomy) and one without (orthologs):

{
  "goals": [
    {
      "label": "Search sequences",
      "criteria": [
        {"label": "Large DB / high ID", "tools": [{"name": "easy-linsearch"}]},
        {"label": "General / remote", "tools": [{"name": "easy-search"}]}
      ]
    },
    {
      "label": "Find orthologs",
      "tools": [{"name": "easy-rbh", "description": "1 : 1 reciprocal best hit"}]
    }
  ]
}

Large suite with multi-tool criteria

examples/samtools_tool_selection.json — 5 goals, 12 tools. Some criteria point to multiple tools (e.g., "Quick summary" -> flagstat + idxstats).

Embedding in Tool Help

Add the diagram to each tool's <help> section using a relative image path:

<help format="markdown"><![CDATA[
**Which Samtools tool should I use?**

![Samtools Tool Selection Guide](static/images/samtools_tool_selection.png)

-----

**samtools view** filters and converts SAM/BAM/CRAM files...
]]></help>

Place the PNG at:

tools/<suite>/
├── static/
│   └── images/
│       └── <suite>_tool_selection.png
├── macros.xml
├── <suite>_tool_a.xml
└── ...

Galaxy serves files from static/ relative to the tool directory, so the ![](static/images/...) path works in the rendered help.

Script Reference

render_tool_diagram.py --input <JSON> --output <PNG> [--dpi N]

The script auto-detects tier structure (3-tier, 4-tier, or mixed) from the JSON. No configuration needed beyond the JSON definition.