SuperAPI AI 工具集

tooluniverse-lab-data-standardization

数据与分析

查看项目

更新于 10-19 04:11

技能介绍

实验室仪器数据标准化

该技能用于把实验室仪器的原始输出文件转换为标准化、结构化的格式,并在输出中区分原始测量值与计算/派生值,同时保留显式可追溯性,便于上传至 LIMS/ELN、数据湖或进行下游分析。

适用场景:当用户需要将酶标仪、分光光度计(如 NanoDrop)、qPCR 仪、细胞计数仪、色谱仪等仪器的导出文件(CSV、TSV、XLSX 或可提取文本的 PDF 表格)转换为标准化结构化格式;需要在 LIMS 或数据湖上传前分离原始仪器读数与计算/派生值并保留追溯关系;需要获得 ASM 风格文档的扁平化二维 CSV 版本以便表格导入;或需要验证生成的 JSON 文档结构是否健全(可追溯性、数值、无重复 ID)。不适用于通用表格清洗/重塑(应使用 tooluniverse-data-wrangling)、FASTQ 质控(tooluniverse-fastq-qc)、VCF/变异文件(tooluniverse-variant-analysis)、蛋白质组原始文件(mzML、RAW,tooluniverse-proteomics-analysis)或单细胞矩阵(h5ad、10X,tooluniverse-single-cell)。

双层转换策略:Tier 1(native)在已安装 allotropy 且文件匹配受支持供应商时启用,使用真实的 allotropy 库生成认证 ASM 输出,输出标记为 tier: "native";Tier 2(fallback)在 allotropy 缺失或供应商无法识别时启用,使用技能自带的通用表格解析器(仅依赖 pandas/openpyxl/pdfplumber 等已声明的 ToolUniverse 依赖),输出标记为 tier: "fallback" 并附带说明。allotropy 是可选依赖,不属于 ToolUniverse 声明的包依赖,脚本在运行时通过 try: import allotropy 检测,缺失时不会报错,而是打印安装命令并使用 Tier 2。

工作流程:1)识别输入文件(CSV/TSV/XLSX/PDF),对于 Excel 还需确定工作表;2)运行转换脚本:python scripts/convert_instrument_data.py <input_file> --output-dir <out_dir>,脚本会自动检测层级(若已安装 allotropy 且给定或可推断 --vendor 则优先尝试 native,否则自动使用回退解析器),并在输出目录写入 <stem>_asm.json 和 <stem>_flat.csv;3)阅读控制台输出,确认实际运行的层级以及找到的测量值/计算值数量,零测量值会作为警告而非静默成功;4)验证输出:python scripts/validate_output.py <out_dir>/<stem>_asm.json,或使用 --strict 将每个警告升级为失败;5)按需重新扁平化:python scripts/flatten_to_csv.py <out_dir>/<stem>_asm.json -o <path>.csv,该脚本仅支持 tier: "fallback" 文档;6)报告实际运行的层级、测量/计算值计数、验证器警告/错误以及输出文件位置,绝不报告工具未实际产生的值。

选项参考(convert_instrument_data.py):--output-dir 指定输出目录(默认 <input_dir>/<stem>_asm_results);--sheet 指定 Excel 工作表名称/索引(仅 xlsx);--vendor 强制指定 Tier 1 的 allotropy 供应商名称;--force-fallback 即使安装了 allotropy 也跳过 Tier 1(用于测试/一致性);--format {json,csv,both} 指定输出格式(默认 both)。

诚实契约:绝不伪造数值,输出 JSON/CSV 中的每个数字必须直接来自源文件,无法找到或无法确信解析的值将被省略而非猜测;绝不声称产生了未实际生成的认证 ASM 输出,Tier 2 输出始终标记为 fallback 并附说明,不冒充认证转换;可追溯性优先,回退解析器仅当能在同一行中识别至少一个原始列作为指向对象时,才将值归类为计算值;依赖缺失时明确说明,若未安装 allotropy,打印 pip install allotropy 指令并继续使用回退层级,不假装 Tier 1 已运行。

参考资料:references/schema_overview.md 描述 JSON 文档结构和字段规则;references/supported_instruments.md 说明 Tier 1 与 Tier 2 实际解析的内容以及如何枚举已安装的 allotropy 供应商列表;references/field_classification_guide.md 提供原始值与计算值的启发式规则,并附常见仪器类型计算字段表。