Add SamestrGal tutorial draft

[xens25]

Adds a new GTN tutorial on detecting shared microbial strains with SameStr by using an FMT-treated rCDI dataset. PR includes tutorial.md, the workflow and tests

[SaimMomin12]

Note: This review was drafted by Claude (Claude Code) and reviewed by @SaimMomin12 before posting.

@xens25 Nice work on this - the pedagogical structure is genuinely good. The key-terms box, the per-tool parameter-explanation comment boxes, the "Why these parameter values?" details box, and the warning about the reduced dataset all show real care, and the question/solution boxes target the right concepts. Comments below cover tutorial.md only.

Blockers

1. All four referenced images are missing from the PR. None of the 6 added files is an image, and all four paths 404 on the branch:

• L64 ../../images/samestr-workflow.png
• L523 ../../images/samestr-taxon-counts.png
• L530 ../../images/samestr-cooccurrences.png
• L550 ../../images/samestr-strain-events.png

This is why build-site and lint are failing. The path convention (../../images/ → topics/microbiome/images/) is correct — the files just need committing. It also makes the entire results section and two of the three question boxes unanswerable, since the questions quote values that only exist in the screenshots.

2. The PR description is still TODO: Describe your changes here.. — please fill it in, and mark the PR as a draft if it still is one.

Front matter (L1–L27)

• Missing subtopic: metagenomics. Without it the tutorial won't be filed under a subtopic on the Microbiome topic page. See topics/microbiome/tutorials/beer-data-analysis/tutorial.md for a reference.
• Missing tags: — at minimum metagenomics, microbiome, and microgalaxy (the microGalaxy community filters on that tag; the .ga file already carries these tags, so the tutorial should match).
• Missing edam_ontology: — e.g. topic_3174 (Metagenomics), topic_3697 (Microbial ecology), topic_0637 (Taxonomy).
• Missing requirements:. For level: Intermediate, please link prerequisites (Galaxy 101 / collections, plus an intro metagenomics tutorial) so learners aren't hitting Apply Rules cold.
• Consider answer_histories: or at least a link to a finished public history. Given the warning at L168–L171 that changing parameters can silently produce no output, a reference history is high value here.
• time_estimation: 2H looks optimistic — the tutorial has learners run the pipeline twice (whole workflow, then tool-by-tool), including two MetaPhlAn passes. Worth re-timing, or restructuring (see below).

Naming

The tutorial uses SamestrGal, SameStr, and Samestr interchangeably, sometimes in the same sentence — e.g. the objectives at L12–L14 ("Run the SamestrGal workflow… Explain the role of each tool in the SameStr workflow"), and L62 / L66. Please settle on one convention: SameStr for the tool/suite, and either drop "SamestrGal" entirely or define it once as the name of the Galaxy workflow. I'd lean toward titling around the analysis rather than a coined name — e.g. "Detection of shared microbial strains with SameStr" — and renaming the directory to samestr-strain-detection.

Structure

The tutorial runs the same analysis twice. Section 2 (L114) runs the complete workflow, then section 3 (L175) repeats every step manually. The parameter values are duplicated between the two sections, which is a maintenance trap — they will drift. Two options:

• Make the step-by-step section the main path and move the one-click workflow run to a short optional section at the end ("now that you understand each step, here's the whole thing as a workflow"), or
• keep the workflow-first order but drop the duplicated parameter table from section 2 and point at the per-tool sections instead.

Related: L177 tells the reader to "start by uploading the data and building a paired collection as described in step 2 of Running SamestrGal as a Complete Workflow." Collection building is a data-prep step, not a workflow step — move it into the Get data hands-on box at L74 so both paths share it and there's no forward reference.

Correctness / accuracy

