From d0d55ab1e48ccb87f9c2eaedda6afc8034ac9def Mon Sep 17 00:00:00 2001 From: Otto Date: Tue, 20 Oct 2026 21:44:31 -0400 Subject: [PATCH 1/5] Add Shannon diversity protocol Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- PROTOCOLS.yaml | 30 ++++- protocols/shannon-diversity/protocol.md | 120 ++++++++++++++++++ .../tests/counts_and_zeros/expected.csv | 3 + .../tests/counts_and_zeros/input.csv | 4 + .../tests/counts_and_zeros/test.yaml | 12 ++ .../tests/missing_values/input.csv | 4 + .../tests/missing_values/test.yaml | 12 ++ 7 files changed, 184 insertions(+), 1 deletion(-) create mode 100644 protocols/shannon-diversity/protocol.md create mode 100644 protocols/shannon-diversity/tests/counts_and_zeros/expected.csv create mode 100644 protocols/shannon-diversity/tests/counts_and_zeros/input.csv create mode 100644 protocols/shannon-diversity/tests/counts_and_zeros/test.yaml create mode 100644 protocols/shannon-diversity/tests/missing_values/input.csv create mode 100644 protocols/shannon-diversity/tests/missing_values/test.yaml diff --git a/PROTOCOLS.yaml b/PROTOCOLS.yaml index 7b75ea9..7943b4b 100644 --- a/PROTOCOLS.yaml +++ b/PROTOCOLS.yaml @@ -1,6 +1,6 @@ spec_version: 0.1.0 repository: waldronlab/agent-protocols -generated_at: '2026-10-18T03:16:26Z' +generated_at: '2026-10-21T01:30:30Z' protocols: - name: cbea-signature-enrichment description: Test microbial signatures, such as those curated in BugSigDB, for taxonomic @@ -398,6 +398,34 @@ protocols: - microbiome - preprocessing protocol_url: https://raw.githubusercontent.com/waldronlab/agent-protocols/main/protocols/prevalence-filtering/protocol.md +- name: shannon-diversity + description: Calculate the Shannon diversity index for each sample in a feature-by-sample + abundance table. + version: 1.0.0 + authors: + - name: Otto Infield-Harm + orcid: 0009-0009-8629-6124 + - name: Levi Waldron + orcid: 0000-0003-2725-0694 + reviews: [] + date: '2026-10-20' + status: draft + type: atomic + artifact_doi: null + collection_doi: 10.5281/zenodo.22731694 + protocol_citation: 10.1002/j.1538-7305.1948.tb01338.x + method_origin_citation: 10.1002/j.1538-7305.1948.tb01338.x + license: CC-BY-4.0 + protocols_used: [] + upstream_repositories: [] + database_urls: [] + key_packages: [] + category: Statistical Analysis + tags: + - alpha-diversity + - shannon + - microbiome + protocol_url: https://raw.githubusercontent.com/waldronlab/agent-protocols/main/protocols/shannon-diversity/protocol.md - name: ward-linkage-signature-matrix-clustering description: Cluster and display a signature similarity matrix using Ward minimum-variance hierarchical linkage. diff --git a/protocols/shannon-diversity/protocol.md b/protocols/shannon-diversity/protocol.md new file mode 100644 index 0000000..e6b6d8c --- /dev/null +++ b/protocols/shannon-diversity/protocol.md @@ -0,0 +1,120 @@ +--- +name: "shannon-diversity" +description: "Calculate the Shannon diversity index for each sample in a feature-by-sample abundance table." +version: "1.0.0" +authors: + - name: "Otto Infield-Harm" + orcid: "0009-0009-8629-6124" + - name: "Levi Waldron" + orcid: "0000-0003-2725-0694" +reviews: [] +date: "2026-10-20" +status: draft +type: "atomic" + +artifact_doi: ~ +collection_doi: "10.5281/zenodo.22731694" +protocol_citation: "10.1002/j.1538-7305.1948.tb01338.x" +method_origin_citation: "10.1002/j.1538-7305.1948.tb01338.x" +license: "CC-BY-4.0" +protocols_used: [] +upstream_repositories: [] +database_urls: [] +key_packages: [] +category: "Statistical Analysis" +tags: + - alpha-diversity + - shannon + - microbiome +--- + +# Shannon diversity of a single sample + +Calculate one Shannon diversity value for each sample in a feature-by-sample abundance +table. The calculation is descriptive: this protocol does not compare groups, test +hypotheses, or interpret the resulting values. + +## Materials + +- **Input table:** A CSV file with one row per feature and one column per sample. The + first column contains unique feature identifiers, and the remaining columns contain + non-negative numeric abundances. +- **Input scale:** A required parameter, either `counts` or `proportions`. +- **Logarithm base:** An optional parameter, defaulting to the natural logarithm (`e`). + The base must be greater than 1. +- **Depth normalization:** `none`. This protocol does not rarefy or otherwise + normalize samples to a common sequencing depth. The supplied abundances and this + setting must be recorded with the result. + +## Steps + +### Step 1: Validate the table and parameters + +Read the input as a feature-by-sample table and preserve the sample column names. +Reject the input if the feature identifiers are missing or duplicated, if there are +no sample columns, if an abundance is non-numeric or negative, or if any abundance +is missing. Missing values must stop the calculation; they must not be imputed, +converted to zero, or silently omitted. + +Require the input scale to be explicitly declared as `counts` or `proportions`. +Reject any other value. Require the logarithm base to be greater than 1. + +### Step 2: Convert abundances to proportions + +For each sample independently, let $x_{ij}$ be the abundance of feature $i$ in +sample $j$. + +For `counts`, calculate + +$$ +p_{ij} = \frac{x_{ij}}{\sum_{i} x_{ij}}. +$$ + +Reject a count sample whose total is zero. For `proportions`, require the values to +be non-negative and to sum to 1 within a numerical tolerance of $10^{-12}$; +reject a sample outside that tolerance rather than silently renormalizing it. + +Do not rarefy, subsample, or otherwise alter the sample totals. Zero-valued +features remain part of the table but make no contribution to the index. + +### Step 3: Calculate Shannon diversity + +For each sample $j$, calculate + +$$ +H_j = -\sum_{i:p_{ij}>0} p_{ij}\log_b(p_{ij}), +$$ + +where $b$ is the requested logarithm base. Terms with $p_{ij}=0$ are omitted, +because their limiting contribution is zero. + +### Step 4: Write the result + +Write a CSV table with exactly two columns, `sample_id` and `shannon`, and one row +for each input sample. Preserve the input sample-column order. Do not add feature +summaries, group labels, confidence intervals, tests, plots, or interpretations. +Record the input scale, logarithm base, and `depth_normalization: none` alongside +the execution metadata, not as additional rows or columns in this output table. + +## Notes + +The Shannon index was introduced by Shannon (1948), which is cited as both the +source of this protocol's calculation and the method origin. Manghi et al. +(*Nature Communications*, 2025, DOI: 10.1038/s41467-025-66888-1) is an application +of the method, not the method-origin citation. + +This protocol intentionally does not perform rarefaction. Because Shannon diversity +can depend on sequencing depth, comparisons across samples with different depths +must be treated as potentially confounded unless depth normalization is handled by +a separate, explicitly documented procedure. + +## History & Reviews + + +### Version 1.0.0 (2026-10-20) + +#### Changes +- Initial protocol for calculating per-sample Shannon diversity. + +#### Reviews +*No reviews yet.* diff --git a/protocols/shannon-diversity/tests/counts_and_zeros/expected.csv b/protocols/shannon-diversity/tests/counts_and_zeros/expected.csv new file mode 100644 index 0000000..15d070b --- /dev/null +++ b/protocols/shannon-diversity/tests/counts_and_zeros/expected.csv @@ -0,0 +1,3 @@ +sample_id,shannon +sample_a,0.6931471805599453 +sample_b,0.5623351446188083 diff --git a/protocols/shannon-diversity/tests/counts_and_zeros/input.csv b/protocols/shannon-diversity/tests/counts_and_zeros/input.csv new file mode 100644 index 0000000..69ec556 --- /dev/null +++ b/protocols/shannon-diversity/tests/counts_and_zeros/input.csv @@ -0,0 +1,4 @@ +feature_id,sample_a,sample_b +feature_1,1,1 +feature_2,1,3 +feature_3,0,0 diff --git a/protocols/shannon-diversity/tests/counts_and_zeros/test.yaml b/protocols/shannon-diversity/tests/counts_and_zeros/test.yaml new file mode 100644 index 0000000..a144f95 --- /dev/null +++ b/protocols/shannon-diversity/tests/counts_and_zeros/test.yaml @@ -0,0 +1,12 @@ +name: counts_and_zeros +description: Count data are converted to proportions and zero-valued features contribute zero. +inputs: + data: {path: input.csv} + input_scale: counts + log_base: e + depth_normalization: none +expected_outputs: + result: {path: expected.csv} +evaluation: + mode: exact + numeric_tolerance: 1.0e-12 diff --git a/protocols/shannon-diversity/tests/missing_values/input.csv b/protocols/shannon-diversity/tests/missing_values/input.csv new file mode 100644 index 0000000..5a1e92c --- /dev/null +++ b/protocols/shannon-diversity/tests/missing_values/input.csv @@ -0,0 +1,4 @@ +feature_id,sample_a,sample_b +feature_1,1,1 +feature_2,,3 +feature_3,0,0 diff --git a/protocols/shannon-diversity/tests/missing_values/test.yaml b/protocols/shannon-diversity/tests/missing_values/test.yaml new file mode 100644 index 0000000..77c350e --- /dev/null +++ b/protocols/shannon-diversity/tests/missing_values/test.yaml @@ -0,0 +1,12 @@ +name: missing_values +description: Missing abundance values must stop the calculation rather than be imputed or treated as zero. +inputs: + data: {path: input.csv} + input_scale: counts + log_base: e + depth_normalization: none +evaluation: + mode: diagnostic + accepted_outcomes: + - outcome: refused_for_missing_values + expected_absent: [result] From 247e7ad744e6330d9b922c3f5c35b942f35f4284 Mon Sep 17 00:00:00 2001 From: Otto Date: Mon, 26 Oct 2026 22:07:40 -0400 Subject: [PATCH 2/5] Address review of the Shannon diversity protocol Move every input condition into Materials as must/should conditions (ADR 0017): a non-rarefied count table now proceeds with a warning that advises rarefaction, and the separate validation step is removed. Consolidate the rarefaction text, drop depth normalization as a material, name the vegan and scikit-bio calls, and loosen the proportion-sum tolerance to 1e-6. counts_and_zeros becomes a diagnostic test that requires the warning alongside the results; its expected values are confirmed with vegan and scikit-bio. Co-Authored-By: Claude Opus 5.5 --- protocols/shannon-diversity/protocol.md | 105 +++++++++++------- .../tests/counts_and_zeros/test.yaml | 12 +- .../tests/missing_values/test.yaml | 1 - 3 files changed, 69 insertions(+), 49 deletions(-) diff --git a/protocols/shannon-diversity/protocol.md b/protocols/shannon-diversity/protocol.md index e6b6d8c..49da148 100644 --- a/protocols/shannon-diversity/protocol.md +++ b/protocols/shannon-diversity/protocol.md @@ -7,8 +7,7 @@ authors: orcid: "0009-0009-8629-6124" - name: "Levi Waldron" orcid: "0000-0003-2725-0694" -reviews: [] -date: "2026-10-20" +date: "2026-10-26" status: draft type: "atomic" @@ -18,9 +17,13 @@ protocol_citation: "10.1002/j.1538-7305.1948.tb01338.x" method_origin_citation: "10.1002/j.1538-7305.1948.tb01338.x" license: "CC-BY-4.0" protocols_used: [] -upstream_repositories: [] +upstream_repositories: + - "https://github.com/vegandevs/vegan" + - "https://github.com/scikit-bio/scikit-bio" database_urls: [] -key_packages: [] +key_packages: + - "vegan" + - "scikit-bio" category: "Statistical Analysis" tags: - alpha-diversity @@ -31,35 +34,42 @@ tags: # Shannon diversity of a single sample Calculate one Shannon diversity value for each sample in a feature-by-sample abundance -table. The calculation is descriptive: this protocol does not compare groups, test -hypotheses, or interpret the resulting values. +table. The calculation is descriptive: this protocol does not rarefy, subsample, or +otherwise normalize samples to a common sequencing depth, and it does not compare groups, +test hypotheses, or interpret the resulting values. ## Materials -- **Input table:** A CSV file with one row per feature and one column per sample. The - first column contains unique feature identifiers, and the remaining columns contain - non-negative numeric abundances. -- **Input scale:** A required parameter, either `counts` or `proportions`. -- **Logarithm base:** An optional parameter, defaulting to the natural logarithm (`e`). - The base must be greater than 1. -- **Depth normalization:** `none`. This protocol does not rarefy or otherwise - normalize samples to a common sequencing depth. The supplied abundances and this - setting must be recorded with the result. +- **Input data:** + - `data` — a CSV table with one row per feature and one column per sample. The first + column must contain unique, non-missing feature identifiers, and there must be at + least one sample column. Every other cell must be a non-negative number, and no cell + may be missing: a missing value must not be imputed, converted to zero, or omitted. + - When `input_scale` is `proportions`, each sample column must sum to 1 within an + absolute tolerance of $10^{-6}$. A sample outside that tolerance is not renormalized. + - When `input_scale` is `counts`, samples should be rarefied or otherwise normalized to + a common sequencing depth, so that every sample column has the same total. If the + totals differ, proceed, and warn that the Shannon values depend on sequencing depth + and are not comparable across samples, and advise rarefying to a common depth before + comparing them. Proportions carry no depth, so this condition cannot be checked on + them. +- **Parameters:** + - `input_scale` — whether `data` holds `counts` or `proportions`. Required, with no + default, because the scale changes Step 1 and cannot be told reliably from the values. + It must be one of those two words. + - `log_base` — the base $b$ of the logarithm in Step 2. The default is `e`, the natural + logarithm, which gives the index in nats; `2` gives bits. It must be `e` or a number + greater than 1. +- **Software & Repositories:** + - `vegan` (https://github.com/vegandevs/vegan) — R package; `diversity()` computes + Step 2. + - `scikit-bio` (https://github.com/scikit-bio/scikit-bio) — Python package; + `skbio.diversity.alpha.shannon()` computes Step 2. + - Either is optional. Any implementation that follows Steps 1 and 2 is acceptable. ## Steps -### Step 1: Validate the table and parameters - -Read the input as a feature-by-sample table and preserve the sample column names. -Reject the input if the feature identifiers are missing or duplicated, if there are -no sample columns, if an abundance is non-numeric or negative, or if any abundance -is missing. Missing values must stop the calculation; they must not be imputed, -converted to zero, or silently omitted. - -Require the input scale to be explicitly declared as `counts` or `proportions`. -Reject any other value. Require the logarithm base to be greater than 1. - -### Step 2: Convert abundances to proportions +### Step 1: Convert abundances to proportions For each sample independently, let $x_{ij}$ be the abundance of feature $i$ in sample $j$. @@ -70,14 +80,13 @@ $$ p_{ij} = \frac{x_{ij}}{\sum_{i} x_{ij}}. $$ -Reject a count sample whose total is zero. For `proportions`, require the values to -be non-negative and to sum to 1 within a numerical tolerance of $10^{-12}$; -reject a sample outside that tolerance rather than silently renormalizing it. +If a count sample's total is zero, its proportions are undefined: stop, report which +sample it is, and produce no output. For `proportions`, use the values as given: +$p_{ij} = x_{ij}$. -Do not rarefy, subsample, or otherwise alter the sample totals. Zero-valued -features remain part of the table but make no contribution to the index. +Zero-valued features remain part of the table but make no contribution to the index. -### Step 3: Calculate Shannon diversity +### Step 2: Calculate Shannon diversity For each sample $j$, calculate @@ -85,16 +94,25 @@ $$ H_j = -\sum_{i:p_{ij}>0} p_{ij}\log_b(p_{ij}), $$ -where $b$ is the requested logarithm base. Terms with $p_{ij}=0$ are omitted, -because their limiting contribution is zero. +where $b$ is `log_base`. Terms with $p_{ij}=0$ are omitted, because their limiting +contribution is zero. + +The same calculation, for a feature-by-sample matrix `x` with feature identifiers as row +names: + +- R: `vegan::diversity(x, index = "shannon", MARGIN = 2, base = exp(1))`. `MARGIN = 2` + treats columns as samples; the function's default, `MARGIN = 1`, treats rows as samples. +- Python: `skbio.diversity.alpha.shannon(x[:, j], base=math.e)` for each sample column `j`. + +Replace `exp(1)` or `math.e` with $b$ when `log_base` is not `e`. -### Step 4: Write the result +### Step 3: Write the result Write a CSV table with exactly two columns, `sample_id` and `shannon`, and one row for each input sample. Preserve the input sample-column order. Do not add feature summaries, group labels, confidence intervals, tests, plots, or interpretations. -Record the input scale, logarithm base, and `depth_normalization: none` alongside -the execution metadata, not as additional rows or columns in this output table. +Record `input_scale`, `log_base`, and any warning given under Materials alongside the +execution metadata, not as additional rows or columns in this output table. ## Notes @@ -103,15 +121,16 @@ source of this protocol's calculation and the method origin. Manghi et al. (*Nature Communications*, 2025, DOI: 10.1038/s41467-025-66888-1) is an application of the method, not the method-origin citation. -This protocol intentionally does not perform rarefaction. Because Shannon diversity -can depend on sequencing depth, comparisons across samples with different depths -must be treated as potentially confounded unless depth normalization is handled by -a separate, explicitly documented procedure. +Both `vegan::diversity()` and `skbio.diversity.alpha.shannon()` divide each sample by its +own total, so they accept counts and proportions alike; neither checks the conditions in +Materials, which must be checked first. `vegan::diversity()` returns `NA` for a sample +with a missing value rather than stopping. Pass the logarithm base explicitly to both: +the default of `shannon()` has differed between scikit-bio releases. ## History & Reviews -### Version 1.0.0 (2026-10-20) +### Version 1.0.0 (2026-10-26) #### Changes - Initial protocol for calculating per-sample Shannon diversity. diff --git a/protocols/shannon-diversity/tests/counts_and_zeros/test.yaml b/protocols/shannon-diversity/tests/counts_and_zeros/test.yaml index a144f95..714ee41 100644 --- a/protocols/shannon-diversity/tests/counts_and_zeros/test.yaml +++ b/protocols/shannon-diversity/tests/counts_and_zeros/test.yaml @@ -1,12 +1,14 @@ name: counts_and_zeros -description: Count data are converted to proportions and zero-valued features contribute zero. +description: Counts with unequal sample totals give per-sample Shannon values, zero-valued features contribute zero, and the executor warns that the samples were not rarefied. inputs: data: {path: input.csv} input_scale: counts log_base: e - depth_normalization: none -expected_outputs: - result: {path: expected.csv} evaluation: - mode: exact + mode: diagnostic numeric_tolerance: 1.0e-12 + accepted_outcomes: + - outcome: computed_with_depth_warning + expected_outputs: + result: {path: expected.csv} + expected_warning: raref # matches rarefy, rarefied, rarefying, rarefaction diff --git a/protocols/shannon-diversity/tests/missing_values/test.yaml b/protocols/shannon-diversity/tests/missing_values/test.yaml index 77c350e..7562751 100644 --- a/protocols/shannon-diversity/tests/missing_values/test.yaml +++ b/protocols/shannon-diversity/tests/missing_values/test.yaml @@ -4,7 +4,6 @@ inputs: data: {path: input.csv} input_scale: counts log_base: e - depth_normalization: none evaluation: mode: diagnostic accepted_outcomes: From f0f5b5f8ad8e11721cbaf1bb9630aace5776571f Mon Sep 17 00:00:00 2001 From: Otto Date: Tue, 27 Oct 2026 22:04:12 -0400 Subject: [PATCH 3/5] Drop file-format wording and record Levi Waldron's review The input and result are tables, not necessarily CSV files, so the protocol no longer names a format or implies writing to disk. Adds the approved review of 1.0.0 to the frontmatter and History. Co-Authored-By: Claude Opus 5.5 --- protocols/shannon-diversity/protocol.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/protocols/shannon-diversity/protocol.md b/protocols/shannon-diversity/protocol.md index 49da148..748f3c8 100644 --- a/protocols/shannon-diversity/protocol.md +++ b/protocols/shannon-diversity/protocol.md @@ -7,6 +7,12 @@ authors: orcid: "0009-0009-8629-6124" - name: "Levi Waldron" orcid: "0000-0003-2725-0694" +reviews: + - name: "Levi Waldron" + orcid: "0000-0003-2725-0694" + date: "2026-10-27" + protocol_version: "1.0.0" + status: approved date: "2026-10-26" status: draft type: "atomic" @@ -41,7 +47,7 @@ test hypotheses, or interpret the resulting values. ## Materials - **Input data:** - - `data` — a CSV table with one row per feature and one column per sample. The first + - `data` — a table with one row per feature and one column per sample. The first column must contain unique, non-missing feature identifiers, and there must be at least one sample column. Every other cell must be a non-negative number, and no cell may be missing: a missing value must not be imputed, converted to zero, or omitted. @@ -106,9 +112,9 @@ names: Replace `exp(1)` or `math.e` with $b$ when `log_base` is not `e`. -### Step 3: Write the result +### Step 3: Return the result -Write a CSV table with exactly two columns, `sample_id` and `shannon`, and one row +Create a table with exactly two columns, `sample_id` and `shannon`, and one row for each input sample. Preserve the input sample-column order. Do not add feature summaries, group labels, confidence intervals, tests, plots, or interpretations. Record `input_scale`, `log_base`, and any warning given under Materials alongside the @@ -136,4 +142,8 @@ the default of `shannon()` has differed between scikit-bio releases. - Initial protocol for calculating per-sample Shannon diversity. #### Reviews -*No reviews yet.* + +**Review by Levi Waldron ([0000-0003-2725-0694](https://orcid.org/0000-0003-2725-0694))** +- **Date:** 2026-10-27 +- **Status:** `approved` +- **Notes:** Review given on waldronlab/agent-protocols#53. From 37a39f5b858aad0d24cb13efa25a0db63f3c7a88 Mon Sep 17 00:00:00 2001 From: Otto Date: Sun, 1 Nov 2026 17:34:48 -0500 Subject: [PATCH 4/5] Updated links to refer to original documentation. Will do more work on tests this week. Co-Authored-By: Claude Opus 5.5 --- protocols/shannon-diversity/protocol.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/protocols/shannon-diversity/protocol.md b/protocols/shannon-diversity/protocol.md index 748f3c8..d6e96f8 100644 --- a/protocols/shannon-diversity/protocol.md +++ b/protocols/shannon-diversity/protocol.md @@ -67,9 +67,9 @@ test hypotheses, or interpret the resulting values. logarithm, which gives the index in nats; `2` gives bits. It must be `e` or a number greater than 1. - **Software & Repositories:** - - `vegan` (https://github.com/vegandevs/vegan) — R package; `diversity()` computes - Step 2. - - `scikit-bio` (https://github.com/scikit-bio/scikit-bio) — Python package; + - `vegan` (CRAN: https://cran.r-project.org/package=vegan) — R package; + `diversity()` computes Step 2. + - `scikit-bio` (PyPI: https://pypi.org/project/scikit-bio/) — Python package; `skbio.diversity.alpha.shannon()` computes Step 2. - Either is optional. Any implementation that follows Steps 1 and 2 is acceptable. From 6679f06c04fd05b547e8129a624b74f2c9130d6a Mon Sep 17 00:00:00 2001 From: Otto Date: Mon, 2 Nov 2026 15:37:22 -0500 Subject: [PATCH 5/5] Added some new tests. AI made the tests, which were then verified "by hand" with a calculator. Note the only bad-data test that accepts something other than refusal is the matrix transposition one, because the protocol specifically states to not fix other things (like renormalizing, imputing, etc.). More tests could probably be added but these are a few to start. --- .../tests/features_in_columns/expected.csv | 4 ++++ .../tests/features_in_columns/input.csv | 4 ++++ .../tests/features_in_columns/test.yaml | 15 +++++++++++++++ .../tests/invalid_log_base/input.csv | 3 +++ .../tests/invalid_log_base/test.yaml | 11 +++++++++++ .../tests/negative_values/input.csv | 4 ++++ .../tests/negative_values/test.yaml | 11 +++++++++++ .../tests/proportions/expected.csv | 3 +++ .../shannon-diversity/tests/proportions/input.csv | 5 +++++ .../shannon-diversity/tests/proportions/test.yaml | 11 +++++++++++ .../proportions_not_summing_to_one/input.csv | 4 ++++ .../proportions_not_summing_to_one/test.yaml | 11 +++++++++++ .../tests/rarefied_counts/expected.csv | 4 ++++ .../tests/rarefied_counts/input.csv | 5 +++++ .../tests/rarefied_counts/test.yaml | 11 +++++++++++ .../tests/zero_total_sample/input.csv | 3 +++ .../tests/zero_total_sample/test.yaml | 11 +++++++++++ 17 files changed, 120 insertions(+) create mode 100644 protocols/shannon-diversity/tests/features_in_columns/expected.csv create mode 100644 protocols/shannon-diversity/tests/features_in_columns/input.csv create mode 100644 protocols/shannon-diversity/tests/features_in_columns/test.yaml create mode 100644 protocols/shannon-diversity/tests/invalid_log_base/input.csv create mode 100644 protocols/shannon-diversity/tests/invalid_log_base/test.yaml create mode 100644 protocols/shannon-diversity/tests/negative_values/input.csv create mode 100644 protocols/shannon-diversity/tests/negative_values/test.yaml create mode 100644 protocols/shannon-diversity/tests/proportions/expected.csv create mode 100644 protocols/shannon-diversity/tests/proportions/input.csv create mode 100644 protocols/shannon-diversity/tests/proportions/test.yaml create mode 100644 protocols/shannon-diversity/tests/proportions_not_summing_to_one/input.csv create mode 100644 protocols/shannon-diversity/tests/proportions_not_summing_to_one/test.yaml create mode 100644 protocols/shannon-diversity/tests/rarefied_counts/expected.csv create mode 100644 protocols/shannon-diversity/tests/rarefied_counts/input.csv create mode 100644 protocols/shannon-diversity/tests/rarefied_counts/test.yaml create mode 100644 protocols/shannon-diversity/tests/zero_total_sample/input.csv create mode 100644 protocols/shannon-diversity/tests/zero_total_sample/test.yaml diff --git a/protocols/shannon-diversity/tests/features_in_columns/expected.csv b/protocols/shannon-diversity/tests/features_in_columns/expected.csv new file mode 100644 index 0000000..5f19b93 --- /dev/null +++ b/protocols/shannon-diversity/tests/features_in_columns/expected.csv @@ -0,0 +1,4 @@ +sample_id,shannon +sample_a,2 +sample_b,1.5 +sample_c,1 diff --git a/protocols/shannon-diversity/tests/features_in_columns/input.csv b/protocols/shannon-diversity/tests/features_in_columns/input.csv new file mode 100644 index 0000000..9de073b --- /dev/null +++ b/protocols/shannon-diversity/tests/features_in_columns/input.csv @@ -0,0 +1,4 @@ +sample_id,feature_1,feature_2,feature_3,feature_4 +sample_a,2,2,2,2 +sample_b,4,2,2,0 +sample_c,4,4,0,0 diff --git a/protocols/shannon-diversity/tests/features_in_columns/test.yaml b/protocols/shannon-diversity/tests/features_in_columns/test.yaml new file mode 100644 index 0000000..79bcead --- /dev/null +++ b/protocols/shannon-diversity/tests/features_in_columns/test.yaml @@ -0,0 +1,15 @@ +name: features_in_columns +description: Samples in rows and features in columns; the executor transposes the table and computes per-sample values, or refuses. +inputs: + data: {path: input.csv} + input_scale: counts + log_base: 2 +evaluation: + mode: diagnostic + numeric_tolerance: 1.0e-12 + accepted_outcomes: + - outcome: orientation_corrected + expected_outputs: + result: {path: expected.csv} + - outcome: refused_for_orientation + expected_absent: [result] diff --git a/protocols/shannon-diversity/tests/invalid_log_base/input.csv b/protocols/shannon-diversity/tests/invalid_log_base/input.csv new file mode 100644 index 0000000..b5f48f5 --- /dev/null +++ b/protocols/shannon-diversity/tests/invalid_log_base/input.csv @@ -0,0 +1,3 @@ +feature_id,sample_a,sample_b +feature_1,1,2 +feature_2,1,2 diff --git a/protocols/shannon-diversity/tests/invalid_log_base/test.yaml b/protocols/shannon-diversity/tests/invalid_log_base/test.yaml new file mode 100644 index 0000000..0fb5a98 --- /dev/null +++ b/protocols/shannon-diversity/tests/invalid_log_base/test.yaml @@ -0,0 +1,11 @@ +name: invalid_log_base +description: A log base below 1 must be refused rather than used, which would give negative Shannon values. +inputs: + data: {path: input.csv} + input_scale: counts + log_base: 0.5 +evaluation: + mode: diagnostic + accepted_outcomes: + - outcome: refused_for_invalid_log_base + expected_absent: [result] diff --git a/protocols/shannon-diversity/tests/negative_values/input.csv b/protocols/shannon-diversity/tests/negative_values/input.csv new file mode 100644 index 0000000..f2d9f84 --- /dev/null +++ b/protocols/shannon-diversity/tests/negative_values/input.csv @@ -0,0 +1,4 @@ +feature_id,sample_a,sample_b +feature_1,2,3 +feature_2,2,-1 +feature_3,0,2 diff --git a/protocols/shannon-diversity/tests/negative_values/test.yaml b/protocols/shannon-diversity/tests/negative_values/test.yaml new file mode 100644 index 0000000..a8ad2cc --- /dev/null +++ b/protocols/shannon-diversity/tests/negative_values/test.yaml @@ -0,0 +1,11 @@ +name: negative_values +description: A negative abundance must stop the calculation rather than be dropped, zeroed, or made positive. +inputs: + data: {path: input.csv} + input_scale: counts + log_base: e +evaluation: + mode: diagnostic + accepted_outcomes: + - outcome: refused_for_negative_values + expected_absent: [result] diff --git a/protocols/shannon-diversity/tests/proportions/expected.csv b/protocols/shannon-diversity/tests/proportions/expected.csv new file mode 100644 index 0000000..f7b57c3 --- /dev/null +++ b/protocols/shannon-diversity/tests/proportions/expected.csv @@ -0,0 +1,3 @@ +sample_id,shannon +sample_a,1 +sample_b,2 diff --git a/protocols/shannon-diversity/tests/proportions/input.csv b/protocols/shannon-diversity/tests/proportions/input.csv new file mode 100644 index 0000000..10810da --- /dev/null +++ b/protocols/shannon-diversity/tests/proportions/input.csv @@ -0,0 +1,5 @@ +feature_id,sample_a,sample_b +feature_1,0.5,0.25 +feature_2,0.5,0.25 +feature_3,0,0.25 +feature_4,0,0.25 diff --git a/protocols/shannon-diversity/tests/proportions/test.yaml b/protocols/shannon-diversity/tests/proportions/test.yaml new file mode 100644 index 0000000..c9a360a --- /dev/null +++ b/protocols/shannon-diversity/tests/proportions/test.yaml @@ -0,0 +1,11 @@ +name: proportions +description: Proportions that sum to 1 are used as given, with zero proportions omitted from the sum. +inputs: + data: {path: input.csv} + input_scale: proportions + log_base: 2 +expected_outputs: + result: {path: expected.csv} +evaluation: + mode: exact + numeric_tolerance: 1.0e-12 diff --git a/protocols/shannon-diversity/tests/proportions_not_summing_to_one/input.csv b/protocols/shannon-diversity/tests/proportions_not_summing_to_one/input.csv new file mode 100644 index 0000000..38d89f8 --- /dev/null +++ b/protocols/shannon-diversity/tests/proportions_not_summing_to_one/input.csv @@ -0,0 +1,4 @@ +feature_id,sample_a,sample_b +feature_1,0.5,0.5 +feature_2,0.5,0.3 +feature_3,0,0.1 diff --git a/protocols/shannon-diversity/tests/proportions_not_summing_to_one/test.yaml b/protocols/shannon-diversity/tests/proportions_not_summing_to_one/test.yaml new file mode 100644 index 0000000..e30b2b1 --- /dev/null +++ b/protocols/shannon-diversity/tests/proportions_not_summing_to_one/test.yaml @@ -0,0 +1,11 @@ +name: proportions_not_summing_to_one +description: A proportions sample summing to 0.9 must be refused rather than renormalized. +inputs: + data: {path: input.csv} + input_scale: proportions + log_base: e +evaluation: + mode: diagnostic + accepted_outcomes: + - outcome: refused_for_proportions_not_summing_to_one + expected_absent: [result] diff --git a/protocols/shannon-diversity/tests/rarefied_counts/expected.csv b/protocols/shannon-diversity/tests/rarefied_counts/expected.csv new file mode 100644 index 0000000..7e2cfdb --- /dev/null +++ b/protocols/shannon-diversity/tests/rarefied_counts/expected.csv @@ -0,0 +1,4 @@ +sample_id,shannon +sample_a,2 +sample_b,1.5 +sample_c,0 diff --git a/protocols/shannon-diversity/tests/rarefied_counts/input.csv b/protocols/shannon-diversity/tests/rarefied_counts/input.csv new file mode 100644 index 0000000..7705c49 --- /dev/null +++ b/protocols/shannon-diversity/tests/rarefied_counts/input.csv @@ -0,0 +1,5 @@ +feature_id,sample_a,sample_b,sample_c +feature_1,2,4,8 +feature_2,2,2,0 +feature_3,2,2,0 +feature_4,2,0,0 diff --git a/protocols/shannon-diversity/tests/rarefied_counts/test.yaml b/protocols/shannon-diversity/tests/rarefied_counts/test.yaml new file mode 100644 index 0000000..d089ea6 --- /dev/null +++ b/protocols/shannon-diversity/tests/rarefied_counts/test.yaml @@ -0,0 +1,11 @@ +name: rarefied_counts +description: Counts rarefied to a common depth of 8 give per-sample Shannon values in bits, including zero for a sample with a single nonzero feature. +inputs: + data: {path: input.csv} + input_scale: counts + log_base: 2 +expected_outputs: + result: {path: expected.csv} +evaluation: + mode: exact + numeric_tolerance: 1.0e-12 diff --git a/protocols/shannon-diversity/tests/zero_total_sample/input.csv b/protocols/shannon-diversity/tests/zero_total_sample/input.csv new file mode 100644 index 0000000..7a8737a --- /dev/null +++ b/protocols/shannon-diversity/tests/zero_total_sample/input.csv @@ -0,0 +1,3 @@ +feature_id,sample_a,sample_b +feature_1,2,0 +feature_2,2,0 diff --git a/protocols/shannon-diversity/tests/zero_total_sample/test.yaml b/protocols/shannon-diversity/tests/zero_total_sample/test.yaml new file mode 100644 index 0000000..31133e3 --- /dev/null +++ b/protocols/shannon-diversity/tests/zero_total_sample/test.yaml @@ -0,0 +1,11 @@ +name: zero_total_sample +description: A count sample whose total is zero has undefined proportions, so the calculation stops with no output. +inputs: + data: {path: input.csv} + input_scale: counts + log_base: e +evaluation: + mode: diagnostic + accepted_outcomes: + - outcome: refused_for_zero_total_sample + expected_absent: [result]