PK-Sim 生理药代动力学（PBPK）建模与模拟

PK-Sim 是 Open Systems Pharmacology（OSP）推出的全身生理药代动力学（PBPK）建模工具。
本技能涵盖模型搭建、模拟运行、参数优化、药物-药物相互作用（DDI）、群体 PK 与结果分析。

前置条件

• 已安装 PK-Sim（https://github.com/Open-Systems-Pharmacology/PK-Sim/releases）
• 命令行工具 PKSim.CLI.exe 与 PKSim.exe 位于同一安装目录
• 脚本化接口走 R（⚠ 重要更正）：OSP 没有 Python 绑定，pip install ospsuite 在 PyPI 上是 404。
• R >= 4.4：https://cran.r-project.org/bin/windows/base/
• OSPSuite-R 12.4.3：从 GitHub release 的 ospsuite_12.4.3.zip 安装（Windows 二进制）
• 4 个非 CRAN 依赖：rSharp / ospsuite.utils / tlf / ospsuite.plots（不是 rClr）
• .NET 8 运行时（必装，见下）
• 安装命令、环境变量、踩坑表见 references/r-api.md（2026-09-09 全流程实测）
• 能力边界：能加载/改参数/换个体/跑/算 NCA；不能从零创建化合物/协议/制剂
  —— Building Blocks 需 GUI 建一次，或用 OSP 官方模型 + scripts/run_pbpk.md 中的 R 脚本（另存为 run_pbpk.r 后运行，GUI 0 次）
• ⚠ .NET 8 运行时（ospsuite 通过 rSharp 调 .NET，缺它 library(ospsuite) 直接报错）
• 探测方式：rSharp 执行 dotnet --list-runtimes，要求输出含 Microsoft.NETCore.App 8.x
• 安装（免管理员，装到用户目录）：
  powershell Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force & dotnet-install.ps1 -Runtime dotnet -Channel 8.0 -InstallDir C:\Users\<你>\.workbuddy\binaries\dotnet -NoPath
• 运行 R 前必须设（反斜杠风格，POSIX 风格 C:/... rSharp 识别不到）：
  powershell $env:PATH = "C:\Users\<你>\.workbuddy\binaries\dotnet;" + $env:PATH $env:DOTNET_ROOT = "C:\Users\<你>\.workbuddy\binaries\dotnet"
• 仅「1. 定义化合物 → 入口 B（SMILES 预测）」需要 RDKit：pip install rdkit
• ⚠ 与 OSPSuite-R 完全无关：rdkit 在 Python 3.13 可用
  （实测 Python 3.13.14 + rdkit 2026.3.6），RDLogger 的报错噪音已在脚本内关闭。
  RDKit 与 OSPSuite-R 可分置于两套环境（Python 3.13 / R 4.x），互不影响。

工作流程概览

1. 定义化合物
2. 定义个体
3. 定义给药方案
4. 创建模拟
5. 运行与比较
6. 参数优化
7. 导出

1. 定义化合物

新建项目时有两条入口，按手头数据情况选择：

> 两条入口不互斥。推荐做法：先用 B 生成一套完整初值把模型搭起来跑通 →
> 拿到实测数据后逐项替换 → 用第 6 节参数优化收敛。这样在无数据阶段也能开始建模，
> 又不会把预测值当成最终取值。

入口 A：手动输入参数

必需参数（最小可用模型）：

ADME 属性：

入口 B：由 SMILES 预测参数（无实测数据时）

用 scripts/predict_compound.py，基于 RDKit 分子描述符 + 规则式模型，
输出可直接填入 PK-Sim 的化合物参数，并对每一项标注可信度。

# 生成完整预测报告（中文）
python scripts/predict_compound.py --smiles "CC(C)Cc1ccc(cc1)C(C)C(=O)O" --name "Ibuprofen"

# 输出 JSON，便于脚本串联 / 自动填表
python scripts/predict_compound.py --smiles "..." --json

# 用 JSON 传入（含名称）
python scripts/predict_compound.py --input-json '{"smiles":"CCO","name":"乙醇"}'

# 只看理化参数，跳过类药性与 ADME 规则预测
python scripts/predict_compound.py --smiles "..." --no-adme

