Skip to content

Add Shannon diversity protocol - #53

Open
ohih8 wants to merge 6 commits into
waldronlab:mainfrom
ohih8:protocol/shannon-diversity
Open

ohih8 wants to merge 6 commits into
waldronlab:mainfrom
ohih8:protocol/shannon-diversity

Conversation

@ohih8

@ohih8 ohih8 commented Oct 21, 2026

Copy link
Copy Markdown
Collaborator

Closes #50

Adds Shannon diversity protocol and two small tests for it. More tests should be added in the future, however these are the most important and it is probably a good idea to wait until the testing infrastructure is fully set up before generating a large amount of tests.
NOTE: This Protocol does not include rarefaction or sequencing depth-normalization as an intentional design choice by me to simplify the protocol. It can certainly be added if desired, however I wanted to keep the protocol concise.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@ohih8
ohih8 requested a review from lwaldron as a code owner October 21, 2026 02:01

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

@ohih8

ohih8 commented Oct 21, 2026

Copy link
Copy Markdown
Collaborator Author

@claude review

Comment thread protocols/shannon-diversity/protocol.md Resolved
Comment thread protocols/shannon-diversity/protocol.md Resolved
Comment thread protocols/shannon-diversity/protocol.md Resolved
evaluation:
mode: diagnostic
accepted_outcomes:
- outcome: refused_for_missing_values

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this part of the protocol standard? Probably what we needed is "error" or "refused"

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The standard allows any label, and its own example uses refused_for_orientation. If you want a fixed set of labels, that would be a question for the standard repo.

Comment thread protocols/shannon-diversity/protocol.md Resolved
Comment thread protocols/shannon-diversity/protocol.md Resolved
Comment thread protocols/shannon-diversity/protocol.md Resolved
@lwaldron

Copy link
Copy Markdown
Member

Hi @ohih8 , please see waldronlab/agent-protocol-standard#46 for instructions on clarifying how to specify the rarefaction recommendation in this PR.

ohih8 and others added 2 commits October 26, 2026 22:07
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 <noreply@anthropic.com>
@ohih8
ohih8 requested a review from lwaldron October 27, 2026 02:20
@ohih8

ohih8 commented Oct 27, 2026

Copy link
Copy Markdown
Collaborator Author

still need to think about this: Come up with a strict definition of what belongs in materials, and how materials are validated.

@lwaldron

lwaldron commented Oct 27, 2026 •

Copy link
Copy Markdown
Member

still need to think about this: Come up with a strict definition of what belongs in materials, and how materials are validated.

I've done some formalizing of what belongs in materials in ADR 0017, Conditions on Materials, and updated the standard accordingly (waldronlab/agent-protocol-standard#47).

What belongs in Materials

  • Every input the protocol consumes: data, parameters, software, reference data.
  • Every condition an input must or should satisfy.
  • Steps use materials but don't add new conditions on them. Statements about what the protocol does or doesn't do go in the overview or Notes.

Two tiers for Materials requirements

  • must: the executor stops, says which condition failed, and produces no outputs.
  • should: the executor proceeds, warns the user with the condition and its consequence, and records the warning.

I've also added agent skills there to create, update, and validate protocols, which will help enforce these rules. Welcoming feedback if this leaves any ambiguity or problems!

@ohih8

ohih8 commented Oct 28, 2026

Copy link
Copy Markdown
Collaborator Author

Hi Dr. Waldron, over the last two days Ive updated the PR, and resolved the comments (many were already fixed from the standard changes). I left one up that asks about the error name, but it doesn't affect the protocol itself much.

@lwaldron lwaldron left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great - one minor fix not to specify a file format when unnecessary (that I should add to guidelines) then I'll merge.

Comment thread protocols/shannon-diversity/protocol.md Outdated

### Step 3: Write the result

Write a CSV table with exactly two columns, `sample_id` and `shannon`, and one row

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't have to be csv - "create a table" should be enough. You might not want to write it to disk before using it in your next step of analysis.

Comment thread protocols/shannon-diversity/protocol.md Resolved
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 <noreply@anthropic.com>
@ohih8

ohih8 commented Oct 28, 2026

Copy link
Copy Markdown
Collaborator Author

Fixed the file format stuff and added the review, the one thing is that the Notes section currently reads:

This is just a placeholder, so if you could add your own thoughts that would be great. The standard requires that the Notes section not be empty, I think, but I don't just want to put words in your mouth for the review.

Otto

@ohih8
ohih8 requested a review from lwaldron October 28, 2026 19:30
Comment thread protocols/shannon-diversity/protocol.md Resolved
ohih8 and others added 2 commits November 1, 2026 17:34
…n tests this week.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… 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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Protocol: Shannon diversity of a single sample

2 participants