name: instrument-data-to-allotrope description: 将实验室仪器输出文件（PDF、CSV、Excel、TXT）转换为Allotrope Simple Model (ASM) JSON格式或扁平化的2D CSV。当科学家需要为LIMS系统、数据湖或下游分析标准化仪器数据时使用此技能。支持自动检测仪器类型。输出包括完整的ASM JSON、用于轻松导入的扁平化CSV，以及数据工程师可导出的Python代码。常见触发场景包括转换仪器文件、标准化实验室数据、准备数据上传到LIMS/ELN系统，或为生产管道生成解析器代码。

仪器数据到Allotrope转换器

将仪器文件转换为标准化的Allotrope Simple Model (ASM)格式，用于LIMS上传、数据湖或移交数据工程团队。

注意：这是一个示例技能

此技能演示了技能如何支持您的数据工程任务——自动化模式转换、解析仪器输出和生成生产就绪的代码。

为您的组织定制：

修改references/文件以包含您公司的特定模式或本体映射

使用MCP服务器连接到定义您模式的系统（例如，您的LIMS、数据目录或模式注册表）

扩展scripts/以处理专有仪器格式或内部数据标准

此模式可适用于任何需要格式间转换或针对组织标准进行验证的数据转换工作流。

工作流概述

检测仪器类型：从文件内容中自动检测或用户指定
解析文件：使用allotropy库（原生）或灵活的后备解析器
生成输出：
- ASM JSON（完整语义结构）
- 扁平化CSV（2D表格格式）
- Python解析器代码（用于数据工程师移交）
交付：带有摘要和使用说明的文件

当不确定时： 如果不确定如何将字段映射到ASM（例如，这是原始数据还是计算值？设备设置还是环境条件？），请向用户澄清。参考references/field_classification_guide.md获取指导，但当模糊性存在时，与用户确认而不是猜测。

快速开始

# 首先安装要求
pip install allotropy pandas openpyxl pdfplumber --break-system-packages

# 核心转换
from allotropy.parser_factory import Vendor
from allotropy.to_allotrope import allotrope_from_file

# 使用allotropy转换
asm = allotrope_from_file("instrument_data.csv", Vendor.BECKMAN_VI_CELL_BLU)

输出格式选择

ASM JSON（默认） - 带本体URI的完整语义结构

最适合：期望ASM的LIMS系统、数据湖、长期归档
根据Allotrope模式验证

扁平化CSV - 2D表格表示

最适合：快速分析、Excel用户、不支持JSON的系统
每个测量成为一行，元数据重复

两者 - 生成两种格式以获得最大灵活性

计算数据处理

重要： 将原始测量值与计算/衍生值分开。

原始数据 → measurement-document（直接仪器读数）
计算数据 → calculated-data-aggregate-document（衍生值）

计算值必须通过data-source-aggregate-document包含可追溯性：

"calculated-data-aggregate-document": {
  "calculated-data-document": [{
    "calculated-data-identifier": "SAMPLE_B1_DIN_001",
    "calculated-data-name": "DNA完整性数字",
    "calculated-result": {"value": 9.5, "unit": "(unitless)"},
    "data-source-aggregate-document": {
      "data-source-document": [{
        "data-source-identifier": "SAMPLE_B1_MEASUREMENT",
        "data-source-feature": "电泳迹线"
      }]
    }
  }]
}

按仪器类型的常见计算字段：

仪器	计算字段
细胞计数器	存活率%、稀释调整后的细胞密度值
分光光度计	浓度（从吸光度）、260/280比率
平板读取器	来自标准曲线的浓度、%CV
电泳	DIN/RIN、区域浓度、平均大小
qPCR	相对数量、倍数变化

有关原始与计算分类的详细指导，请参见references/field_classification_guide.md。

验证

在交付给用户之前始终验证ASM输出：

python scripts/validate_asm.py output.json
python scripts/validate_asm.py output.json --reference known_good.json  # 与参考比较
python scripts/validate_asm.py output.json --strict  # 将警告视为错误

验证规则：

基于Allotrope ASM规范（2024年12月）
最后更新：2026-01-07
来源：https://gitlab.com/allotrope-public/asm

软验证方法： 未知技术、单位或样本角色生成警告（非错误），以允许向前兼容性。如果Allotrope在2024年12月后添加新值，验证器不会阻止它们——它会标记以进行手动验证。如果需要更严格的验证，使用--strict模式将警告视为错误。

它检查的内容：

正确的技术选择（例如，多分析物分析 vs 平板读取器）
字段命名约定（空格分隔，非连字符）
计算数据具有可追溯性（data-source-aggregate-document）
测量和计算值存在唯一标识符
必需的元数据存在
有效单位和样本角色（对未知值进行软验证）