• L34, L40: Clostridium difficile → Clostridioides difficile. The currently accepted name is Clostridioides; the cdifficile bib entry is itself titled "Clostridioides difficile", so the body text contradicts its own reference. Mention the older name once in parentheses if useful.
• L542: the solution contradicts itself. Question 2 asks "Can you tell from this table whether any strain persisted in the patient? How would you tell?" The answer begins "No." and then explains exactly how you can tell. The table does answer the question — the answer is "yes, and the finding is no persistence." Suggested rewrite: "Yes. The Pre-FMT/Post-FMT row shows shared_strain = 0, so no clade was confirmed as the same strain between those samples — this data shows no evidence of persistence."
• L536: "Why is it less likely that Pre-FMT and Donor share anything?" As written this is too strong — an unrelated donor and patient will routinely share common commensal species, which is exactly what the shared_species / shared_clade columns count. The solution only holds at strain level; suggest rewording to "share the same strain".
• L347: the Apply Rules regex is fragile. ^[^_]+_(.*)$ strips everything up to the first underscore. It works only because step 3 (L97) renamed the samples to Pre-FMT / Donor / Post-FMT. A learner who skips the rename (raw names are 28A_R1, 28B_R2, …) or brings their own data with underscores in sample names gets silently mangled identifiers and confusing downstream failures. Please add a warning box and make the rename explicitly non-optional.
• L308: "Percent identity" = 0.9 — the label says percent, the value is a fraction. One clarifying clause would help ("expressed as a fraction, so 0.9 = 90%"), and ideally the label gets fixed in the tool wrapper.
• L181 overclaims: "to ensure that no sequencing-quality errors are introduced" — trimming reduces the impact of quality errors, it doesn't guarantee none.
• L130 / L194 hg19: fine if that's what the KneadData reference-data table offers, but hg19 is dated. If a newer build is cached, prefer it; otherwise add a one-line note that this is the bundled KneadData database.
• L552–L556: please double-check the three event label strings (shared_strain, other_strain, same_clade) against the actual SameStr Summarize output values — they need to match exactly for readers to find them.

Missing explanation

• SGB is never defined. The results section leans entirely on identifiers like t__SGB4285, t__SGB15299, t__SGB6362 (L561, L572) but never explains that MetaPhlAn 4 reports species-level genome bins, what the t__ prefix means, or why a clade has a bin ID rather than a species name. Please add SGB (and "marker gene") to the key-terms box at L38 — this is essential for interpreting the final table.
• L45, the MVS definition is hard to parse: "the fraction of shared positions with enough coverage between two samples that contain at least one matching nucleotide" — the relative clause dangles. Suggest: "Of all positions covered in both samples, the fraction at which the two samples share at least one nucleotide variant."
• L338 / L342: the Flatten → Apply Rules step is by far the most error-prone action in the tutorial, and it's the only one with no snippet and no screenshot. A Rule Builder screenshot would help a lot. A one-sentence aside that this is a workaround for the tool's flat-list input requirement would also tell readers it isn't a conceptual step.
• L462, SameStr Stats: the details box discusses f_covered, f_mono and f_poly but shows no example output, unlike the Summarize section which gets three figures. Either add a figure or turn it into a question that has the learner read their own values.
• The results section is screenshot-only. The learner has just generated these exact outputs, so the text should direct them to open their datasets, with the figures as reference. As written, questions quoting 895 / 2783 / t__SGB4285 break if the screenshots or reference data ever change.

Workflow reference

L120 hard-codes a usegalaxy.eu published-workflow ID (8e13c87e751e88d8). Since the PR ships workflows/main_workflow.ga, please point at the GTN-hosted workflow instead — it appears on the tutorial's Workflows tab, works across servers, and stays in sync with the repo. The {% snippet faqs/galaxy/workflows_run_trs.md %} pattern is the usual approach. Also worth giving the .ga file a meaningful name rather than main_workflow.ga.

Markdown / GTN style

• L32: <!-- This is a comment. --> — leftover from the template, please delete.
• L203: snippet indentation is wrong. > {% snippet faqs/galaxy/tools_select_collection.md %} sits at one > level but needs to be indented under list item 1 (> ) like the other snippets. As-is it terminates the list, and step 2 at L210 will renumber as "1." The warning box right after it is at > >, so indentation is inconsistent within this one box.
• L213 / L215: wrong icon. These are collections but use {% icon param-file %} — should be {% icon param-collection %}.
• Outputs are named by internal API name rather than the label the user sees: paired_output / unmatched_paired (L207, L213, L215) and sam_output_file (L261). Please use the visible output names so learners can find them in the history.
• Inconsistent input references: most steps use (output of **Tool** {% icon tool %}), but L477–L478 refers to inputs by hands-on-box title ("the collection produced by the Remove Empty SNV Profile Datasets step"). Suggest standardizing on the former.
• L424 and L431: two separate hands-on boxes for two runs of the same tool. These can be merged into one box with steps 1 and 2.
• Heading case is mixed — "SamestrGal Workflow Overview", "Get data", "Pre-processing of reads with KneadData", "Taxon Counts table", "Co-occurrence table". GTN prefers sentence case; pick one and apply throughout.
• Trailing whitespace on L181, L379, L472, L552.
• The import URL list at L85–L90 is out of order: 28C_R1, 28C_R2, 28A_R1, 28B_R2, 28A_R2, 28B_R1. Sorting them (28A_R1, 28A_R2, 28B_R1, …) would let learners match them against the rename table at L97 — better still, rename the files on Zenodo to Donor_R1 etc. and drop the rename step entirely.
• Cross-file note: L80–L82 points learners to GTN - Material → {{ page.topic_name }}, but data-library.yaml still has the template placeholders name: New topic / description: Topic summary (and empty ext: ''), so that path won't exist. Setting the topic to Microbiome and ext: fastqsanger.gz would fix it.

