docs(reference): complete API coverage — every __all__ symbol documented (goal-13j) (#57)

chaoming0625 · web-flow · commit b843b9a0bc2d · 2026-06-19T17:03:11.000+08:00
Author observation.rst as the canonical home for the HRF-kernel family, HRFBold
and TemporalAverage (moved off forward.rst to avoid duplicate-object warnings).
Add the previously-undocumented symbols to their canonical pages:
- models.rst: XY_Oscillator, JansenRitTR, the 10 WilsonCowan variants
- noise.rst: the Noise base class
- forward.rst: LeadfieldReadout (+ cross-refs to observation.rst)
- utilities.rst: delay_index, and the Initializer/Array/Parameter type aliases

index.rst: name the Simulator/Network/Fitter entry points in API conventions.

Coverage audit: all 84 brainmass.__all__ symbols documented on exactly one page
(0 missing, 0 duplicated). make doctest green (257 tests, 0 failures); make html
build succeeded with 0 new broken-ref/orphan/duplicate warnings.

Co-authored-by: Chaoming Wang &lt;wcm.brainsim@gmail.com&gt;
diff --git a/CONTEXT.md b/CONTEXT.md
@@ -936,3 +936,51 @@ Gotchas inherited: (a) execute notebooks with PYTHONPATH=<worktree-root> jupyter
 - **⚠ Build-helper re-run trap (cost a clobber-and-recover cycle):** the gitignored `dev/build_case_studies.py` regenerates **all 5** notebooks (stripping outputs). After executing 3, I edited the spec + re-ran the builder to fix HORN → it **silently overwrote the 3 already-executed notebooks back to un-executed**. They showed `errors=0` but ALSO `outputs=0` (the tell). **Lesson: after ANY builder re-run, re-execute EVERY notebook, not just the changed one** — or check file size / output-count, not just exit code. (Also: `jq '.cells[].outputs[]?'` returned empty/`null` and masked this; a small Python `json.load` loop counting `output_type`/`image/png` per cell is the reliable check.)
 - **Per-model API confirmations (executed):** `WongWangStep` = reduced **decision** model, `update(coherence=)` → `(r1,r2)` Hz, states `S1`/`S2`, noise via `noise_s1`/`noise_s2` (`GaussianNoise(N, sigma=…*u.nA)`); distinct from `WongWangExcInhStep`. `JansenRitStep.update` takes a 3-tuple `(M_inp*u.mV, E_inp*u.Hz, I_inp*u.mV)` via `Simulator(inputs=lambda i,t: (...))`; `eeg()` = `E−I` mV. **MEG forward from an mV source: use base `LeadFieldModel(sensor_unit=u.tesla, scale=u.nA*u.meter/u.mV)`** — `MEGLeadFieldModel`'s hardcoded `scale=nA·m/tesla` is dimensionally wrong for an mV source and yields mV not T (the standing goal-13e MEG-scale note, confirmed again).
 - **make html:** baseline (detached `git worktree add --detach /tmp/bm_base_13i origin/main`, `make clean` first) and worktree both **build succeeded, 108 warnings / 93 unique normalized** (strip worktree path + `:LINE:`), **byte-identical: 0 new, 0 removed** — same pre-existing autosummary-duplicate + source-docstring set as goals 13a–13h. `nb_execution_mode="off"` renders committed outputs; all 5 case studies appear in `_build/html/gallery/case_studies/*.html` with their real results (e.g. "fitted C", "final test accuracy" grep-confirmed in the HTML). Only the 5 `docs/gallery/case_studies/*.ipynb` are tracked changes; `dev/` + `_build/` + `*/generated` stay gitignored.
+
+### 2026-06-19 · goal-13j reference-polish
+- **Headline — the API reference is now COMPLETE: every one of the 84 `brainmass.__all__`
+  symbols is documented on exactly ONE reference page** (audit script over `__init__.py`
+  `__all__` × the autosummary/`.. data::` entries of every `reference/*.rst`: 0 missing, 0
+  duplicated; only `__version__`/`__version_info__` are intentionally un-autosummary'd version
+  metadata). Docs-only: `git diff --stat origin/main -- brainmass/` **empty**; 6 RST files changed
+  (`forward`, `index`, `models`, `noise`, `observation`, `utilities`). `make doctest` **257 tests,
+  0 failures**; `make html` **build succeeded**.
+- **Coverage gaps found + where fixed:** `XY_Oscillator` + `JansenRitTR` + the **10 WilsonCowan
+  variants** (`WilsonCowanNoSaturationStep`/`Symmetric`/`Simplified`/`Linear`/`Divisive`/
+  `DivisiveInput`/`Delayed`/`Adaptive`/`ThreePopBase`/`ThreePopulationStep`) → `models.rst` (new
+  "Wilson-Cowan Variants" section + an Oscillator-base note + a JansenRitTR note); **`Noise`** base
+  → `noise.rst` (new "Base Class" section); **`LeadfieldReadout`** → `forward.rst` lead-field
+  autosummary (+ a unit-aware-`LeadFieldModel`-vs-trainable-`LeadfieldReadout` "use which" note);
+  **`delay_index`** + type aliases **`Initializer`/`Array`/`Parameter`** → `utilities.rst` (aliases
+  via `.. data::`, NOT autosummary — they are `typing.Union`/`ArrayLike`, not classes/functions, so
+  autosummary/autoclass would warn). Renamed the utilities page title to "Utilities & Types".
+- **⚠ THE canonical-page trap (the central design decision):** the 7 observation symbols
+  (`HRFKernel`, the 4 HRF kernels, `HRFBold`, `TemporalAverage`) were **already autosummary'd on
+  `forward.rst`** (goal-12). Authoring `observation.rst` with its own autosummary would have created
+  **7 NEW `duplicate object description` warnings** (the exact failure mode the goal warned about).
+  Fix: made **`observation.rst` the single canonical home** (full autosummary + intro + math +
+  runnable `>>>` doctests) and **removed those autosummary entries from `forward.rst`**, replacing
+  them with `:class:~brainmass.X` cross-refs + a `:doc:observation` pointer. Result: duplicate-object
+  warnings **53 → 53 (zero delta)**. Lesson for any future "add a page" docs goal: grep the existing
+  `reference/*.rst` for the symbol FIRST; if it's already autosummary'd elsewhere, MOVE it (don't
+  add a second `:toctree:` entry) — cross-reference with `:class:`/`:func:` instead.
+- **⚠ make html warning delta is +21 raw (108→129) / +21 unique normalized (93→114), and it is
+  EXPECTED + benign:** all 21 are pre-existing **source-docstring** formatting warnings
+  (`[docutils]` "Field list ends without a blank line" ×11 + `[ref.footnote]` "Footnote [1]/[2] is
+  not referenced" ×10) emitted from the `brainmass/` docstrings of the **WilsonCowan variants +
+  LeadfieldReadout** — symbols that had **never been rendered into any page before** (no autosummary
+  entry → autodoc never ran on them). Documenting them (the goal's whole point) makes autosummary
+  generate their stub pages, which surfaces the latent docstring warnings. **0 new broken-ref, 0 new
+  orphan, 0 new/changed duplicate-object, 0 removed** — the only gated categories are all clean; all
+  my `:class:`/`:doc:` cross-refs resolve. These warnings live in source I'm forbidden to touch
+  (`git diff --stat origin/main -- brainmass/` empty); a fast follow-up could fix the WilsonCowan/
+  LeadfieldReadout docstrings (blank line before the field-list end; add `[1]`/`[2]` in-text
+  back-references) to retire all 21 at the source.
+- **Baseline method (unchanged from 13e–13i):** detached `git worktree add --detach /tmp/bm_base_13j
+  origin/main`, `make clean` first on BOTH sides, normalize by stripping the worktree path +
+  `:LINE:`, then `comm` the sorted-unique sets — the incremental build re-emits only changed-page
+  warnings and lies, so the clean normalized diff is the gate.
+- **index.rst** already listed all pages (table + quick-nav cards + toctree, from 13a/13b); added a
+  "High-level entry points" lead-in to the API-conventions section naming `Simulator`/`Network`/
+  `Fitter` and pointed the utilities row at "type aliases". `datasets.rst`/`viz.rst` (13b) verified
+  complete + style-consistent (autosummary-only house style) — no changes needed.
diff --git a/docs/reference/forward.rst b/docs/reference/forward.rst
@@ -136,29 +136,15 @@ BOLD signals are typically acquired at TR ~ 1-2 seconds. Downsample high-frequen
 Convolution-based BOLD (HRF kernels)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. autosummary::
-   :toctree: generated/
-   :nosignatures:
-   :template: classtemplate.rst
-
-   HRFBold
-   HRFKernel
-   FirstOrderVolterraHRFKernel
-   GammaHRFKernel
-   DoubleExponentialHRFKernel
-   MixtureOfGammasHRFKernel
-
-:class:`HRFBold` is a second, complementary BOLD path: instead of integrating the
-four-state Balloon-Windkessel ODE, it **convolves** downsampled neural activity
-with a closed-form hemodynamic response function (HRF) kernel, then decimates to
-the repetition time (TR):
-
-.. math::
-
-   \text{BOLD} = k_1 V_0 \,(\,h * y_{\text{ds}} - 1\,),
-
-where :math:`y_{\text{ds}}` is the temporally-averaged neural activity, :math:`h`
-the HRF kernel and :math:`*` 1-D convolution along time.
+:class:`BOLDSignal` is the biophysical (Balloon-Windkessel ODE) BOLD path. A
+second, complementary path -- :class:`~brainmass.HRFBold`, which **convolves**
+downsampled neural activity with a closed-form hemodynamic response function (HRF)
+kernel -- together with the HRF-kernel family
+(:class:`~brainmass.HRFKernel`, :class:`~brainmass.FirstOrderVolterraHRFKernel`,
+:class:`~brainmass.GammaHRFKernel`, :class:`~brainmass.DoubleExponentialHRFKernel`,
+:class:`~brainmass.MixtureOfGammasHRFKernel`) and the
+:class:`~brainmass.TemporalAverage` downsampler, are documented on the dedicated
+:doc:`observation` page.
 
 **When to use which BOLD path:**
 
@@ -167,7 +153,7 @@ the HRF kernel and :math:`*` 1-D convolution along time.
    :header-rows: 1
 
    * - Aspect
-     - :class:`HRFBold` (convolution)
+     - :class:`~brainmass.HRFBold` (convolution)
      - :class:`BOLDSignal` (Balloon-Windkessel)
    * - Form
      - Single linear convolution with an HRF kernel
@@ -179,57 +165,8 @@ the HRF kernel and :math:`*` 1-D convolution along time.
      - **Fitting** / quick BOLD from a long neural trajectory
      - Biophysical realism
 
-Both are kept; neither replaces the other.
-
-**HRF kernel family.** Four closed-form kernels (each a callable ``kernel(t)``
-returning a dimensionless :math:`h(t)`; ``t`` is a time :class:`~brainunit.Quantity`,
-or a plain array interpreted as milliseconds):
-
-- :class:`FirstOrderVolterraHRFKernel` -- TVB canonical underdamped damped-oscillator
-  (Friston et al. 2000).
-- :class:`GammaHRFKernel` -- peak-normalised gamma pdf (Boynton et al. 1996).
-- :class:`DoubleExponentialHRFKernel` -- damped-oscillation difference (Polonsky et al. 2000).
-- :class:`MixtureOfGammasHRFKernel` -- difference of gammas / SPM canonical (Glover 1999).
-
-**Example:**
-
->>> import brainmass
->>> import brainunit as u
->>> import jax.numpy as jnp
->>> t = jnp.arange(2000.)
->>> z = 1.0 + 0.5 * jnp.sin(2 * jnp.pi * t[:, None] / 800.0)   # slow neural drive
->>> bold = brainmass.HRFBold(
-...     period=200. * u.ms, downsample_period=4. * u.ms,
-...     kernel=brainmass.FirstOrderVolterraHRFKernel(duration=400. * u.ms),
-... )
->>> y = bold(z, dt=1. * u.ms)
->>> y.shape[1]
-1
-
-
-Temporal Averaging
-^^^^^^^^^^^^^^^^^^
-
-.. autosummary::
-   :toctree: generated/
-   :nosignatures:
-   :template: classtemplate.rst
-
-   TemporalAverage
-
-:class:`TemporalAverage` downsamples a trajectory by averaging over non-overlapping
-windows of ``w = round(period / dt)`` samples (``y[k] = mean(signal[k*w : (k+1)*w])``;
-trailing partial windows are dropped). It is the **averaging** complement to the
-point-decimation ``Simulator(sample_every=k)`` subsampling -- smoother and
-anti-aliased -- and is the downsampler :class:`HRFBold` uses internally. Apply it as
-a post-transform on a run trajectory:
-
->>> import brainmass
->>> import brainunit as u
->>> import jax.numpy as jnp
->>> signal = jnp.arange(20.).reshape(20, 1)
->>> brainmass.TemporalAverage(period=5. * u.ms)(signal, dt=1. * u.ms).shape
-(4, 1)
+Both are kept; neither replaces the other. See :doc:`observation` for the kernel
+forms, equations and runnable examples.
 
 
 EEG/MEG Lead-Field Models
@@ -243,7 +180,16 @@ EEG/MEG Lead-Field Models
    LeadFieldModel
    EEGLeadFieldModel
    MEGLeadFieldModel
-
+   LeadfieldReadout
+
+:class:`LeadFieldModel` (and its :class:`EEGLeadFieldModel` / :class:`MEGLeadFieldModel`
+specializations) is the **unit-aware physical** forward operator -- it carries
+brainunit units, aggregates vertices to regions, and can sample a measurement-noise
+covariance. :class:`LeadfieldReadout` is a complementary, lightweight **trainable**
+EEG/MEG head on unitless arrays: a single learnable lead-field matrix (optionally
+L1/L2 normalised) suitable for end-to-end gradient fitting. Use
+:class:`LeadFieldModel` when you have a physically-calibrated lead field with units;
+use :class:`LeadfieldReadout` when the projection is a parameter to be learned.
 
 Lead-field models perform linear mapping from source dipoles to sensor measurements:
 
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -48,7 +48,7 @@ The ``brainmass`` package provides the following components:
    * - :doc:`viz`
      - Thin plotting helpers for time series, connectivity, and spectra
    * - :doc:`utilities`
-     - Utility functions for common operations
+     - Utility functions, the model catalogue, and public type aliases
 
 
 Quick Navigation
@@ -121,7 +121,21 @@ Quick Navigation
 General API Conventions
 -----------------------
 
-All neural mass models and dynamics classes in ``brainmass`` follow these conventions:
+**High-level entry points:**
+
+Most workflows go through three orchestration classes (see :doc:`orchestration`)
+rather than driving the step models by hand:
+
+- :class:`Simulator` -- wraps any model (a single node or a whole-brain
+  :class:`Network`) in the compiled run loop and collects monitored trajectories
+  into a unit-aware result dict.
+- :class:`Network` -- wires a node model into a delay-coupled whole-brain network
+  from a connectome.
+- :class:`Fitter` -- fits a model's trainable parameters to data behind one
+  ``.fit`` call, swapping gradient / Nevergrad / SciPy backends.
+
+The per-step conventions below describe the underlying model contract that these
+entry points build on.
 
 **Initialization:**
 
diff --git a/docs/reference/models.rst b/docs/reference/models.rst
@@ -179,11 +179,16 @@ Oscillator Models
    :nosignatures:
    :template: classtemplate.rst
 
+   XY_Oscillator
    HopfStep
    VanDerPolStep
    StuartLandauStep
    KuramotoNetwork
 
+:class:`XY_Oscillator` is the shared two-variable ``(x, y)`` planar-oscillator base
+that :class:`HopfStep`, :class:`StuartLandauStep` and :class:`VanDerPolStep` specialise;
+instantiate the concrete subclasses for simulations.
+
 
 **Example: Hopf Oscillator**
 
@@ -253,8 +258,13 @@ Rate-Based Models
 
    WilsonCowanStep
    JansenRitStep
+   JansenRitTR
    WongWangStep
 
+:class:`JansenRitTR` wraps :class:`JansenRitStep` with an inner dt-substep loop that
+emits one output sample per acquisition repetition time (TR) -- the in-package
+precedent for TR-rate observation.
+
 
 **Example: Wilson-Cowan Model**
 
@@ -300,6 +310,35 @@ The Jansen-Rit model simulates EEG-like signals from a cortical column with thre
    # The output represents pyramidal membrane potential (EEG proxy)
 
 
+Wilson-Cowan Variants
+^^^^^^^^^^^^^^^^^^^^^^
+
+Beyond the canonical :class:`WilsonCowanStep`, ``brainmass`` ships a family of
+Wilson-Cowan variants that swap the activation nonlinearity, normalisation, or add
+adaptation / explicit delays / a third population. They share the same
+``(rE, rI)``-style state and ``update`` contract.
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+   :template: classtemplate.rst
+
+   WilsonCowanNoSaturationStep
+   WilsonCowanSymmetricStep
+   WilsonCowanSimplifiedStep
+   WilsonCowanLinearStep
+   WilsonCowanDivisiveStep
+   WilsonCowanDivisiveInputStep
+   WilsonCowanDelayedStep
+   WilsonCowanAdaptiveStep
+   WilsonCowanThreePopBase
+   WilsonCowanThreePopulationStep
+
+:class:`WilsonCowanThreePopBase` is the shared base for the three-population
+variant; instantiate :class:`WilsonCowanThreePopulationStep` (or another concrete
+variant) for simulations.
+
+
 Spiking Network Reductions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/reference/noise.rst b/docs/reference/noise.rst
@@ -115,6 +115,21 @@ For custom use cases, generate noise samples directly:
 API Reference
 -------------
 
+Base Class
+^^^^^^^^^^
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+   :template: classtemplate.rst
+
+   Noise
+
+:class:`Noise` is the abstract base every noise process subclasses; it defines the
+common ``in_size`` / ``update`` contract. Instantiate one of the concrete processes
+below rather than :class:`Noise` directly.
+
+
 Stateless Noise
 ^^^^^^^^^^^^^^^
 
diff --git a/docs/reference/observation.rst b/docs/reference/observation.rst
diff --git a/docs/reference/utilities.rst b/docs/reference/utilities.rst