# 已有实测 fu：传入后【六】消除与分布全部结果按实测值重算（强烈推荐）
python scripts/predict_compound.py --smiles "..." --fu 0.13

# 指定体重（影响 Vss 总量与 t½，默认 70 kg）
python scripts/predict_compound.py --smiles "..." --fu 0.13 --body-weight 60

# 指定 GFR fraction（肾滤过分数：1.0=纯滤过，<1 净重吸收，>1 主动分泌）
# 参照：OSP 官方达格列净模型取 0.79
python scripts/predict_compound.py --smiles "..." --fu 0.09 --gfr-fraction 0.79

依赖安装：pip install rdkit
> ⚠ Python 环境可与 ospsuite 分开：本脚本只依赖 rdkit（不依赖 pythonnet），
> 实测 Python 3.13.14 + rdkit 2026.3.6 可用；而 ospsuite 要求 3.8–3.12。
> 两者各用一个虚拟环境即可，互不影响。

输出参数的可信度分级（报告第一节会逐项标注）：

同时输出辅助判读信息：分子描述符、可电离基团与 pKa 区间、Lipinski/Veber/QED/SA Score/PAINS、
BBB 与 GI 吸收等规则式预测，以及一份必须实测的参数清单（Clint、CYP 亚型参数、
转运体参数、Peff、血浆蛋白结合实测等——这些无法由结构预测）。

🔬 该脚本的精度已做文献对照实测（7 个常见药物，脚本 pk-sim-test/validate_adme.py）：

⚠ 必须知道的几条局限：

1. fu 与 pKa 是弱相关外推，不是预测值。同类化合物的实测 fu 可相差一个数量级，
   所以脚本输出的是「初值 + 建议搜索区间」，搜索区间用于第 6 节的参数识别。
2. 特殊酸性结构可能被漏判。烯醇式 β-二酮、4-羟基香豆素（如华法林，pKa≈5）
   不会被通用酚羟基 SMARTS 捕获。脚本对「MW>250 且 logP>2 却未识别到强酸基团」的分子
   会自动放宽 fu 搜索区间并给出警告，但仍建议核查实测 pKa/fu。
3. ESOL 对多羟基/糖苷类系统性低估（实测教训，2026-09 达格列净案例）：
   脚本算 9.85 mg/L，OSP 官方模型识别值 221 mg/L，低估 22.4 倍（1.35 log），
   超出 ESOL 声明的 ±1 log。触发条件：羟基 ≥4 或检出吡喃/呋喃糖环。
   此时脚本会把估算值标为下界并给出乐观上界（+1.35 log），
   建议把「下界–上界」作为溶解度参数识别的搜索区间。
   ⚠ 溶解度是口服溶出模型的直接输入，低估会导致吸收被严重低估，务必用实测值覆盖。
4. 这是建模起点，不是 ADME 数据替代品。进入参数优化阶段后，
   凡有实测值的参数一律以实测为准；正式模型中不得直接引用预测 fu/pKa 作为最终取值。

> 💡 建模前先查 OSP 官方模型库：github.com/Open-Systems-Pharmacology 已发布
> 100+ 化合物的完整 PBPK 模型（含达格列净、咖啡因等），带参数识别终值与验证报告。
> 有现成模型时直接用，比从 SMILES 从零预测可靠得多。仓库内含
> Dapagliflozin-Model.json（完整工程导出）与参数表 Section2.3_Model_Parameters_and_Assumptions.md。
> ⚠ 注意 .pksim5 是 SQLite 数据库，无法由 JSON 重新封装，需装 ospsuite 或开 GUI 转换。

消除与分布参数估算（报告【六】节）

> ⚠ 先厘清一件事：PK-Sim 里不填「消除常数」。它是机制性模型，你填的是机制参数，
> 由 PK-Sim 自己算 CL 与 t½。所以「由 SMILES 预测消除」要拆成三个不同的问题：

脚本【六】节输出四块：

