jinko-vpop

Jinkō Vpop SDK 工作流

使用此技能通过 SDK 执行技术 vpop 和 vpop-design 工作流。使用 assets/distrib.json 中允许的分布形式；如有专用的分布设计技能，请将更深入的分布设计交由该技能处理。

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

核心规则

• 直接上传 vpop 时，使用 client.create_vpop_from_csv() 或 client.create_vpop_from_dataframe()。
• 创建边缘分布 vpop 设计时，使用 client.create_vpop_design_from_design()。
• 使用 design.generate_vpop() 从 VpopDesign 生成不可变的 Vpop。
• 生成前检查 design.diagnostics（或 design.get_sanity()），并先修复报告的错误。
• 使用 design.descriptors（create*/set_distribution*）和 design.correlations 编辑现有设计的描述符/相关性，不要替换原始负载。
• 将 Vpop 项目条目视为已生成/已上传的产物，不可就地编辑。
• 编辑 vpop 设计，而非已生成的 vpops，然后重新生成新的 vpop。
• 创建或更新项目条目前，必须获得明确确认，或要求脚本使用 --apply。
• 如果 vpop 将与某个模型配合使用，CSV 标题和边缘设计中的描述符 ID 必须与实际模型组件 ID 一致。
• 拒绝边缘列表中重复的描述符 ID；否则转换为映射时会静默丢弃较早的条目。
• 对所有 LogUniform、LogNormal 或 LogNormalTruncated 负载，遵循下文的“对数尺度分布”；对 Mixture 权重，遵循“混合分布”。

项目文件夹规范

• 优先在专用的 Jinkō 文件夹中创建 vpops 和 vpop 设计，而不是放在项目根目录。工作流开始时，询问或建议一个文件夹名称，例如 YYYY-MM-DD-<experiment-name>。
• 尽可能复用名称完全匹配的现有文件夹：client.get_folder_by_name(name, exact_match_only=True)。
• 如果文件夹不存在，只有在用户确认后，或脚本使用 --apply 运行时，才创建文件夹。
• 解析出一个文件夹对象或文件夹 ID，然后将 folder=folder 传递给支持此参数的 SDK 创建调用。

随附资源

• assets/toy_vpop.csv：使用玩具模型描述符 Dose 和 k_elim 的双患者 vpop CSV。
• assets/toy_marginals.json：针对 Dose 和 k_elim 的边缘分布列表形式的 vpop 设计。
• assets/distrib.json：允许使用的边缘分布形式的权威来源。

SDK 脚本

请使用脚本，而不是在聊天中嵌入冗长的 Python 示例。安装 SDK 后，这些脚本可通过 PATH 作为控制台脚本使用，也可按下方所示通过 python -m 运行。

• jinko.cli.create_vpop_from_csv：直接上传 CSV，或通过 pandas DataFrame 上传（使用 --method dataframe）。
• jinko.cli.create_vpop_design_from_design：根据唯一 { "id": ..., "distribution": ... } 条目列表创建 vpop 设计，并可在诊断通过后选择生成 vpop。
• jinko.cli.inspect_vpop：检查现有 vpop 的内容、描述或统计信息。
• jinko.cli.edit_vpop_design：按顺序更新或添加描述符；如果后续编辑失败，会报告已应用的 ID，并在成功前运行编辑后的诊断。

示例：

python -m jinko.cli.create_vpop_from_csv --csv skills/jinko-vpop/assets/toy_vpop.csv
python -m jinko.cli.create_vpop_from_csv --csv skills/jinko-vpop/assets/toy_vpop.csv --apply
python -m jinko.cli.create_vpop_from_csv --csv skills/jinko-vpop/assets/toy_vpop.csv --folder 2026-06-15-vpop-study --create-folder --apply
python -m jinko.cli.create_vpop_design_from_design --design skills/jinko-vpop/assets/toy_marginals.json --model-sid cm-... --apply --generate
python -m jinko.cli.inspect_vpop --vpop-sid vp-... --statistics --correlations
python -m jinko.cli.edit_vpop_design --vpop-design-sid vd-... --design skills/jinko-vpop/assets/toy_marginals.json --apply

CSV 上传模式

最简 CSV 格式为每位患者一行：

patientIndex,Dose,k_elim
1,1.0,0.08
2,1.2,0.12

