SuperAPI AI 工具集

jinko-data-table

数据与分析

查看项目

更新于 10-16 02:33

技能介绍

用途:该技能用于通过 jinko-sdk 处理 Jinkō 数据表,适合需要上传观测数据以支持试验叠加(trial overlays)或校准目标(calibration objectives)的场景。数据表行结构相同,元数据可用时会报告适应度函数兼容性。

前置条件:需要已初始化的 jinko-sdk 连接,且 SDK 版本满足其 metadata.requires_sdk 范围。先运行 jinko-sdk-setup 技能(../jinko-sdk-setup/SKILL.md),检查通过后再继续。会话码只能交换一次,因此在本技能自身 SDK 进程前需再次调用 get_session_code。若未找到该技能,可从 novainsilico/jinko-skills 安装。

主要能力:使用 client.create_data_table_from_csv() 处理 CSV 文件或字节;client.create_data_table_from_sqlite() 处理 SQLite 文件或字节;client.create_data_table_from_dataframe() 处理 pandas DataFrame。用 get_data_table()、content()、summary()、validate()、export() 检查已有数据表。创建或检查后,若数据表需通过 trial/calibration 的 dataTableDesigns 附加,可检查 metadata.public.validForFitnessFunction。通过 jinko-trial 附加数据表的试验流程应使用 validForFitnessFunction: True 的数据表;点值叠加表可能上传成功但试验启动健全性检查失败。

项目文件夹规范:建议在专用 Jinkō 文件夹内创建数据表,而非项目根目录。工作流开始时询问或提议文件夹名,例如 YYYY-MM-DD-<experiment-name>。尽量复用精确匹配的已有文件夹:client.get_folder_by_name(name, exact_match_only=True)。若文件夹不存在,仅在用户确认或脚本以 --apply 运行时创建。解析出一个文件夹对象或 id,然后传给支持 folder 参数的 SDK 创建调用。

行结构:修改 CSV 结构前先读 assets/data-table.json。支持点值行(obsId、time、value,可选 unit、armScope、ranges、weight、reference)和范围行(obsId、time、narrowRangeLowBound、narrowRangeHighBound,可选 unit、armScope、宽范围、weight、reference)。time 使用 ISO-8601 时长字符串,如 PT0S、PT6H、P1D。

附带资源:assets/toy_data_table_values.csv 为点值观测;assets/toy_data_table_ranges.csv 为范围观测;assets/data-table.json 为支持行的模式子集。

SDK 脚本:安装 SDK 后作为控制台脚本位于 PATH,也可用 python -m 运行。jinko.cli.create_data_table 会试运行校验每行 CSV,并以 --apply 创建数据表;可用 --allowed-obs-id、--require-unit、--require-experiment-ref、--require-fitness 约束校准输入。jinko.cli.inspect_data_table 检查已有数据表,可用 --require-fitness 强制适应度兼容。示例:python -m jinko.cli.create_data_table --source skills/jinko-data-table/assets/toy_data_table_ranges.csv --method csv;python -m jinko.cli.create_data_table --source extracted.csv --allowed-obs-id Drug --require-unit --require-experiment-ref --require-fitness --apply;python -m jinko.cli.create_data_table --source skills/jinko-data-table/assets/toy_data_table_ranges.csv --method csv --apply;python -m jinko.cli.create_data_table --source skills/jinko-data-table/assets/toy_data_table_ranges.csv --method csv --folder 2026-06-15-fit-data --create-folder --apply;python -m jinko.cli.create_data_table --source skills/jinko-data-table/assets/toy_data_table_values.csv --method dataframe --apply;python -m jinko.cli.inspect_data_table --data-table-sid dt-... --fitness --validate。

参考路由:行结构与适应度函数说明见 references/data-table-schema.md;检查必需列时读 assets/data-table.json。

限制:依赖 jinko-sdk 连接与版本范围;会话码仅能交换一次;点值叠加表可能不满足试验启动健全性检查;文件夹创建需确认或 --apply。