Writing

Three paragraphs are single blocks of 470–1,035 characters and would read better as bulleted lists, especially since two of them are enumerations:

• L62 (851 chars) walks the entire pipeline in prose immediately before the workflow diagram. A numbered list would mirror the figure.
• L183 (1,035 chars) repeats "is another of the internal tools" three times. A list with one bullet each for Trimmomatic / TRF / FastQC / host removal would be much clearer.
• L579 (conclusion, 624 chars) is one paragraph that mostly restates key_points.

Smaller ones:

• L375: "Why do we have less datasets than before?" → "fewer".
• L449: "SameStr Stats produces one of the final outputs of the workflow, since its results are not required by any subsequent tool" — the "since" reverses cause and effect. Try: "SameStr Stats is a side branch of the workflow: its output is a final result and is not consumed by any later tool."
• L108: the #donor / #pre-fmt / #post-fmt tags are added "so they are easy to identify later in the workflow" but are never referenced again — the renaming in step 3 already does that job. Either drop the step or say what the tags are actually for (propagation through collections).

[xens25]

Hi @shiltemann , could I get a review on this tutorial? It's part of my thesis and should be ready for my submission. Appreciate any help!

[shiltemann]

@xens25 Thanks a lot for your contribution, I am happy to have a look at this :)

[shiltemann]

Thanks a lot @xens25! Very nice tutorial and workflow :)

I am testing the tutorial now, I have not made it to the end yet, so may add a few more comments later, but this way you can already get started.

[shiltemann]

I wonder if the title could be adapted to make it clearer for learners not familiar with the tool and acronyms.

Perhaps something closer to how you formulated your learning questions/objectives, e.g. "Detecting shared microbial strains across metagenomic samples"?
(unless this method is very specific to this type of data, or if the tool name is really something so popular people will look for that specifically)

What do you think? Up to you but maybe something to consider.

[shiltemann]

Is SamestrGal just SameStr for Galaxy? Maybe put that in parentheses because it confused me for a second that this acronym was not introduced yet.

[shiltemann]

Just so you are aware, you can also define these abbreviations in metadata, then use braces when you use them to link to their definition (if that is useful for you).

see here for more info https://galaxyproject.github.io/training-material/topics/contributing/tutorials/create-new-tutorial-content/tutorial.html#abbreviations

[shiltemann]

Tip: when writing tool names, you can use e.g. {% tool KneadData %} for a bit nicer formatting.

[shiltemann]

If we rename the files in Zenodo, people wont have to do this somewhat tedious renaming step in Galaxy.

Or skip the renaming and rely on the tags to know which is Pre/Donor/Post, which would also illustrate the usefulness of the tags.

[shiltemann]

I would be as explicit as possible in hands on boxes and match the names of the outputs in Galaxy exactly

Suggested change

	> - {% icon param-collection %} *"Taxonomic profile"*: the taxonomic profile collection produced by **MetaPhlAn** {% icon tool %}
	> - {% icon param-collection %} *"Taxonomic profile"*: `Predicted taxon relative abundances` collection produced by **MetaPhlAn** {% icon tool %}

[shiltemann]

this box seems a bit out of place here?

[shiltemann]

It might be worth briefly discussion the outputs after this step. Even if people cant view the binary outputs, just briefly mention what the SNV profile outputs are/contain.

And maybe worth having them look at the alignment stats output, do a bit of a QC check there?

[shiltemann]

The Apply rules tool is a complicated tool and not so widely known, so be as explicit as possible.

Setting list Identifier to column B involves more steps, e.g.

• clicking on "rules"
• click on "Add/Modify column definitions"
• ...

[shiltemann]

very nice that you added this :)

[xens25]

@shiltemann Thank you for all your feedback. I realized I had accidentally uploaded an older version of the tutorial, which is why some of your comments referenced content that was already outdated. I've now pushed the corrected version with your feedback applied. Let me know if there's anything else to change