本项目是一条自包含的神经数据科学教学与验证流水线——每一本 canonical
notebook 都可以在 Jupyter 中按顺序 Run All 完整运行，不依赖任何外部
.py 模块。
流水线覆盖当前 19 本自包含 notebook（NB-00 → NB-12）：
- 非齐次 Poisson 过程（NHPP）与尖峰触发平均（STA/STC）
- 线性动力系统（LDS）与 Kalman 滤波 / RTS 平滑
- 变分推断生成模型（LFADS）
- 拓扑数据分析（TDA）：持久同调 + cocycle circular coordinates
- Poisson GLM 编码模型
- Bayesian 解码与信息论
- PCA / UMAP / CEBRA 嵌入
- RSA / CCA / CKA 表征比较
- 一致性 / 健全性审计脚本（仓库级
audit_notebooks.py，见下） - 经典 ML（K-means / DBSCAN / PCA / Isomap / t-SNE / UMAP）
- CANN、Fourier 稳定性、RNN 路径积分、ToMATo 拓扑聚类
- Place cell arena：DoG 感受野 + PC-GCRNN 训练
- Phase-shuffle 与 Gaussian-noise null 显著性检验（NB-10）
所有计算逻辑都内联在 cell 中：每个 notebook 的第一个 cell 提供了本项目唯一
的"持久化基础设施"——notebook_artifacts 助手（字节稳定 .npz 写入 + 同伴
.manifest.json），后续 NB 直接复制同一段 cell 到自己的导入区即可，无需
pipeline.py 或 artifact_contract.py。
- Python >= 3.10
- Conda (推荐) 或 pip
numpy
scipy
matplotlib
scikit-learn
statsmodels
torch
ripser (persim)
umap-learn
cebra
jupyter
安装命令（推荐使用 conda）：
conda create -n neural-ds python=3.10
conda activate neural-ds
conda install numpy scipy matplotlib scikit-learn statsmodels jupyter
pip install torch ripser umap-learn cebraNB-04B（LFADS）、NB-10A（CEBRA）和 NB-11（PC-GCRNN）支持 CUDA 加速：
conda install pytorch pytorch-cuda=11.8 -c pytorch -c nvidia无 GPU 时仍可运行，但速度会显著变慢。
cd /path/to/LU/notebooks在 Jupyter 中打开后 Run All，或：
jupyter nbconvert --to notebook --execute --inplace \
--ExecutePreprocessor.timeout=7200 NB-08A_Tuning_GLM_Ridge.ipynb按编号顺序运行 canonical notebook（每本都是自包含的，但会复用前序 artifact）：
# Canonical re-run (12 notebooks): each writes its artifact under
# notebooks/artifacts/ and a paired .manifest.json.
for notebook in \
NB-00_Setup_Foundations.ipynb \
NB-02A_NHPP_STA_STC.ipynb \
NB-04A_LDS_Kalman.ipynb \
NB-04B_LFADS.ipynb \
NB-06_TDA_Basics.ipynb \
NB-08A_Tuning_GLM_Ridge.ipynb \
NB-08B_Decoding_Information.ipynb \
NB-10A_Population_Embeddings.ipynb \
NB-12_Representational_Comparison.ipynb
do
jupyter nbconvert --to notebook --execute --inplace \
--ExecutePreprocessor.timeout=7200 "$notebook"
done
# Static audit script (no execution): checks JSON validity, parse(),
# no duplicate future imports, no saved exception outputs, no
# broken cross-notebook links, setup-cell consistency, and that all
# declared artifact dependencies form an acyclic DAG.
python audit_notebooks.py --manifest notebooks/artifacts --report audit_report.json教学层笔记本（NB-01/02/03/04/05/07/08/09/10/11）独立运行，无需 canonical 流水线产物。它们已经修补了与 NB-00 artifact 名的兼容性。
audit_notebooks.py 是仓库级静态审计脚本（不执行任何 cell）。它检查：
- 所有 19 本 notebook 是否是合法 JSON 且每个 code cell 可被
compile()解析 - 是否存在重复的
from __future__ import annotations - 是否遗留 saved exception outputs 或不存在的 notebook 交叉引用
- 所有声明的 artifact 输入是否形成无环 DAG（producer/consumer 一致）
- 当前源码哈希是否与新生成的 manifest 一一对应
python audit_notebooks.py --manifest notebooks/artifacts --report audit_report.json
cat audit_report.json环境恢复后的 数值 验收在每本 notebook 末尾的断言里： NB-02A 的最近邻 peak 距离、NB-04 的因果性、NB-04A 的 covariance ordering、 NB-06/10 的 null 全流水线重跑、NB-08A 的 fold-scaling、NB-08 的 Skaggs fixture、NB-10A 的 trial boundary、NB-11 的 median position error ≤ 0.10 m、 NB-12 的 held-out CCA。
- 40,000 个 time bins (80 trials × 500 bins/trial)
- 84 个神经元（24 HD + 24 place + 36 grid cells）
- Split 划分：Train（56 trials）/ Val（12 trials）/ Test（12 trials）
- Test sample IDs：34000..39999
- ring_xy：
shape=(720, 2)，HSV 上色环，用于 H1 单环教学 - ring_theta_rad：
shape=(720,)，环上真实相位（弧度） - torus_4d：
shape=(64, 4)，严格 8×8 网格产品 torus，σ=0.015；用于统计 null - torus_theta_rad / torus_phi_rad：
shape=(64,)，torus 真实相位 - 教学图（
nb00_data_preview.png）中的 3D torus display 使用独立生成的 1200 点 密集云（不进入 artifact），保持 R=3, r=1 标准参数化
| Notebook | 输出文件 | 描述 |
|---|---|---|
| NB-00 | nb00_foundations.npz |
Ring/torus 基础输入（5 个 canonical keys） |
| NB-02A | nb02a_single_neuron.npz |
单神经元 NHPP + STA/STC |
| NB-02A | nb02a_population.npz |
Canonical 群体数据 |
| NB-04A | nb04a_latent_dynamics.npz |
LDS/Kalman 状态 |
| NB-04B | nb04b_lfads.npz |
LFADS 生成模型输出 |
| NB-06 | nb06_tda.npz |
TDA persistence diagrams（27 keys） |
| NB-08A | nb08a_encoding.npz |
GLM 编码模型参数 |
| NB-08B | nb08b_decoding.npz |
Bayesian 解码结果 |
| NB-09 | nb09_stability_metrics.npz |
ToMATo / local-PH 稳定性指标 |
| NB-10 | nb10_null_distributions.npz |
Shuffle + Gaussian null（1999×2）+ 4 p-val |
| NB-10 | nb10_null_checkpoint.npz |
Null 计算 checkpoint |
| NB-10A | nb10a_cebra.npz |
PCA/UMAP/CEBRA 嵌入 |
| NB-12 | nb12_representation.npz |
RSA/CCA/CKA 比较 |
每个 .npz 都伴随一个 .manifest.json，记录 producer notebook、参数、
随机种子、依赖版本、执行时间、数组 schema 与输入 artifact 列表。
| Notebook | 内容 | 输出 PNG |
|---|---|---|
| NB-01 | 经典 ML（PCA / K-means / DBSCAN / UMAP） | nb01_pca/kmeans/dbscan/dr_comparison/dimension_curse/umap_noise.png |
| NB-02 | Gaussian smoothing / Hilbert / FFT / Grid rate maps | nb02_gaussian_smoothing/bandpass_filtering/hilbert_transform/grid_*.png |
| NB-03 | CANN 网络 + Fourier 稳定性 | nb03_weight_profiles/fourier_spectra/three_way_comparison.png |
| NB-04 | RNN 路径积分 + 持久同调（逐 hidden-unit 时间置乱） | nb04_hidden_states/persistence.png |
| NB-05 | 流形 + Rips complex + 同调教学 | nb05_betti_numbers/manifolds/simplicial_complex/torus_loops/homology_cohomology.png |
| NB-06 | TDA 基础（24 cells，9 inline） | nb06_ring_tda/torus_tda/barcode_3d/how_to_read_barcode/persistence_diagram/sampling_comparison/population_point_clouds/null_significance/population_persistence.png |
| NB-07 | Cocycle + circular coordinates（400 landmarks） | nb07_circle_coordinates/decoded_phase_torus/klein_bottle/pipeline.png |
| NB-08 | 统计推断 / permutation test / GLM | nb08_grid_score/circular_stats/permutation_test/glm.png |
| NB-09 | 拓扑聚类（ToMATo + local-PH） | nb09_kmeans_failure/local_ph_comparison/tomato/cell_types.png |
| NB-10 | Integration：hex vs square + nulls | nb10_full_pipeline/exp1_square_hex/exp2_phase_shuffle/exp3_random.png |
| NB-11 | Place cell arena（DoG + PC-GCRNN） | nb11_dog/trajectory/rate_maps*.png（100k-step 训练已运行；CE loss + recurrent L2） |
NB-13 在每个 artifact 上执行下列数值重算（无 SHA 比对）：
- Environment：关键科学库已安装
- ArtifactsAndProvenance：每个 artifact 存在、可读、schema 与 manifest 一致、DAG 边匹配
- CanonicalPopulationAndCausality：population schema 通过；单神经元
causal_drive重算一致 - KalmanRTSAndLFADS：Kalman 滤波 + RTS 平滑重算一致、协方差对称/PSD、smoother RMSE ≤ filter RMSE；LFADS finite、KL schedule ≥ 1、bits/spike > 0
- TDA：synthetic torus H1/H2 persistence 重算一致；population 点云 H1/H2 重算一致
- PoissonEncoding：模型/零假设偏差、解释率重算一致；预测严格为正
- HeldOutDecodingInformation：posterior (6000, 36) 形状/归一化；信息、p-value、bootstrap CI 重算一致
- Embeddings：4 个 test 嵌入 (6000, 3) 且 finite；4 张 PNG 文件存在且为有效 PNG
- Representation：RSA statistic / p-value 重算一致；CCA 奇异值 ∈ [0, 1]；orthogonal CKA > 0.95；noise CKA < 0.3
- RealArtifactRoundTrip：每个 artifact 重 zip 后逐数组字节一致
如果所有门通过，报告 status: "ACCEPTED"；否则 REJECTED，但 notebook 不会
抛出异常，方便读者逐门排查。
NB-00~NB-11 教学层笔记本经过逐 Cell 可视化与科学正确性审查，全部修复完成：
- NB-00：canonical 4D torus 保持 64 点（8×8 grid，σ=0.015），用于统计 null 严格保持；教学图 3D display 改用独立生成的 1200 点密集云（R=3, r=1）
- NB-01 / NB-05：恢复科学计算 imports；NB-05 C5 Klein bottle panel SyntaxError 已修复（F2: β=(1,2,1)、F47: β=(1,1,0)）
- NB-06：24 个 code cells，240 个 FPS landmarks + maxdim=2，恢复 9 张 Gardner 风格内联图；H1 两个、H2 一个领先 bar 清晰可见
- NB-07：400 个 FPS landmarks，F47 cocycle + GL(2,Z) 旋转， 两个 circular-coordinate alignment 分别为 0.997 和 0.999
- NB-09：ToMATo 参数与真实标签链路修复；固定样本 ARI=1.000， 子样本中位 ARI=0.926
- NB-10：1999 次 shuffle null + 1999 次 Gaussian null，四个 upper-tail p-values 全部为 0.0005
- NB-04：修复失效 null 代码，替换为科学含义明确的逐 hidden-unit 时间 置乱对照（明确为 sensitivity check，非 inferential test）
- NB-11：loss 已修正为 softmax cross-entropy + recurrent L2；training
schema 更新为
pcgcrnn_place_code_ce_v7；100k-step 训练已完成并写入 checkpoint；held-out median position error ≤ 0.10 m 与相对改善 ≥ 50% 已在 notebook 末尾断言
验证结果：
- 所有 notebook 的 code cells 通过 AST
- 无保存的 error output
- 关键 PNG 均非空
- NB-06 有 9 个 inline image outputs，NB-10 有 4 个
- NB-00 artifact 仍只有 5 个 canonical keys
- NB-06 canonical/null schema 保持完整（未新增条目）
- 已删除所有一次性迁移脚本，未恢复已删除的
artifact_contract.py/pipeline.py
Barcode 可视化（参考 Gardner Fig. 3 / Extended Data Fig. 3C）：
- H0/H1/H2 bars 按维度垂直分组排列
- 关键 H1 bars 用深色（#1f77b4 深蓝）突出
- 有限 bars 着色 viridis（亮度 ∝ persistence）
- Essential H0 用黑色箭头从 birth 向右延伸到边缘
- 标注 max persistence 数值
- 显示 null q95 threshold 的 dashed line
Persistence Diagram（参考 Gardner Extended Data Fig. 3D）：
- 黑色 dashed 对角线（birth = death）
- H1 紫 #9467bd，H2 橙 #ff7f0e
- Marker size ∝ persistence
- Essential H0 用黑色三角形标记
3D Embedding：
- 点大小 s=24-30，HSV 角度着色
- α=0.82-0.88，edge colors='none'
- box aspect=(1, 1, 0.45)，展示 torus 扁平特征