CellSys仿真数据输出与结果分析：从原始CSV到论文图的全流程指南

1. 在CellSys里，跑完一个case只是拿回了一堆原始产物

细胞群体动力学仿真这个方向，最容易给人造成错觉的就是那句“跑完了”。控制台刷到最后一行，屏幕上跳出一个最终细胞数量，很多人就觉得实验闭环了。但真正用CellSys做过完整课题的人都有体会：模型能不能回答生物学问题，靠的不是最后那个数字，而是运行过程中到底把哪些状态、哪些事件、哪些空间信息老老实实写到了磁盘上。数据输出配置合理，后面的结果分析就像有水有电的厨房，想做什么都顺手；配置不合理，模型演算得再精细，最终也只是浪费了几天机时。

所以我一直把数据输出看作是仿真实验里的“第一个交付物”。不是在收尾阶段补一个保存按钮，而是要在启动模拟之前就按研究问题设计清楚：我关心细胞总量的时间曲线，就不能只导出终态快照；我关心细胞迁移模式，就必须输出单细胞的连续轨迹；我关心空间结构对群体增长的影响，那微环境浓度场就得和细胞位置同步落盘。CellSys这类软件提供了多层级的输出通道，但它们之间的组合、频率和物理含义并不总是一目了然，需要你在动手前先对“要看什么”有明确判断。

这第10次分享，我准备把数据输出与结果分析里最容易被忽视又最影响产出的几个环节摊开来讲：先带你看清CellSys输出体系里各类文件的用途，再讲从原始输出到统计量怎么算才算对，然后给出一套可以直接搬走的Python分析流程，最后聊聊输出异常时怎么排查，以及如何把常用分析沉淀成一条命令行。内容偏工程实践，我尽量说人话，也会把踩过的坑直接标出来。

1.1 先分清三个层次：原始事件、可读数据、生物学结论

仿真内部真正发生的是离散事件。某一个细胞在模拟时间第2400分钟完成了分裂，另一个细胞在第6150分钟因为营养不足进入凋亡，还有个细胞在一段时间内持续沿着趋化梯度方向改变坐标。这些事件是仿真的“底片”，信息量最大但颗粒度也太细，直接拿来做统计非常痛苦。

CellSys的输出模块通常会在上层做一层累积和投影，形成可读数据。最典型的就是每隔固定模拟时间写一次的全局统计表：这个时刻总共有多少细胞、活细胞占多少、死亡事件累计了多少。更细一点的可读数据是单细胞级别表格，逐行列出每个细胞的坐标、半径、细胞周期状态、代数、父细胞ID等。再往上走，才是研究者真正关心的生物学结论：例如倍增时间是不是符合预期、不同处理条件下细胞迁移能力是否有显著差异、模拟产生的空间结构与体外实验照片是否一致。

我在指导搭档做分析时发现，很多人容易跳层。程序一结束就去截屏最终3D视图，然后试图从一张静态图上说明“增殖受到了抑制”。这是不靠谱的，因为一张图既没有过程信息，也没有重复样本之间的波动范围。正确路径是从原始事件日志里提取关键时间点，整理成可读的中间表格，再用统计或可视化手段把表格压缩成结论。你只有把三个层次分得足够清楚，才知道CellSys的哪些输出按钮该开、哪些可以关。

1.2 一套合格的输出配置至少要覆盖哪四类信息

可以把细胞群体动力学仿真里的“结果面”粗略拆成四个维度：群体现量、单细胞状态、事件流和微环境场。群体现量回答“有多少细胞在什么时间活着”，单细胞状态回答“这些细胞各自处在什么表型、什么空间位置”，事件流回答“分裂、死亡、迁移这些关键动作发生的时间和地点”，微环境场回答“氧气、营养物质、信号分子在细胞周围是怎么分布的”。

