13c-metabolic-flux

碳-13 代谢通量推断

将经过审核的碳图、明确的示踪剂混合物和校正后的标记测量数据， 转化为可行的通量估计，以及关于实验约束了哪些通量的证据。 使用捆绑的求解器，而不是重建同位素平衡或独立拟合每个 反应。它运行 mfapy 的 EMU 正向模拟器，并用 SciPy 在 质量平衡的可行空间中拟合通量。它不使用 FBA 目标函数。

范围与所需证据

此实现支持代谢和同位素稳态、一个或多个示踪剂实验共享的单一 通量状态、非负单向反应通量， 以及碳子集质量分布。可逆反应是分别映射的两个 方向。测量误差为高斯分布，带有提供的协方差或已披露的 对角近似。

在拟合之前，获取：

• 碳网络以及每个原子归属的来源。仅凭化学计量 无法指明标记原子去向。将区室记录为独立的代谢物 ID。
• 两个稳态假设的证据。代谢物丰度稳定并不能 确立同位素稳态。时间过程标记需要带池大小和初始标记的 INST-MFA； 不要将其平均到此求解器中。
• 每个碳输入的位置异构体分布，包括未标记 补充物、同化时的碳酸氢盐/CO2，以及示踪剂杂质。
• 碎片碳归属、自然丰度校正历史，以及报告均值的 不确定度。原始峰强度、衍生化谱图和 MS/MS 跃迁需要经过验证的预处理，然后才能构建这些输入。
• 通量单位、细胞外速率测量或所声明的相对通量参考， 以及生物学上合理的边界。仅凭标记分数无法设定绝对速率。

如果缺少必要信息，请指明并准备输入模板；不要 编造碎片归属、原子映射、同位素校正或测量误差。 在准备输入时阅读 references/input-contract.md。 在解释实际拟合之前阅读 references/inference.md。

安装经过测试的引擎

在用户的分析目录中运行。将 SKILL_DIR 设置为此技能安装目录， 使用实际解析的路径。将环境和生成的结果保留在此技能之外。

uv venv --python 3.12 .venv-mfa
uv pip install --python .venv-mfa/bin/python -r "$SKILL_DIR/assets/requirements.txt"

以下命令使用 .venv-mfa/bin/python；在 Windows 上使用环境的 Scripts/python.exe。mfapy 从不可变的 Git 修订版安装，因为它 未在 PyPI 上分发。安装会执行依赖构建代码；模型输入 是数据，不是用户提供的 Python。适配器在标识符和原子映射 语法到达 mfapy 内部生成的数值函数之前对其进行限制。

固定的提交在 2026-09-30 与上游 master 匹配。其 README 将 最新更改标记为 "064"，但其已安装的发行版仍报告 0.6.3；在分析记录中 将 Git 提交与包版本一起保留。更新后的 NumPy/SciPy 固定版本要求 Python 3.12 或更高版本；上述命令使用经过测试的 3.12 环境。请参阅 references/inference.md 中经过审核的正向模型 契约。

工作流

1. 准备明确的输入。 将相关的模型资产复制到分析目录中， 然后仅根据经过审查的证据替换其科学内容。随附的模型 是演示，并非经过验证的特定生物体重建。为每个生物学条件 使用单独的数据集；只有当示踪剂重复样本的生物学通量状态 可被合理认为共享时，才对它们进行联合拟合。

2. 检查契约和可行性。

   .venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" check \
     --model model.json --data measurements.json --output input-check.json
   

   这会检查原子数量和守恒、片段、示踪剂总和、不确定性 矩阵、边界以及稳态质量平衡可行性。它无法验证一个 化学上一致的原子映射在生物学上是否正确，或样本是否达到稳态。

3. 演练正向模型。 提供声明单位下的一个质量平衡通量向量。 将预测的标记与参考值或独立推导的限值进行比较。

   .venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" simulate \
     --model model.json --data measurements.json --fluxes fluxes.json \
     --output simulated-mdvs.json
   

4. 拟合并剖析与问题相关的通量。

   .venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" fit \
     --model model.json --data measurements.json --starts 12 --seed 2026 \
     --profile v3 --profile v7 --profile-points 31 --profile-starts 6 \
     --output fit.json
   

   将 v3 和 v7 替换为实际的反应 ID。每个剖析点固定该反应， 并重新优化冗余通量。对于非线性网络，在解释剖析之前， 用不同的种子和更多起始点重复进行。较小的残差并不是 可识别性结果。

5. 检查证据。 检查失败的起始点、残差模式、质量平衡、 活跃边界、局部敏感性秩和剖析状态。以实际网格分辨率报告 阈值交叉区间。如果它们太粗糙，则细化网格。 每个请求的剖析在所述误差模型下给出一个单通量区间； 多个 95% 剖析并不是整个网络的联合 95% 区域。 如果某个剖析找到了比基线更好的解，则重新运行拟合；不要发布 过时的区间。失败的剖析点是未知，而不是被数据排除。

