Migrate to the two-question citation scheme - #39
Merged
Merged
Conversation
Simplify README and CONTRIBUTING to make onboarding easier for new contributors. Shift focus to scientific correctness over syntax, point to template and issues, and clarify AUTHORING.
Follows waldronlab/agent-protocol-standard ADR 0014: `method_citation` becomes `method_origin_citation` and optional, `protocol_citation` becomes required. The six HUMAnN protocols cite the eLife HUMAnN paper as `protocol_citation`, since it describes the database-build procedures. `independent-filtering-variance` is a first definition — the procedure is written here, not transcribed — so it cites this collection's concept DOI, which is how a protocol states that rather than leaving a gap a reader has to interpret. AUTHORING.md's citation section is rewritten as the two questions with their own answers, rather than one distinction explained against itself. It no longer needs the rewrite-the-steps counterfactual. No version bumps: the procedures are unchanged and a bump would cascade through `humann4-database-build`'s five pinned dependencies, as with the `stable` change. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved citation metadata, documentation links, and validation guidance issues remain.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
This PR migrates protocol metadata and documentation to the two-question citation scheme.
Changes:
- Adds
protocol_citationand renamesmethod_citationtomethod_origin_citation. - Updates citation metadata for seven protocols.
- Revises contributor, authoring, validation, and onboarding guidance.
File summaries
| File | Summary |
|---|---|
README.md |
Updates contributor onboarding guidance. |
protocols/independent-filtering-variance/protocol.md |
Migrates citation metadata and terminology. |
protocols/humann4-utility-mapping/protocol.md |
Migrates citation metadata. |
protocols/humann4-translated-search-build/protocol.md |
Migrates citation metadata. |
protocols/humann4-sgb-aggregation/protocol.md |
Migrates citation metadata. |
protocols/humann4-database-build/protocol.md |
Updates composite citation metadata. |
protocols/humann4-chocophlan-build/protocol.md |
Migrates citation metadata. |
protocols/humann4-augmented-clustering/protocol.md |
Migrates citation metadata. |
CONTRIBUTING.md |
Revises contribution and validation guidance. |
AUTHORING.md |
Documents the new citation model and authoring guidance. |
Review details
Suppressed comments (7)
AUTHORING.md:121
- This is the same broken relative link as above, so the out-of-scope example cannot be opened. It should target
protocols/independent-filtering-variance/protocol.mdfrom this root-level document.
For example, [independent-filtering-variance](agent-protocols/protocols/independent-filtering-variance) ends by saying it doesn't define or perform hypothesis testing, p-value
AUTHORING.md:49
- These two alternatives are written as one YAML mapping with the
protocol_citationkey repeated. Copying the example can therefore be rejected by strict YAML parsers or silently select only the second value; split the alternatives into separate YAML code blocks.
# written here; nobody published this procedure before
protocol_citation: "10.5281/zenodo.22731694" # this repository's concept DOI
AUTHORING.md:94
- The newly added “ie” should be punctuated as “i.e.,” in this sentence; the current form is a grammatical/usage error in the authoring guidance.
Another way to think about it is: in a methods section, would you say "we did X", ie name the procedure? If so, it's a protocol. Or would you say, "we did X as part of Y". If so, X is likely a step in protocol Y.
CONTRIBUTING.md:11
- This link lands on the whole repository skeleton, while the next step tells contributors to copy a single
protocol.md; the actual example file is nested undertemplate/protocols/example-protocol/. Link directly to that file or clarify the navigation so contributors do not copy the wrong directory.
[Protocol Template](https://github.com/waldronlab/agent-protocol-standard/tree/main/template)
CONTRIBUTING.md:11
- This link targets
main, whose template still uses the retiredmethod_citationfield and leavesprotocol_citationoptional. A contributor following this new instruction would start from metadata that does not implement the two-question scheme; point at the migrated template/ADR or update this link only after the standard change lands.
[Protocol Template](https://github.com/waldronlab/agent-protocol-standard/tree/main/template)
CONTRIBUTING.md:40
- This
mainlink currently points to a standard that still documentsmethod_citationas the atomic field andprotocol_citationas optional, contradicting the requiredprotocol_citationand optionalmethod_origin_citationdocumented above. Link to the migrated standard revision or update this reference once the companion change is merged.
[`PROTOCOL_STANDARD.md`](https://github.com/waldronlab/agent-protocol-standard/blob/main/PROTOCOL_STANDARD.md)
protocols/humann4-database-build/protocol.md:28
- The migration renames the frontmatter field to
method_origin_citation, but this explanatory comment still refers to the nonexistentmethod_citationsfield. Update the comment so it describes the current schema.
# though the protocol is composite. The constituent protocols' own method_citations are inherited.
method_origin_citation: "10.7554/eLife.65088"
- Files reviewed: 10/10 changed files
- Comments generated: 10
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| - If a sibling protocol shares your `method_citation`, `## Notes` says how yours differs. | ||
| protocols already say. | ||
| - It's a unit that can be reused in different analyses. | ||
| - `method_origin_citation` is the method's origin. `protocol_citation`, if present, describes this procedure. |
| itself — the index is a function of both. Hand edits are overwritten by the next such push — and | ||
| until then, the index disagrees with the protocols it claims to describe, which is worse than | ||
| either. | ||
| *(If you prefer to run the validator locally before pushing, you can clone `waldronlab/agent-protocol-standard` and run `Rscript scripts/validate-protocol.R <path-to-your-protocol>`)* |
|
|
||
| method_citation: "10.7554/eLife.65088" | ||
| protocol_citation: "10.7554/eLife.65088" | ||
| method_origin_citation: "10.7554/eLife.65088" |
Comment on lines
+26
to
+28
| # The bioBakery paper proposes this database-construction pipeline as a method, so it belongs here even | ||
| # though the protocol is composite. The constituent protocols' own method_citations are inherited. | ||
| method_citation: "10.7554/eLife.65088" | ||
| method_origin_citation: "10.7554/eLife.65088" |
|
|
||
| method_citation: "10.7554/eLife.65088" | ||
| protocol_citation: "10.7554/eLife.65088" | ||
| method_origin_citation: "10.7554/eLife.65088" |
|
|
||
| method_citation: "10.7554/eLife.65088" | ||
| protocol_citation: "10.7554/eLife.65088" | ||
| method_origin_citation: "10.7554/eLife.65088" |
The four database-build protocols — chocophlan, translated-search, utility- mapping, and the composite that sequences them — no longer carry a method_origin_citation. Building a tool's reference database originates no method, which is ADR 0014's own motivating example; keeping the eLife DOI there labelled that paper as the method's inventor rather than as the description of the procedure, which is what it is and where it now sits. The maintainer and Copilot reached this independently. independent-filtering-variance cites Bourgon 2010 as its protocol_citation rather than this collection. It encodes what that paper describes without fixing additional parameters or steps, so the paper published these instructions. Requiring a prespecified tie-breaker is operational detail that makes a published procedure executable, not a new procedure — if that were enough to constitute a first definition, nothing would ever be a transcription. No protocol in this repository is a first definition today. Also from the review, all pre-existing rather than introduced here: three typos in AUTHORING.md, two links that resolved to `agent-protocols/agent-protocols/` from the repository root, a checklist line still saying protocol_citation is optional, and a local validation command that passed a single protocol path where the validator takes a directory. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
lwaldron
commented
Sep 13, 2026
|
|
||
| Example: "We employed random forest classification (`method_citation`) as implemented by Pasolli et al. 2016. (`protocol_citation`)." | ||
| The primary literature where the method was **first proposed** — not a paper that used it. Leave-one- | ||
| dataset-out cross-validation was first applied to microbiome data by Pasolli 2016, but proposed by |
Member
Author
There was a problem hiding this comment.
drop the leave-one-dataset-out example
| But a string of methods can be published as a method in its own right, and then `method_citation` is right: | ||
| a two-stage hierarchical meta-analysis is a method, and so is `humann4-database-build`. Ask whether the | ||
| paper proposes the combination as an approach people would cite, or just describes running the steps. | ||
| **Omit the field if the protocol originates no method.** Documenting how to build a tool's reference |
Member
Author
There was a problem hiding this comment.
Drop this Omit instruction because it is unnecessary and confusing.
Maintainer: drop the leave-one-dataset-out example, and drop the "omit the field" instruction, which explained at length something the sentence above it already said. What remains is that a paper applying an established method is the commonest wrong answer, because it is usually the paper you read. Also from the review: the two protocol_citation examples were one YAML block with the key repeated, so copying it would have been rejected by a strict parser or silently taken the second value. Two blocks now. And "ie" is "i.e.". The lead-in called self-citation "the normal answer for a protocol written in this repository". After citing Bourgon on independent-filtering-variance that is false — every protocol here encodes a published procedure, and none is a first definition. It now says so. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The guidance presented the two answers as a pair of equally likely cases. They are not: a protocol almost always encodes a procedure someone published, and that paper is the answer. Self-citation applies only where no publication describes the procedure, and is expected to be rare. The transcription case now leads, self-citation is marked as the exception, and the instruction is to reach for it only after looking for the paper and concluding there is none. No protocol in this repository needs it today — including independent-filtering-variance, which encodes what Bourgon 2010 describes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion to waldronlab/agent-protocol-standard#34 (ADR 0014).
method_origin_citationprotocol_citation10.1016/j.cell.2019.01.00110.7554/eLife.6508810.7554/eLife.6508810.7554/eLife.6508810.7554/eLife.6508810.7554/eLife.6508810.1016/j.cell.2019.01.00110.7554/eLife.6508810.7554/eLife.6508810.7554/eLife.6508810.7554/eLife.6508810.7554/eLife.6508810.1073/pnas.091400510710.5281/zenodo.22731694The eLife HUMAnN paper describes the database-build procedures, so it is the protocol citation for all six.
independent-filtering-varianceis a first definition — Bourgon 2010 proposed the method, but the procedure as written here is ours — so it cites this collection's concept DOI. That is the scheme's way of stating "published here" rather than leaving a gap a reader has to interpret.AUTHORING.md's citation section is rewritten as two questions with their own answers, instead of one distinction explained against itself. The rewrite-the-steps counterfactual is gone.No version bumps. The procedures are unchanged, and a bump would cascade through
humann4-database-build's five pinned dependencies — same reasoning as thestablechange in #38.One judgment call left open for you. Four of these — chocophlan-build, translated-search-build, utility-mapping, database-build — now carry the same DOI in both fields. ADR 0014's own motivating example says building a reference database originates no method, which argues for omitting
method_origin_citationon those four entirely. I kept the existing assertion rather than silently retract a citation claim: changing it is a literature judgment, not a migration. Say the word and I'll drop it on whichever of the four you think qualify.Validated against both the new validator and the currently released
@v0tooling — passes on both, so this does not need the standard PR merged or a release cut first.🤖 Generated with Claude Code