1. 肾清除（生理学确定关系）：CLr = fu × GFR × GFR fraction，
   GFR 取 125 mL/min（70 kg 成人），GFR fraction 默认 1.0（纯滤过）。
   ⚠ 只含肾小球滤过：若化合物是 OAT/OCT 底物，主动分泌会使实际 CLr 显著更高
   （滤过分数>1）；若存在肾小管重吸收则更低（<1）。
   实测参照：OSP 官方达格列净模型拟合值 0.79，即默认假设在该例高估肾清除约 27%。
   已知滤过分数时用 --gfr-fraction 覆盖。
2. 代谢途径（酶归属）：判断以 CYP 还是 UGT 为主，见下方专节。
3. 肝 Clint 搜索区间 + 情景表：按 logP 分档给出区间（刻意跨 1–1.5 个数量级），
   并列出 5 档 Clint → 各自的肝 CL、提取比、预计 t½。用法是拿实测 t½ 或 CL 对照
   该表定位量级，再交给第 6 节参数识别精修，而不是直接取用。
4. Vss 估算：用 Øie-Tozer 方程（Oie & Tozer 1979）
   Vss = Vp(1+R_E/I) + fu·Vp·(Ve/Vp − R_E/I) + Vr·fu/fut，
   并对无法预测的组织游离分数 fut 做 ±3 倍敏感性扫描。

代谢途径（CYP 还是 UGT）—— Clint 数值之外的独立问题

为什么单独列：Clint 的数值可以按 logP 分档估算，但酶归属推不出来；
而酶归属直接决定 DDI 模拟时选哪个抑制剂/诱导剂——数值对、酶选错，DDI 结论照样错。

实测教训（达格列净，2026-09）：脚本默认按 CYP 提示，但该药物料平衡显示
UGT1A9 → 3-O-葡萄糖醛酸 61.4%、UGT2B7 → 5.5%、CYP 氧化仅 9.1%。
即 Clint 数值（36.7 µL/min/mg）可用，酶归属必须人工改为 UGT1A9。

判断规则（启发式，非预测模型）：

⚠ 只数羟基（[OX2H]），不用 NumHDonors。曾按 HBD 判导致二甲双胍误报
（HBD=4 全部来自胍基 NH，实际以原形肾排）；咖啡因则因 logP=−1.03 险些被误判为"代谢低"
（实际 >95% 经 CYP1A2），故"原形排泄"规则必须同时限定碱性。

🔬 该规则在 7 个已知药物上与实测途径一致率 7/7（达格列净 UGT、布洛芬/咖啡因/
普萘洛尔/地西泮/华法林 CYP、二甲双胍原形肾排）。样本仍很小，仅作提示。

Clint 情景表 —— 拿实测 t½ 或 CL 对照，定位落在哪一档：      （布洛芬实例）
    Clint(µL/min/mg)    肝CL(L/h)      提取比(%)     预计t½(h)
  ──────────────────────────────────────────────────────
                 5.0       0.215         0.2       28.92
                12.6        0.54         0.6       13.64
                31.6       1.345         1.5        5.91
                79.5       3.305         3.8        2.48   ← 实测 t½≈2 h 落在这档
               200.0       7.859         9.0        1.06

这张表怎么用（布洛芬已实测验证）：文献值 t½≈2 h、CL≈3.5 L/h，对照上表
Clint≈79.5 那档（CL 3.3 L/h、t½ 2.5 h）最吻合；而由实测 CL 反解的真实 Clint 是
84.4 µL/min/mg —— 两者几乎一致。这说明用实测 t½ 对照该表定位 Clint 量级是可行的，
定位后再交给参数识别精修即可。

🔬 该模块已做反解验证（5 个已知药物，脚本 pk-sim-test/validate_elimination.py）：

> 最后一行是关键：Vss 的主要误差来自 fu 预测而非 Vss 公式。
> 普萘洛尔用预测 fu 误差 9.6 倍，换实测 fu 后降到 1.84 倍。
> 所以有实测 fu 时务必用 --fu 传入——本节所有数字都与 fu 成正比或反比，
> fu 差 N 倍，肝/肾清除率就差约 N 倍。

⚠ 该模块的硬限制（务必阅读）：

