exp: freeze Larkum public innovation pilot

1 files changed, 97 insertions, 0 deletions

diff --git a/LARKUM_PUBLIC_PILOT.md b/LARKUM_PUBLIC_PILOT.md
new file mode 100644
index 0000000..883946d
--- /dev/null
+++ b/LARKUM_PUBLIC_PILOT.md
@@ -0,0 +1,97 @@
+# Larkum public-data innovation pilot
+
+## Purpose and status
+
+This exploratory pilot asks whether subtracting the dendritic activity predicted
+from local spine traffic exposes a direction-independent trial-outcome signal in
+public neural recordings.  It is an independent biological consistency test for
+the innovation operation, not a test of network training or an exact
+somato-dendritic residual.  The data structure and class counts were inspected
+before this protocol was fixed, so the result is not an untouched confirmation.
+
+The data are from Maristany de las Casas et al., *Science* (2026), “Tuft
+dendrites in frontal motor cortex enable flexible learning,” DOI
+`10.1126/science.adx4358`.  The archived public data are released under CC BY
+4.0 at `https://doi.gin.g-node.org/10.12751/g-node.etlk5k/`.
+
+## Fixed dataset
+
+Use the eleven `Figure2/Data/*_dff.mat` sessions in archive
+`10.12751_g-node.etlk5k.zip`:
+
+- animals `DCO1`, `DCO2`, and `DCO4`;
+- saline (`Sal`) and chemogenetic NDNF activation (`DCZ`) conditions;
+- trial-aligned `spine_local`, `branch`, `TrialTypes`, `Choice`, and `DirOut`;
+- omit trials with a non-finite choice or malformed neural arrays.
+
+No Figure 1, 3, 4, 5, or 6 endpoint enters this pilot.  Those modules do not
+provide the same trial-level pairing needed here.
+
+## Fixed innovation estimator
+
+For every session, subtract the first 30-frame mean from every spine and branch
+ROI on each trial.  The expected branch trace is a multi-output ridge regression
+from all local-spine traces, frame identity, instruction identity, and their
+interaction.  The ridge coefficient is fixed at `1.0`.
+
+The predictor never receives choice, correctness, outcome, drug condition, or
+future-session data.  Saline trials are five-fold cross-fitted in contiguous
+trial blocks.  The DCZ predictor is fitted once on all saline trials from the
+same session and then frozen.  The innovation is
+
+```text
+branch activity - predicted branch activity.
+```
+
+A simpler task-template residual subtracts the saline mean trace for the same
+instruction without using spine activity.
+
+## Fixed endpoint
+
+The outcome window is 0 to 1 second after report onset, corresponding to the
+public analysis time axis from -3 to 3 seconds over 180 frames.  Split this
+window into six bins.  In each bin summarize the population by signed mean,
+mean absolute activity, and RMS activity.  This produces the same 18 features
+for raw branch activity, task-template residual, spine-conditioned innovation,
+and local-spine activity.
+
+The primary endpoint is cross-instruction, leave-one-animal-out decoding of
+`DirOut`:
+
+1. hold out one animal;
+2. train a balanced logistic decoder on one instruction direction from the
+   other two animals;
+3. test it on the opposite instruction direction in the held-out animal;
+4. repeat in the other direction and for all three held-out animals;
+5. pool the out-of-fold predictions and report AUROC.
+
+This split is load-bearing.  Correctness is determined by instruction and lick
+direction, so ordinary random cross-validation can relabel sensory or movement
+activity as an outcome signal.  Under the cross-instruction split, a pure
+choice-direction signal reverses sign.  A choice-only decoder is retained as a
+negative control.
+
+Report separately for saline and DCZ:
+
+- AUROC for raw branch, task-template residual, spine-conditioned innovation,
+  local spine, and choice-only control;
+- per-animal AUROC and the number of correct/error trials;
+- the paired AUROC difference between innovation and raw branch;
+- the saline-minus-DCZ change in innovation AUROC;
+- 95% descriptive intervals from 5,000 session-block bootstrap samples,
+  resampling sessions within animal.
+
+The bootstrap describes stability across the released sessions.  With only
+three animals, it is not treated as population-level animal inference.
+
+## Decision rule
+
+The pilot supports the narrow biological claim only if saline innovation has
+AUROC above 0.5, exceeds raw branch activity, and the gain has the same sign in
+all three held-out animals.  A weaker DCZ innovation endpoint is a causal
+consistency result, not a required pass condition because DCZ has few error
+trials.  Failure, sign inconsistency, or an advantage confined to ordinary
+within-instruction decoding rejects this dataset as flagship evidence.
+
+Regardless of outcome, this pilot cannot establish improved learning,
+scalability, or an exact Harnett-style soma-dendrite residual.