6. 交付有界的科学结果。 包含模型和数据哈希、包 版本、来源/修正溯源、单位和参考通量、拟合预测、 残差诊断、剖析图或表格，以及未解决的通量组合。 保留 JSON 产物。将数据支持的点估计与沿平坦方向的 任意优化器选择区分开。只有在测试了其预测标记沿该方向 发生变化之后，才建议额外的测量。

示例

这些可执行示例使用合成的、仅示踪剂数据。没有隐藏的天然 丰度校正，并且示踪剂比例已经包含未标记材料。

恢复一个途径拆分；然后移除信息性测量

分析性双路径模型将双碳底物通过保碳途径或 碳交换途径输送。摄取固定为 100。80% 碳-1 标记的进料和 M+1 = 0.56 的碳-1 片段确定保碳途径 为 70，交换途径为 30。

.venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" fit \
  --model "$SKILL_DIR/assets/branch-model.json" \
  --data "$SKILL_DIR/assets/branch-identifiable.json" \
  --profile straight --profile-points 41 --output branch-fit.json

.venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" fit \
  --model "$SKILL_DIR/assets/branch-model.json" \
  --data "$SKILL_DIR/assets/branch-unresolved.json" \
  --profile straight --output unresolved-fit.json

第一次拟合大约恢复 70/30。在其声明的高斯误差模型下， straight 的分析 95% 区间约为 67.55–72.45；脚本报告 包含阈值交叉的网格区间。第二次拟合只有整个 分子分布，而这对于两条途径是相同的。预期局部秩为零 和 unresolved_within_bounds；其返回的拆分是任意最优值。

assets/branch-fluxes.json 提供 70/30 正向模拟向量。

重现已发表的环状网络计算

.venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" simulate \
  --model "$SKILL_DIR/assets/tca-model.json" \
  --data "$SKILL_DIR/assets/tca-tracer.json" \
  --fluxes "$SKILL_DIR/assets/tca-fluxes.json" --output tca-simulation.json

.venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" fit \
  --model "$SKILL_DIR/assets/tca-model.json" \
  --data "$SKILL_DIR/assets/tca-reference-mdv.json" \
  --profile v3 --profile v7 --output tca-fit.json

第一条命令重现已发表的舍入谷氨酸 MDV [0.3464, 0.2695, 0.2708, 0.0807, 0.0286, 0.0039]。 第二条使用合成参考测量来恢复接近 50 的谷氨酸分支 通量，同时认识到这种标记并不能解析 富马酸/草酰乙酸交换。约束诱导的上边缘并不是 测量确定的交换区间的证据。

解读边界

• 位置异构体字符串按从左到右碳 1 到碳 N排列。 "100000" 表示碳-1 标记的葡萄糖。仅凭质量分布无法确定 该位置混合物。适配器会处理 mfapy 反转的整数位排序。
• 天然丰度校正与示踪剂纯度校正是不同的操作。 输入必须采用文档规定的仅示踪剂基准，并以一致方式在源混合物中表示 示踪剂杂质。不要对同一贡献校正两次。
• 含 N 个碳的质量分布最多有 N 个独立分量，因为其总和为 一。该工具移除一个分箱并使用降维后的协方差。在可用时保留跨分箱 相关性。对角 SEM 拟合明确是近似的。
• symmetric 标志表示对恒等映射和完整碳序反转进行等权平均， 如同捆绑的延胡索酸/琥珀酸映射。它不是任意的分子 对称性。其他排列需要明确受支持的模型表示。
• 此命令行不支持：非稳态 MFA、反应速率的同位素效应、 未建模的池或区室、MS/MS 联合分布、多元素同位素 校正、分数碳化学计量/伪反应，以及生物体规模 性能保证。对于这些情况，请使用经过验证的专用模型/引擎，并 保留相同的输入/来源与可辨识性规范。

实现与验证

scripts/mfa.py 是命令行接口。scripts/_mfa_model.py 验证输入并将其适配到 mfapy EMU 模拟器；scripts/_mfa_fit.py 处理可行通量坐标、 多起点优化、诊断秩和剖面计算。 引擎固定于 assets/requirements.txt。

位于 tests/13c-metabolic-flux/ 的仓库测试套件检查已发布参考、 解析拆分恢复与似然剖面、未解析路径与交换、 带相关误差的省略分箱不变性、并行示踪剂、绝对速率 锚定、重复底物缩合、对称性、无效映射和命令行行为。 这些检查确立了经过测试的数值行为，而非对用户模型进行生物学验证， 也不证明相对于任何特定语言模型的优势。

来源

• 测试修订版处的 mfapy 源代码，版本 0.6.3；API 文档。
• Matsuda 等（2021），mfapy：用于基于 13C 的代谢通量分析的开源 Python 包。
• Antoniewicz、Kelleher 和 Stephanopoulos（2007），基本代谢物单元（EMU）：用于建模同位素分布的新框架。
• TCA 网络改编自 mfapy 的 MIT 许可示例文件；署名 和完整声明位于 assets/mfapy-license.txt。