1. 肝 Clint 的 QSAR 外部 R² 仅约 0.16–0.5，误差常达数倍
   （Pirovano 2016 微粒体 Rext²=30%；1487 化合物研究回归 R²=0.16）。
   文献原话是「fub is structurally more predictable than Clint」。
   所以脚本给的是搜索区间，不是预测值。
2. fut 的关系式是本地校准（n=5），不是文献发表模型。
   它由 5 个药物的实测 Vss 反解拟合得到，样本极小，仅用于给出量级。
3. Vss 的文献基准：即使用实测 fup 输入，Vss 预测仍只有约 60–70% 的化合物
   落在 2 倍误差内（254 个临床化合物评估，Drug Metab Dispos 2021）。
4. 下列情形估算基本失效：主要经胆汁排泄、转运体底物、logP>5、MW>600。
   此时必须以实测为准。
5. ⚠ Vss ≠ Vz：不要拿临床 t½ 反推 Vss。脚本的 t½ 由 ln2·Vss/CL 算出
   （稳态容积定义），而临床报告常用 ln2·Vz/CL（终末相容积）。多室药物两者可差约 2 倍
   ——达格列净实测差 1.94×。所以对照情景表时，若用临床 t½ 定位，
   要考虑这层系统性差异，不要以为脚本的 Vss 算错了。

模型类型选择：
- 小分子：每器官 4 室（血浆 / 间质 / 细胞内 / 血细胞）
- 大分子（单抗 / 蛋白）：双孔模型 + FcRn 再循环
- ⚠ 上述 SMILES 预测规则仅适用于小分子；MW > 900 时脚本会提示改用大分子模型

2. 定义个体 / 群体

种属（Species）：Human（人）、Mouse（小鼠）、Rat（大鼠）、Minipig（小型猪）、Dog（犬）、
Monkey（猴）、Beagle（比格犬）、Rabbit（兔）

2.1 人种群（Population / Ethnicity）的选择

GUI 路径：Individual → Create → Biometrics，Species 选 Human 之后，
紧邻的下一个下拉框就是 Population。

PK-Sim 内置的人类种群共 8 个（官方文档 v12，与 ospsuite-R 的 HumanPopulation
枚举长度一致）：

⚠ PK-Sim 没有 Chinese（中国人群）种群。east_asian 底层是 Tanaka 1996 的体测数据，
代表的是「亚洲人平均体型」，不是中国人专有数据库。三条替代路线：

• 路线 A（最快）：直接用 japanese。报告里必须写明"以日本人群解剖生理数据近似中国
  人群"，并对亲脂、高 Vss 药物做敏感性分析。
• 路线 B（推荐）：选 east_asian 后，在 Biometrics 里手填目标人群的身高/体重/BMI，
  让 PK-Sim 按此缩放器官体积与血流——这是把中国人装进模型的正规做法。
• 路线 C（最严谨）：建 Population 而非 Individual，在 Population Parameters Ranges
  里按中国人群的年龄/身高/体重/BMI 分布约束，生成虚拟中国人群。

> 体型造成的 Vss 差异是机理性的（器官与脂肪体积直接进模型），
> 无法事后用一个系数补回来。

2.2 选了种群之后：什么会变，什么不会

会自动改变（数据库直接给不同值）：身高/体重/BMI 的年龄-性别分布、各器官体积与血流
速率、体成分（脂肪/肌肉/骨比例，决定亲脂药物 Vss）、血细胞比容、胃肠道分段体积与 pH 廓型。

★ 不会改变（这是最容易误解的一处）：

2.3 用 define_individual.py 拉齐上述决策

python scripts/define_individual.py --list                      # 列出 8 个种群
python scripts/define_individual.py --population chinese        # 中国人群替代路线
python scripts/define_individual.py --population chinese --gender male --age 45 \
       --height 172 --weight 76 --scr 88 --fm "CYP2C19=0.45"
python scripts/define_individual.py --population japanese --json

输出【一】种群溯源 /【二】人体测量学 /【三】肾功能 /【四】变与不变 /
【五】族裔代谢表型缩放 /【六】GUI 与 R·Python 代码。所有文献型数值都带 confidence，
其中代谢表型频率一律标 low，必须按目标人群原文核实后才可写进报告。

两条必须记住的结论：

