diff --git a/book/back-matter/glossary.md b/book/back-matter/glossary.md index 2919adb..e3e4fb9 100644 --- a/book/back-matter/glossary.md +++ b/book/back-matter/glossary.md @@ -42,7 +42,7 @@ Directory Format 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 MOSHPIT (previously the *metagenome distribution*) provides a collection of plugins for analysis of microbiome shotgun metagenomics data. + These are generally grouped by a theme. For example, the *qiime2 distribution* provides a collection of plugins for analysis of microbiome amplicon data, while MOSHPIT (previously 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 diff --git a/book/plugins/how-to-guides/automate-testing.md b/book/plugins/how-to-guides/automate-testing.md index e0d80c3..e2b5138 100644 --- a/book/plugins/how-to-guides/automate-testing.md +++ b/book/plugins/how-to-guides/automate-testing.md @@ -119,7 +119,7 @@ With the bracketed terms defined as: - ``: the next QIIME 2 release epoch. QIIME 2 releases are scheduled for the first Wednesday of April and October, so this value is always predictable. For example, if the most recent release was 2024.10, your `` would be 2025.4. -- ``: the QIIME 2 distribution that your plugin should be installed under (e.g., `amplicon` or `moshpit`). +- ``: the rachis distribution that your plugin should be installed under (e.g., `qiime2` or `moshpit`). - `` (optional): the branch of your repository that testing will be performed against. If not specified, this will default to your repository's *Default branch* (e.g., `main`). If you don't include this, you should leave off the `@` symbol following `.git`. You can set up any additional GHAs on your repository that you feel will be beneficial to your plugin and general development workflow. diff --git a/book/plugins/how-to-guides/distribute-on-gh.md b/book/plugins/how-to-guides/distribute-on-gh.md index 6dcf8ed..51c19ca 100644 --- a/book/plugins/how-to-guides/distribute-on-gh.md +++ b/book/plugins/how-to-guides/distribute-on-gh.md @@ -16,7 +16,7 @@ The GitHub command line interface is used here as it's easier to document and te Create a new template plugin, according to the instructions in [](plugin-from-template). Pay attention to the question about the "target distribution" - this enables templating of installation instructions and test machinery against the distribution of your choice. -For example, if you want your plugin to expand upon the `amplicon` distribution, this is where you indicate that. +For example, if you want your plugin to expand upon the `qiime2` distribution, this is where you indicate that. After completing those steps, return to this page. diff --git a/book/plugins/how-to-guides/facilitate-installation.md b/book/plugins/how-to-guides/facilitate-installation.md index e233ba6..704eeed 100644 --- a/book/plugins/how-to-guides/facilitate-installation.md +++ b/book/plugins/how-to-guides/facilitate-installation.md @@ -1,3 +1,5 @@ +/// TODO: this needs a bit of an overhaul to handle our updated naming scheme (to prevent confusion for people moving forward) + (facilitating-installation)= # Facilitating installation of your plugin for users diff --git a/book/plugins/how-to-guides/maximize-compatibility.md b/book/plugins/how-to-guides/maximize-compatibility.md index abf440b..e2a8a04 100644 --- a/book/plugins/how-to-guides/maximize-compatibility.md +++ b/book/plugins/how-to-guides/maximize-compatibility.md @@ -15,7 +15,7 @@ The Caporaso Lab is not taking on new responsibility for distributing plugins ri You can consider the existing distributions to be foundations that you can build on, or you can create and distribute your own conda metapackages. Some guidance on each of these approaches: - - Your install instructions can indicate that a user should install whichever distribution you depend on (e.g., `tiny`, `amplicon`, or `moshpit`) and then illustrate how to install your plugin(s) in that environment however it makes sense (e.g., `conda` or `pip`). Complete install instructions are drafted for you in the `README.md` of plugins that you build using our template (see [](plugin-from-template)). + - Your install instructions can indicate that a user should install whichever distribution you depend on (e.g., `tiny`, `qiime2`, `moshpit`, etc) and then illustrate how to install your plugin(s) in that environment however it makes sense (e.g., `conda` or `pip`). Complete install instructions are drafted for you in the `README.md` of plugins that you build using our template (see [](plugin-from-template)). - Alternatively, you can compose and share your own distribution of plugins (e.g., building from the `tiny` distribution) that captures the set of functionality you’d like to share. Either of these approaches is totally fine, with the following caveats. @@ -29,4 +29,4 @@ With the above information in mind, refer to [](facilitating-installation) for i You can request feedback on your plugin as a whole from more experienced QIIME 2 developers by reaching out through the {{ developer_discussion }}. However, be cognizant of the fact that doing code review takes a long time to do well: you should only request this when you feel like you have a final draft of the plugin that you'd like to release, and expect that the reviewer may point out that there is a bunch more work that should be done before you release. Please have others who you work closely with -- ideally experienced software developers, and even more ideally experienced QIIME 2 plugin developers -- review it first. -If you have questions along the way, you can ask those whenever - just be sure to review *[Developing with QIIME 2](https://develop.qiime2.org/)* and search the forum in case your question has already been answered previously. \ No newline at end of file +If you have questions along the way, you can ask those whenever - just be sure to review *[Developing with QIIME 2](https://develop.qiime2.org/)* and search the forum in case your question has already been answered previously. diff --git a/book/plugins/how-to-guides/set-up-development-environment.md b/book/plugins/how-to-guides/set-up-development-environment.md index bce770e..2a0faf3 100644 --- a/book/plugins/how-to-guides/set-up-development-environment.md +++ b/book/plugins/how-to-guides/set-up-development-environment.md @@ -33,7 +33,7 @@ conda update conda The QIIME 2 "Tiny Distribution" is a minimal set of QIIME 2 functionality for building and using plugins through the QIIME 2 command line, and is intended for use by developers who want a minimal QIIME 2 environment to work in. ```{note} -We recommend starting your development with the "Tiny Distribution", unless you specifically need plugins that are installed in other QIIME 2 distributions, such as the Amplicon Distribution or MOSHPIT (previously known as the Metagenome Distribution), in which case see [](other-distros). +We recommend starting your development with the "Tiny Distribution", unless you specifically need plugins that are installed in other rachis distributions, such as the QIIME 2 Distribution or MOSHPIT (previously known as the Metagenome Distribution), in which case see [](other-distros). ``` ```{note} @@ -44,28 +44,27 @@ Things change relatively quickly with development environments, so it doesn't hu `````{tab-set} -````{tab-item} macOS +````{tab-item} macOS (x86_64) ```bash __Q2DEV_ENV_NAME=q2dev-tiny-$(date "+%Y-%m-%d") -conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-tiny-macos-latest-conda.yml +conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/rachis-tiny-osx-64-conda.yml conda activate $__Q2DEV_ENV_NAME ``` ```` -````{tab-item} Linux +````{tab-item} Linux (x86_64) ```bash __Q2DEV_ENV_NAME=q2dev-tiny-$(date "+%Y-%m-%d") -conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-tiny-ubuntu-latest-conda.yml +conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/rachis-tiny-linux-64-conda.yml conda activate $__Q2DEV_ENV_NAME ``` ```` -````{tab-item} macOS (Apple Silicon) +````{tab-item} macOS (ARM64) ```bash __Q2DEV_ENV_NAME=q2dev-tiny-$(date "+%Y-%m-%d") -CONDA_SUBDIR=osx-64 conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-tiny-macos-latest-conda.yml +conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/rachis-tiny-osx-arm64-conda.yml conda activate $__Q2DEV_ENV_NAME -conda config --env --set subdir osx-64 ``` ```` ````` @@ -136,29 +135,29 @@ make test (other-distros)= ## Installing other QIIME 2 distributions -### Amplicon distribution +### qiime2 (previously known as the *Amplicon distribution*) `````{tab-set} -````{tab-item} macOS +````{tab-item} macOS (x86_64) ```bash -__Q2DEV_ENV_NAME=q2dev-amplicon-$(date "+%Y-%m-%d") -conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-amplicon-macos-latest-conda.yml +__Q2DEV_ENV_NAME=q2dev-qiime2-$(date "+%Y-%m-%d") +conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/rachis-qiime2-osx-64-conda.yml conda activate $__Q2DEV_ENV_NAME ``` ```` -````{tab-item} Linux +````{tab-item} Linux (x86_64) ```bash -__Q2DEV_ENV_NAME=q2dev-amplicon-$(date "+%Y-%m-%d") -conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-amplicon-ubuntu-latest-conda.yml +__Q2DEV_ENV_NAME=q2dev-qiime2-$(date "+%Y-%m-%d") +conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/rachis-qiime2-linux-64-conda.yml conda activate $__Q2DEV_ENV_NAME ``` ```` ````{tab-item} macOS (Apple Silicon) ```bash -__Q2DEV_ENV_NAME=q2dev-amplicon-$(date "+%Y-%m-%d") -CONDA_SUBDIR=osx-64 conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-amplicon-macos-latest-conda.yml +__Q2DEV_ENV_NAME=q2dev-qiime2-$(date "+%Y-%m-%d") +CONDA_SUBDIR=osx-64 conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/rachis-qiime2-osx-64-conda.yml conda activate $__Q2DEV_ENV_NAME conda config --env --set subdir osx-64 ``` @@ -167,29 +166,20 @@ conda config --env --set subdir osx-64 ### MOSHPIT (previously known as the *Metagenome distribution*) -`````{tab-set} -````{tab-item} macOS +````{tab-item} Linux (x86_64) ```bash __Q2DEV_ENV_NAME=moshpit-dev-$(date "+%Y-%m-%d") -conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-moshpit-macos-latest-conda.yml +conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/rachis-moshpit-linux-64-conda.yml conda activate $__Q2DEV_ENV_NAME ``` ```` -````{tab-item} Linux -```bash -__Q2DEV_ENV_NAME=moshpit-dev-$(date "+%Y-%m-%d") -conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-moshpit-ubuntu-latest-conda.yml -conda activate $__Q2DEV_ENV_NAME -``` -```` +### pathogenome -````{tab-item} macOS (Apple Silicon) +````{tab-item} Linux (x86_64) ```bash -__Q2DEV_ENV_NAME=moshpit-dev-$(date "+%Y-%m-%d") -CONDA_SUBDIR=osx-64 conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-moshpit-macos-latest-conda.yml +__Q2DEV_ENV_NAME=pathogenome-dev-$(date "+%Y-%m-%d") +conda env create -n $__Q2DEV_ENV_NAME --file https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/rachis-pathogenome-linux-64-conda.yml conda activate $__Q2DEV_ENV_NAME -conda config --env --set subdir osx-64 ``` ```` -````` diff --git a/book/plugins/how-to-guides/use-metadata.md b/book/plugins/how-to-guides/use-metadata.md index ded6705..6b73aed 100644 --- a/book/plugins/how-to-guides/use-metadata.md +++ b/book/plugins/how-to-guides/use-metadata.md @@ -74,7 +74,7 @@ All types of data columns can be instantiated as `CategoricalMetadataColumn` - v ## How can the Metadata API Help Me? -The `qiime2.metadata.Metadata` API has many interesting features - here are some of the more commonly utlitized elements amongst the plugins within the Amplicon {term}`Distribution`. +The `qiime2.metadata.Metadata` API has many interesting features - here are some of the more commonly utlitized elements amongst the plugins within the qiime2 {term}`Distribution`. ### Merging Metadata @@ -124,4 +124,3 @@ This will generate an artifact containing the metadata that your function provid `ImmutableMetadata` artifacts can be [viewed as `Metadata`](artifacts-as-metadata), so they can be used anywhere that a typical metadata `.tsv` file can be provided as input in QIIME 2. This includes q2-metadata's `tabulate` visualizer. Additionally, if you want to obtain a `.tsv` file representation of an `ImmutableMetadata` artifact, you can [export it](https://docs.qiime2.org/2024.2/tutorials/exporting/). - diff --git a/book/plugins/references/patterns.md b/book/plugins/references/patterns.md index 061fb74..57ad24e 100644 --- a/book/plugins/references/patterns.md +++ b/book/plugins/references/patterns.md @@ -11,7 +11,7 @@ When you're naming inputs, outputs, and parameters for your actions, look at oth ### Metadata parameter name recommendations -We make the following recommendations for naming `Metadata` parameters, based on [a review](https://gist.github.com/gregcaporaso/4be64940f80256316e3308d2ae2ec0da) of how these had actually been named in the plugins in the QIIME 2 *amplicon distribution* in November 2025. +We make the following recommendations for naming `Metadata` parameters, based on [a review](https://gist.github.com/gregcaporaso/4be64940f80256316e3308d2ae2ec0da) of how these had actually been named in the plugins in the rachis *qiime2 distribution* in November 2025. - If your action takes only one sample metadata input, call it `metadata`. ([example: `kmer-diversity`](https://amplicon-docs.qiime2.org/en/latest/references/plugins/boots.html#q2-action-boots-kmer-diversity)) - If your action takes only one feature metadata input, call it `feature-metadata`.