jinko-task-from-nonmem

Jinkō 任务：从 NONMEM 转换

将 NONMEM 运行转换为可用的 Jinkō 试验。

前置条件： 此技能需要已初始化的 jinko-sdk 连接，以及满足其 metadata.requires_sdk 范围要求的 SDK。运行 jinko-sdk-setup 技能 （../jinko-sdk-setup/SKILL.md），并且只有在检查通过后才能继续。会话代码只能兑换一次，因此在此技能自己的 SDK 进程启动 前，请再次调用 get_session_code。如果找不到该技能，请从 novainsilico/jinko-skills 安装。

此技能还需要转换器的额外依赖，而 SDK 默认不会安装该依赖：

pip install "jinko-sdk[nonmem2jinko]"

转换器是 nonmem2jinko 包。它随 jinko-sdk 一起提供，但需要单独导入。该额外依赖会添加 scipy，数值检查会用它对参考求解结果进行积分。没有它，所有脚本仍可运行，但 --check solve 会报错并提示所需的额外依赖。

核心规则

• 运行脚本。切勿手动翻译 $PK；只有脚本的输出会经过验证。
• 务必检查数值，并报告测得的一致性。没有数值结果，就绝不能声称转换成功；报告的结论也必须有对应结果。
• 说明数值所依据的参考来源。--reference scipy 用于隔离平台影响；rxode2 也涵盖读取过程；nonmem 则会与原始运行写入的 $TABLE 进行比较，不需要许可证，只需要该文件。这些参考来源不可互换。当前，rxode2 数值参考会拒绝需要协变量覆盖的模型，而不是拿不一致的输入进行比较。
• 遇到阻断错误就停止。若不告知用户因此会失去什么，不要传入 --allow-issues。
• 应用之前先阅读报告。单位和名称是推断得出的，对于给定数据集而言，其中一些推断可能有误。
• 时间单位错误会悄无声息地改变动力学。Jinkō 接受任意时间单位，但求解和返回的结果都以秒为单位。请根据数据集确认剂量、体积和时间单位。
• 在平台自身的时间网格上进行比较。Time 是可请求的序列，应请求该序列。记录的事件会插入自己的时间点，因此根据 tMin/tStep 对重建网格，会导致数值与错误的时间点配对。

脚本

脚本	用途
convert_model.py	将控制流转换为计算模型
convert_trial.py	将模型与 vpop、方案、输出集和试验组合
compare_against_reference.py	数值检查。不可跳过
upload_data_tables.py	将群体数据转换为数据表，绑定到试验并叠加显示在可视化中
render_equivalence_report.py	将测得的比较结果生成 Markdown 报告
publish_equivalence_report.py	将报告发布为 Jinkō 文档

项目写入默认采用试运行模式，只有传入 --apply 才会执行。对于脚本支持 --overwrite 的本地构件输出，必须显式指定路径参数；默认会保留现有文件。

编排

1. 请求 .ext、.phi 和数据集。每项都能提升转换效果；仅凭控制流也足以开始。
2. 执行试运行转换。根据报告处理问题：--time-unit、 --amount-unit、--volume-unit、--unit SYMBOL=unit、 --rename NONMEM=jinkoId。
3. 应用转换，然后运行。
4. 使用与转换相同的 --time-unit 进行数值检查。跳过求解属于失败，而非证据。报告数值及其参考值。
5. 只要有人需要依赖该模型，而此人并非执行转换的人，就应渲染模型并提供等价性报告。

每个写入步骤都需要 --folder NAME --create-folder，以便将一次运行的条目放在一起；还需要 --json-out FILE，供下一步获取 SID。不要从文本说明中抓取 SID。

--parent-folder NAME 会将该文件夹嵌套在另一个文件夹中。项目累积了多次转换时请使用此选项：以日期命名的文件夹下，为每个模型创建一个子文件夹，可将每次运行的证据放在一起，并按时间顺序排列运行记录。不使用此选项时，项目根目录会堆满模型名称，而且无法看出每个模型对应哪次运行。

决策

人群（convert_trial.py）。--population design（默认）可在之后于 Jinkō 中编辑。phi 会重放拟合得到的受试者。sampled 会从 $OMEGA 所表示的完整多元正态分布中抽样；有限样本的实际协方差存在抽样误差，必须进行测量，不能称其为精确值。

随机效应（两个转换器均适用）。--vpop-mode etas（默认）通过 ETA 边际分布和相关性表示目标 $OMEGA 协方差。parameters 则将边际分布放在派生参数上：在 UI 中更易读，但只有在不存在协变量效应时才等价。

给药（convert_trial.py）。--dosing auto（默认）会在数据集具有分组结构时使用分组，否则使用按患者设置的时段。每位受试者都有个体化用药史的研究——例如新生儿苯巴比妥、按体重分组的单次剂量——不具有分组结构；per-patient 会将每位患者自己的给药时间和剂量放入 vpop。需要使用 --population phi 或 sampled，因为给药计划依赖患者表。

不确定性（convert_trial.py）。--eps-clones N 可生成每位患者的预测锥。需要使用 --population phi 或 sampled。这不是 VPC，详见 references/residual-error.md。

**拒绝转换，并指出具体记录：**稳态（SS）给药、$MIX、嵌套随机效应、以 SD 表示的 $OMEGA/$SIGMA、相关性或 Cholesky、仅含 $PRED 的模型、无法读取的缩写代码（MPAST、变量 ETA() 下标、CALL、include）、动力学所需但读取记录级数据项（如 DV 或 EVID）的参数，以及 IF(AMT.GT.0) TDOS = TIME——拒绝此写法的原因正是，用模拟时间替代它看似合理，却会悄无声息地导致给药后时间为零。

报告但不拒绝：$PRIOR 和 $NONPARAMETRIC 影响的是估计过程，而非前向模型，因此估计值会按原样转换。

采用明确说明的近似进行转换：DOSE = AMT 指向模型的剂量参数，因此剂量量各不相同的受试者只会读取第一个剂量；时变协变量只保留其基线值；选择适用哪种随机效应的协变量不能表示为一个 vpop 边际分布；通过权重表示的组合误差模型（Y = F + W*EPS(1)，W = F*θ + θ）会连同其系数一起诊断，但输出的观测值不包含残差误差。

参考资料

• references/workflow.md — 命令、标志和完整操作流程
• references/validation.md — 数值检查及其各自的验证内容
• references/reporting.md — 等效性报告、数据表和叠加图
• references/conversion-map.md — 各类 NONMEM 结构的转换结果
• references/residual-error.md — $ERROR、$SIGMA 和克隆近似

通用操作机制由更底层的技能负责：jinko-model 负责组件，jinko-vpop 负责群体，jinko-protocol 负责治疗臂，jinko-trial 负责运行，jinko-data-table 负责数据表，jinko-trial-viz 负责可视化，jinko-document 负责文档。