13c-metabolic-flux

Carbon-13 代谢通量推断

将经过审核的碳映射、明确的示踪剂混合物和校正后的标记测量值， 转化为可行的通量估计，并判断实验对哪些通量有所约束。 请使用随附的求解器，而不是自行重建同位素平衡或逐个拟合反应。 该求解器运行 mfapy 的 EMU 正向模拟器，并使用 SciPy 在满足质量平衡的可行空间中拟合通量。它不使用 FBA 目标函数。

适用范围与所需证据

此实现适用于代谢稳态和同位素稳态、一个或多个示踪实验共用的 单一通量状态、非负单向反应通量，以及碳子集质量分布。可逆反应需映射为两个独立方向。 测量误差采用高斯分布，并提供协方差矩阵或明确说明使用对角近似。

拟合前，请获取：

• 碳网络以及每个原子分配的来源。仅凭化学计量关系无法确定标记原子的去向。将不同区室记录为独立的代谢物 ID。
• 对两项稳态假设的证据。代谢物丰度稳定并不能证明已达到同位素稳态。时间序列标记实验需要使用包含代谢物池大小和初始标记情况的 INST-MFA；不要将其平均后输入此求解器。
• 每种碳输入的位点同位素异构体分布，包括未标记补充物、被同化的碳酸氢盐/CO2，以及示踪剂杂质。
• 片段碳原子分配、天然丰度校正记录，以及报告均值的不确定性。在构建这些输入前，原始峰强度、衍生化光谱和 MS/MS 转换均需经过验证的预处理。
• 通量单位、胞外速率测量值或明确的相对通量参考，以及有生物学依据的边界。仅凭标记比例无法确定绝对速率。

如果缺少必要信息，请指出缺少什么并准备输入模板；不要臆造片段分配、原子映射、同位素校正或测量误差。 准备输入时请阅读 references/input-contract.md。 解读实际拟合结果前，请阅读 references/inference.md。

安装经过测试的引擎

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

uv venv --python 3.11 .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 内部生成的数值函数之前对其进行限制。

工作流

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. 检查证据。 检查失败的启动、残差模式、质量平衡、 活跃边界、局部灵敏度秩以及轮廓状态。按实际网格分辨率报告阈值交叉 区间；如果分辨率过粗，请细化网格。如果轮廓找到比基线更好的解，请重新运行 拟合；不要发布过时的区间。轮廓点拟合失败表示结果未知，而非数据已将其排除。

6. 交付有界的科学结果。 包含模型和数据哈希值、软件包 版本、来源／修正溯源信息、单位和参考通量、拟合预测值、 残差诊断、轮廓图或表格，以及尚未解析的通量组合。 保留 JSON 成果文件。将数据支持的点估计与平坦方向上的任意 优化器选择区分开。只有在检验过额外测量是否会改变沿该方向的预测标记结果后，才 建议增加测量。

示例

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

恢复通路分流；然后移除有信息量的测量

这个解析型双路径模型将一种双碳底物分别送入保碳路径或 碳交换路径。摄取量固定为 100。碳-1 标记比例为 80% 的底物，以及 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 个独立分量，因为各分量之和为 1。该工具会移除一个分箱，并使用降维后的协方差。若有跨分箱相关性，应予以保留。仅使用对角 SEM 的拟合明确属于近似。
• symmetric 标志表示对恒等映射和完整碳顺序反转取等权平均，如随附的富马酸／琥珀酸映射所示。它不表示任意分子对称性。其他排列需要使用明确支持的模型表示。
• 此 CLI 不支持：非稳态 MFA、反应速率的同位素效应、未建模的池或区室、MS/MS 联合分布、多元素同位素校正、碳化学计量数为分数的反应／伪反应，以及生物体尺度的性能保证。对于这些情况，请使用经过验证的专用模型／引擎，并保持同样的输入／溯源和可辨识性规范。

实现与验证

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

tests/13c-metabolic-flux/ 中的仓库测试会检查已发表的参考结果、解析拆分恢复和似然剖面、未解析的路径与交换、相关误差下省略分箱的不变性、并行示踪剂、绝对速率锚定、重复底物缩合、对称性、无效映射以及 CLI 行为。 这些检查确立的是经过测试的数值行为，而非对用户模型的生物学验证，也不代表其相较于任何特定语言模型具有经过测量的优势。

来源

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

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本，以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。对于任何会改变结果的值，应询问，不要猜测。
3. 先运行小规模版本。 先在小型子集（一个样本、一条染色体、几千个细胞）上运行流程。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 在解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
输入之间的基因组版本或标识符不匹配	停止并进行统一（liftover、ID 映射）后再继续。
当前安装版本缺少这些说明中提到的函数、标志或端点	查看已安装版本自带的文档（help()、--help、官方文档），调整做法并告知用户。切勿编造 API。
必需的输入、标识符或参数含糊不清	询问用户，或在运行前明确说明所作的假设。

诚信规则

• 切勿编造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请直言说明。
• 不要作出超出统计数据支持范围的生物学意义解读；应报告多重检验校正结果。
• 请将此处与特定版本相关的细节视为可能已过时：根据已安装版本的官方文档进行确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，务必先征得同意。

相关技能

• cobrapy：使用 COBRApy（Python，导入 cobra）对 SBML、JSON、YAML 或 MATLAB 格式的基因组规模模型运行基于约束的代谢建模。