实际项目里不太可能每次都把四类全输出到最高时间分辨率，否则I/O压力会直接把模拟拖成龟速。我在早期的一个肿瘤球模拟里把所有通道按最小间隔全开，2000个细胞的case跑出了几十GB过程文件，后来磁盘满了导致最后几个时间片没写全，整个batch作废。那次之后我养成了习惯：正式批量模拟前先用单case做一次“磁盘开销测试”，估算每小时会产生多少数据，再根据实验目的决定输出频率。如果只是观察群体是否进入平台期，全局统计每50步一次就够了；但如果你要追踪某条谱系或者分析细胞轨迹，单细胞级输出频率就要加密到与迁移事件时间尺度匹配。

2. CellSys会输出哪些文件：先看清格式再谈结果分析

不同版本的CellSys在界面和文件命名上可能不完全一样，但输出逻辑基本遵循一套通用思路：配置备份、运行日志、全局统计、单细胞快照、轨迹文件和空间场文件各司其职。拿到一个全新仿真任务后，我建议你第一步不是打开图表界面，而是进到结果目录里，用tree或文件管理器把生成物浏览一遍。这一步能快速告诉你这个版本到底开放了哪些输出通道，以及在哪个配置文件里可以调整参数。

以我常用的一个case目录为例，输出结构通常长这样：

code复制result/
├── logs/
│   ├── run.log
│   └── events.log
├── time_series.csv
├── cell_positions/
│   ├── t0000_cells.csv
│   ├── t0500_cells.csv
│   └── ...
├── cell_tracks/
│   ├── cell_0001.csv
│   ├── cell_0002.csv
│   └── ...
└── fields/
    ├── t0000_oxygen.vti
    ├── t0500_oxygen.vti
    └── ...

这个结构最舒服的地方在于把“随时间变化的汇总数据”和“按细胞展开的明细数据”分离了。time_series.csv只有一张，适合先读进来做整体趋势判断；cell_positions和cell_tracks是一大堆小文件，适合后期做单细胞级挖掘；fields目录下的场文件则保留着空间连续性信息。我强烈建议你在第一次运行后就完整记录一份目录说明，标清楚每个文件来自哪个输出开关，免得三个月后回来根本想不起t开头文件里的坐标单位到底是像素还是微米。

2.1 全局统计表time_series.csv：大多数分析的起点

time_series.csv几乎是我打开每个输出目录后第一个看的文件，也是入门者最容易上手的部分。它的每一行代表一个输出时刻的全局状态快照。常见的字段大概包括下面这些：

读这张表时，最先确认的就是time这一列的单位和步长。有的模型把时间定义成迭代步，一步相当于模拟时间0.5分钟；有的模型直接按分钟推进，输出间隔又是按步数来算。如果没搞清楚换算关系，后续把多条模拟曲线画在同一张图里时，横轴就会牛头不对马嘴。我自己的习惯是在输出配置里让time列始终保存“模拟时间”，而不是步数，这样不同随机种子下的多个模拟可以直接对齐比较。

2.2 单细胞快照和事件日志：挖掘个体差异的富矿

全局统计表只能回答“整体怎么样”，回答不了“哪些细胞贡献了这个整体变化”。这时候就要去翻cell_positions目录。它按输出时刻保存全细胞列表，每个文件内部一行一个细胞。关键字段通常包括：cell_id、parent_id、x、y、z、radius、cell_type、cell_cycle_state、generation、age和neighbor_count。

cell_id和parent_id是重建谱系树的钥匙。如果你要研究一个突变克隆是否能占领整个群体，就得根据这两个ID把后代关系串起来。radius和坐标配合可以判断细胞是否准备分裂，因为很多模型会规定细胞体积达到一定阈值才触发分裂。neighbor_count可能看着不起眼，却是分析局部拥挤的关键：当细胞密度上升导致邻居数量超过某个阈值时，增殖往往会被抑制，你需要在全局总量还没变化时就察觉到这个信号。

events.log则是异步追加的事件流，和固定时间间隔的快照不同。它记录的是分裂、死亡、迁移、接触等具体动作发生的瞬间，包含time、cell_id、event_type、事件发生坐标和可能附带的属性描述。做因果分析时，事件日志比固定快照可靠得多，因为它不会因为采样间隔太粗而漏掉两个时间点之间发生的短命事件。