1. BMI 阈值本身有族裔差异。同一个 BMI 24.3 的人，WHO 标准判"正常"，中国 WGOC
   标准判"超重"（≥24）。目标人群是中国人群时按中国标准判定，并在 Population
   Parameters Ranges 里按中国分布约束 BMI。
2. eGFR 方程之间有量级差。同一病人同一份肌酐，J-MDRD 与 CKD-EPI 2021 可相差 40% 以上。
   日本方程基于酶法肌酐校准，中国实验室多为碱性苦味酸法，两者 Scr 本身不可比；
   跨中心数据统一用 CKD-EPI 2021（无种族系数）做横向对比。

肾功能不全个体算出的个体 GFR（mL/min 与 L/h）可直接放进 predict_compound.py
的 CLr = fu × GFR × fraction 重算肾清除。

2.4 把族裔表型落到 PK-Sim

单个途径：CLh_new/CLh_old = 1 − fm_enzyme × (1 − 相对活性比)
多个途径：CLh_new/CLh_old = 1 − Σ fm_i × (1 − 相对活性比_i)

⚠ 不要把各酶的倍数连乘——CL_h 是各途径 Clint 按 fm 的加权和，连乘会把第二次缩放
施加在已缩过的总量上，系统性高估剩余清除率。

三条落地路径（同一件事的三种粒度，报告里要写明用了哪种）：
① 把该酶途径的分代谢 Clint 乘以倍数；
② Expression Profile 里调该酶在肝脏的相对表达量；
③ 做虚拟人群时用 User Defined Variability 给该酶表达加分布，按 PM/IM/EM 三档拆分。

> ⚠ 脚本化时的坑：HumanPopulation 的枚举名不等于 GUI 显示名，且随版本可能有差异。
> 先跑 names(HumanPopulation)（R）确认本版本真实写法，不要凭记忆写——
> 已知的可靠写法是 Japanese_Population（ospsuite 官方 vignette 中的例子）。

个体参数：
- 年龄、体重、身高、性别
- 疾病状态（肾功能不全、肝功能不全）

群体模拟：
- 定义协变量分布（体重、年龄、酶活性）
- 个体数量（通常 100-1000）
- 儿童会自动应用 CYPs / UGTs 的个体发育（ontogeny）函数

特殊人群：
- 肾功能不全：降低 GFR（值用 define_individual.py 算，见 2.3）
- 肝功能不全：降低 CYP 活性（Child-Pugh 分级缩放）
- 儿童：基于个体发育的酶 / 转运体成熟过程
- 老年：调整器官血流量，GFR 随年龄下降
- 妊娠：Population 选 Pregnant (Dallmann et al. 2017)，含胎盘转运的专用模型

3. 定义给药方案

口服剂型：
- Dissolved（已溶解）：速释
- Weibull：控释（溶出曲线 f = 1 - exp(-alpha*t^beta)）
- Particle dissolution（颗粒溶出）：取决于粒径
- Table（表格）：自定义溶出曲线

多次给药：设置给药间隔与给药次数；稳态评估需 ≥5 个半衰期。

4. 创建并运行模拟

> 三条路可走，按"全程不碰 PK-Sim GUI"程度从高到低：
> A. OSPSuite-R 全自动（推荐；化合物在 OSP 库 100+ 范围内可做到 GUI 0 次）→
> B. PKSim.CLI 跑已有项目（适合已建好的 .pksim5）→
> C. PK-Sim GUI 手点（最直接；GUI 步骤见 OSP 官方文档）

A. 通过 OSPSuite-R 全自动（推荐）

> 2026-09-09 全流程实测通过（PK-Sim 12.3 + R 4.6.1 + ospsuite 12.4.3 + .NET 8.0.31）。
> 完整踩坑表（10 条报错与对策）见 references/r-api.md 第 9 节。

> 能力边界：加载 .pkml → 改参数 → 换个体 → 跑 → 算 NCA / 敏感性 / 群体模拟 → 导出。
> 不能：从零创建 Building Blocks（Compound/Protocol/Formulation）——需 GUI 建一次，
> 或用 OSP 官方模型（100+ 化合物）走 .json → .pksim5 → .pkml 转换，实现 GUI 0 次。

