仪器数据转换至 Allotrope 格式

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

注意：这是示例技能

本技能演示了技能如何支持你的数据工程任务——自动化模式转换、解析仪器输出并生成可用于生产的代码。

针对你的组织进行自定义：

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

工作流概览

  1. 检测仪器类型 从文件内容（自动检测或用户指定）
  2. 解析文件 使用 allotropy 库（原生）或灵活的备用解析器
  3. 生成输出：
  4. 交付 文件，附带摘要和使用说明

不确定时： 如果你不确定如何将字段映射到 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

扁平化 CSV - 2D 表格表示

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

计算数据处理

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

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

"calculated-data-aggregate-document": {
  "calculated-data-document": [{
    "calculated-data-identifier": "SAMPLE_B1_DIN_001",
    "calculated-data-name": "DNA integrity number",
    "calculated-result": {"value": 9.5, "unit": "(unitless)"},
    "data-source-aggregate-document": {
      "data-source-document": [{
        "data-source-identifier": "SAMPLE_B1_MEASUREMENT",
        "data-source-feature": "electrophoresis trace"
      }]
    }
  }]
}

按仪器类型的常见计算字段： | 仪器 | 计算字段 | |------------|-------------------| | 细胞计数器 | 存活率 %、细胞密度稀释调整值 | | 分光光度计 | 浓度（来自吸光度）、260/280 比值 | | 酶标仪 | 来自标准曲线的浓度、%CV | | 电泳 | DIN/RIN、区域浓度、平均尺寸 | | qPCR | 相对定量、倍数变化 |

有关原始 vs 计算分类的详细指导，请参见 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 在 2024 年 12 月之后添加新值，验证器不会阻止它们——它会标记以进行手动验证。如果需要更严格的验证，使用 --strict 模式将警告视为错误。

检查内容：

支持的仪器

完整列表请参见 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 不支持该仪器时使用。 此备用方案：

使用灵活解析器：

第 3 层：PDF 提取

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

解析前检查清单

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

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

需要避免的常见错误

错误 正确方法
Manifest 作为对象 使用 URL 字符串
小写检测类型 使用 "Absorbance" 而不是 "absorbance"
"emission wavelength setting" 发射使用 "detector wavelength setting"
所有测量在一个文档中 按孔/样品位置分组
缺少程序元数据 提取每个测量的所有设备设置

面向数据工程师的代码导出

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

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

导出的脚本：

文件结构

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 notebook 版本

示例 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 原生解析失败：

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

ASM 模式验证

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

import jsonschema
# 模式 URL 在 references/asm_schema_overview.md 中