2.3 场文件与边界信息：别让空间数据变成摆设

细胞群体动力学模型的真实感很大程度上来自空间环境。细胞不是悬浮在均匀培养液里，而是被细胞外基质包裹，氧气和营养物浓度在空间上存在梯度。这些梯度通常以场文件形式输出，常见格式包括VTK、VTI和普通文本矩阵。场文件可以直接交给ParaView做等值面或裁切视图，也可以在Python里读出每个空间点的标量值，与细胞位置叠在一起做相关分析。

刚开始我用CellSys模拟时很少去看场文件，直到有一次总细胞数出现了诡异的不对称增长，我才导出了氧气浓度场，发现模拟区域一角存在严重的营养耗竭，细胞在那个角落全部死亡。这个现象靠全局统计表完全看不出来。从那以后，只要模型涉及扩散和消耗型底物，我就一定会输出至少两个时间点的浓度场，一个用于确认初始条件，一个用于检查稳态。

边界信息也一样。细胞群体所在的模拟区域到底是开放边界还是封闭边界，对结果解释影响巨大。封闭边界会人为造成边缘细胞堆积，开放边界则允许细胞迁出统计区域。这两种边界模式下得到的“细胞总数”含义并不等价，所以最好在输出目录里保存一份边界配置快照，或者在日志文件头部记录边界类型，避免分析阶段搞混。

3. 从原始CSV算统计量时，最容易栽在时间对齐和burn-in上

拿到一堆CSV之后，最忌讳的就是打开Excel随手画一条趋势线。仿真数据和实验数据一样，存在“系统预热期”和“随机波动”。尤其是在细胞群体动力学里，初始阶段可能塞进了人为设定的初始细胞团，细胞之间还没建立起真实的邻居关系，整体增殖率会经历一段肉眼可见的扰动。这一段时间里的数据不应该是分析重点，直接纳入统计会显著拉高或拉低早期指标。

处理burn-in没有统一标准，但有一个好办法：先同时画出total_cells和total_deaths随模拟时间的变化，观察群体是否在某个时间点后进入相对稳定的增长模式，再选择该时间点作为正式统计起点。如果模型本身有稳态阶段，那就应该从细胞总数不再剧烈波动的时刻开始分析。如果模拟是从单个细胞或少量细胞启动的，那前几十个小时的数据反而可能是你研究的对象，此时不必剔除，但要明确区分“启动阶段”和“稳定阶段”。

3.1 时间对齐：多个replicate的曲线不能直接横向拼接

很多研究需要使用多个随机种子跑重复，以评估模型随机性造成的结果波动。这时你会遇到一个实际麻烦：不同重复实验虽然设置了相同的输出间隔，但因为动态步长、事件触发等机制，time列未必完全一致。A模拟在时间240、300输出两个点，B模拟可能因为步长调整在245、305才输出。直接把两个DataFrame按行相加求平均是错的，必须先以统一的时间网格为基准做插值。

具体操作可以用pandas里的reindex和interp。先定义一个公共时间轴，比如从0到模拟结束的每一个整数时间点，再让每个重复实验都插值到公共时间轴上，最后对插值后的多列求均值和标准误。这一步我在早期做漏了，当时画出来的平均生长曲线在几个时间点出现奇怪的阶梯状毛刺，排查半天才发现是不同replicate的时间点错位造成的。

3.2 群体增长指标：细胞倍增时间和增长率不是靠肉眼读的

全局统计表里最常被提取的指标是倍增时间。很多新手会找两个时间点，用细胞数减半或翻倍的时间间隔来估算，这种做法很容易受早期波动和晚期平台期干扰。更稳妥的办法是在半对数坐标下找到指数增长区间，对该区间做线性回归，用斜率μ按下式计算倍增时间：T_d = ln2 / μ。

实际操作时还要注意，细胞群体动力学仿真中的“活细胞数”并不一定严格指数增长。如果模型包含资源限制或细胞接触抑制，曲线会发生弯曲，这时候强行套一个指数拟合可能只在一个很窄的时间窗口内有效。我的习惯是先画ln(live_cells) vs time，看一下哪一段肉眼近似直线，再在该区间内用回归而不是两点法。这样即使个别随机种子出现早期波动，结果也不会偏移太多。