最小工作流（实测可跑通）

library(ospsuite)
# ⚠ initPKSim() 可选：本环境不调用也能 loadSimulation（包 .onLoad 自动初始化）

# 1. 加载（只能是 .pkml；.json 快照需先用 PKSim.CLI snap --project 转）
sim <- loadSimulation("C:/path/to/PO SD 10 mg (perm).pkml")

# 2. 改剂量（⚠ 参数名是 parameterPaths 不是 paths；值单位 kg）
setParameterValuesByPath(
  parameterPaths = "Events|PO SD 10 mg|Dissolved|Application_1|ProtocolSchemaItem|Dose",
  values         = 2e-05,          # 20 mg → kg（OSP 内部质量单位是 kg）
  simulation     = sim,
  units          = "kg"
)

# 3. 换个体（⚠ age 必须 double；字段是驼峰 distributedParameters）
ic <- createIndividualCharacteristics(
  species    = Species$Human,
  population = HumanPopulation$Japanese_Population,
  gender     = Gender$Male,
  age        = 30.0,
  ageUnit    = "year(s)"
)
individual <- createIndividual(individualCharacteristics = ic)
setParameterValuesByPath(
  parameterPaths = individual$distributedParameters$paths,   # ⚠ 不是 distributed_parameters
  values         = individual$distributedParameters$values,
  simulation     = sim
)

# 4. 运行（⚠ 复数；返回按模拟 ID 索引的 list，必须取 [[1]]）
res <- runSimulations(simulations = sim)[[1]]

# 5. NCA + 读取（⚠ allQuantityPaths 是字段无括号；QuantityPKParameter 用 $values 复数）
pk <- calculatePKAnalyses(results = res)
for (q in pk$allQuantityPaths)
  for (v in pk$allPKParametersFor(quantityPath = q))
    cat(v$name, v$values, v$unit, "\n")

# 6. 取曲线 + 保存
vals <- getOutputValues(simulationResults = res)   # list(data=513x4, metaData)
saveSimulation(sim, filePath = "out.pkml")

> 封装好的 CLI 版见 scripts/run_pbpk.md（R 源码在文件内代码块中，另存为 run_pbpk.r 即可运行；纯 base R 解析参数，无需 optparse）：
> bat > Rscript run_pbpk.r --template "...\PO SD 10 mg (perm).pkml" ^ > --dose 20 --population japanese --gender male --age 30 --output ".\out" >
> 实测输出：pk_params.csv / time_profile.csv / units.txt / *_modified.pkml。

实测参考值（达格列净 PO 20 mg，Japanese 30 y 男性）

⚠ 输出时间单位是 min 不是 h；尿液分数类 quantity 的 NCA 会输出 NaN/Inf，属 OSP 正常行为。

OSPSuite-R 主要 API 速查（实测确认存在）

⚠ 已不存在 / 已废弃（勿再用）：setEndSimulationTime、loadProject、
createCompound、createProtocol、createFormulation、convertSnapshot、
runSimulation（单数，deprecated）、setParameterValue（单数）、identifyParameters。

B. 通过 PK-Sim CLI（Windows）

> ⚠ 实测校正（PK-Sim 12.3），以下三点最易出错：
> 1. --output / -o 是输出文件夹，不是文件路径
> 2. 指定模拟用 --simulations（复数），不是 --simulation；
> 多个模拟用空格分隔，名称含空格必须加引号
> 3. run 的输入是含 batch json 的文件夹，不接受 --project + --simulation

# 运行并导出项目中全部模拟（CSV + PKML）
PKSim.CLI export --project <ProjectFile>.pksim5 --output <OutputFolder> --csv --pkml --run

# 仅运行指定的模拟（注意复数）
PKSim.CLI export --project <ProjectFile>.pksim5 --output <OutputFolder> --csv --run \
                 --simulations "IV 1 mg" "PO 10 mg"

# 短选项：-p 项目 / -o 输出 / -r 先运行 / -c csv / -k pkml / -x xml / -j json / -e excel
PKSim.CLI export -p <ProjectFile>.pksim5 -o <OutputFolder> -cr

