Merge branch 'dev' of https://github.com/qiime2/q2-fmt into finishing…

…-touches

README.md

@@ -2,125 +2,9 @@
 Note: This software is in **Alpha release** and interfaces are subject to change.
 ![](https://github.com/qiime2/q2-fmt/actions/workflows/ci-dev.yaml/badge.svg)
 
+q2-fmt is a [QIIME2](https://qiime2.org/) plugin providing all-in-one suite for assessing engraftment extent following Fecal Microbiota Transplants! 
+
+To learn more about installing and using q2-fmt, refer to the [q2-fmt documentation](https://q2-fmt.readthedocs.io/)
 ## Demo
 [![](https://raw.githubusercontent.com/qiime2/q2-fmt/master/demo/screenshot.png)
 **Interactive Link**](https://view.qiime2.org/visualization/?type=html&src=https%3A%2F%2Fraw.githubusercontent.com%2Fqiime2%2Fq2-fmt%2Fmaster%2Fdemo%2Fraincloud-baseline0.qzv)
-
-## Installation
-
-Please note that this software is now an alpha release. Initial conda packages are available, but have not been tested in integration against our other plugins yet. For now, create a fresh conda environment for q2-fmt using the following command: 
-
-Note: This is a `Development` install of q2-fmt
-Mac OS instructions 
-```bash
-CONDA_SUBDIR=osx-64 conda env create \
- -n q2-fmt-2024.10 \
- -f https://raw.githubusercontent.com/qiime2/q2-fmt/dev/environment-files/2024.10-q2-fmt-environment.yml
-```
-
-Linux instructions
-```bash
-conda env create \
- -n q2-fmt-2024.10 \
- -f https://raw.githubusercontent.com/qiime2/q2-fmt/dev/environment-files/2024.10-q2-fmt-environment.yml
-```
-
-Then activate your new environment as usual.
-```bash
-conda activate q2-fmt-2024.10
-```
-
-## Examples
-Example data can be generated using the `--example-data` flag on each action
-described below. This will create a directory structure to match the examples
-(you will need to `cd` into the appropriate directory first).
-
-```bash
-qiime fmt --example-data fmt-examples/
-cd fmt-examples/cc/cc-baseline/
-```
-
-**Plot Engraftment**
-
-This pipeline will execute the below actions in order to produce engraftment
-plots in a single step. To learn more, see the examples below this.
-```bash
-qiime fmt cc \
-  --i-diversity-measure div-measure.qza \
-  --m-metadata-file md.tsv \
-  --p-compare baseline \
-  --p-time-column week \
-  --p-reference-column InitialDonorSampleID \
-  --p-subject-column SubjectID \
-  --p-where '[SampleType]="stool"' \
-  --p-filter-missing-references \
-  --p-against-group 0 \
-  --p-p-val-approx asymptotic \
-  --o-stats stats.qza \
-  --o-raincloud-plot raincloud-plot.qzv
-```
-
----
-
-**Group Timepoints**
-
-First the data must be collected from your study and organized into groups with
-some relevant diversity measure. We will use Faith's Phylogenetic Diversity in
-these examples, but other measures, including beta diversity metrics, are
-supported.
-
-This command will produce two collections of groups: one for subjects at each
-timepoint, and another for references/donors and any control groups.
-```bash
-qiime fmt group-timepoints \
-  --i-diversity-measure div-measure.qza \
-  --m-metadata-file md.tsv \
-  --p-where '[SampleType]="stool"' \
-  --p-time-column week \
-  --p-reference-column InitialDonorSampleID \
-  --p-subject-column SubjectID \
-  --p-filter-missing-references \
-  --o-timepoint-dists timepoint-dists.qza \
-  --o-reference-dists reference-dists.qza
-```
-
-**Statistical Tests**
-
-Wilcoxon Signed Rank tests and Mann-Whitney U tests are available through
-[q2-stats](https://github.com/qiime2/q2-stats) and can be used for FMT analysis.
-These two tests are differentiated by the semantic type of the input to ensure
-the applicability of the test (i.e. only matched pairs for Wilcoxon,
-and independent groups for Mann-Whitney).
-
-Comparisons for Wilcoxon Signed Rank:
- - baseline: Compare each timepoint against a reference timpoint
- - consecutive: Compare each timepoint against its next timepoint
-
-Comparisons for Mann-Whitney U:
- - reference: Compare other groups against a particular reference group
- - all-pairwise: Compare all pairwise groups.
-
-The `against-each` parameter is needed to compare the timepoints against the
-references/controls. The `engraftment` pipeline above does this
-automatically.
-
-```bash
-qiime stats wilcoxon-srt \
-  --i-distribution timepoint-dists.qza \
-  --p-compare baseline \
-  --p-baseline-group 0 \
-  --p-p-val-approx asymptotic \
-  --o-stats stats_baseline0.qza
-```
-
-**Raincloud Plots**
-
-Also available through [q2-stats](https://github.com/qiime2/q2-stats) -
-a statistical test is not required to generate the plots, but if provided,
-will produce a table showing the results of the test.
-```bash
-qiime stats plot-rainclouds \
-  --i-data timepoint-dists.qza \
-  --i-stats stats_baseline0.qza \
-  --o-visualization raincloud-baseline0.qzv
-```

book/q2_fmt_book/_config.yml

@@ -8,7 +8,7 @@
 title                       : q2-fmt book  # The title of the book. Will be placed in the left navbar.
 author                      : Chloe Herman  # The author of the book
 copyright                   : "2024"  # Copyright year to be placed in the footer
-logo                        : logo.png  # A path to the book logo
+logo                        : _images/logo.png  # A path to the book logo
 
 # Force re-execution of notebooks on each build.
 # See https://jupyterbook.org/content/execute.html
@@ -26,12 +26,21 @@ bibtex_bibfiles:
 
 # Information about where the book exists on the web
 repository:
-  url: https://github.com/cherman2/q2-fmt book  # Online location of your book
+  url: https://github.com/qiime2/q2-fmt/book  # Online location of your book
   path_to_book: book  # Optional path to your book, relative to the repository root
   branch: dev  # Which branch of the repository should be used when creating links (optional)
 
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
 html:
   use_issues_button: true
-  use_repository_button: true
+  use_repository_button: true
+
+
+sphinx:
+  extra_extensions:
+    - q2doc.usage
+    - q2doc.external_links
+    - sphinx_exercise
+  config:
+    html_baseurl: https://q2-fmt.readthedocs.io/en/latest

book/q2_fmt_book/_toc.yml

@@ -3,7 +3,21 @@
 
 format: jb-book
 root: intro
-chapters:
-- file: markdown
-- file: notebooks
-- file: markdown-notebooks
+parts:
+- caption: Tutorial
+  chapters:
+    - file: tutorial/tutorial
+- caption: How-To Guides
+  chapters: 
+    - file: how-to-guides/installation
+- caption: Explanation
+  chapters: 
+    - file: explanation/placeholder
+- caption: Reference
+  chapters: 
+    - file: reference/reference
+- caption: Back Matter
+  chapters:
+    - file: works-cited
+
+

book/q2_fmt_book/explanation/placeholder.md

@@ -0,0 +1,5 @@
+# Explanations
+
+This section of the q2-fmt docs is currently under 🛠️ development 🧰! 
+
+Check back soon for more information on explanations of the methods in q2-fmt! 

book/q2_fmt_book/how-to-guides/installation.md

@@ -0,0 +1,37 @@
+# Installation
+
+Please note that this software is now an *alpha release* and interfaces are subject to change. 
+For now, create a fresh  `Development` conda environment for q2-fmt using the following command: 
+
+These installation installs will have the classic qiime2 amplicon env and q2-fmt.
+
+
+Mac OS instructions 
+```bash
+CONDA_SUBDIR=osx-64 conda env create \
+ -n q2-fmt-2024.10 \
+ -f https://raw.githubusercontent.com/qiime2/q2-fmt/dev/environment-files/2024.10-q2-fmt-environment.yml
+```
+
+Linux instructions
+```bash
+conda env create \
+ -n q2-fmt-2024.10 \
+ -f https://raw.githubusercontent.com/qiime2/q2-fmt/dev/environment-files/2024.10-q2-fmt-environment.yml
+```
+
+Then activate your new environment as usual.
+```bash
+conda activate q2-fmt-2024.10
+```
+
+## Updating an existing env to have q2-fmt 
+
+If you have an existing qiime2 env that you want to install q2-fmt in, please run the following command: 
+```bash 
+conda activate <env-name> # conda env you wish to install this plugin into
+
+conda env update --file https://raw.githubusercontent.com/qiime2/q2-fmt/dev/environment-files/2024.10-q2-fmt-environment.yml
+```
+
+Awesome! Now, you are ready to start assessing engraftment extent with q2-fmt!

book/q2_fmt_book/intro.md

@@ -1,11 +1,48 @@
-# Welcome to your Jupyter Book
+# QIIME 2 FMT Book
 
-This is a small sample book to give you a feel for how book content is
-structured.
-It shows off a few of the major file types, as well as some sample content.
-It does not go in-depth into any particular topic - check out [the Jupyter Book documentation](https://jupyterbook.org) for more information.
+This tutorial was orignally made for the 2024 [ITN](https://www.itcrtraining.org/) / [QIIME 2](https://qiime2.org) Workshop, taught 27 - 29 August 2024 at the National Institutes of Health. 
+If you are interested in the original workshop tutorial, please visit: https://q2-cat-book.readthedocs.io/en/2024.08.27-q2-itn/. 
+This tutorial is now the offical documentation for the q2-fmt plugin.
 
-Check out the content pages bundled with this sample book to see more.
+```{admonition} Code of Conduct
+Please review the [QIIME 2 Community Code of Conduct](https://forum.qiime2.org/t/qiime-2-community-code-of-conduct/9057).
+All workshop instructors agreed to abide by these community expectations and we hope you will too as you become involved in the QIIME 2 community.
+```
+
+This tutorial will walk you through all the functionality available in q2-fmt. 
+We will start with a metadata file and feature table. 
+We will discuss choosing an even sampling depth and generating diversity metrics so that we are prepared to run our data through q2-fmt.
+Grab a cup of coffee or tea ☕, and lets jump right in!
+
+## Recommended readings
+
+The following readings will provide background information for this tutorial.
+These are presented in priority order.
+
+1. [_Assessing Engraftment Following Fecal Microbiota Transplant_](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC11042410/) ({cite:t}`herman_2024`)
+1. [_Reconstitution of the gut microbiota of antibiotic-treated patients by autologous fecal microbiota transplant_](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6468978/) ({cite:t}`taur-autofmt-2018`)
+1. [_Compilation of longitudinal microbiota data and hospitalome from hematopoietic cell transplantation patients_](https://www.nature.com/articles/s41597-021-00860-8) ({cite:t}`liao-data-2021`)
+1. [_Reproducible, interactive, scalable and extensible microbiome data science using QIIME 2_](https://doi.org/10.1038/s41587-019-0209-9) ({cite:t}`bolyen-qiime2-2019`)
+1. [_q2-longitudinal: Longitudinal and Paired-Sample Analyses of Microbiome Data_](http://dx.doi.org/10.1128/mSystems.00219-18) ({cite:t}`bokulich-q2long-2018`)
+1. [Getting started with QIIME 2](https://gregcaporaso.github.io/q2book/using/getting-started.html)
+1. [_Experiences and lessons learned from two virtual, hands-on microbiome bioinformatics workshops_](https://doi.org/10.1371/journal.pcbi.1009056) ({cite:t}`dillon-workshops-2021`)
+
+## Thank you to our funders
+
+This tutorial  was funded in part by NIH National Cancer Institute Informatics Technology for Cancer Research grant [1U24CA248454-01](https://reporter.nih.gov/project-details/9951750) to JGC.
+
+The preparation and dissemination of the data used in this tutorial was funded in part by the National Institutes of Health (NIH) grants U01 AI124275, R01 AI137269 and U54 CA209975 to Joao B. Xavier.
+
+This website is built with MyST Markdown and Jupyter Book, which are supported in part with [funding](https://sloan.org/grant-detail/6620) from the Alfred P. Sloan Foundation.
+
+## Reusing
+
+ <p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://q2-fmt.readthedocs.io/en/latest/intro.html">q2-fmt-book</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://cap-lab.bio">Caporaso Lab</a> is licensed under <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/?ref=chooser-v1" target="_blank" rel="license noopener noreferrer" style="display:inline-block;">CC BY-NC-SA 4.0.<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/nc.svg?ref=chooser-v1" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/sa.svg?ref=chooser-v1" alt=""></a></p>
+
+ You are free distribute, remix, adapt, and build upon the material in any medium or format, for noncommercial purposes only, as long as credit is given to the original creator. Adaptations must be shared under the same terms.
+
+
+## Table of Contents
 
 ```{tableofcontents}
-```
+```