3.3 运动与迁移特征：MSD是比“平均位移”更可靠的统计量

如果你研究的是细胞迁移，CellSys的单细胞轨迹文件是核心输入。评价迁移能力最常用的指标不是“平均位移”，而是均方位移（MSD）。以二维迁移为例，某个细胞的时间间隔τ对应的MSD可以这样算：对该细胞所有间隔为τ的位置对，计算位移平方的平均值。如果运动近似随机扩散，MSD与τ会呈线性关系，比例系数对应4倍扩散系数D。如果存在定向运动，MSD曲线会向上弯曲；如果细胞受限于局部范围，MSD会逐渐到达平台。

统计时特别需要注意帧率是否匹配迁移尺度。如果输出间隔太长，细胞已经发生了多次转向和碰撞，MSD在小时间尺度上的信息会丢失。如果输出间隔太短，位置噪声会被放大，导致短时MSD出现虚假的超扩散。我一般会同时计算lag=1帧、5帧和20帧的MSD，观察曲线斜率是否稳定，再选择合适的滞后范围做拟合。

3.4 空间模式指标：判断“聚集”不能只凭视觉

细胞群体空间分布是不是聚集，用眼睛看3D散点图很容易误判。更严谨的做法是用Ripley's K函数或配对相关函数g(r)来分析。简单来说，这类方法比较“实际观测到的邻居数量”与“在相同密度下完全随机分布时的期望邻居数量”之间的差值。K(r)高于随机期望，说明细胞在尺度r上存在聚集；低于随机值则说明存在排斥。

空间指标的计算结果对边界非常敏感，尤其在模拟区域边缘，细胞没有区域外的邻居，会低估局部密度。所以分析前需要做边缘校正，或者只分析距边界一定距离内的细胞。如果你的模型本身就是一个球体或类球体，直接使用平面Ripley's K并不合适，需要换成球面或三维版本的统计量。

4. 一套可以直接用的Python分析流程：从time_series到论文图

数据分析用Python是再自然不过的选择。Pandas做表格清洗，Matplotlib或者Seaborn做图，遇到大规模CSV再用PyArrow或Dask优化。下面这套流程我几乎在每个CellSys项目里都会复用，你可以把它当成起点，按字段差异调整。

4.1 先读全局统计表并快速判断run是否正常

拿到结果目录后的第一步，我通常运行一个小脚本打印time_series的关键列和基本统计。这样能快速发现文件是否存在、时间点数量是否合理、有没有明显异常值。

python复制import pandas as pd
import os

result_path = "result/time_series.csv"
if not os.path.exists(result_path):
    raise FileNotFoundError("没有找到time_series.csv，请检查输出配置")

df = pd.read_csv(result_path)
print(df.head())
print(df.describe())

如果文件存在但行数明显少于预期，说明输出频率或模拟时长有问题。此时先不要做任何高级分析，回到模拟日志里确认程序有没有正常跑完。很多仿真软件在磁盘空间不足或内存溢出时，会默默结束最后一段时间片，导致输出的时间序列覆盖不到终点。数据缺失这个问题，越早发现越好。

4.2 批量绘制多个随机种子的生长曲线

下面的代码可以读取同一目录下多个模拟子目录，把它们的live_cells曲线插值到统一时间轴后，画出均值曲线和置信区间带。这在正式实验中非常实用。

python复制import glob
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

sim_dirs = sorted(glob.glob("sim_*"))
all_curves = []

for d in sim_dirs:
    f = os.path.join(d, "time_series.csv")
    tmp = pd.read_csv(f).set_index("time")["live_cells"]
    all_curves.append(tmp)

# 统一时间轴
common_time = np.arange(0, 2000, 10)
interpolated = []
for idx, s in enumerate(all_curves):
    s_interp = s.reindex(s.index.union(common_time)).interpolate()
    s_interp = s_interp.reindex(common_time)
    interpolated.append(s_interp)