# 批量运行：输入为含 batch json 文件的文件夹
PKSim.CLI run --input <InputFolder> --output <OutputFolder> --csv

# 项目 <-> 快照互转（--input 与 --output 均为文件夹）
PKSim.CLI snap --input <ProjectFolder>  --output <SnapshotFolder> --snapshot
PKSim.CLI snap --input <SnapshotFolder> --output <ProjectFolder>  --project

输出结构：<OutputFolder>/<SimulationName>/<SimulationName>-Results.csv（及同名 .pkml）。

子命令清单：run / snap / export / qualification / help / version；
用 PKSim.CLI help <cmd> 查看各自完整参数。

C. 通过 PK-Sim GUI

完整 GUI 步骤在 OSP 官方文档，按需要查对应章节：

> 为什么不抄到本技能里：OSP 文档每版本同步更新；本技能只列权威入口避免失效。

5. 参数识别（优化）

将模型参数拟合到观测数据。

常优化的参数：
1. 脂溶性（影响分布）
2. 特异性清除率 / Clint（影响消除）
3. 特异性肠渗透性（影响吸收）
4. 游离分数（不确定时）
5. 酶促代谢的 kcat

优化方法：Nelder-Mead、Levenberg-Marquardt

6. 药物-药物相互作用（DDI）模拟

步骤：
1. 建立经充分验证的促变药（perpetrator）模型，含抑制 / 诱导参数
2. 建立含代谢通路的受变药（victim / substrate）模型
3. 定义相关酶的表达谱
4. 创建同时含两个化合物的 DDI 模拟
5. 分别在「有 / 无促变药」条件下运行，计算 AUCR 与 CmaxR

CYP 抑制输入：Ki 值（uM）、抑制类型（competitive 竞争性、noncompetitive 非竞争性、
uncompetitive 反竞争性、mechanism-based 基于机制）。机制型抑制（MBI）另需 Kinact、KI。

CYP 诱导输入：Emax（诱导倍数）、EC50（uM）。

DDI 判定标准：
- AUCR ≥ 1.25：弱 DDI
- AUCR ≥ 2.0：中等 DDI
- AUCR ≥ 5.0：强 DDI

7. 敏感性分析

识别对 PK 输出影响最大的参数：将每个参数变动 ±10%，计算其敏感系数。

8. PK 参数计算

基于浓度-时间数据（模拟值或观测值）：

用 scripts/calculate_pk.py 从模拟 CSV 输出自动计算 PK 参数（中文报告 + JSON，自带 NCA 质控告警）。

> ⚠ Vz 与 Vss 不是一回事：Vd（=Vz）是末端相容积，多室模型中通常与稳态容积 Vss 不同量。
> 达格列净案例中二者相差约 1.94 倍。旧版的 Vd 字段实为 Vz，现已同时输出 Vz 供区分，
> Vd 仅作兼容保留。

基本用法

# 标准用法：PK-Sim 导出的时间列是 min，必须显式声明，脚本自动换算为 h
python scripts/calculate_pk.py --input results.csv --time-unit min --dose 100 --route iv

# 时间在第 1 列、浓度在第 2 列（PK-Sim 首列常为 IndividualId）
python scripts/calculate_pk.py --input results.csv --time-col 1 --conc-col 2 \
    --time-unit min --dose 100

# 浓度为 µmol/L 时（PK-Sim 常用），用分子量换算到 mg/L
python scripts/calculate_pk.py --input results.csv --time-unit min --dose 5 \
    --conc-unit umol/L --mol-weight 408.87

# 末端自动选点不合理时，手动锁定末端相窗口
python scripts/calculate_pk.py --input results.csv --time-unit min --dose 100 \
    --lambda-z-range 6,24

# JSON 输出供下游脚本消费
python scripts/calculate_pk.py --input results.csv --json --output pk_params.json

主要参数：--time-unit {h,min}、--conc-unit、--mol-weight、--route {iv,po,ev,infusion}、
--method {linlog,linear,log}、--lambda-z-range、--iv-back-extrapolate、--json、--output。
退出码：0 成功 / 1 运行错误 / 2 输入错误。

