Repository navigation
manuscript content integration - #49
Conversation
Things to check on the Read the Docs build
Side-note: |
<!-- PR guidance and examples: https://github.com/rachis-org/governance/blob/main/pr_template_guidelines.md --> <!-- rachis Generative AI Policy: https://github.com/rachis-org/governance/blob/main/ai_policy.md --> # Description <!-- REQUIRED: Briefly describe this PR, or link the issue it closes. --> Requirement of qiime2/gut-to-soil-tutorial#49 Allows an env var `Q2DOC_BASE_COMMAND` to be set per RTD project, which sets the preferred base command for the rendered usage examples. # AI Disclosure <!-- REQUIRED: Check exactly one option. --> - [x] NO AI USED. - [ ] AI USED.
|
hey @gregcaporaso i made a small change to update the rescript gtdb call. see this PR for reference: bokulich-lab/RESCRIPt#271 the tl;dr is that the particular gtdb version we are using (202.0) doesn't have the same content available on their new mirror (world-wide-europe), which is now the default db_url that's being used (instead of the previous primary vs mirror). the |
| ::: | ||
|
|
||
| #### Training our (suboptimal) 16S rRNA taxonomy classifier | ||
| Here we are going to train our [suboptimal](#suboptimal-classifier-explanation) 16S rRNA classifier. | ||
| The taxonomic classifier used here is trained on reference sequences and taxonomy from GTDB version 202.0, which is an old version of the GTDB reference database [@10.1093/nar/gkab776]. |
There was a problem hiding this comment.
This is probably the best place to add a brief explanation of the added db_url='australia' parameter (if you think that should be clarified) @gregcaporaso
There was a problem hiding this comment.
I think I'm just going to leave this as-is without mentioning it. Let's see if anyone asks (and if so, we can add a mention) and in the meantime I'll reach out to GTDB to see if they might be interested in mirroring those files too. If they know that we're going to be pointing people at them for educational processes, that might be a motivator to mirror the files, in which case we could drop the non-default.
| :label: fig-kmer-pcoa | ||
| :alt: Ordination of the averaged kmer Bray-Curtis distances | ||
|
|
||
| **Ordination of the averaged kmer Bray-Curtis distances.** Principal Coordinates Analysis (PCoA) scatter plots are a common way to visualize microbiome beta diversity. PCoA embeds the samples so that distances in the scatter plot approximate the distances in the `DistanceMatrix`, and the axes present how much of the total variance each coordinate explains. Each point represents a single sample, and coloring of points based on metadata is commonly used to aid in discovery of patterns. This plot suggests that through the composting process, the samples look less like fecal material and more like food compost in their microbial composition. The orientation of a PCoA axis is arbitrary. Here, axis 1 is drawn with human excrement at the left so the composting series reads left to right. The percentage on each axis is the share of the total variation in the distance matrix that the axis captures. That value is high here because this constructed data set has only six samples and was designed to model a simple transition along the composting time series; in real data with many samples and sources of variation a low percentage is normal. For example, the percent variation explained by Unweighted UniFrac PCoA axis 1 for Meilander et al. (2024) was 11.26% (the interactive Emperor plot is linked from https://doi.org/10.5281/zenodo.13887456). |
There was a problem hiding this comment.
| **Ordination of the averaged kmer Bray-Curtis distances.** Principal Coordinates Analysis (PCoA) scatter plots are a common way to visualize microbiome beta diversity. PCoA embeds the samples so that distances in the scatter plot approximate the distances in the `DistanceMatrix`, and the axes present how much of the total variance each coordinate explains. Each point represents a single sample, and coloring of points based on metadata is commonly used to aid in discovery of patterns. This plot suggests that through the composting process, the samples look less like fecal material and more like food compost in their microbial composition. The orientation of a PCoA axis is arbitrary. Here, axis 1 is drawn with human excrement at the left so the composting series reads left to right. The percentage on each axis is the share of the total variation in the distance matrix that the axis captures. That value is high here because this constructed data set has only six samples and was designed to model a simple transition along the composting time series; in real data with many samples and sources of variation a low percentage is normal. For example, the percent variation explained by Unweighted UniFrac PCoA axis 1 for Meilander et al. (2024) was 11.26% (the interactive Emperor plot is linked from https://doi.org/10.5281/zenodo.13887456). | |
| **Ordination of the averaged kmer Bray-Curtis distances.** Principal Coordinates Analysis (PCoA) scatter plots are a common way to visualize microbiome beta diversity. PCoA embeds the samples so that distances in the scatter plot approximate the distances in the `DistanceMatrix`, and the axes represent how much of the total variance each coordinate explains. Each point represents a single sample, and coloring of points based on metadata is commonly used to aid in discovery of patterns. This plot suggests that through the composting process, the samples look less like fecal material and more like food compost in their microbial composition. The orientation of a PCoA axis is arbitrary. Here, axis 1 is drawn with human excrement at the left so the composting series reads left to right. The percentage on each axis is the share of the total variation in the distance matrix that the axis captures. That value is high here because this constructed data set has only six samples and was designed to model a simple transition along the composting time series; in real data with many samples and sources of variation a low percentage is normal. For example, the percent variation explained by Unweighted UniFrac PCoA axis 1 for Meilander et al. (2024) was 11.26% (the interactive Emperor plot is linked from https://doi.org/10.5281/zenodo.13887456). |
There was a problem hiding this comment.
sorry, the diff of this suggestion is not helpful here. my suggestion was just to replace:
and the axes present how much of the total variance each coordinate explains
with:
and the axes represent how much of the total variance each coordinate explains
There was a problem hiding this comment.
I did specifically mean present here, since the axis labels present those values.
There was a problem hiding this comment.
Thanks for clarifying the diff!
lizgehret
left a comment
lizgehret
left a comment
There was a problem hiding this comment.
Hey @gregcaporaso overall this looks great, only a few small suggestions inline.
My one additional comment is that it might be a bit confusing for readers to 'suddenly' see QIIME 2 and rachis being used in a way that could be interpreted as 'interchangeably' (and to be fair, we are likely already doing this in our other tutorials, but this one I noticed at the beginning so figured it was worth bringing up). Take it or leave it, but it could be worth adding a small comment at the top of the tutorial distinguishing the two (or link off to a description elsewhere).
…igration) Replaces the tutorial page's prose with the text of the gut-to-soil manuscript (Google Doc export of 2026-09-15) in the manuscript's order, adds the manuscript's 'The data' section and diversity-metric discussion as collapsed dropdowns, places all 17 exercises with their Appendix 2 solutions adjacent, imports the 21 manuscript figures with their captions as MyST include fragments (docs/figures/, generated by the figures repository's make tutorial-figures), converts citations to doi: references and footnote URLs to inline links, and tags glossary terms with xref links. Commands stay as describe-usage blocks; kmer-diversity now samples without replacement; annotation-create, replay-provenance --recurse and make-report are plain shell blocks. MANUSCRIPT-INTEGRATION-REVIEW.md lists every substitution and open item for review. The prose is @gregcaporaso's. Claude Code transposed it into MyST, built the figure export, and made the mechanical substitutions listed in the review file; @gregcaporaso directed the structure and reviewed each step. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Figure 4 shows two example fastq files, not four; the constructed-dataset link targets the 'Constructed data for figures' subsection so the hover preview shows it; the TaxonomicClassifier paragraph is a note admonition; the differential-abundance warning moves inline in place of the 'As a word of caution' paragraph; the Conclusion closes with a 'A final word on the tutorial data' heading after the sign-off paragraph. Changes decided by @gregcaporaso on manual review; Claude Code applied them and updated the review file. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
An in-review citation with the full author list, requested by @gregcaporaso; wording of the lead-in by Claude Code. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Its open items move to the pull request's checklist and its decisions are recorded in the branch history, per @gregcaporaso. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
General text edits; unbold 'Demultiplexed sequence data' (no glossary entry backs it), spell Microbe Mix as in the metadata, fix a typo in the diversity dropdown, and drop the integration review list now that its open items live in the pull request. Edits by @gregcaporaso; the review-file removal was his call.
Move the why-HEC margin tip below the data dropdown and link it to the original-study subsection, link the metadata section to the tutorial-subset subsection and the closing word to the data dropdown, cite the study by DOI in the data section, list the figures covered in the diversity-background dropdown title, point readers at the project glossary, fix a verb agreement in the closing text, and expand the closing paragraph with the Compost Microbiome Lab link. Written by @gregcaporaso without AI assistance.
The port wrote every citation as a bare DOI link, which MyST renders as a narrative citation ('DADA2 Callahan et al. (2016)'). Citations that follow a name as a reference now use the [@doi] form and render parenthetically ('DADA2 (Callahan et al., 2016)'); the two in the data section that are the subject of their sentence stay narrative. 20 lines changed; the build links 19 DOIs with no warnings.
Style question raised by @gregcaporaso on review; change made by Claude Code.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Fix the Compost Microbiome Lab link in the closing paragraph, and apply three wording suggestions from the pull request review: 'stable down to low even sampling depths', 'we can be less concerned' in place of first person, and 'q2-composition plugin' as the link text. Link fix by @gregcaporaso; suggestions by @lizgehret, accepted by @gregcaporaso. No AI assistance in the content; Claude Code only folded the four commits into one when linearizing the branch. Co-authored-by: Liz Gehret <54517601+lizgehret@users.noreply.github.com>
6107807 to
cf1de42
Compare
|
One last build and review and then this should be good to go. |
@lizgehret - almost forgot to respond to this. The way I was approaching this was by saying that they first should read Getting Started with QIIME 2, which directly addresses this. This is here: 
|
Description
This PR integrates content from the gut-to-soil tutorial manuscript (now in review) to the online version of the tutorial. This is a large re-write of the content, which now includes solutions to all exercises, images based a constructed data set for help in understanding microbiome data types, and several new commands including Result annotation and Report generation.
AI Disclosure
AI Usage Details
No AI was used to write the manuscript text, the figure captions, or the updated glossary entries. Claude Code (Anthropic) was used extensively in preparing the constructed data set used in the Figures 3–21 (the remaining figures are screenshots), and to integrate content from Google Docs back into MyST. The words are human-written; AI was used to improve accessibility and facilitate building.