mat = pd.concat(interpolated, axis=1)
mean_curve = mat.mean(axis=1)
upper = mean_curve + 1.96 * mat.std(axis=1) / np.sqrt(mat.shape[1])
lower = mean_curve - 1.96 * mat.std(axis=1) / np.sqrt(mat.shape[1])

plt.figure(figsize=(6, 4))
plt.plot(common_time, mean_curve, label="mean")
plt.fill_between(common_time, lower, upper, alpha=0.3, label="95% CI")
plt.xlabel("Simulated time")
plt.ylabel("Live cells")
plt.legend()
plt.tight_layout()
plt.savefig("growth_curve.pdf", dpi=300)

这份代码里最关键的步骤是reindex + interpolate。它把不同模拟在时间轴上的微小错位抹平了。先做插值再算均值，不会把某个时间点的误差传导给其他时间点，得到的置信区间也更能反映随机种子之间的真实差异。

4.3 单细胞轨迹和MSD计算

如果你只有少部分细胞被追踪，处理起来很轻量。假设某个细胞轨迹文件包含frame、x、y、z四列，可以这样算不同滞后时间下的MSD：

python复制import numpy as np
import pandas as pd

track = pd.read_csv("result/cell_tracks/cell_0001.csv")
track = track.sort_values("frame")
pos = track[["x", "y", "z"]].to_numpy()

