Expand help text and add SVG schematics for sample sheet tools

Add "What is a sample sheet?" sections, concrete examples, and SVG
diagrams to both __CONVERT_SAMPLE_SHEET__ and __SAMPLE_SHEET_TO_TABULAR__
so newcomers understand what sample sheets are and when to use each tool.
Also adds the missing macros import to sample_sheet_to_tabular.xml.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
nekrut
2026-03-01 23:02:59 +00:00
parent fea583da75
commit f841fc1e26
4 changed files with 324 additions and 8 deletions
+68 -6
View File
@@ -26,21 +26,83 @@
Synopsis
========
Converts a sample sheet collection back to its corresponding list collection type.
Strips sample sheet metadata and produces a regular list collection.
========================
What is a sample sheet?
========================
A sample sheet is a special type of Galaxy collection that pairs each dataset with structured metadata — such as replicate number, treatment condition, or tissue type. It works like a regular list collection but with an attached spreadsheet of per-sample information.
===========
Description
===========
This tool takes a sample sheet collection and produces a regular list collection, removing all sample sheet metadata (column definitions and row values).
This tool removes the metadata layer from a sample sheet and converts it to the corresponding regular list collection type. The datasets themselves are unchanged — only the column definitions and row values are discarded.
The conversion follows this mapping:
- ``sample_sheet`` becomes ``list``
- ``sample_sheet:paired`` becomes ``list:paired``
- ``sample_sheet:paired_or_unpaired`` becomes ``list:paired_or_unpaired``
- ``sample_sheet`` ``list``
- ``sample_sheet:paired`` ``list:paired``
- ``sample_sheet:paired_or_unpaired`` ``list:paired_or_unpaired``
Use this tool when you need to pass a sample sheet to a tool that expects a regular list collection, or when you want to discard the sample sheet metadata.
Use this when you need to pass a sample sheet to a tool that only accepts regular list collections.
========
Examples
========
**Flat sample sheet**
Suppose you have an RNA-seq experiment uploaded as a sample sheet collection with metadata about each sample::
Sample Sheet: "RNA-seq experiment"
Column definitions: replicate (int), treatment (string)
sample1.fastq | replicate=1, treatment="control"
sample2.fastq | replicate=2, treatment="treated"
Running **Convert sample sheet** strips the metadata and produces a plain list::
List: "RNA-seq experiment (converted)"
sample1.fastq
sample2.fastq
Same datasets, same identifiers, but now it is a regular list that any tool can consume.
-------
**Paired sample sheet**
If your sample sheet contains paired-end reads (``sample_sheet:paired``), the tool converts it to ``list:paired``::
Sample Sheet (paired): "WGS samples"
Column definitions: replicate (int)
sample1 -> [forward, reverse] | replicate=42
sample2 -> [forward, reverse] | replicate=43
After conversion::
List (paired): "WGS samples (converted)"
sample1 -> [forward, reverse]
sample2 -> [forward, reverse]
The paired structure is preserved; only the metadata is removed.
-------
.. image:: ${static_path}/images/tools/collection_ops/convert_sample_sheet.svg
:alt: Convert sample sheet to list collection
:width: 500
-------
.. class:: warningmark
If you need to preserve the metadata, use the **Sample sheet to tabular** tool first to export it as a tab-separated table before converting.
----
+69 -2
View File
@@ -2,6 +2,9 @@
name="Sample sheet to tabular"
version="1.0.0">
<description>to extract sample sheet metadata as a table</description>
<macros>
<import>model_operation_macros.xml</import>
</macros>
<edam_operations>
<edam_operation>operation_3359</edam_operation>
</edam_operations>
@@ -45,17 +48,81 @@ cp '$out_config' '$output'
Synopsis
========
Converts sample sheet metadata into a tabular dataset.
Exports the metadata from a sample sheet collection as a tab-separated table.
========================
What is a sample sheet?
========================
A sample sheet is a special type of Galaxy collection that pairs each dataset with structured metadata — such as replicate number, treatment condition, or tissue type. It works like a regular list collection but with an attached spreadsheet of per-sample information.
===========
Description
===========
This tool takes a sample sheet dataset collection and extracts its metadata into a tab-separated file. Each row corresponds to an element in the sample sheet collection. The first column contains the element identifier, followed by columns for each metadata field defined in the sample sheet.
This tool reads the column definitions and row values from a sample sheet collection and writes them to a tabular dataset. The first column is always the element identifier (sample name). The remaining columns match the metadata fields defined in the sample sheet. The datasets in the collection are not affected — only the metadata is extracted.
When **Include column headers** is enabled, the first row will contain the column names, with ``element_identifier`` as the first column followed by the names from the sample sheet column definitions.
You can customize how special values are represented in the output using the replacement parameters for null values, empty strings, and boolean values.
========
Examples
========
**Basic extraction (without headers)**
Given a sample sheet with three samples and two metadata columns (``replicate`` of type int, ``treatment`` of type string)::
Sample Sheet: "RNA-seq experiment"
sample1.fastq | replicate=1, treatment="control"
sample2.fastq | replicate=2, treatment="treated"
sample3.fastq | replicate=3, treatment="control"
The output tabular file contains::
sample1 1 control
sample2 2 treated
sample3 3 control
-------
**With headers enabled**
Enabling **Include column headers** adds a header row::
element_identifier replicate treatment
sample1 1 control
sample2 2 treated
sample3 3 control
-------
**Replacement parameters**
If some metadata values are null or boolean, you can control their text representation:
- *Replace 'null' values with*: converts missing values (default: empty string, or use ``-`` or ``NA``)
- *Replace boolean 'true'/'false' values with*: controls how booleans are written (default: ``TRUE`` / ``FALSE``)
For example, with null replacement set to ``NA``::
element_identifier replicate is_paired
sample1 1 TRUE
sample2 NA FALSE
-------
.. image:: ${static_path}/images/tools/collection_ops/sample_sheet_to_tabular.svg
:alt: Sample sheet to tabular dataset
:width: 500
-------
.. class:: infomark
This tool creates a new tabular dataset (not a collection operation), so normal quota usage applies.
]]></help>
</tool>
@@ -0,0 +1,82 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 620 220" width="620" height="220">
<defs>
<filter id="shadow" x="-4%" y="-4%" width="110%" height="110%">
<feGaussianBlur in="SourceAlpha" stdDeviation="2" result="blur"/>
<feComponentTransfer in="blur">
<feFuncA type="linear" slope="0.3"/>
</feComponentTransfer>
<feMerge>
<feMergeNode/>
<feMergeNode in="SourceGraphic"/>
</feMerge>
</filter>
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
<polygon points="0 0, 10 3.5, 0 7" fill="#555"/>
</marker>
</defs>
<!-- Left: Sample Sheet container -->
<rect x="10" y="10" width="240" height="195" rx="8" ry="8" fill="#d9ead3" stroke="#888" stroke-width="1" filter="url(#shadow)"/>
<text x="130" y="32" text-anchor="middle" font-family="sans-serif" font-size="13" font-weight="bold" fill="#333">Sample Sheet: "RNA-seq"</text>
<!-- Metadata table -->
<!-- Header row -->
<rect x="22" y="44" width="80" height="22" fill="#fff" stroke="#aaa" stroke-width="0.5"/>
<rect x="102" y="44" width="36" height="22" fill="#fce5cd" stroke="#aaa" stroke-width="0.5"/>
<rect x="138" y="44" width="100" height="22" fill="#fce5cd" stroke="#aaa" stroke-width="0.5"/>
<text x="62" y="59" text-anchor="middle" font-family="sans-serif" font-size="11" font-weight="bold" fill="#333">Name</text>
<text x="120" y="59" text-anchor="middle" font-family="sans-serif" font-size="11" font-weight="bold" fill="#b45309">rep</text>
<text x="188" y="59" text-anchor="middle" font-family="sans-serif" font-size="11" font-weight="bold" fill="#b45309">treatment</text>
<!-- Row 1 -->
<rect x="22" y="66" width="80" height="22" fill="#fff" stroke="#aaa" stroke-width="0.5"/>
<rect x="102" y="66" width="36" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<rect x="138" y="66" width="100" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<text x="62" y="81" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#333">sample1</text>
<text x="120" y="81" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">1</text>
<text x="188" y="81" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">control</text>
<!-- Row 2 -->
<rect x="22" y="88" width="80" height="22" fill="#fff" stroke="#aaa" stroke-width="0.5"/>
<rect x="102" y="88" width="36" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<rect x="138" y="88" width="100" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<text x="62" y="103" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#333">sample2</text>
<text x="120" y="103" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">2</text>
<text x="188" y="103" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">treated</text>
<!-- Row 3 -->
<rect x="22" y="110" width="80" height="22" fill="#fff" stroke="#aaa" stroke-width="0.5"/>
<rect x="102" y="110" width="36" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<rect x="138" y="110" width="100" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<text x="62" y="125" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#333">sample3</text>
<text x="120" y="125" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">3</text>
<text x="188" y="125" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">control</text>
<!-- Metadata label -->
<text x="155" y="155" text-anchor="middle" font-family="sans-serif" font-size="10" font-style="italic" fill="#b45309">metadata columns</text>
<line x1="110" y1="140" x2="110" y2="148" stroke="#b45309" stroke-width="0.8" stroke-dasharray="2,2"/>
<line x1="110" y1="148" x2="200" y2="148" stroke="#b45309" stroke-width="0.8" stroke-dasharray="2,2"/>
<line x1="200" y1="140" x2="200" y2="148" stroke="#b45309" stroke-width="0.8" stroke-dasharray="2,2"/>
<!-- Arrow -->
<line x1="270" y1="107" x2="360" y2="107" stroke="#555" stroke-width="2" marker-end="url(#arrowhead)"/>
<text x="315" y="98" text-anchor="middle" font-family="sans-serif" font-size="12" font-weight="bold" fill="#555">Convert</text>
<!-- Right: List collection container -->
<rect x="380" y="10" width="220" height="195" rx="8" ry="8" fill="#d9ead3" stroke="#888" stroke-width="1" filter="url(#shadow)"/>
<text x="490" y="32" text-anchor="middle" font-family="sans-serif" font-size="13" font-weight="bold" fill="#333">List: "RNA-seq"</text>
<!-- Dataset items -->
<rect x="400" y="50" width="180" height="28" rx="4" ry="4" fill="#fff" stroke="#aaa" stroke-width="0.7"/>
<text x="490" y="69" text-anchor="middle" font-family="sans-serif" font-size="12" fill="#333">sample1.fastq</text>
<rect x="400" y="86" width="180" height="28" rx="4" ry="4" fill="#fff" stroke="#aaa" stroke-width="0.7"/>
<text x="490" y="105" text-anchor="middle" font-family="sans-serif" font-size="12" fill="#333">sample2.fastq</text>
<rect x="400" y="122" width="180" height="28" rx="4" ry="4" fill="#fff" stroke="#aaa" stroke-width="0.7"/>
<text x="490" y="141" text-anchor="middle" font-family="sans-serif" font-size="12" fill="#333">sample3.fastq</text>
<!-- Subtitle -->
<text x="490" y="172" text-anchor="middle" font-family="sans-serif" font-size="10" font-style="italic" fill="#666">same datasets, no metadata</text>
</svg>

