cobrapy

COBRApy 是一个用于代谢模型约束重建与分析（Constraint-Based Reconstruction and Analysis，COBRA）的 Python 库，主要服务于系统生物学研究。它可以处理基因组尺度代谢模型，对细胞代谢进行计算模拟，开展代谢工程分析并预测表型行为。

版本说明：示例以 PyPI 上的 cobra 0.31.1 为目标（import cobra）。文档地址为 cobrapy.readthedocs.io，代码仓库为 opencobra/cobrapy。

适用场景

在以下情况可使用本技能：加载、构建或导出基因组尺度代谢模型（SBML、JSON、YAML）；在 COBRA 模型上运行 FBA、pFBA、FVA 或通量采样；执行基因或反应敲除筛选与生产包络分析；设计或优化生长培养基与交换约束；对不可行模型进行缺口填补或验证模型一致性。

安装

uv pip install "cobra==0.31.1"

MATLAB 模型读写（可选）：

uv pip install "cobra[array]==0.31.1"

COBRApy 使用 optlang 管理求解器。GLPK 通过 swiglpk 自动安装。对于大型 MILP/QP，cobra 0.29+ 增加了混合求解器（HIGHS/OSQP）；model.solver = "osqp" 现在会经由 hybrid 路由，未来版本可能在普通 LP 上报错——在可用时优先使用 model.solver = "hybrid"。

核心能力

模型管理：可从本地内置模型（textbook、e_coli_core、iJO1366、salmonella）或远程仓库（BiGG / BioModels，需联网，首次获取后缓存）加载模型，也可通过 read_sbml_model、load_json_model、load_yaml_model 从文件读取；支持以 SBML（推荐）、JSON（兼容 Escher）、YAML（人类可读）格式保存。
模型结构与组件：可访问 model.reactions、model.metabolites、model.genes，按 ID 或索引获取具体对象，并查看反应方程、通量边界、基因-反应规则（GPR）、代谢物化学式与区室等属性。
通量平衡分析（FBA）：通过 model.optimize() 执行标准优化，读取目标值与通量；slim_optimize() 仅返回目标值以提升性能；可修改目标函数；支持简约 FBA（pfba）与几何 FBA（geometric_fba）。
通量变异性分析（FVA）：计算各反应的通量范围，可设置 fraction_of_optimum（如 0.9）、启用 loopless 消除热力学不可行环路，或指定反应列表。
基因与反应敲除研究：提供单基因/单反应/双基因/双反应删除函数，双删除支持多进程；也可用上下文管理器手动敲除。
生长培养基与最小培养基：查看与修改 model.medium（需整体重新赋值），并通过 minimal_medium 计算最小培养基，可选择最小化总输入通量或最小化组分数（后者使用 MILP，较慢）。
通量采样：使用 sample 函数以 OptGP（默认，支持并行）或 ACHR 方法采样可行通量空间，并可验证样本有效性。
生产包络：通过 production_envelope 计算表型相平面，可指定反应、目标与碳源，并用 matplotlib 或 pandas 绘图。
缺口填补：通过 gapfill 结合通用反应数据库（SBML/JSON，cobra 0.31+ 未内置）为模型补充反应使其可行。
模型构建：使用 Model、Reaction、Metabolite 从零构建模型，添加代谢物与化学计量、设置基因-反应规则、添加边界反应并设定目标。

常见工作流

包括：加载模型并预测生长；基因敲除筛选（识别必需基因与影响较小的基因）；培养基优化（计算达到最大生长一定比例所需的最小培养基）；通量不确定性分析（先做 FVA，再对范围较大的反应采样分析分布）；使用上下文管理器进行临时修改（退出后自动还原）。

最佳实践

临时修改使用上下文管理器以避免状态管理问题；分析前用 model.slim_optimize() 验证模型可行性；优化后检查解状态（optimal 表示求解成功）；热力学可行性重要时使用 loopless FVA；在 FVA 中合理设置 fraction_of_optimum 以探索次优空间；对计算开销大的操作（采样、双删除）并行化，基因组尺度模型上先从小 n 和 processes=1 开始；模型交换与长期存储优先使用 SBML 格式；仅需目标值时使用 slim_optimize()；验证通量样本以确保数值稳定性；从工作流示例写出 CSV/PNG 前确认输出路径。

故障排查

不可行解：检查培养基约束、反应边界与模型一致性；优化缓慢：通过 model.solver 尝试不同求解器（GLPK、CPLEX、Gurobi）；无界解：确认交换反应具有合适的上界；导入错误：确保文件格式正确且 SBML 标识符有效。

参考资料

references/workflows.md 提供详细的分步工作流示例；references/api_quick_reference.md 提供常用函数签名与模式（其中“Key Concepts”涵盖 DictList 访问模式、通量边界约定、基因-反应规则与 EX_ 交换反应符号约定）。官方文档：https://cobrapy.readthedocs.io/en/latest/

代理操作流程

检查环境，确认工具版本、参考基因组/注释版本与输入格式；明确输入，确认格式、标识符与参数，对会影响结果的取值应询问而非猜测；先在小规模子集上运行；按上述说明与参考执行完整任务；验证结果，检查 QC 指标、样本身份、基因组版本一致性与批次效应；报告运行内容（版本、命令、参数）、已检查项与仍不确定项。

若出现以下情况：输入间基因组版本或标识符不匹配，应停止并在继续前统一（liftover、ID 映射）；说明中的函数、标志或端点在已安装版本中缺失，应查阅该版本自身文档（help()、--help、官方文档）并告知用户，绝不臆造 API；必需输入、标识符或参数不明确，应询问用户或在运行前明确说明假设。

完整性规则

绝不捏造结果、参数、标识符、引用或统计量；无法运行或验证的内容应如实说明；不超出统计支持范围解释生物学意义，并报告多重检验校正；此处版本相关细节可能过时，应针对已安装版本的官方文档进行确认；涉及花钱、占用共享 GPU 或云配额、接触个人或患者数据、或不可撤销的操作前应先询问。

技能介绍