教程2：1D CANN：ROI Bump 拟合教程¶

目标：基于 1D CANN bump 拟合模块，从 ROI 时间序列中提取 bump 中心位置、宽度与幅度，并生成轨迹可视化。

背景：果蝇 Central Complex 的 EPG 环形编码（Kim et al., Science 2017 [35]）。

.. note:: 如需深入了解 ROI bump 拟合的实验背景，可参阅 :cite:p:`Kim2017RingAttractor`。

0. 背景与方法简介¶

本教程聚焦 单环连续吸引子网络（1D CANN） 上的神经群体活动，核心目标是从 ROI 时间序列中追踪 bump 的：

位置（center）
高度（amplitude）
宽度（width）

这些随时间变化的参数反映 bump 在环形网络中的动态演化。

0.1 数据来源与结构¶

本案例参考果蝇 Central Complex 的 EPG 环形编码数据：

数据类型：钙成像 ROI 荧光强度（16 ROI）
文献来源：Kim et al., Science, 2017
直觉解释：每个 ROI 对应环上的一个位置，bump 在环上移动

本教程使用 load_roi_data 的示例数据；你也可以替换为自己的 ROI 矩阵。

0.2 分析流程概览¶

载入 ROI 数据（T × N）
通过 MCMC 拟合 bump 参数
得到每一帧的 center / amplitude / width
可视化 bump 随时间的轨迹（静态或动画）

0.3 输出结构与解释¶

roi_bump_fits 返回四个核心对象：

bumps：每帧拟合的 bump 对象
fits：(time, pos, amplitude, kappa) 序列
nbump：每帧 bump 数量与重建信号
centrbump：中心化 bump 曲线（用于可视化）

如何解读：

pos：bump 在环上的中心位置（相位）
amplitude：bump 峰值强度
kappa：bump 宽度（越大越窄）

1. 数据准备¶

本示例使用 load_roi_data 载入 16 ROI 的示例数据。你可以替换为自己的 ROI 时间序列矩阵（形状 (T, N)）。

[1]:

from canns.data.loaders import load_roi_data

roi_data = load_roi_data()
print(roi_data.shape)

Loaded ROI data: shape (4957, 16)
(4957, 16)

1.1 预处理建议¶

建议先对 ROI 信号做 平滑/归一化 （可提升拟合稳定性）
若存在 NaN/缺失值，先做插值或剔除
ROI 数量需与 n_roi 一致

2. Bump 拟合¶

使用 roi_bump_fits 进行 MCMC 拟合，输出：

fits：每帧的 bump 参数
nbump：每帧 bump 数量
centrbump：中心化 bump 曲线

[2]:

import numpy as np
from canns.analyzer import data

cfg = data.BumpFitsConfig(
    n_steps=5000,
    n_roi=16,
    random_seed=42,
)

bumps, fits, nbump, centrbump = data.roi_bump_fits(roi_data, config=cfg)

print(f"frames: {len(fits)}")
print(f"avg bumps per frame: {np.mean(nbump):.2f}")

Initial likelihood: -66502.15
Using Numba acceleration (n_roi=16, parallel=No)

MCMC fitting: 100%|██████████| 5000/5000 [01:37<00:00, 51.11it/s, Log-Likelihood=-14214.64]

frames: 3161
avg bumps per frame: 137.84

3. 生成动画¶

使用 create_1d_bump_animation 生成 bump 轨迹动画。

[6]:

anim_cfg = data.CANN1DPlotConfig.for_bump_animation(
    show=True,
    # save_path="bump_analysis_demo.mp4",
    nframes=60,
    fps=30,
    title="1D CANN Bump Analysis",
)

data.create_1d_bump_animation(
    fits_data=fits,
    config=anim_cfg,
)

参数建议¶

n_steps：MCMC 迭代次数（越大越稳定，但更慢）
n_roi：ROI 数量（默认 16）
n_bump_max：每帧最大 bump 数
sigma_diff / ampli_min / kappa_mean：控制 bump 形状

性能提示：

若安装 numba，拟合会显著加速
数据较长时，可先用较小 n_steps 快速确认趋势，再逐步增大

可视化示例¶

../../../_images/bump_analysis_demo.gif — *1D bump 轨迹示意（动画）*¶