After

Width:  |  Height:  |  Size: 5.4 KiB

@@ -0,0 +1,105 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 220" width="640" height="220">
<defs>
<filter id="shadow" x="-4%" y="-4%" width="110%" height="110%">
<feGaussianBlur in="SourceAlpha" stdDeviation="2" result="blur"/>
<feComponentTransfer in="blur">
<feFuncA type="linear" slope="0.3"/>
</feComponentTransfer>
<feMerge>
<feMergeNode/>
<feMergeNode in="SourceGraphic"/>
</feMerge>
</filter>
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
<polygon points="0 0, 10 3.5, 0 7" fill="#555"/>
</marker>
</defs>
<!-- Left: Sample Sheet container -->
<rect x="10" y="10" width="240" height="195" rx="8" ry="8" fill="#d9ead3" stroke="#888" stroke-width="1" filter="url(#shadow)"/>
<text x="130" y="32" text-anchor="middle" font-family="sans-serif" font-size="13" font-weight="bold" fill="#333">Sample Sheet: "RNA-seq"</text>
<!-- Metadata table -->
<!-- Header row -->
<rect x="22" y="44" width="80" height="22" fill="#fff" stroke="#aaa" stroke-width="0.5"/>
<rect x="102" y="44" width="36" height="22" fill="#fce5cd" stroke="#aaa" stroke-width="0.5"/>
<rect x="138" y="44" width="100" height="22" fill="#fce5cd" stroke="#aaa" stroke-width="0.5"/>
<text x="62" y="59" text-anchor="middle" font-family="sans-serif" font-size="11" font-weight="bold" fill="#333">Name</text>
<text x="120" y="59" text-anchor="middle" font-family="sans-serif" font-size="11" font-weight="bold" fill="#b45309">rep</text>
<text x="188" y="59" text-anchor="middle" font-family="sans-serif" font-size="11" font-weight="bold" fill="#b45309">treatment</text>
<!-- Row 1 -->
<rect x="22" y="66" width="80" height="22" fill="#fff" stroke="#aaa" stroke-width="0.5"/>
<rect x="102" y="66" width="36" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<rect x="138" y="66" width="100" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<text x="62" y="81" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#333">sample1</text>
<text x="120" y="81" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">1</text>
<text x="188" y="81" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">control</text>
<!-- Row 2 -->
<rect x="22" y="88" width="80" height="22" fill="#fff" stroke="#aaa" stroke-width="0.5"/>
<rect x="102" y="88" width="36" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<rect x="138" y="88" width="100" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<text x="62" y="103" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#333">sample2</text>
<text x="120" y="103" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">2</text>
<text x="188" y="103" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">treated</text>
<!-- Row 3 -->
<rect x="22" y="110" width="80" height="22" fill="#fff" stroke="#aaa" stroke-width="0.5"/>
<rect x="102" y="110" width="36" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<rect x="138" y="110" width="100" height="22" fill="#fff8e1" stroke="#aaa" stroke-width="0.5"/>
<text x="62" y="125" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#333">sample3</text>
<text x="120" y="125" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">3</text>
<text x="188" y="125" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#b45309">control</text>
<!-- Metadata label -->
<text x="155" y="155" text-anchor="middle" font-family="sans-serif" font-size="10" font-style="italic" fill="#b45309">metadata columns</text>
<line x1="110" y1="140" x2="110" y2="148" stroke="#b45309" stroke-width="0.8" stroke-dasharray="2,2"/>
<line x1="110" y1="148" x2="200" y2="148" stroke="#b45309" stroke-width="0.8" stroke-dasharray="2,2"/>
<line x1="200" y1="140" x2="200" y2="148" stroke="#b45309" stroke-width="0.8" stroke-dasharray="2,2"/>
<!-- Arrow -->
<line x1="270" y1="107" x2="370" y2="107" stroke="#555" stroke-width="2" marker-end="url(#arrowhead)"/>
<text x="320" y="92" text-anchor="middle" font-family="sans-serif" font-size="11" font-weight="bold" fill="#555">Extract</text>
<text x="320" y="105" text-anchor="middle" font-family="sans-serif" font-size="11" font-weight="bold" fill="#555">metadata</text>
<!-- Right: Tabular dataset -->
<rect x="390" y="10" width="235" height="195" rx="8" ry="8" fill="#cfe2f3" stroke="#888" stroke-width="1" filter="url(#shadow)"/>
<text x="507" y="32" text-anchor="middle" font-family="sans-serif" font-size="13" font-weight="bold" fill="#333">Tabular dataset</text>
<!-- Table header row -->
<rect x="400" y="44" width="90" height="22" fill="#a4c2f4" stroke="#7a9ec7" stroke-width="0.5"/>
<rect x="490" y="44" width="40" height="22" fill="#a4c2f4" stroke="#7a9ec7" stroke-width="0.5"/>
<rect x="530" y="44" width="85" height="22" fill="#a4c2f4" stroke="#7a9ec7" stroke-width="0.5"/>
<text x="445" y="59" text-anchor="middle" font-family="monospace" font-size="10" font-weight="bold" fill="#1a3c6e">element_id</text>
<text x="510" y="59" text-anchor="middle" font-family="monospace" font-size="10" font-weight="bold" fill="#1a3c6e">rep</text>
<text x="572" y="59" text-anchor="middle" font-family="monospace" font-size="10" font-weight="bold" fill="#1a3c6e">treatment</text>
<!-- Data row 1 -->
<rect x="400" y="66" width="90" height="22" fill="#fff" stroke="#bbb" stroke-width="0.5"/>
<rect x="490" y="66" width="40" height="22" fill="#fff" stroke="#bbb" stroke-width="0.5"/>
<rect x="530" y="66" width="85" height="22" fill="#fff" stroke="#bbb" stroke-width="0.5"/>
<text x="445" y="81" text-anchor="middle" font-family="monospace" font-size="10" fill="#333">sample1</text>
<text x="510" y="81" text-anchor="middle" font-family="monospace" font-size="10" fill="#333">1</text>
<text x="572" y="81" text-anchor="middle" font-family="monospace" font-size="10" fill="#333">control</text>
<!-- Data row 2 -->
<rect x="400" y="88" width="90" height="22" fill="#f3f6fc" stroke="#bbb" stroke-width="0.5"/>
<rect x="490" y="88" width="40" height="22" fill="#f3f6fc" stroke="#bbb" stroke-width="0.5"/>
<rect x="530" y="88" width="85" height="22" fill="#f3f6fc" stroke="#bbb" stroke-width="0.5"/>
<text x="445" y="103" text-anchor="middle" font-family="monospace" font-size="10" fill="#333">sample2</text>
<text x="510" y="103" text-anchor="middle" font-family="monospace" font-size="10" fill="#333">2</text>
<text x="572" y="103" text-anchor="middle" font-family="monospace" font-size="10" fill="#333">treated</text>
<!-- Data row 3 -->
<rect x="400" y="110" width="90" height="22" fill="#fff" stroke="#bbb" stroke-width="0.5"/>
<rect x="490" y="110" width="40" height="22" fill="#fff" stroke="#bbb" stroke-width="0.5"/>
<rect x="530" y="110" width="85" height="22" fill="#fff" stroke="#bbb" stroke-width="0.5"/>
<text x="445" y="125" text-anchor="middle" font-family="monospace" font-size="10" fill="#333">sample3</text>
<text x="510" y="125" text-anchor="middle" font-family="monospace" font-size="10" fill="#333">3</text>
<text x="572" y="125" text-anchor="middle" font-family="monospace" font-size="10" fill="#333">control</text>
<!-- Subtitle -->
<text x="507" y="157" text-anchor="middle" font-family="sans-serif" font-size="10" font-style="italic" fill="#555">tab-separated metadata export</text>
</svg>

After

Width:  |  Height:  |  Size: 7.4 KiB