diff --git a/book/_static/dwq2-dark.png b/book/_static/dwq2-dark.png index 8d01292..6e75b30 100644 Binary files a/book/_static/dwq2-dark.png and b/book/_static/dwq2-dark.png differ diff --git a/book/_static/dwq2-light.png b/book/_static/dwq2-light.png index 89ef6b0..e2a8c0d 100644 Binary files a/book/_static/dwq2-light.png and b/book/_static/dwq2-light.png differ diff --git a/book/_static/favicon.ico b/book/_static/favicon.ico old mode 100755 new mode 100644 diff --git a/book/back-matter/glossary.md b/book/back-matter/glossary.md index 62981fa..aadc170 100644 --- a/book/back-matter/glossary.md +++ b/book/back-matter/glossary.md @@ -18,11 +18,30 @@ breaking change For example, if a plugin method added a new required input in version 2, that would be a breaking change with respect to version 1: calling the method without that new parameter would fail in version 2, but would have succeeded with version 1. This may also be called a backward incompatible change or an API change. +Conda metapackage + A metapackage is a package with no files, only metadata. + They are typically used to collect several packages together into a single package via dependencies. + ([source](https://docs.conda.io/projects/conda-build/en/stable/resources/commands/conda-metapackage.html)) + +Deployment + An installation of QIIME 2 as well as zero-or-more {term}`interfaces ` and {term}`plugins `. + The collection of interfaces and plugins in a deployment can be defined by a {term}`distribution` of QIIME 2. + +Distribution + A collection of QIIME 2 plugins that are installed together through a single {term}`conda metapackage`. + These are generally grouped by a theme. For example, the *amplicon distribution* provides a collection of plugins for analysis of microbiome amplicon data, while the *metagenome distribution* provides a collection of plugins for analysis of microbiome shotgun metagenomics data. + When a distribution is installed, that particular installation of QIIME 2 is an example of a {term}`deployment`. + DRY An acronym of *Don't Repeat Yourself*, and a critical principle of software engineering and equally applicable in research data management. For more information on DRY and software engineering in general, see {cite:t}`pragprog20`. The {cite:t}`pragprog20` content on DRY is available in a [free example chapter here](https://media.pragprog.com/titles/tpp20/dry.pdf). +Interface + The layer of QIIME 2 that users (either humans or other computer software) interact with. + {term}`q2cli` and the {term}`Python 3 API` are the two interfaces covered in *Using QIIME 2*. + Other interfaces include *Galaxy* (see https://cancer.usegalaxy.org) and Adagio (more info on that soon!). + method A type of QIIME 2 {term}`action` that takes one or more {term}`artifacts ` or {term}`parameters ` as input, and produces one or more {term}`artifacts ` as output. For example, the `filter-features` {term}`action` in the `q2-feature-table` {term}`plugin` is a {term}`method`. diff --git a/book/intro.md b/book/intro.md index be38fdf..44a1cb6 100644 --- a/book/intro.md +++ b/book/intro.md @@ -4,16 +4,45 @@ ```{admonition} Development status of this content :class: note -*Using QIIME 2* is in an early stage of development, and as a result the documentation at https://docs.qiime2.org is still your best source for learning to use QIIME 2. -Over the next few months (as of 16 September 2024), existing content will be migrated and new content will developed, and ultimately *Using QIIME 2* will replace all content at https://docs.qiime2.org. +*Using QIIME 2* is in an early stage of development, and as a result the documentation at https://docs.qiime2.org is still an important source of information for learning to use QIIME 2. +Over the next few months (as of 10 October 2024), existing content will be migrated and new content will developed. +Ultimately https://docs.qiime2.org will be retired. While *Using QIIME 2* is in development, some URLs may change. -You can find some details on the plan for the development of *Using QIIME 2* [here](https://develop.qiime2.org/en/latest/docs/user-documentation.html). - The canonical URL for this project is https://use.qiime2.org. ``` -The content in each part of this book is organized under the [Diátaxis](https://diataxis.fr/) framework {cite}`diataxis`, which organizes content into *Chapters* containing *Tutorials*, *How-To-Guides*, *Explanations*, and *References*. +## Goals and development plan for *Using QIIME 2* + +As the ecosystem of QIIME 2 {term}`distributions ` and {term}`plugins ` continues to grow, it has become necessary to make a split in the documentation between general-purpose information that describes how to use QIIME 2 itself (i.e., "the QIIME 2 framework" 🌳), and how to apply the tools it supports to achieve your data analysis goals. +We know that you're interested in QIIME 2 primarily for the latter -- to achieve specific analysis goals related to microbiome data science -- so our goal is that *Using QIIME 2* serves primarily as a source for you to refer to when you need to accomplish specific tasks that are general to using the system. +That includes things like [using `Artifacts` as metadata](metadata-merge), replaying provenance[^replaying-provenance-issue], and [configuring your parallel computing environment](parallel-configuration). +It will also include explanations that can help you understand the system when you want to go deeper, including things like what QIIME 2 {term}`Artifacts ` (e.g., {term}`.qza ` files) and {term}`Visualizations ` (e.g., {term}`.qzv ` files) are[^result-explanation-issue], and why you need to import your data into `Artifacts` before using QIIME 2[^importing-explanation-issue]. +Generally speaking, **understanding these topics will help you understand what you're doing and empower you to become a QIIME 2 power user, but they aren't strictly necessary to perform simple data analysis.** + +In addition to *Using QIIME 2*, we are building distribution-specific and plugin-specific documentation. +**These will be designed to quickly get you started with performing your first data analysis with QIIME 2,** and will fall into a few categories. + +### Distribution-specific documentation + +The "old" user documentation at https://docs.qiime2.org serves this purpose for the *amplicon distribution*. +For example, you can start there to get instructions on how to [install QIIME 2](https://docs.qiime2.org/2024.5/install/), use it to carry out an [analysis of microbiome amplicon data](https://docs.qiime2.org/2024.5/tutorials/moving-pictures-usage/), and [see a reference](https://docs.qiime2.org/2024.5/plugins/) of the {term}`plugins ` and {term}`actions ` that are included in the *amplicon distribution*. +That user documentation predates the diverse distributions and plugins that now exist in the ecosystem - it therefore mixes distribution-specific information with the general purpose information that is currently being transitioned to *Using QIIME 2*. + +### Plugin-specific documentation + +Stand-alone plugins (i.e., those not included in existing distributions), like [q2-boots](https://github.com/caporaso-lab/q2-boots), will provide their own documentation linked from the new QIIME 2 Library[^new-library-not-live]. +For now, you can refer to the [q2-boots documentation here](https://q2-boots.readthedocs.io/en/latest/), as an example of where we're going. + +### Data-set specific documentation + +Finally we'll also have some documentation that is focused on analysis of specific interesting data sets. +A good current example of this is the [QIIME 2 **C**ancer **A**utoFMT **T**utorial (q2-cat-book)](https://q2-cat-book.readthedocs.io/en/latest/). +This may sometimes cross distributions and stand-alone plugins, for example perhaps integrating tools from the *amplicon* and *metagenome* distributions to analyze paired 16S and metagenome data. + +## Organization of *Using QIIME 2* + +*Using QIIME 2* is organized under the [Diátaxis](https://diataxis.fr/) framework {cite}`diataxis`, which categorizes content into *sections* containing *Tutorials*, *How-To-Guides*, *Explanations*, and *References*. Each serves a different goal for the reader: ```{list-table} @@ -35,6 +64,7 @@ Each serves a different goal for the reader: - Provide specific **information** (e.g., a list of utilities available through {term}`q2cli`). ``` +You can navigate these sections on the left sidebar. (acknowledgements)= ## Acknowledgements @@ -62,3 +92,8 @@ Initial support for the development of QIIME 2 was provided through a [grant](ht ## License

Using QIIME 2 led by Greg Caporaso is licensed under CC BY-NC-ND 4.0 .

+ +[^replaying-provenance-issue]: See [here](https://github.com/caporaso-lab/using-qiime2/issues/13). + [^new-library-not-live]: The new QIIME 2 Library is not yet live, but will be soon (as of 10 October 2024). + [^result-explanation-issue]: See [here](https://github.com/caporaso-lab/using-qiime2/issues/11). + [^importing-explanation-issue]: See [here](https://github.com/caporaso-lab/using-qiime2/issues/12). \ No newline at end of file diff --git a/environment.yml b/environment.yml index 6d86511..34e82f3 100644 --- a/environment.yml +++ b/environment.yml @@ -6,5 +6,7 @@ channels: dependencies: - qiime2-tiny - jupyter-book + - pip - pip: - - q2doc @ git+https://github.com/qiime2/sphinx-ext-qiime2.git@master \ No newline at end of file + - q2doc @ git+https://github.com/qiime2/sphinx-ext-qiime2.git@master + - q2-dwq2 @ git+https://github.com/caporaso-lab/q2-dwq2.git@main \ No newline at end of file