From ecf640c9758bca6c7764eb33bbd5bd606878187b Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" Date: Thu, 15 Oct 2026 09:36:22 +0100 Subject: [PATCH] docs: optional environment fields in the bug form; the clr_welch settings in the README Both CodeRabbit findings from #143, accepted; the PR merged before the fixes could ride on it, so they land here. - The bug report form required R and browser versions from everyone: a command-line reporter has no browser to name, and a web-interface reporter often cannot know the server's R version, so both fields forced placeholder answers. They are now optional, each with the wording that says when it applies; Julia stays required, since every reporter runs the Julia server. - The differential-abundance README section described only the default nb_glm method and listed only offset and min_prevalence, presenting the analysis as NB-only; clr_welch and replacement_delta have been in the pipeline config and code since the upstream syncs. The section now documents method and replacement_delta, notes that offset applies to nb_glm only, and states clr_welch's effect as a CLR difference, not a fold change. The wording follows config/defaults/pipeline.yml's own comments for the same keys. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- .github/ISSUE_TEMPLATE/bug_report.yml | 6 ++---- README.md | 27 ++++++++++++++++++++------- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 3cf88518..f790ca1b 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -37,15 +37,13 @@ body: 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` - validations: - required: true - type: input id: browser attributes: label: Browser and version - validations: - required: true + description: Only for problems in the web interface; leave empty for command-line reports. - type: input id: commit attributes: diff --git a/README.md b/README.md index dafa4711..bbdd938d 100644 --- a/README.md +++ b/README.md @@ -260,20 +260,33 @@ sub-group. Counts are summed per taxon at the chosen rank, with rows that have no name at that rank pooled as `Unclassified`. This happens after the read-count bounds and any `analysis.exclude_categories` entry that applies to `differential`. Each -taxon is fitted with its own negative-binomial GLM, `MASS::glm.nb(y ~ group + -offset(log(size factor)))`, on the raw integer read counts. There are no -pseudocounts. The group coefficient gets a Wald test, and Benjamini-Hochberg -adjustment runs over the taxa that produced a p-value. Size factors come from -the whole count matrix and are centred to a geometric mean of 1. The code is in +taxon is fitted by the configured method. The default, `nb_glm`, fits a +negative-binomial GLM, `MASS::glm.nb(y ~ group + offset(log(size factor)))`, +on the raw integer read counts; there are no pseudocounts, the group +coefficient gets a Wald test, and the effect is a log2 fold change. Size +factors come from the whole count matrix and are centred to a geometric mean +of 1. The alternative, `clr_welch`, runs Welch's t-test on centred log-ratios +over the taxa passing `min_prevalence`, after `zCompositions::cmultRepl` +replaces their zeros; its effect is a difference in CLR units, not a fold +change. Under either method, Benjamini-Hochberg adjustment runs over the taxa +that produced a p-value. The code is in `src/analysis/differential.jl`, and the route in `src/server/routes/analysis.jl`. Settings live under `analysis.differential` (see [Configuring analysis](#configuring-analysis-analysis-in-pipelineyml)): +- `method`: `nb_glm` (default) or `clr_welch`, as above. - `offset`: `tss` (default) uses each sample's total reads. `rle` uses the - median of ratios over the taxa with reads in every sample. + median of ratios over the taxa with reads in every sample. Used by `nb_glm` + only; `clr_welch` ignores it, since log-ratios carry no library size. - `min_prevalence`: a fraction from 0 to 1 (default 0). A taxon with reads in a - smaller fraction of the samples is not fitted. + smaller fraction of the samples is not fitted. For `clr_welch` it is applied + before zero replacement, so on a sparse table it also keeps imputed values + for rare taxa out of every sample. +- `replacement_delta`: `clr_welch` only; `cmultRepl`'s `frac`, between 0 and 1 + (default 0.65). An imputed proportion above its taxon's smallest observed + proportion is lowered to this fraction of it. A replaced zero is not a + measurement. The result is a volcano plot and a table. The plot draws log2 fold change against -log10 of the raw p-value, coloured by whether the adjusted p-value is