max_lag = min(50, len(pos) // 2)
lags = np.arange(1, max_lag + 1, dtype=int)
msd = []

for lag in lags:
    disp = pos[lag:] - pos[:-lag]
    msd.append(np.mean(np.sum(disp ** 2, axis=1)))

msd = np.array(msd)

要注意pos[lag:]和pos[:-lag]的长度一致，所以逐对相减得到的是所有时间窗的位移向量。对于高频率输出的轨迹，可能还需要先做一步平滑去除细胞中心坐标的抖动，否则短滞后MSD会被噪声污染。平滑时我会用滑动中位数而不是均值，因为中位数对离群点更鲁棒。

4.4 空间快照的可视化：二维散点图与场叠加热力图

如果关注空间分布，可以用散点图直接观察细胞位置，并用颜色区分细胞类型或状态。下面这样处理就足够生成一张可供讨论的二维投影图：

python复制snap = pd.read_csv("result/cell_positions/t0500_cells.csv")
plt.figure(figsize=(6, 6))
sc = plt.scatter(snap["x"], snap["y"],
                 c=snap["cell_type"], cmap="tab10", s=5)
plt.colorbar(sc, label="cell type")
plt.gca().set_aspect("equal")
plt.savefig("spatial_snapshot_t0500.png", dpi=300)

如果要把细胞位置和营养梯度叠在一起，最好用ParaView或pyvista打开VTK/VTI场文件。单纯用Matplotlib做三维体绘制效率不高，实际分析中我也很少直接需要整场细节，通常只提取细胞所在位置的局部浓度值做回归图。

5. 输出数据不对劲时，我按什么顺序做现场排查

数据分析和实验一样，大概率会撞上“结果看起来不太对”的时刻。不要慌，也别立刻改模型参数。先把输出数据本身检查一遍，因为很多时候问题出在输出配置，而不是生物模型逻辑。

5.1 现象、可能原因和行动方向对照表

我整理了一个最常用的排查表，每次数据反常先对表操作：

这张表不是金科玉律，但它能缩短从“看到异常”到“找到原因”的定位路径。很多时候我们过度相信输出文件一定精确描述仿真过程，其实数据链路里任何一环——坐标单位换算、字段计算、采样时刻——都可能出错。

5.2 一次实际排查链路：time列间隔不均让你误判振荡

我模拟某个环境受限的细胞群体时，time_series里活细胞数量出现了明显的锯齿状波动，初看像周期振荡。但我翻了events.log后发现分裂事件在时间轴上分布很均匀，并没有对应的周期性停顿。问题出在哪里？后来我把time列相邻差值打出来，发现它并不是固定值，而是随着细胞数量增加不断变长，因为程序是按固定迭代步数输出，而每个迭代步代表的模拟时间随着局部计算复杂度发生了动态变化。也就是说，输出的“行间隔”在整个运行过程中并不等于相等的时间间隔。

找到根源之后，我在输出配置里把触发方式改成了按模拟时间输出，而不是按迭代步数输出。锯齿状波动立刻消失了，曲线恢复了平滑的增长-平台形态。这让我养成了一个习惯：拿到任何时间序列数据，第一步先画一下time列相邻差值，确认采样时间是否均匀。这一步几秒钟就能完成，却能避免后续所有基于“等间隔假设”的统计分析全部失效。

5.3 文件明明存在，但数据内容偏少时的处理思路

还有一种常见情况：文件数量不少，但每个文件里的行数比预期少很多。比如在一个预期有5000个细胞的时刻，输出的单细胞快照只有3000行。直觉反应是模型丢细胞了，但更常见的原因是输出模块默认只保存了“状态活跃”的细胞，处于凋亡清除流程中的细胞或免疫细胞可能被过滤掉。遇到这种情况，不要急着怀疑模型bug，先去查软件文档或配置文件里的过滤逻辑。

如果确实需要保存所有细胞，包括正在死亡或已经失去增殖能力的个体，就需要在输出配置中把过滤选项关掉，或者在事件日志里单独记录这些细胞的状态。否则你最关心的凋亡细胞群可能从头到尾都不会出现在单细胞快照里，导致对所有死亡相关指标的分析失真。

6. 让常跑的指标分析变成一条命令行：把一次性脚本沉淀下来

项目进行到中后期，你会发现同一个分析脚本会被反复执行几十遍，尤其是模仿不同处理条件或随机种子时。如果每次都要打开Jupyter Notebook逐格跑，不仅浪费时间，还容易因为手动改路径产生错误。这时候值得花一点时间把刚刚写的分析流程封装成命令行工具。

我通常用一个Python文件analyze_cellsys.py来完成这件事，核心参数包括输入目录-i、输出目录-o、是否需要绘制轨迹图--tracks、是否读入场文件--fields等。整体框架大致是：

python复制import argparse

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("-i", "--input", required=True,
                        help="CellSys result directory")
    parser.add_argument("-o", "--output", required=True,
                        help="analysis output directory")
    parser.add_argument("--tracks", action="store_true",
                        help="analyze single-cell tracks")
    args = parser.parse_args()

    os.makedirs(args.output, exist_ok=True)
    # 1. load time series
    # 2. generate summary.csv
    # 3. plot growth curve
    # 4. trajectory analysis if enabled

if __name__ == "__main__":
    main()

入口函数并不复杂，但把分析逻辑统一收口之后，重复性工作就变成了一条命令：

bash复制python analyze_cellsys.py -i result/conditionA -o report_A
python analyze_cellsys.py -i result/conditionB -o report_B

批量处理多组模拟时，还可以在shell里写一个循环：

bash复制for d in sim_*/; do
  name=${d%/}
  python analyze_cellsys.py -i "$d" -o "report_${name}"
done

如果多个case的分析结果需要横向比较，建议每个case的分析脚本都额外输出一个summary.csv，里面固定写好case名、最终活细胞数、指数期增长率、倍增时间等关键指标。这样你不需要重新打开几十张PDF图，只要把每个summary.csv拼接起来，就能给出一张各条件对比总表，后续画柱状图或做显著性检验都方便很多。

把分析脚本沉淀为命令行之后，还有一个小技巧：在输出目录里同步生成一份analysis_config.json，记录本次分析用的文件路径、输出频率、随机种子对应的参数。这个文件相当于分析过程的“实验记录”，以后任何人拿到你的结果目录，都能知道这些图表是从哪个原始输出算出来的。我一个人做项目时觉得这个步骤可有可无，直到有一次需要把两周前的结果重新出图，才发现没有配置文件的情况下，连坐标单位都要靠猜。从那以后，我和团队约定每次分析都必须附带配置记录，这也是数据输出与结果分析里最后但同样重要的一环。