如果 vpop 用于驱动模型，请使用实际组件 ID，而不要使用 age 或 weight 等生物学标签。

边际分布设计模式

在技能资源和脚本中使用边际分布条目列表：

[
  {"id": "Dose", "distribution": {"tag": "Uniform", "lowBound": 0.8, "highBound": 1.2}},
  {"id": "k_elim", "distribution": {"tag": "NormalTruncated", "mean": 0.1, "stdev": 0.02, "lowBound": 0.01, "highBound": 0.3}}
]

该脚本会将此列表转换为 create_vpop_design_from_design(marginal_distributions=...) 所需的 SDK 映射。

对数尺度分布

Agent 经常把描述符的物理最小值和最大值填入 LogUniform 的 lowBound 和 highBound。Jinkō 随后会在 base**min 和 base**max 之间采样。对于 base: 10、范围为 0.001 到 10 的物理值，采样结果约为 1 到 1e10。设计诊断会接受此载荷，因此只有在生成的 Vpop 中才会出现错误。

字段	尺度	物理范围 1e-4 到 1e-2，base: 10
LogUniform lowBound、highBound	log_base(value)	-4、-2
LogNormal、LogNormalTruncated mean、stdev	log_base(value)	中位数为 1e-3：mean: -3
LogNormalTruncated posLowBound、posHighBound	物理值	1e-4、1e-2

按以下顺序编写每个对数尺度载荷：

1. 根据来源，写下描述符单位下的物理范围或中位数。
2. 使用代码计算对数尺度参数，不要手动计算：math.log(value, base)。对于 base: 10，使用 math.log10(value)。小于或等于 0 的物理边界没有对数：请使用正的下界或其他分布。
3. 进行反向换算，并在创建设计前于回复中说明物理结果：“LogUniform(lowBound=-4, highBound=-2, base=10) 采样范围为 1e-4 到 1e-2。”
4. 如果往返换算得出的范围与来源不符，请停止。对数尺度字段中误填了物理值的典型迹象是：参数小于 1，但 lowBound 和 highBound 都为正数。

[
  {"id": "k_on", "distribution": {"tag": "LogUniform", "lowBound": -4, "highBound": -2, "base": 10}},
  {"id": "k_elim", "distribution": {"tag": "LogNormalTruncated", "mean": -1, "stdev": 0.3, "posLowBound": 0.01, "posHighBound": 1, "base": 10}}
]

k_on 条目采样范围为 1e-4 到 1e-2。k_elim 条目的截断前中位数为 0.1，取值范围为 0.01 到 1。

其他 Jinkō 对象使用不同的约定。使用 log_transform=True 的 CMA-ES 校准中，mean 和 std 采用 log10(x)，而 min_bound 和 max_bound 是物理值（jinko-calibration-cmaes）。未经换算，不要在校准先验和 vpop 设计之间复制边界值。

使用对数尺度边际分布生成 Vpop 后，请读回描述符统计数据，并将最小值、最大值和中位数与步骤 1 中的物理范围进行比较：

python -m jinko.cli.inspect_vpop --vpop-sid vp-... --statistics

混合分布

每个 mixture 项都是一个 [weight, distribution] 对。权重是相对权重，不是概率，不必总和为 1：Jinkō 会进行归一化。请使用易于阅读的正整数。对于 2:1 的比例，写 2 和 1，不要写 0.6666667 和 0.3333333。对于已发表的 13.5% 亚组，如果精度足够，可写 27 和 173，或四舍五入为 1 和 6。

{"id": "k_elim", "distribution": {"tag": "Mixture", "mixture": [
  [2, {"tag": "LogNormal", "mean": -1, "stdev": 0.2, "base": 10}],
  [1, {"tag": "LogNormal", "mean": -0.5, "stdev": 0.2, "base": 10}]
]}}

k_elim 条目将三分之二的患者分配到第一个分量。每个分量都遵循各自的尺度规则，包括上述对数尺度规则。

参考资料路由

• 如需了解直接上传 CSV/DataFrame 的详情，请阅读 references/csv-vpop.md。
• 如需了解边际 vpop 设计和生成的详情，请阅读 references/vpop-design.md。
• 添加或更改边际分布形状前，请阅读 assets/distrib.json。