实验室仪器数据转换：功能详解

本工具像一个万能翻译器，能听懂各种仪器的"语言"，并将它们翻译成统一的"标准语"。下面详细介绍它的各项能力。

核心功能

1. 自动仪器识别

它能做什么：你不需要告诉工具这是什么仪器的数据，它会自动识别。

工作原理：工具通过分析文件的结构、列名、数据模式等特征，智能判断仪器类型。

支持识别的线索：

• 文件扩展名（.xlsx、.csv、.pdf）
• 文件内的列名模式（如 "Cell Viability"、"Absorbance"）
• 数据的数值范围和格式
• 特定厂商的文件结构

准确率：常见仪器的识别准确率在 95% 以上。

示例：

输入：viCell_results.xlsx
自动识别：Beckman Vi-CELL BLU（置信度 95%）

2. 多格式解析

支持的输入格式：

• Excel（.xlsx、.xls）
• CSV（.csv）
• PDF（.pdf）
• 文本文件（.txt）

解析策略：

第一优先级：使用 allotropy 原生解析器
    ↓
第二优先级：使用灵活回退解析器
    ↓
第三优先级：PDF 表格提取 + 回退解析器

为什么需要分层策略？

• 原生解析器：处理厂商专用格式，提取最完整的元数据
• 回退解析器：处理非标准格式，确保数据不会"卡住"
• PDF 提取：当数据只能以 PDF 形式获取时使用

3. 双模式输出

模式 A：ASM JSON（完整语义结构）

适合场景：

• 上传到 LIMS 系统
• 存入数据湖长期保存
• 需要完整可追溯性
• 与其他系统对接

特点：

• 包含完整的 Allotrope 本体信息
• 每个字段都有标准化的 URI
• 区分原始数据和计算数据
• 包含所有仪器设置和环境条件

数据结构示例：

{
  "measurement-document": {
    "measurement-identifier": "SAMPLE_001",
    "instrument-identifier": "VI-CELL-001",
    "measurement-time": "YYYY-MM-DDThh:mm:ssZ",
    "device-setting": [
      {"setting-type": "total-volume", "value": 0.5, "unit": "mL"}
    ],
    "measurement-result": {
      "cell-concentration": {
        "value": 1.5,
        "unit": "cells/mL"
      }
    }
  }
}

模式 B：扁平化 CSV（二维表格）

适合场景：

• 快速查看数据
• 在 Excel 中分析
• 导入到不支持 JSON 的系统
• 制作报告和图表

特点：

• 每个测量结果占一行
• 元数据列会重复
• 列名清晰易懂
• 可直接在 Excel 中打开

数据结构示例：

sample_identifier,total_value,viable_value,viability_percent,unit
SAMPLE_001,1.5,1.4,93.3,cells/mL
SAMPLE_002,1.8,1.7,94.4,cells/mL

4. 智能数据分类

问题：仪器输出的一些数据是测量值，一些是计算值。如何区分？

工具的解决方案：

• 原始数据（measurement-document）：直接从仪器读取的数值
• 计算数据（calculated-data-aggregate-document）：经过公式计算的结果

为什么要区分？

• 可追溯性：计算数据需要记录数据来源
• 验证需求：原始数据和计算数据的验证标准不同
• 复现性：明确知道每个值的来源

示例：

计算数据会包含追溯信息：

"calculated-data-aggregate-document": {
  "calculated-data-document": [{
    "calculated-data-name": "viability_percent",
    "calculated-result": {"value": 93.3, "unit": "%"},
    "data-source-aggregate-document": {
      "data-source-document": [{
        "data-source-identifier": "total_cell_count",
        "data-source-identifier": "viable_cell_count"
      }]
    }
  }]
}

5. 数据验证

验证内容：

• ✓ 仪器类型是否正确
• ✓ 字段命名是否符合规范（空格分隔，不用连字符）
• ✓ 单位是否有效
• ✓ 计算数据是否有追溯信息
• ✓ 必需的元数据是否存在

软验证模式（默认）：

• 未知的单位或技术会生成警告，不会阻止转换
• 允许 Allotrope 标准更新后的新值
• 适合日常使用，不会因为标准更新而失败

严格验证模式：

python scripts/validate_asm.py output.json --strict

• 所有警告都视为错误
• 适合生产环境或质量要求高的场景

6. 代码导出

功能：生成独立的 Python 脚本，可以重复使用或交给数据工程师。

使用场景：

• 需要定期转换相同格式的文件
• 想将转换流程集成到自动化管道
• 需要与其他系统对接

生成命令：

python scripts/export_parser.py \
  --input "data.csv" \
  --vendor "VI_CELL_BLU" \
  --output "parser_script.py"

生成的脚本特点：

• 不依赖外部文件（自包含）
• 包含详细的注释
• 可以在 Jupyter Notebook 中运行
• 生产环境可用

7. 批量处理

场景：你有 100 个仪器文件需要转换。

方法：

# 使用 shell 脚本批量处理
for file in data/*.xlsx; do
  python scripts/convert_to_asm.py "$file"
done

优势：

• 一次设置，批量转换
• 不需要为每个文件手动操作
• 保证转换的一致性

支持的仪器类型

工具支持大量仪器，这里列出最常见的几类：

细胞计数仪

• Beckman Vi-CELL BLU
• Beckman Vi-CELL XR
• ChemoMetec NucleoCounter

分光光度计

• Thermo NanoDrop One/Eight/8000
• Unchained Labs Lunatic

酶标仪

• Molecular Devices SoftMax Pro
• PerkinElmer EnVision
• BioTek Gen5
• BMG CLARIOstar

电泳系统

• Agilent TapeStation
• Agilent BioAnalyzer

qPCR 仪

• Applied Biosystems QuantStudio
• Bio-Rad CFX

液相色谱仪

• Waters Empower
• Thermo Chromeleon

完整列表请参考 references/supported_instruments.md。

功能对比表

下一步

了解功能后，你可以：

1. 查看应用场景，看看其他用户如何使用这些功能
2. 阅读工作原理，理解工具的技术细节