支持的仪器

完整列表见references/supported_instruments.md。关键仪器：

类别	仪器
细胞计数	Vi-CELL BLU、Vi-CELL XR、NucleoCounter
分光光度法	NanoDrop One/Eight/8000、Lunatic
平板读取器	SoftMax Pro、EnVision、Gen5、CLARIOstar
ELISA	SoftMax Pro、BMG MARS、MSD Workbench
qPCR	QuantStudio、Bio-Rad CFX
色谱法	Empower、Chromeleon

检测与解析策略

层级1：原生allotropy解析（首选）

始终先尝试allotropy。 直接检查可用供应商：

from allotropy.parser_factory import Vendor

# 列出所有支持的供应商
for v in Vendor:
    print(f"{v.name}")

# 常见供应商：
# AGILENT_TAPESTATION_ANALYSIS  （用于TapeStation XML）
# BECKMAN_VI_CELL_BLU
# THERMO_FISHER_NANODROP_EIGHT
# MOLDEV_SOFTMAX_PRO
# APPBIO_QUANTSTUDIO
# ... 许多更多

当用户提供文件时，在回退到手动解析之前检查allotropy是否支持。 scripts/convert_to_asm.py自动检测仅涵盖allotropy供应商的一个子集。

层级2：灵活的后备解析

仅在allotropy不支持该仪器时使用。 此后备：

不生成calculated-data-aggregate-document
不包括完整可追溯性
产生简化的ASM结构

使用灵活解析器：

列名模糊匹配
从标题中提取单位
从文件结构中提取元数据

层级3：PDF提取

对于仅PDF文件，使用pdfplumber提取表格，然后应用层级2解析。

解析前清单

在编写自定义解析器之前，始终：

检查allotropy是否支持 - 如果可用，使用原生解析器
查找参考ASM文件 - 检查references/examples/或询问用户
查看仪器特定指南 - 检查references/instrument_guides/
根据参考验证 - 运行validate_asm.py --reference <file>

要避免的常见错误

错误	正确方法
清单作为对象	使用URL字符串
小写检测类型	使用"Absorbance"而非"absorbance"
“发射波长设置”	对于发射，使用"检测器波长设置"
所有测量在一个文档中	按孔/样本位置分组
缺少程序元数据	提取每个测量的所有设备设置

数据工程师的代码导出

生成科学家可以移交的独立Python脚本：

# 导出解析器代码
python scripts/export_parser.py --input "data.csv" --vendor "VI_CELL_BLU" --output "parser_script.py"

导出的脚本：

除了pandas/allotropy外无外部依赖
包括内联文档
可在Jupyter笔记本中运行
数据管道生产就绪

文件结构

instrument-data-to-allotrope/
├── SKILL.md                          # 此文件
├── scripts/
│   ├── convert_to_asm.py            # 主转换脚本
│   ├── flatten_asm.py               # ASM → 2D CSV转换
│   ├── export_parser.py             # 生成独立解析器代码
│   └── validate_asm.py              # 验证ASM输出质量
└── references/
    ├── supported_instruments.md     # 带Vendor枚举的完整仪器列表
    ├── asm_schema_overview.md       # ASM结构参考
    ├── field_classification_guide.md # 不同字段类型放置位置
    └── flattening_guide.md          # 扁平化工作原理

使用示例

示例1：Vi-CELL BLU文件

用户："将此细胞计数数据转换为Allotrope格式"
[上传 viCell_Results.xlsx]

Claude：
1. 检测Vi-CELL BLU（95%置信度）
2. 使用allotropy原生解析器转换
3. 输出：
   - viCell_Results_asm.json（完整ASM）
   - viCell_Results_flat.csv（2D格式）
   - viCell_parser.py（可导出代码）

示例2：代码移交请求

用户："我需要给我们的数据工程师代码来解析NanoDrop文件"

Claude：
1. 生成自包含的Python脚本
2. 包括示例输入/输出
3. 文档化所有假设
4. 提供Jupyter笔记本版本

示例3：LIMS就绪的扁平化输出

用户："将此ELISA数据转换为可上传到我们LIMS的CSV"

Claude：
1. 解析平板读取器数据
2. 生成带列的扁平化CSV：
   - sample_identifier, well_position, measurement_value, measurement_unit
   - instrument_serial_number, analysis_datetime, assay_type
3. 针对常见LIMS导入要求进行验证

实现说明

安装allotropy

pip install allotropy --break-system-packages

处理解析失败

如果allotropy原生解析失败：

记录错误以调试
回退到灵活解析器
向用户报告元数据完整性降低
建议从仪器导出不同格式

ASM模式验证

当可用时，根据Allotrope模式验证输出：

import jsonschema
# 参考references/asm_schema_overview.md中的模式URL