diff --git a/apps/cadecon/src/lib/tutorial/content/01-basics.ts b/apps/cadecon/src/lib/tutorial/content/01-basics.ts index ef9962b..41bc272 100644 --- a/apps/cadecon/src/lib/tutorial/content/01-basics.ts +++ b/apps/cadecon/src/lib/tutorial/content/01-basics.ts @@ -67,7 +67,7 @@ export const basicsTutorial: Tutorial = { element: '[data-tutorial="kernel-convergence"]', title: 'Watching It Converge', description: - 'As the run increases in iterations, these tabbed charts track the learning process: Kernel shape over iterations, plus Alpha, Threshold, PVE, Event Rate, and Spike Eff. trends. A good run shows these settling toward stable values. Don\u2019t judge a fit until the run has converged.', + 'As the run iterates, these tabbed charts track the learning process. Asymptote (shown first) is the at-a-glance health check \u2014 small charts of the four things that should flatten out as the run settles: kernel shape (peak time & FWHM), kernel-fit quality (R\u00b2), reconstruction quality (PVE), and activity stability. Kernel shows the kernel shape evolving over iterations with the per-subset spread; Distributions shows per-cell histograms once the run finishes. A good run shows the Asymptote curves leveling off \u2014 don\u2019t judge a fit until the run has converged.', side: 'bottom', popoverClass: 'driver-popover--wide', }, diff --git a/apps/cadecon/src/lib/tutorial/content/03-theory.ts b/apps/cadecon/src/lib/tutorial/content/03-theory.ts index 6fe9d85..6e96349 100644 --- a/apps/cadecon/src/lib/tutorial/content/03-theory.ts +++ b/apps/cadecon/src/lib/tutorial/content/03-theory.ts @@ -96,16 +96,11 @@ export const theoryTutorial: Tutorial = { 'Both parts of the loop improve each other over each iteration until they converge on a consistent answer. To handle large recordings, many subsets of cells and time are solved in parallel and their kernels combined. This back-and-forth is exactly what you see happening in the convergence panel.', }, // Step 11: Stopping + final inference. - // NOTE: The exact stop criterion \u2014 and whether the reported kernel comes from - // the stopping iteration or a potentially better earlier iteration \u2014 is still - // being finalized (see iteration-manager.ts: best-residual tracking + the - // currently-disabled patience early-stop). Keep this description general until - // the approach is locked in, then tighten the wording here. { title: 'How does CaDecon know when to stop?', description: - 'More iterations aren\u2019t always better. Once the kernel and spikes stop changing much from one pass to the next, extra iterations add little \u2014 and the fit can even drift after it has peaked. CaDecon watches how much the kernel changes between iterations and settles once it stabilizes. In practice a good solution usually emerges within just a handful of iterations.

' + - 'There is also a maximum-iteration limit, but that is only a safety cap to stop a run that never settles \u2014 it is not how a healthy run should normally end. With a stable kernel in hand, CaDecon runs one final inference across every cell, which is why results appear for all your cells, not just the subsets it learned from.', + 'More iterations aren\u2019t always better. Once the kernel stops changing much from one pass to the next, extra iterations add little \u2014 and the fit can even drift after it has peaked. Rather than watch the raw time constants (which can trade off against each other), CaDecon judges convergence by the kernel\u2019s shape \u2014 its rise-to-peak time and its width (FWHM). An iteration counts as stable when both change by less than a small tolerance, and CaDecon declares convergence only after several consecutive stable iterations, so one lucky pass can\u2019t stop it early. In practice a good solution usually emerges within just a handful of iterations.

