From fb82c67414cfb7521a6b33925dafa319d77b0b6a Mon Sep 17 00:00:00 2001 From: jamesli124 <58196853+jamesli124@users.noreply.github.com> Date: Thu, 23 Jul 2026 14:38:26 -0500 Subject: [PATCH] docs: document the Miller-Madow correction added to regional-mds PR #183 added an opt-in --miller-madow flag to regional-mds (bias correction for rMDS in low-depth regions) but only updated docstrings and CLI help text, not the hand-written prose docs: - user_guide/features.rst: explains what the correction does and that it's off by default. - workflow/index.rst: the Snakemake config's per-command option list grouped "mds / regional-mds" as sharing one option set via a shared *_sep/*_header shorthand; --miller-madow only exists on regional-mds, so that was no longer accurate. Split into two entries. The API reference (autodoc, pulls from docstrings) and CLI reference (sphinx-click, pulls from --help) already covered this automatically -- verified by a full `sphinx-build -W --keep-going` (zero warnings) and inspecting the rendered HTML output for both. Co-Authored-By: Claude Sonnet 5 --- docs/documentation/user_guide/features.rst | 11 ++++++++--- docs/documentation/workflow/index.rst | 6 +++++- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/documentation/user_guide/features.rst b/docs/documentation/user_guide/features.rst index c11578c..6333bfc 100644 --- a/docs/documentation/user_guide/features.rst +++ b/docs/documentation/user_guide/features.rst @@ -59,9 +59,14 @@ Motif Diversity Score (MDS) MDS (*Jiang et al. 2020*) is the normalized Shannon entropy of the end-motif k-mer distribution, summarizing end-motif diversity in a single number. The regional Motif Diversity Score (rMDS) computes that same entropy per genomic -region (*Bandaru et al. 2026*). - -:Commands: ``mds`` (whole sample), ``regional-mds`` (per region) +region (*Bandaru et al. 2026*). Because the underlying plug-in entropy +estimator is biased downward in regions with few fragments, ``regional-mds`` +accepts an optional ``--miller-madow`` flag that applies a Miller-Madow bias +correction, making rMDS values comparable across regions of differing depth. +It is off by default, so existing output is unchanged unless requested. + +:Commands: ``mds`` (whole sample), ``regional-mds`` (per region, optionally + bias-corrected with ``--miller-madow``) Cleavage profile ---------------- diff --git a/docs/documentation/workflow/index.rst b/docs/documentation/workflow/index.rst index 39944ed..5e9c989 100644 --- a/docs/documentation/workflow/index.rst +++ b/docs/documentation/workflow/index.rst @@ -179,7 +179,11 @@ Each command's options below carry the FinaleToolkit flag they map to. Optional (``--strand``: ``both``, ``forward``, or ``reverse``), ``*_mapq`` (``-q``), ``*_workers`` (``-t``). -**mds** / **regional-mds**: ``*_sep`` (``-s``), ``*_header`` (``--header``). +**mds**: ``mds_sep`` (``-s``), ``mds_header`` (``--header``). + +**regional-mds**: ``regional_mds_sep`` (``-s``), ``regional_mds_header`` +(``--header``), ``regional_mds_miller_madow`` (``--miller-madow``; +Miller-Madow bias correction, off by default). **wps**: ``wps_site_bed`` (positional REGIONS), ``wps_reference`` (``-r``), ``wps_chrom_sizes`` (``--chrom-sizes``), ``wps_interval_size`` (``-i``),