内置质控告警（不必再自行核查）

脚本会自动检查并在报告末尾告警：

> 实测对照：某份 Time [min] 的短 CSV 忘记加 --time-unit min，
> 脚本同时给出「AUC 外推 67.0%」「t½=415.9 h 超过观测时长 240 h，请确认时间单位为小时」两条告警；
> 同场景旧版脚本完全静默、直接返回半衰期被放大 60 倍的结果。

与旧版的行为差异（调用方需注意）

1. 默认改用 linear-up / log-down：上升段线性、下降段对数（NCA 标准）。
   稀疏采样（每 8 h 一点）时旧版线性法使 AUC 高估 5.28%，新版无系统性偏差。
   需复现旧行为用 --method linear。
2. 外推用 Clast_pred（末端回归预测值）而非实测末点，降低单点噪声影响。
3. 数值输出按有效数字（不再四舍五入到 6 位小数），旧版会把 ≤1e-7 mg/L 的 Cmax 塌缩为 0。
4. 输出 JSON 增加 units、notes、warnings、terminal_points、Clast_predicted
   等字段；原有 Cmax/Tmax/AUC0_t/AUC0_inf/lambda_z/t_half/CL/Vd/Vss/MRT/N_points 全部保留。

> 仍未提供的能力：脚本面向单剂量数据，不计算多剂量稳态参数
> （Cmin、Cavg、蓄积比）；Vss 对血管外给药含 MAT 偏差，需 Vss 时应使用静脉给药数据。

9. IVIVE：体外到体内外推

将体外实验数据转化为 PBPK 模型输入。

肝清除（充分搅拌模型，well-stirred model）：
CLhep = Qh * fu * Clint / (Qh + fu * Clint)
Clint = in_vitro_clint * MPPGL * liver_weight
MPPGL = 每克肝的微粒体蛋白量（人约 40 mg/g）

肠渗透性：Peff = f(fu_gut, Caco-2_Papp)，基于相关性缩放。

肾清除：CLrenal = fu * GFR + CLR_secretion - CLR_reabsorption

各物种详细缩放因子见 references/ivive_reference.md。

10. 导出与报告

导出格式（由 PKSim.CLI export 的标志位控制，一律输出到文件夹）：
- -c / --csv : 结果数据，文件名 <SimulationName>-Results.csv
- -k / --pkml : 模拟交换格式，单个模拟可复用
- -x / --xml : 模拟模型 XML
- -j / --json : 结果 JSON（仅单个模拟可用）
- -e / --excel : xlsx 格式结果
- snap --snapshot: JSON 快照，可读、适合版本控制

报告模板：
1. 化合物理化性质表
2. ADME 表征
3. 模型结构与假设
4. 观测值 vs 预测值叠加图
5. PK 参数对比表
6. DDI 预测结果（如适用）
7. 敏感性分析龙卷风图
8. 群体模拟统计量

项目文件约定

• PK-Sim 项目：.pksim5（二进制，含全部构建模块）
• 模拟导出：.pkml（XML，单个模拟）
• 快照：.json（可读，适合版本控制）
• 观测数据：.csv 或 .xls（时间、浓度、误差）
• 结果：.csv（时间 + 全部输出）
• 实际列结构（实测 PK-Sim 12.3）：IndividualId、Time [min]、
  Organism|PeripheralVenousBlood|<Compound>|Plasma (Peripheral Venous Blood) [µmol/l]、……
• ⚠ 时间单位为 min；列名带单位后缀；首列 IndividualId（群体模拟时为多个个体）
• 输出目录：<OutputFolder>/<SimulationName>/<SimulationName>-Results.csv（+ 同名 .pkml）

关键参考

• PK-Sim 文档：https://docs.open-systems-pharmacology.org/working-with-pk-sim/pk-sim-documentation
• OSP Python API：https://github.com/Open-Systems-Pharmacology/OSPSuite.Python
• OSP R API：https://github.com/Open-Systems-Pharmacology/OSPSuite.R
• PK-Sim 发行版：https://github.com/Open-Systems-Pharmacology/PK-Sim/releases
• 社区论坛：https://github.com/Open-Systems-Pharmacology/Forum