mcvickerlab · Jaureguy760 · Apr 19, 2026 · Apr 19, 2026
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -117,7 +117,7 @@ calibrated for the overdispersion typical of RNA-seq count data.
 
 The standard threshold is FDR < 0.05. For discovery analyses you may want
 FDR < 0.1. For validation or follow-up experiments, consider FDR < 0.01.
-See :doc:`methods/statistical_models` for the BH procedure and the NaN-propagation warning.
+See :doc:`user_guide/analysis` for the BH procedure and the NaN-propagation warning.
 
 **My output has very few significant sites. What's wrong?**
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -77,7 +77,6 @@ Documentation
    :caption: Statistical Methods
 
    methods/mapping_filter
-   methods/statistical_models
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/methods/mapping_filter.rst b/docs/source/methods/mapping_filter.rst
@@ -320,7 +320,7 @@ The typical WASP2 workflow:
 See Also
 --------
 
-- :doc:`statistical_models` — beta-binomial LRT and FDR applied to the counts
+- :doc:`/user_guide/analysis` — beta-binomial LRT + FDR CLI and defaults
 
 References
 ----------

diff --git a/docs/source/methods/statistical_models.rst b/docs/source/methods/statistical_models.rst
diff --git a/docs/source/tutorials/bulk_workflow.rst b/docs/source/tutorials/bulk_workflow.rst
@@ -110,7 +110,7 @@ Step 3 — Test for allelic imbalance
 
 The beta-binomial LRT tests :math:`\mu = 0.5` against :math:`\mu \neq 0.5`
 per region, correcting for overdispersion and multiple testing via
-Benjamini–Hochberg (:doc:`/methods/statistical_models`).
+Benjamini–Hochberg (:doc:`/user_guide/analysis`).
 
 ``--phased`` applies only when the VCF GT field uses ``0|1`` / ``1|0``; pass
 it off for unphased data.
@@ -168,5 +168,5 @@ See Also
 - :doc:`/user_guide/counting` — counting CLI reference
 - :doc:`/user_guide/analysis` — analysis CLI reference
 - :doc:`/methods/mapping_filter` — canonical WASP filter contract
-- :doc:`/methods/statistical_models` — the LRT and beta-binomial model
+- :doc:`/user_guide/analysis` — analysis CLI + defaults + contracts
 - :doc:`/tutorials/single_cell_workflow` — single-cell RNA-seq / ATAC-seq
diff --git a/docs/source/tutorials/single_cell_workflow.rst b/docs/source/tutorials/single_cell_workflow.rst
@@ -160,5 +160,5 @@ See Also
 
 - :doc:`/user_guide/single_cell` — barcode format, Seurat/Scanpy export
 - :doc:`/user_guide/analysis` — analysis CLI reference
-- :doc:`/methods/statistical_models` — beta-binomial LRT
+- :doc:`/methods/mapping_filter` — canonical WASP filter contract
 - :doc:`bulk_workflow` — sibling tutorial for bulk RNA-seq / ATAC-seq
diff --git a/docs/source/user_guide/analysis.rst b/docs/source/user_guide/analysis.rst
@@ -78,6 +78,29 @@ Notes
 * For bulk analysis, region columns are auto-detected when present in the count
   TSV. Use ``--region_col`` only when you need to override that behavior.
 
+Defaults and contracts
+----------------------
+
+- ``pseudocount`` defaults to **1** (added to both ``ref_count`` and
+  ``alt_count`` — Laplace-style shrinkage toward :math:`\mu = 0.5`,
+  conservative under :math:`H_0`).
+- ``min_count`` defaults to **10**; regions with :math:`N < 10` are dropped.
+- Beta-binomial LRT: :math:`\rho` is held at its **null-model MLE** while
+  maximizing the alternative likelihood over :math:`\mu` (profile likelihood,
+  df = 1). :math:`\rho` is not jointly re-estimated under :math:`H_1`.
+- Dispersion optimizer bounds :math:`\rho \in (10^{-6},\, 1-10^{-6})`; the
+  linear-dispersion model clips the logit at :math:`\pm 10` for numerical
+  stability on extreme :math:`N`.
+- FDR correction uses :func:`scipy.stats.false_discovery_control` with
+  ``method='bh'`` (Benjamini–Hochberg). ``scipy`` raises on NaN p-values,
+  but a hand-written BH loop using ``np.minimum.accumulate`` silently
+  propagates NaN through the cumulative minimum — always drop or impute
+  NaN p-values before BH correction.
+
+See the upstream mapping-filter docs (:doc:`/methods/mapping_filter`) for the
+WASP2 canonical filter contract that applies to both remapping and counting
+steps.
+
 Outputs
 -------