| name | tool-selection-diagram |
| description | Generate a tool selection flowchart diagram (PNG) for a Galaxy tool suite from a JSON definition. Use when creating visual guides that help users pick the right tool in a multi-tool suite. |
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
| Item | Value |
|---|
| Input | JSON definition file |
| Output | PNG flowchart image |
| Script | tool-selection-diagram/scripts/render_tool_diagram.py |
| Dependencies | Pillow (Python) |
| Font | Atkinson Hyperlegible (falls back to DejaVu Sans) |
| Colors | Galaxy "Paired" colormap from gxy-colors.svg |
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
| Field | Type | Required | Notes |
|---|
title | string | Yes | Diagram caption (e.g., "MMseqs2 Tool Selection Guide") |
start_question | string | Yes | Root node — the question users start with |
goals[].label | string | Yes | Analysis goal (tier 2 node) |
goals[].criteria | array | No | Decision criteria (tier 3 nodes). Mutually exclusive with goals[].tools at the same level. |
goals[].criteria[].label | string | Yes | Criterion text |
goals[].criteria[].tools | array | Yes | Tools under this criterion |
goals[].tools | array | No | Tools directly under a goal (3-tier path, no criteria). Mutually exclusive with goals[].criteria. |
tools[].name | string | Yes | Tool name as it appears in Galaxy |
tools[].description | string | No | Short description shown below the tool node |
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:
| Situation | Tier Structure | Example |
|---|
| Only 1-2 tools, choice is obvious | 3-tier (goal -> tools) | Sort/Index -> samtools sort, samtools index |
| Users need guidance to pick | 4-tier (goal -> criterion -> tools) | Search -> "Large DB" -> linsearch, "Sensitive" -> search |
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-tiersamtools_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:
| Pattern | When to Use | Structure |
|---|
| 3-tier | Tools under a goal are self-explanatory or few | Start -> Goal -> Tool(s) |
| 4-tier | Users need a decision criterion to choose | Start -> Goal -> Criterion -> Tool(s) |
| Mixed | Some goals need criteria, others don't | Mix of both in one diagram |
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):
| Tier | Color | Hex | Usage |
|---|
| Start | Dark navy | #2c3143 | Root question node |
| Goal | Blue | #2077b3 | Analysis goal nodes |
| Criterion | Light orange | #fdbf6f | Decision criterion nodes |
| Tool | Green | #74c376 | Galaxy tool nodes |
Text colors: white on dark backgrounds (Start, Goal), dark navy on light backgrounds (Criterion, Tool).
Common Mistakes
| Mistake | Why It's Wrong | Fix |
|---|
| Tool names don't match Galaxy UI | Users can't find the tool | Use exact Galaxy tool names (e.g., "samtools view" not "SAMtools View") |
| Too many tools under one criterion | Diagram becomes unreadable | Split into multiple criteria or group differently |
Missing start_question | Script will error | Always include a root question |
| Labels too long (>40 chars) | Text gets clipped in nodes | Shorten labels; use description for details |
Using both criteria and tools on one goal | Invalid JSON structure | Each goal uses one or the other, not both |
Missing title | No caption on diagram | Always set a descriptive title |
| Descriptions on non-tool nodes | Only tool nodes show descriptions | Move extra text to criterion labels |
| Not verifying PNG after generation | Overlapping text or layout issues | Always open and visually check the output |
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"><
-----
**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  path works in the rendered help.
Script Reference
render_tool_diagram.py --input <JSON> --output <PNG> [--dpi N]
| Flag | Required | Default | Description |
|---|
--input | Yes | — | Path to JSON definition file |
--output | Yes | — | Output PNG path |
--dpi | No | 150 | Output resolution |
The script auto-detects tier structure (3-tier, 4-tier, or mixed) from the JSON. No configuration needed beyond the JSON definition.
