From 9fc2f71a387297d63d09695bb6de09121c360784 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Fri, 16 Oct 2026 23:28:03 +0100 Subject: [PATCH 1/3] docs: explain differential methods and streamline contribution forms --- .github/ISSUE_TEMPLATE/bug_report.yml | 57 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 41 ++++++++++++++++ .github/pull_request_template.md | 19 ++++++++ README.md | 27 ++++++++++ 4 files changed, 144 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..f790ca1b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,57 @@ +name: Bug report +description: Something in MetaManifold does not work as documented. +labels: [bug] +body: + - type: markdown + attributes: + value: | + Search the existing issues first. Raise issues about a fork's own code on that fork. + - type: textarea + id: steps + attributes: + label: Steps or command + description: The command you ran, or the steps in the web interface, so that someone else can repeat them. + validations: + required: true + - type: textarea + id: expected + attributes: + label: What you expected + validations: + required: true + - type: textarea + id: actual + attributes: + label: What happened + description: Include the error message, the server log lines, or a screenshot. + validations: + required: true + - type: input + id: julia + attributes: + label: Julia version + placeholder: output of `julia --version` + validations: + required: true + - type: input + id: r + attributes: + label: R version + description: Only if the problem touches the R runtime; leave empty if you do not know it. + placeholder: output of `R --version | head -1` + - type: input + id: browser + attributes: + label: Browser and version + description: Only for problems in the web interface; leave empty for command-line reports. + - type: input + id: commit + attributes: + label: MetaManifold commit + placeholder: output of `git rev-parse --short HEAD` + - type: textarea + id: config + attributes: + label: Relevant configuration + description: The keys from `pipeline.yml` or the run's `run_config.yml` that bear on the problem. + render: yaml diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..312c2aec --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,41 @@ +name: Feature request +description: Suggest a new feature or a change to an existing one. +labels: [enhancement] +body: + - type: markdown + attributes: + value: | + Search the existing issues first. To change an architectural decision, describe the change + here before writing any code. The settled decisions in CONTRIBUTING.md can be discussed in an + issue, but a pull request does not reopen them. + - type: textarea + id: problem + attributes: + label: Problem + description: What you are trying to do, and what stops you now. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed change + description: What MetaManifold should do instead. For a statistical method, name the method and a reference for it. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + - type: dropdown + id: area + attributes: + label: Area + options: + - Pipeline stages + - Analysis and statistics + - Web interface + - Configuration + - Installation and toolchain + - Other + validations: + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..d7f121ff --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,19 @@ +## Change and reason + + + +## Validation + + + +## Scope + + + +## Contribution checks + +- [ ] I followed [CONTRIBUTING.md](../CONTRIBUTING.md). +- [ ] This branch starts at current upstream main and contains no merges from fork main. +- [ ] CI has run and passes. +- [ ] Existing licensing, citation and acknowledgement text is unchanged. diff --git a/README.md b/README.md index 1fe02ca8..dee3ec40 100644 --- a/README.md +++ b/README.md @@ -240,6 +240,33 @@ The composition view classifies each ASV/OTU into a biological category and rend Organism-category composition of two runs as stacked bars

+### Differential abundance + +In a study's analysis workspace, select two conditions (runs or pooled-run +subgroups), a results table and a shared taxonomic rank. The first condition +is the reference. Counts are aggregated by taxon after the selected read-count +bounds and applicable `analysis.exclude_categories` filters. + +`analysis.differential.method` chooses the method: + +- `nb_glm` (default): a negative-binomial GLM per taxon using `MASS::glm.nb`, + with a library-size offset. The effect is log2 fold change; positive values + indicate greater abundance in the second condition. `offset` selects `tss` + (default) or `rle` scaling. +- `clr_welch`: Welch's t-test on centred log-ratios after multiplicative zero + replacement with `zCompositions::cmultRepl`. The effect is a CLR difference, + not a fold change. `replacement_delta` controls the replacement fraction + (default 0.65); `offset` is not used. + +For either method, `min_prevalence` (default 0) filters taxa by the fraction of +samples with nonzero counts. Benjamini–Hochberg adjustment includes only taxa +that produced a p-value. Failed or filtered taxa have no substitute p-value; +inspect their status and note in the results table. Invalid input or an +unavailable required R package produces an explicit error. + +Implementation and reference tests: `src/analysis/differential.jl`, +`src/server/routes/analysis.jl`, and `test/unit/test_differential.jl`. + ### Figures and report The Figures tab lays analysis charts out on a page (A4, letter or a journal From ea974a2328f7f44ad9afeb2f10e5803cd4e31e62 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 17 Oct 2026 04:26:56 +0100 Subject: [PATCH 2/3] docs: clarify that workspace does not apply sample read bounds --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dee3ec40..c4307a2d 100644 --- a/README.md +++ b/README.md @@ -244,8 +244,10 @@ The composition view classifies each ASV/OTU into a biological category and rend In a study's analysis workspace, select two conditions (runs or pooled-run subgroups), a results table and a shared taxonomic rank. The first condition -is the reference. Counts are aggregated by taxon after the selected read-count -bounds and applicable `analysis.exclude_categories` filters. +is the reference. Counts are aggregated by taxon after applicable +`analysis.exclude_categories` filters. This workspace does not pass sample +read-count bounds to the differential-abundance request, so those bounds do +not exclude samples from this analysis. `analysis.differential.method` chooses the method: From f841caa514cd8ff4745de5937df6b55b2fc27fb3 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 17 Oct 2026 11:50:59 +0100 Subject: [PATCH 3/3] docs: clarify study-scoped differential options and fix contribution link --- .github/pull_request_template.md | 2 +- README.md | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d7f121ff..d5560a53 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,7 +13,7 @@ ## Contribution checks -- [ ] I followed [CONTRIBUTING.md](../CONTRIBUTING.md). +- [ ] I followed [CONTRIBUTING.md](https://github.com/JoshuaJewell/MetaManifold-WebUI/blob/main/CONTRIBUTING.md). - [ ] This branch starts at current upstream main and contains no merges from fork main. - [ ] CI has run and passes. - [ ] Existing licensing, citation and acknowledgement text is unchanged. diff --git a/README.md b/README.md index c4307a2d..ecffd7d8 100644 --- a/README.md +++ b/README.md @@ -249,6 +249,11 @@ is the reference. Counts are aggregated by taxon after applicable read-count bounds to the differential-abundance request, so those bounds do not exclude samples from this analysis. +All `analysis.differential` options below (`method`, `offset`, +`min_prevalence` and `replacement_delta`) are resolved at study scope. +Set them in the study configuration; group and run overrides are not used +by this endpoint, including when called from a group Analysis workspace. + `analysis.differential.method` chooses the method: - `nb_glm` (default): a negative-binomial GLM per taxon using `MASS::glm.nb`,