' + + 'To guard against any late drift, the reported kernel is the consensus (the median shape) of the last few iterations, not whatever the final pass happened to produce. You can make the run stop sooner or keep refining with the Convergence Tolerance setting. There is also a maximum-iteration limit, but that is only a safety cap for a run that never settles \u2014 not how a healthy run should normally end. With a stable kernel in hand, CaDecon runs one final inference across every cell, which is why results appear for all your cells, not just the subsets it learned from.', }, // Step 12: Completion { diff --git a/apps/cadecon/src/lib/tutorial/content/04-interpreting.ts b/apps/cadecon/src/lib/tutorial/content/04-interpreting.ts index 01a084c..88cfc58 100644 --- a/apps/cadecon/src/lib/tutorial/content/04-interpreting.ts +++ b/apps/cadecon/src/lib/tutorial/content/04-interpreting.ts @@ -22,7 +22,7 @@ export const interpretingTutorial: Tutorial = { element: '[data-tutorial="kernel-convergence"]', title: 'Signs of Healthy Convergence', description: - 'Click through the tabs. Kernel and PVE are your first checks: the kernel shape should stop changing and PVE should plateau. Threshold and Alpha should settle rather than drift. Warning signs: values still moving when the run ends (the kernel never stabilized — usually low SNR or an unlucky subset draw; try higher coverage or re-tiling), or a sharp reset mid-run followed by divergence.', + 'Start on the Asymptote tab — its four small charts are your first check. Kernel shape (peak time & FWHM), kernel-fit R², reconstruction PVE, and activity stability should all flatten toward a plateau as the run settles; the green marker shows the iteration where CaDecon declared convergence. The Kernel tab shows the shape itself over iterations, and Distributions shows the per-cell alpha, PVE, and event-rate spread. Warning signs: curves still moving when the run ends (the kernel never stabilized — usually low SNR or an unlucky subset draw; try higher coverage or re-tiling), or a sharp reset mid-run followed by divergence.', side: 'bottom', popoverClass: 'driver-popover--wide', }, @@ -31,7 +31,7 @@ export const interpretingTutorial: Tutorial = { element: '[data-tutorial="kernel-display"]', title: 'Judging Kernel Quality', description: - 'The learned kernel should look like a real calcium transient: a fast rise to a single peak, then a smooth decay. The per-subset free-kernel curves should cluster tightly around the fitted model. Bumpy, multi-peaked, or widely scattered curves mean the subsets disagreed which makes the kernel uncertain. If this is the case, don\u2019t over-trust the deconvolved output. If ground truth is available (like in demo data), it overlays here for comparison.', + 'The learned kernel should look like a real calcium transient: a fast rise to a single peak, then a smooth decay. The per-subset free-kernel curves should cluster tightly around the fitted model. Bumpy, multi-peaked, or widely scattered curves mean the subsets disagreed which makes the kernel uncertain. If this is the case, don\u2019t over-trust the deconvolved output. Watch for a degenerate-fit warning here (e.g. \u201c\u26a0 2/8 fits degenerate\u201d): it means some subsets produced no usable calcium shape \u2014 typically the subsets that caught mostly noise \u2014 which is a cue to raise coverage or re-tile. If ground truth is available (like in demo data), it overlays here for comparison.', side: 'left', }, // Step 4: Iteration selector diff --git a/apps/cadecon/src/lib/tutorial/theory-figures.ts b/apps/cadecon/src/lib/tutorial/theory-figures.ts index abad450..f977d08 100644 --- a/apps/cadecon/src/lib/tutorial/theory-figures.ts +++ b/apps/cadecon/src/lib/tutorial/theory-figures.ts @@ -11,6 +11,7 @@ */ import { computeKernel, computeKernelAnnotations } from '@calab/compute'; +import { OKABE_ITO, NEUTRAL } from '@calab/ui/chart'; // --- Illustrative kernel for the figure (a generic GCaMP-like shape; these are // display-only constants, not algorithm parameters). --- @@ -18,14 +19,14 @@ const FIG_TAU_RISE = 0.1; // s const FIG_TAU_DECAY = 0.6; // s const FIG_FS = 30; // Hz -// --- Colors (match the dashboard palette) --- -const KERNEL_COLOR = 'hsl(280,70%,60%)'; +// --- Colors (shared colorblind-safe Okabe-Ito palette, matching the dashboard) --- +const KERNEL_COLOR = OKABE_ITO.reddishPurple; // kernel / slow component const LABEL_COLOR = '#ccc'; const AXIS_COLOR = 'rgba(255,255,255,0.15)'; -const KEEP_COLOR = 'hsl(280,70%,60%)'; // graded values above the cutoff -const DROP_COLOR = '#6f6f7a'; // graded values below the cutoff (muted grey) -const SPIKE_COLOR = '#2ca02c'; // recovered spikes -const THRESH_COLOR = '#ff7f0e'; // cutoff line +const KEEP_COLOR = OKABE_ITO.reddishPurple; // graded values above the cutoff +const DROP_COLOR = NEUTRAL; // graded values below the cutoff (muted grey) +const SPIKE_COLOR = OKABE_ITO.bluishGreen; // recovered spikes (matches deconv activity) +const THRESH_COLOR = OKABE_ITO.orange; // cutoff line // --- Dimensions --- const SINGLE_W = 400;