From a97d80ffd0713d3f9b74a6f4e5a4842fd53d498c Mon Sep 17 00:00:00 2001 From: Greg Caporaso Date: Thu, 20 Nov 2025 12:50:29 -0700 Subject: [PATCH 1/3] NEW: add documentation on naming conventions for inputs/outputs/parameters --- book/_toc.yml | 1 + book/plugins/references/patterns.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+) create mode 100644 book/plugins/references/patterns.md diff --git a/book/_toc.yml b/book/_toc.yml index 85ecf54..46f1d70 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -53,6 +53,7 @@ parts: - file: plugins/explanations/transformers - file: plugins/references/intro sections: + - file: plugins/references/patterns - file: plugins/references/antipatterns - file: plugins/references/api/intro sections: diff --git a/book/plugins/references/patterns.md b/book/plugins/references/patterns.md new file mode 100644 index 0000000..0feae49 --- /dev/null +++ b/book/plugins/references/patterns.md @@ -0,0 +1,28 @@ +# Plugin development patterns + +This page makes recommendations for plugin developers to help make your plugins consistent with others. +The items outlined on this page aren't requirements, but might improve your users' experience. + +## Name inputs, outputs, and parameters consistently + +It can be frustrating for users if different names are used by different actions to refer to the same thing. +For example, if one action calls a sample metadata parameter `metadata`, and another calls it `sample-metadata`, that makes it harder for users to remember how to call either action (or any others that take sample metadata as input). +When you're naming inputs, outputs, and parameters for your actions, look at other actions in commonly used plugins and try to align your naming with existing naming when it makes sense.[^my-name-is-better] + +### 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. + +- If your action takes only one sample metadata input, call it `metadata`. ([example](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`. +- If your action takes a sample metadata input and a feature metadata input, called them `sample-metadata` and `feature-metadata`, respectively. ([example](https://amplicon-docs.qiime2.org/en/latest/references/plugins/emperor.html#q2-action-emperor-biplot)) +- If your action uses a metadata parameter to take a list of identifiers, name that in a way that is relevant for that action. ([example](https://amplicon-docs.qiime2.org/en/latest/references/plugins/rescript.html#q2-action-rescript-get-ncbi-data)) + - If this list of identifiers is used for filtering purposes, call that parameter `ids-to-keep` or `ids-to-exclude`, based on whether the ids provided are retained for the analysis or excluded from the analysis, respectively. ([example](https://amplicon-docs.qiime2.org/en/latest/references/plugins/rescript.html#q2-action-rescript-filter-taxa)) +- If your action takes more than one sample metadata input, called them `metadata1`, `metadatá2`, ... ([example](https://amplicon-docs.qiime2.org/en/latest/references/plugins/metadata.html#q2-action-metadata-merge)) +- If your action takes more than one feature metadata input, called them `feature-metadata1`, `feature-metadata2`, ... + +[^my-name-is-better]: Sometimes you may have a slightly better name than what is widely used. + Counterintuitively, using that name might make your users' experience more challenging because it's not the name they've come to expect. + In this case, it probably makes sense to go with the existing name. + Other times you might have a name that's *much* better than what others are using (e.g., because the other name is actively misleading). + In this case, you should probably go with your name, but it may be worth contacting developers of the other plugins you looked at to discuss a broad change. From 069f1945d5b84c02c52fe6442572842b7166a1f6 Mon Sep 17 00:00:00 2001 From: Greg Caporaso Date: Thu, 20 Nov 2025 13:13:37 -0700 Subject: [PATCH 2/3] squash --- book/plugins/references/patterns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/plugins/references/patterns.md b/book/plugins/references/patterns.md index 0feae49..cd41bed 100644 --- a/book/plugins/references/patterns.md +++ b/book/plugins/references/patterns.md @@ -13,12 +13,12 @@ When you're naming inputs, outputs, and parameters for your actions, look at oth 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. -- If your action takes only one sample metadata input, call it `metadata`. ([example](https://amplicon-docs.qiime2.org/en/latest/references/plugins/boots.html#q2-action-boots-kmer-diversity)) +- 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`. -- If your action takes a sample metadata input and a feature metadata input, called them `sample-metadata` and `feature-metadata`, respectively. ([example](https://amplicon-docs.qiime2.org/en/latest/references/plugins/emperor.html#q2-action-emperor-biplot)) -- If your action uses a metadata parameter to take a list of identifiers, name that in a way that is relevant for that action. ([example](https://amplicon-docs.qiime2.org/en/latest/references/plugins/rescript.html#q2-action-rescript-get-ncbi-data)) - - If this list of identifiers is used for filtering purposes, call that parameter `ids-to-keep` or `ids-to-exclude`, based on whether the ids provided are retained for the analysis or excluded from the analysis, respectively. ([example](https://amplicon-docs.qiime2.org/en/latest/references/plugins/rescript.html#q2-action-rescript-filter-taxa)) -- If your action takes more than one sample metadata input, called them `metadata1`, `metadatá2`, ... ([example](https://amplicon-docs.qiime2.org/en/latest/references/plugins/metadata.html#q2-action-metadata-merge)) +- If your action takes a sample metadata input and a feature metadata input, called them `sample-metadata` and `feature-metadata`, respectively. ([example: `biplot`](https://amplicon-docs.qiime2.org/en/latest/references/plugins/emperor.html#q2-action-emperor-biplot)) +- If your action uses a metadata parameter to take a list of identifiers, name that in a way that is relevant for that action. ([example: `get-ncbi-data`](https://amplicon-docs.qiime2.org/en/latest/references/plugins/rescript.html#q2-action-rescript-get-ncbi-data)) + - If this list of identifiers is used for filtering purposes, call that parameter `ids-to-keep` or `ids-to-exclude`, based on whether the ids provided are retained for the analysis or excluded from the analysis, respectively. ([example: `filter-taxa`](https://amplicon-docs.qiime2.org/en/latest/references/plugins/rescript.html#q2-action-rescript-filter-taxa)) +- If your action takes more than one sample metadata input, called them `metadata1`, `metadatá2`, ... ([example: `merge`](https://amplicon-docs.qiime2.org/en/latest/references/plugins/metadata.html#q2-action-metadata-merge)) - If your action takes more than one feature metadata input, called them `feature-metadata1`, `feature-metadata2`, ... [^my-name-is-better]: Sometimes you may have a slightly better name than what is widely used. From c55b7497a0527e7a26096b806d135ced03e77cb7 Mon Sep 17 00:00:00 2001 From: Greg Caporaso Date: Thu, 20 Nov 2025 13:15:57 -0700 Subject: [PATCH 3/3] squash --- book/plugins/references/patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/plugins/references/patterns.md b/book/plugins/references/patterns.md index cd41bed..061fb74 100644 --- a/book/plugins/references/patterns.md +++ b/book/plugins/references/patterns.md @@ -21,7 +21,7 @@ We make the following recommendations for naming `Metadata` parameters, based on - If your action takes more than one sample metadata input, called them `metadata1`, `metadatá2`, ... ([example: `merge`](https://amplicon-docs.qiime2.org/en/latest/references/plugins/metadata.html#q2-action-metadata-merge)) - If your action takes more than one feature metadata input, called them `feature-metadata1`, `feature-metadata2`, ... -[^my-name-is-better]: Sometimes you may have a slightly better name than what is widely used. +[^my-name-is-better]: Sometimes you may have a slightly better name for an input, output, or parameter than what is widely used. Counterintuitively, using that name might make your users' experience more challenging because it's not the name they've come to expect. In this case, it probably makes sense to go with the existing name. Other times you might have a name that's *much* better than what others are using (e.g., because the other name is actively misleading).