jinko-trial-viz

Jinkō 试验可视化工作流

将此技能用于 TrialVisualization 项目事项：为试验创建可视化、配置绘图区段、检索已存储的可视化载荷，以及运行可视化健全性检查。

试验执行、结果下载和计算所得的绘图数据（trial.results.aggregate_*）请留在 jinko-trial 中；不要仅为了读取数据而创建可视化。请在试验已存在且用户需要 Jinkō 可视化产物或其绘图配置后使用此技能。

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

核心工作流

1. 确定试验：trial = client.get_trial(trial_sid)。
2. 在获得用户明确确认后，创建一个绑定到该试验的空可视化：viz = trial.create_empty_trial_visualization(folder=..., name=..., description=...)。
3. 确定所需的绘图区段，并通过相应的类型化子服务配置每个区段：
   • 时间序列输出使用 viz.timeseries。
   • 标量结果分布和中心位置图使用 viz.scalars。
   • X 对 X 的试验组或 X 对 Y 的变量使用 viz.scatter_plots。
   • 生存分析可视化使用 viz.survival_analysis。
   • 龙卷风式敏感性／贡献视图使用 viz.contribution_analysis。
   • 需要显示观测数据或患者级数据时使用 viz.data_overlay / viz.patients_overlay。
   • 范围限定和分组使用 viz.filters / viz.groups。
   • 顶层选项使用 viz.set_selected_arms(...)、viz.set_equate_baseline(...)、viz.set_time_unit(...)。
4. 每次创建或更新后运行并打印 viz.sanity。如果报告错误，则返回失败并修复可视化。
5. 可随时再次调用区段的 setter 重新配置区段（例如 viz.timeseries.set_selectors([...])）——每次调用只会修补该区段。

SDK 接口

• trial.create_empty_trial_visualization(folder=, name=, description=, version=) 和 trial.create_trial_visualization_from_json(data, ...) — 创建绑定到试验的可视化。
• client.list_trial_visualizations(...)、client.iter_trial_visualizations(...)、client.get_trial_visualization(sid) — 查询元数据。
• viz.content(revision=...) — 完整的类型化内容；viz.sanity / viz.sanity_at(revision, only=[...]) — 诊断（.errors()、.warnings()、.has_errors()、.for_field(...)、.by_field()）。
• 区段子服务均提供 get() / clear() 以及区段专用的 setter：viz.timeseries.set_selectors(...) / add_selectors(...)、viz.scalars.set_selectors(...) / add_selectors(...)、viz.survival_analysis.set_selectors(...) / set_observation_window_from_start_until_end(...) / set_observation_window_from_start_until_time(...) / set_confidence_interval(...)、viz.contribution_analysis.set_selectors(...) / set_quantile(...) / set_input_baseline_only(...) / set_all_baseline(...) / set_custom_baseline(...)、viz.scatter_plots.add_x_vs_x_plot(...) / add_x_vs_y_plot(...) / set_config(...) / set_regression(...)、viz.data_overlay.add_table(...) / set_tables(...) / set_ranges_enabled(...)、viz.filters.add_numeric(...) / add_categorical(...) / add_patient_list(...)、viz.groups.set_group_by_arm(...) / add_scalar_*_grouping(...) / add_categorical_grouping(...)。

各子服务的完整示例请参阅 references/trial-viz-typed-api.md。

SDK 脚本

使用该脚本，通过类型化 API 执行可重复的创建、更新、获取、列出和健全性检查操作。 安装 SDK 后，该脚本会作为控制台脚本出现在 PATH 中，也可按下方所示通过 python -m 运行。

python -m jinko.cli.trial_viz list --limit 20
python -m jinko.cli.trial_viz create --trial-sid tr-... --name "My trial viz" --timeseries Drug --scalar AUC
python -m jinko.cli.trial_viz create --trial-sid tr-... --name "My trial viz" --timeseries Drug --scalar AUC --apply
python -m jinko.cli.trial_viz get --trial-viz-sid tv-... --output-file viz.content.json
python -m jinko.cli.trial_viz update --trial-viz-sid tv-... --scatter-xvsy "AUC,Cmax,control,treated" --apply
python -m jinko.cli.trial_viz sanity --trial-viz-sid tv-... --only timeseries --only scatterPlots

如需配置散点图、叠加、筛选或分组等脚本标志之外的功能，请直接在 Python 中使用类型化子服务（参见 references/trial-viz-typed-api.md）。

项目文件夹规范

• 优先在与试验相同的文件夹或专用分析文件夹中创建试验可视化。
• 通过脚本的 --folder 传入文件夹 ID 或准确的文件夹名称，或者直接在 create_empty_trial_visualization(...) 中设置 folder=folder。
• 如果无法解析明确指定的文件夹，应将其视为错误；切勿静默地在项目根目录中创建可视化。
• 如果用户想在同一分析中添加其他图表，请复用现有的试验可视化；调用相应分区的 setter，而不是创建重复项。

参考资料导航

• 阅读 references/trial-viz-typed-api.md，了解类型化子服务 API。

输出要求

创建或修改可视化时，请报告：

• TrialVisualization SID、核心项目 ID、快照 ID、修订版本（如有）以及 URL（如有）。
• 创建或修补的绘图分区。
• 任何健全性错误或警告，并保留后端字段名称，以便直接进行下一步修复。

检索可视化时，如果用户需要检查、比较差异或复用绘图设置，请返回或保存完整的 JSON 内容。