分析模块¶
btorch.analysis 模块提供了用于神经数据分析的计算工具。
核心模块¶
spiking.py¶
支持 NumPy/PyTorch 双后端的脉冲序列分析工具。
| 函数 | 描述 |
|---|---|
isi_cv |
每个神经元的 ISI 变异系数 |
fano |
Fano 因子(脉冲计数的方差/均值) |
kurtosis |
脉冲计数分布的峰度 |
local_variation |
局部变异度 (LV) - 与速率无关的不规则性 |
isi_cv_population |
全体神经元合并 ISI 的变异系数(默认返回标量) |
compute_raster |
提取用于绘图的脉冲时间/神经元索引 |
firing_rate |
将脉冲卷积为发放率 |
compute_spectrum |
通过 Welch 方法计算功率谱 |
常用参数:
batch_axis:int | tuple[int, ...] | None(别名BatchAxis),用于聚合的轴(例如,用于 trial 的(1, 2))percentiles: 计算神经元的百分位数 -float、tuple[float, ...]或None
命名规则: 不带前缀的名称(isi_cv、fano、kurtosis、local_variation 等)是逐神经元或群体统计量,返回 (value, info);compute_* 是多步流水线(如平滑后再估计),返回各自的结果类型。例如 compute_lyapunov_exponent_from_spikes(脉冲序列 -> 发放率 -> 指数)与 compute_max_lyapunov_exponent(现成的一维序列)。get_* 仅用于轻量的查找/访问器(如 get_cell_types_cache),不用于计算;simulate_* 生成数据;suggest_* 返回启发式选择。
isi_cv_population(spikes) 返回合并 ISI 的标量变异系数(脉冲少于两个时为 NaN);stat=None 时返回合并后的 ISI 本身(脉冲少于两个时为空数组)。
示例:
from btorch.analysis import fano, fano_sweep, isi_cv, local_variation
# NumPy input with batch aggregation across trials
cv, info = isi_cv(
spikes, # shape: [T, B, N]
dt=1.0,
batch_axis=(1,), # aggregate across batch dimension
percentiles=(10, 50, 90), # percentile levels in [0, 100]
)
# cv shape: [N] - per-neuron CV values
# info["cv_levels"], info["cv_percentiles"]: requested levels and their values
# Torch GPU input: returns GPU tensor, uses hybrid CPU/GPU for efficiency
import torch
cv_gpu, _ = isi_cv(torch.from_numpy(spikes).cuda(), dt=1.0, batch_axis=(1,))
# Fano factor with overlapping counting windows, aggregated to one number
ff, info = fano(spikes, window=100, overlap=50, stat="mean")
# Sweep over counting-window sizes 1..50
ff_sweep, info = fano_sweep(spikes, window=50)
# Local Variation (LV) - less sensitive to rate changes than CV
lv, info = local_variation(spikes, dt=1.0, percentiles=(25, 75))
¶
from btorch.analysis import fano, fano_sweep, isi_cv, local_variation
# NumPy input with batch aggregation across trials
cv, info = isi_cv(
spikes, # shape: [T, B, N]
dt=1.0,
batch_axis=(1,), # aggregate across batch dimension
percentiles=(10, 50, 90), # percentile levels in [0, 100]
)
# cv shape: [N] - per-neuron CV values
# info["cv_levels"], info["cv_percentiles"]: requested levels and their values
# Torch GPU input: returns GPU tensor, uses hybrid CPU/GPU for efficiency
import torch
cv_gpu, _ = isi_cv(torch.from_numpy(spikes).cuda(), dt=1.0, batch_axis=(1,))
# Fano factor with overlapping counting windows, aggregated to one number
ff, info = fano(spikes, window=100, overlap=50, stat="mean")
# Sweep over counting-window sizes 1..50
ff_sweep, info = fano_sweep(spikes, window=50)
# Local Variation (LV) - less sensitive to rate changes than CV
lv, info = local_variation(spikes, dt=1.0, percentiles=(25, 75))
statistics.py¶
通用统计工具。
| 函数 | 描述 |
|---|---|
describe_array |
打印描述性统计信息 |
compute_log_hist |
对数间隔直方图 |
get_corr_stats |
脉冲序列的互相关统计 |
connectivity.py¶
网络连接分析。
| 函数 | 描述 |
|---|---|
compute_ie_ratio |
抑制性/兴奋性输入比例 |
HopDistanceModel |
基于 BFS 的跳数距离计算 |
HopDistanceModel 方法:
compute_distances(seeds)→ 包含跳数距离的 DataFramehop_statistics(seeds)→ 按跳数分类的可达性统计reconstruct_path(src, tgt)→ 最短路径
branching.py¶
源自 Wilting & Priesemann (2018) 的 MR 估计。
| 函数 | 描述 |
|---|---|
simulate_branching |
模拟分支过程 |
simulate_binomial_subsampling |
对脉冲序列进行二次采样 |
compute_branching_ratio |
从脉冲计数中估计分支比(MR 估计器) |
compute_lagged_slopes |
滞后回归斜率 r_k(返回 LaggedSlopes 命名元组) |
aggregation.py¶
分组数据聚合。
| 函数 | 描述 |
|---|---|
agg_by_neuron |
按神经元类型聚合 |
agg_by_neuropil |
按神经毡区域聚合 |
agg_conn |
聚合连接权重 |
build_group_frame |
将 [N] 或 [..., N] 转换为长格式的分组值 |
group_values |
按确定的分组顺序返回分组值数组 |
group_summary |
计算每组的描述性统计信息 |
group_ecdf |
计算用于分析/绘图的每组 ECDF 点 |
voltage.py¶
电压轨迹分析。
| 函数 | 描述 |
|---|---|
suggest_skip_timestep |
建议预热期 |
compute_voltage_overshoot |
量化电压稳定性 |
metrics.py¶
选择与掩码工具。
| 函数 | 描述 |
|---|---|
indices_to_mask |
将索引转换为布尔掩码 |
select_on_metric |
按指标选择神经元 (topk, any) |
拟合(btorch.fitting)¶
模型驱动的拟合与调参位于 btorch.fitting,与 btorch.analysis 中的事后统计分离。
tuning.py¶
| 函数 | 描述 |
|---|---|
compute_fi_vi_curve |
对神经元类进行恒定电流扫描,返回 f-I / V-I 曲线 |
two_compartment/(包)¶
双室模型拟合。损失权重等选项由冻结数据类 FitLossConfig 给出,作为 loss= 传给 two_compartment_loss、evaluate_two_compartment_fit、evaluate_fit_across_sweeps 和 fit_two_compartment_model(None 使用默认值)。
fit_two_compartment_model 的方法专属选项分组为冻结数据类,每个后端只接收自己的那一个:TbpttConfig(lr、epochs、chunk_size)用于 "tbptt"/"hybrid",GlobalSearchConfig(param_bounds、maxiter、popsize、local_maxiter、seed、polish)用于 "global"/"hybrid"/"staged",StagedConfig(stages)用于 "staged"。传入所选 method 不使用的配置会抛出 ValueError。模型必须满足 TwoCompartmentModel 协议(TwoCompartmentGLIF 满足)。
from btorch.fitting.two_compartment import (
FitLossConfig,
GlobalSearchConfig,
TbpttConfig,
evaluate_fit_across_sweeps,
fit_two_compartment_model,
)
loss = FitLossConfig(spike_count_weight=5.0, spike_match_window_ms=5.0)
history = fit_two_compartment_model(
model,
sweeps,
method="hybrid",
loss=loss,
search=GlobalSearchConfig(maxiter=20, seed=0),
tbptt=TbpttConfig(epochs=5, chunk_size=500),
)
evaluations, aggregate = evaluate_fit_across_sweeps(model, sweeps, loss=loss)
dynamic_tools/ 子包¶
高级动力系统分析工具。
| 模块 | 描述 |
|---|---|
micro_scale.py |
发放率分布、SPIKE 距离(ISI CV 见 analysis.spiking.isi_cv) |
fano.py |
速率补偿的 Fano 因子(操作时间、均值匹配、模型法) |
complexity.py |
PCIst、表征对齐、增益稳定性、compute_lyapunov_exponent_from_spikes |
criticality.py |
雪崩分析、幂律拟合、DFA |
attractor_dynamics.py |
相空间重构、Kaplan-Yorke 维数 |
lyapunov_dynamics.py |
Lyapunov 指数估计 |
ei_balance.py |
E/I 平衡指标(ECI、滞后相关性) |
E/I 平衡分析 (ei_balance.py)¶
from btorch.analysis.dynamic_tools.ei_balance import (
compute_eci,
compute_lag_correlation,
compute_ei_balance_full
)
# 计算 E/I 抵消指数
eci, info = compute_eci(
I_e, # 兴奋性电流 [T, B, N]
I_i, # 抑制性电流 [T, B, N]
I_ext=None, # 外部电流(可选)
batch_axis=(1,), # 跨 trial 聚合
percentile=0.9 # 计算神经元的百分位数
)
# 计算兴奋性和抑制性电流之间的滞后相关性
peak_corr, corr_info = compute_lag_correlation(
I_e,
-I_i, # 抑制性取负值
dt=1.0,
max_lag_ms=30.0, # 最大滞后(毫秒)
use_fft=True # 基于 FFT 以提高效率
)
# 全面的 E/I 平衡分析
metrics, info = compute_ei_balance_full(
I_e, I_i,
I_ext=None,
dt=1.0,
max_lag_ms=30.0,
batch_axis=(1,)
)
# metrics: eci_mean, eci_median, track_corr_peak_mean, delay_ms_mean, 等。
使用示例¶
from btorch.analysis.spiking import firing_rate, fano
from btorch.analysis.branching import compute_branching_ratio
# 计算发放率
fr = firing_rate(spikes, width=10, dt=0.1)
# 跨窗口的 Fano 因子
ff, info = fano(spikes, window=100)
# 分支比估计
result = compute_branching_ratio(spike_counts)
print(f"Branching ratio: {result['branching_ratio']:.3f}")
后端支持¶
所有脉冲分析函数均支持 NumPy 和 PyTorch:
- NumPy: 标准的基于 CPU 的计算
- PyTorch: 在有益的情况下使用 GPU 加速
- 基于 ISI 的指标 (CV, LV):混合方法(GPU 聚合 → CPU 提取 → GPU 返回)
- 基于计数的指标 (Fano, Kurtosis):通过累积和实现全 GPU 计算
Float16 支持:
- 函数接受 float16 输入
- 内部累加使用 float32 以保证数值精度
- 返回值与输入设备位置保持一致