From a840c5e65a3c36875fad4f7811cd265f86b09a30 Mon Sep 17 00:00:00 2001
From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com>
Date: Fri, 23 Oct 2026 00:48:11 +0000
Subject: [PATCH] docs: record the nine differential methods and the joint
 models' zero handling

`ROADMAP.md` still said that `nb_glm` and `clr_welch` "remain the existing
differential methods", which stopped being true when `zinb`, `hurdle_nb`,
`ancom_bc`, `aldex2`, `songbird`, `multinomial` and `dirichlet_multinomial`
landed. It now lists all nine and points at the README section, and records
that `songbird` (R) and `multinomial` (Julia) are two implementations of one
baseline-category model rather than two models.

The zero-handling note explained why a negative-binomial likelihood needs no
replacement but said nothing about the two joint multinomial models, whose
"when not to replace zeros" advice now names them: a zero count is part of the
likelihood, no size factor is fitted, and conditioning on each sample's read
total makes every effect a log ratio against a reference taxon.

Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
---
 ROADMAP.md                       | 7 ++++++-
 docs/statistics/zero-handling.md | 4 ++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index bc98c01c..4b4beb7f 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -6,7 +6,12 @@ occupancy work. The GitHub Wiki roadmap still needs a synchronized update; see
 
 ## Available now
 
-- `nb_glm` and `clr_welch` remain the existing differential methods.
+- The differential-abundance config offers four per-taxon count models
+  (`nb_glm`, `clr_welch`, `zinb`, `hurdle_nb`) and five compositional models
+  (`ancom_bc`, `aldex2`, `songbird`, `multinomial`, `dirichlet_multinomial`);
+  see [the differential-abundance section](README.md#differential-abundance).
+  `songbird` and `multinomial` are two implementations of the same
+  baseline-category multinomial model.
 - `zinb` and `hurdle_nb` are available in the differential-abundance config and
   UI. They report the count effect and zero/occurrence effect and test group
   effects jointly. The UI surfaces model cautions; BH adjustment remains on.
diff --git a/docs/statistics/zero-handling.md b/docs/statistics/zero-handling.md
index 66095019..49486999 100644
--- a/docs/statistics/zero-handling.md
+++ b/docs/statistics/zero-handling.md
@@ -105,6 +105,10 @@ there is no silent fallback to another estimator.
   valid observations under that model.
 - Raise `min_prevalence` when rare taxa would make imputed values dominate the
   composition. The result reports median and maximum imputed mass per sample.
+- Use `multinomial` or `dirichlet_multinomial` when the whole composition is the
+  unit of inference: a zero count is part of the likelihood, no size factor is
+  fitted, and conditioning on each sample's read total makes every effect a log
+  ratio against a reference taxon rather than an absolute abundance.
 - Consider an occupancy/observation model when detection itself is the object of
   inference, or a zero-inflated or hurdle model when structural and sampling
   zeros must be separated. Those models are not implemented by `clr_welch`, and