instrument-data-to-allotrope

仪器数据转 Allotrope 格式转换器

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

注意：这是一个示例 Skill

本 Skill 演示了 Skill 如何支持您的数据工程任务，包括自动化 schema 转换、解析仪器输出，以及生成可用于生产环境的代码。

如需为您的组织进行定制：

• 修改 references/ 文件，加入贵公司特定的 schema 或本体映射
• 使用 MCP 服务连接定义 schema 的系统（例如您的 LIMS、数据目录或 schema 注册中心）
• 扩展 scripts/，以处理专有仪器格式或内部数据标准

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

工作流概览

1. 从文件内容检测仪器类型（自动检测或由用户指定）
2. 解析文件：使用 allotropy 库（原生）或灵活的回退解析器
3. 生成输出：
   • ASM JSON（完整语义结构）
   • 扁平化 CSV（二维表格格式）
   • Python 解析器代码（用于数据工程师交接）
4. 交付文件，并附上摘要和使用说明

存在不确定性时： 如果您不确定某个字段应如何映射到 ASM（例如，它是原始数据还是计算值？是设备设置还是环境条件？），请向用户询问以作澄清。可参考 references/field_classification_guide.md 获取指导，但若仍存在歧义，应与用户确认，而非凭猜测处理。

快速开始

# Install requirements first
pip install allotropy pandas openpyxl pdfplumber --break-system-packages

# Core conversion
from allotropy.parser_factory import Vendor
from allotropy.to_allotrope import allotrope_from_file

# Convert with allotropy
asm = allotrope_from_file("instrument_data.csv", Vendor.BECKMAN_VI_CELL_BLU)

输出格式选择

ASM JSON（默认）：包含本体 URI 的完整语义结构

• 适用于：要求 ASM 格式的 LIMS 系统、数据湖、长期归档
• 可对照 Allotrope schema 进行校验

扁平化 CSV：二维表格表示

• 适用于：快速分析、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 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	相对定量、倍数变化

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

校验

在将结果交付给用户之前，务必先校验 ASM 输出：

python scripts/validate_asm.py output.json
python scripts/validate_asm.py output.json --reference known_good.json  # Compare to reference
python scripts/validate_asm.py output.json --strict  # Treat warnings as errors

校验规则：

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

软校验方式： 未知的技术、单位或样品角色会生成警告（而非错误），以保证前向兼容性。若 Allotrope 在 2024 年 12 月之后新增了取值，校验器不会阻止这些取值，而是会将其标记出来，供人工核实。如需更严格的校验，可使用 --strict 模式，将警告视为错误处理。

校验内容包括：

• 技术选择是否正确（例如多分析物分析与酶标仪）
• 字段命名规范（以空格分隔，而非连字符）
• 计算数据是否具备可追溯性（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

检测与解析策略

第一层:allotropy 原生解析(优先)

始终优先尝试 allotropy。 直接检查可用的厂商:

from allotropy.parser_factory import Vendor

# List all supported vendors
for v in Vendor:
    print(f"{v.name}")

# Common vendors:
# AGILENT_TAPESTATION_ANALYSIS  (for TapeStation XML)
# BECKMAN_VI_CELL_BLU
# THERMO_FISHER_NANODROP_EIGHT
# MOLDEV_SOFTMAX_PRO
# APPBIO_QUANTSTUDIO
# ... many more

当用户提供文件时,在回退到手动解析之前,先检查 allotropy 是否支持该文件。 scripts/convert_to_asm.py 的自动检测仅覆盖 allotropy 厂商的一部分。

第二层:灵活回退解析

仅当 allotropy 不支持该仪器时使用。 该回退方案:

• 不生成 calculated-data-aggregate-document
• 不包含完整的可追溯性信息
• 生成简化的 ASM 结构

使用灵活解析器时:

• 进行列名模糊匹配
• 从表头中提取单位
• 从文件结构中提取元数据

第三层:PDF 提取

对于仅有 PDF 的文件,使用 pdfplumber 提取表格,然后应用第二层解析。

解析前检查清单

在编写自定义解析器之前,务必:

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 脚本,供科研人员交付使用:

# Export parser code
python scripts/export_parser.py --input "data.csv" --vendor "VI_CELL_BLU" --output "parser_script.py"

导出的脚本:

• 除 pandas/allotropy 外无其他外部依赖
• 包含内联文档
• 可在 Jupyter notebook 中运行
• 可直接用于数据管道的生产环境

文件结构

instrument-data-to-allotrope/
├── SKILL.md                          # This file
├── scripts/
│   ├── convert_to_asm.py            # Main conversion script
│   ├── flatten_asm.py               # ASM → 2D CSV conversion
│   ├── export_parser.py             # Generate standalone parser code
│   └── validate_asm.py              # Validate ASM output quality
└── references/
    ├── supported_instruments.md     # Full instrument list with Vendor enums
    ├── asm_schema_overview.md       # ASM structure reference
    ├── field_classification_guide.md # Where to put different field types
    └── flattening_guide.md          # How flattening works

使用示例

示例 1:Vi-CELL BLU 文件

User: "Convert this cell counting data to Allotrope format"
[uploads viCell_Results.xlsx]

Claude:
1. Detects Vi-CELL BLU (95% confidence)
2. Converts using allotropy native parser
3. Outputs:
   - viCell_Results_asm.json (full ASM)
   - viCell_Results_flat.csv (2D format)
   - viCell_parser.py (exportable code)

示例 2:请求交付代码

User: "I need to give our data engineer code to parse NanoDrop files"

Claude:
1. Generates self-contained Python script
2. Includes sample input/output
3. Documents all assumptions
4. Provides Jupyter notebook version

示例 3:可直接用于 LIMS 的扁平化输出

User: "Convert this ELISA data to a CSV I can upload to our LIMS"

Claude:
1. Parses plate reader data
2. Generates flattened CSV with columns:
   - sample_identifier, well_position, measurement_value, measurement_unit
   - instrument_serial_number, analysis_datetime, assay_type
3. Validates against common LIMS import requirements

实现说明

安装 allotropy

pip install allotropy --break-system-packages

处理解析失败

如果 allotropy 原生解析失败:

1. 记录错误信息以便调试
2. 回退到灵活解析器
3. 向用户报告元数据完整性降低的情况
4. 建议从仪器导出其他格式

ASM 架构验证

在可用时,依据 Allotrope 架构验证输出:

import jsonschema
# Schema URLs in references/asm_schema_overview.md