From f461b640999bc0ddee2f921d2436a0152f38cc84 Mon Sep 17 00:00:00 2001 From: Greg Caporaso Date: Fri, 17 Jan 2025 18:18:53 -0700 Subject: [PATCH 1/3] MAINT: update versions --- book/_config.yml | 3 ++- book/tutorials/intro.md | 46 ++++++++++++++++++----------------------- 2 files changed, 22 insertions(+), 27 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index c967efc..488c62b 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -54,7 +54,8 @@ html: parse: myst_substitutions: miniconda_url: "[Miniconda](https://conda.io/miniconda.html)" - release_epoch: "2024.5" + release_epoch: "2024.10" + development_epoch: "2025.4" tutorial_environment_block: | ````{admonition} Reminder :class: tip diff --git a/book/tutorials/intro.md b/book/tutorials/intro.md index 242aba3..8f2c0ec 100644 --- a/book/tutorials/intro.md +++ b/book/tutorials/intro.md @@ -27,28 +27,28 @@ conda update conda ## Install the QIIME 2 "Tiny Distribution" The QIIME 2 "Tiny Distribution" is a minimal set of QIIME 2 functionality for building and using plugins through the QIIME 2 command line or Python 3 API. -Here's we'll install the most recent release version of QIIME 2, QIIME 2 {{ release_epoch }}. +Here's we'll install the most recent development version of QIIME 2, QIIME 2 {{ development_epoch }}. -% Unfortunately we can't use MyST substitutions in literals, so including `{{ release_epoch }}` in the following install commands won't work. +% Unfortunately we can't use MyST substitutions in literals, so including `{{ development_epoch }}` in the following install commands won't work. % We need to figure out how we want to address this in the future to automatically update these commands on new releases. % Options are having a `latest` URL for release versions, or running a pre-processing script to update these docs before building them. `````{tab-set} ````{tab-item} macOS ```bash -conda env create -n using-qiime2 --file https://data.qiime2.org/distro/tiny/qiime2-tiny-2024.5-py39-osx-conda.yml +conda env create -n using-qiime2 --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-tiny-macos-latest-conda.yml ``` ```` ````{tab-item} Linux ```bash -conda env create -n using-qiime2 --file https://data.qiime2.org/distro/tiny/qiime2-tiny-2024.5-py39-linux-conda.yml +conda env create -n using-qiime2 --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-tiny-ubuntu-latest-conda.yml ``` ```` ````{tab-item} macOS (Apple Silicon) ```bash -CONDA_SUBDIR=osx-64 conda env create -n using-qiime2 --file https://data.qiime2.org/distro/tiny/qiime2-tiny-2024.5-py39-osx-conda.yml +CONDA_SUBDIR=osx-64 conda env create -n using-qiime2 --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-tiny-macos-latest-conda.yml conda activate using-qiime2 conda config --env --set subdir osx-64 ``` @@ -56,7 +56,7 @@ conda config --env --set subdir osx-64 ````{tab-item} Windows (via WSL) ```bash -conda env create -n using-qiime2 --file https://data.qiime2.org/distro/tiny/qiime2-tiny-2024.5-py39-linux-conda.yml +conda env create -n using-qiime2 --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-tiny-ubuntu-latest-conda.yml ``` ```` @@ -80,19 +80,16 @@ You should see something like the following, though the version numbers you'll s ``` System versions -Python version: 3.9.19 -QIIME 2 release: 2024.5 -QIIME 2 version: 2024.5.1 -q2cli version: 2024.5.0 +Python version: 3.10.14 +QIIME 2 release: 2025.4 +QIIME 2 version: 2025.4.0.dev0+11.g85975ad +q2cli version: 2025.4.0.dev0+8.g63d82cb Installed plugins -types: 2024.5.0 +metadata: 2025.4.0.dev0+5.g7af916f +types: 2025.4.0.dev0+6.g11e14d8 -Application config directory -/Users/jgc/miniconda3/envs/using-qiime2/var/q2cli - -Getting help -To get help with QIIME 2, visit https://qiime2.org +... ``` At this stage you have a working QIIME 2 environment, but it doesn't do a whole lot. @@ -113,20 +110,17 @@ If you run `qiime info` again, you should now see a new plugin, `dwq2`, in the l ``` System versions -Python version: 3.9.19 -QIIME 2 release: 2024.5 -QIIME 2 version: 2024.5.1 -q2cli version: 2024.5.0 +Python version: 3.10.14 +QIIME 2 release: 2025.4 +QIIME 2 version: 2025.4.0.dev0+11.g85975ad +q2cli version: 2025.4.0.dev0+8.g63d82cb Installed plugins dwq2: 0+unknown -types: 2024.5.0 - -Application config directory -/Users/jgc/miniconda3/envs/using-qiime2/var/q2cli +metadata: 2025.4.0.dev0+5.g7af916f +types: 2025.4.0.dev0+6.g11e14d8 -Getting help -To get help with QIIME 2, visit https://qiime2.org +... ``` ## Exploring the available functionality From 0a3e51d7e07c641dd5ad00bbe5ebcaba82708107 Mon Sep 17 00:00:00 2001 From: Greg Caporaso Date: Fri, 17 Jan 2025 18:38:27 -0700 Subject: [PATCH 2/3] update environment name to differentiate it from the one used in the tutorial. i don't think this is actually used anywhere, but i noticed it so might as well change it. --- environment.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/environment.yml b/environment.yml index 34e82f3..ac477cd 100644 --- a/environment.yml +++ b/environment.yml @@ -1,4 +1,4 @@ -name: using-qiime2 +name: using-qiime2-dev channels: - https://packages.qiime2.org/qiime2/2024.10/tiny/passed - conda-forge From 723a332dc6db0c8fd4bfa2bf624d1b0f20f3acf4 Mon Sep 17 00:00:00 2001 From: Greg Caporaso Date: Fri, 17 Jan 2025 18:39:14 -0700 Subject: [PATCH 3/3] various minor edits --- book/intro.md | 21 +++++++++++---------- book/tutorials/use-the-artifact-cache.md | 2 +- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/book/intro.md b/book/intro.md index 44a1cb6..58197fa 100644 --- a/book/intro.md +++ b/book/intro.md @@ -1,11 +1,11 @@ # *Using QIIME 2* -**Make QIIME 2 work for you.** +**Your guide to becoming a QIIME 2 Framework power user.** ```{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 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. +Over the next few months (as of 17 January 2025), 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. @@ -14,11 +14,11 @@ The canonical URL for this project is https://use.qiime2.org. ## 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. +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). +That includes things like [using `Artifacts` as metadata](metadata-merge), replaying provenance[^replaying-provenance-issue], [creating and using an artifact cache](artifact-cache-tutorial) 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.** +Generally speaking, **understanding these topics will help you understand what you're doing and empower you to become a QIIME 2 Framework 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. @@ -26,12 +26,12 @@ In addition to *Using QIIME 2*, we are building distribution-specific and plugin ### 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*. +For example, you can start there to get instructions on how to [install QIIME 2](https://docs.qiime2.org/2024.10/install/), use it to carry out an [analysis of microbiome amplicon data](https://docs.qiime2.org/2024.10/tutorials/moving-pictures-usage/), and [see a reference](https://docs.qiime2.org/2024.10/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]. +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](https://library.qiime2.org)[^new-library-wip]. 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 @@ -94,6 +94,7 @@ Initial support for the development of QIIME 2 was provided through a [grant](ht

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 +[^new-library-wip]: The new QIIME 2 Library is in the early stages of development (as of 17 January 2025) - a lot of exciting new functionality for both users and developers is currently in progress! +For the time-being, you can still find the old QIIME 2 Library at https://old-library.qiime2.org. +[^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/book/tutorials/use-the-artifact-cache.md b/book/tutorials/use-the-artifact-cache.md index ca93995..6e0ef15 100644 --- a/book/tutorials/use-the-artifact-cache.md +++ b/book/tutorials/use-the-artifact-cache.md @@ -1,7 +1,7 @@ (artifact-cache-tutorial)= # Using an Artifact Cache -The artifact cache allows users to have finer control over where and how QIIME 2 {term}`Results ` are stored on disk. +An artifact cache allows users to have finer control over where and how QIIME 2 {term}`Results ` are stored on disk. Artifact caches serve two primary purposes: 1. Providing the user with control over where QIIME 2 stores its working (temporary) files.