实验室仪器数据转换：快速入门

欢迎开始使用实验室仪器数据转换工具！本指南将帮助你在 5 分钟内完成第一次数据转换。

前置准备

检查你的环境

在开始之前，确保你的电脑上已经安装了 Python（版本 3.8 或更高）。

打开终端（Terminal）或命令提示符，输入：

python --version

如果显示 Python 版本号，说明已经安装。如果没有，请先安装 Python。

安装依赖包

打开终端，输入以下命令安装所需的 Python 包：

pip install allotropy pandas openpyxl pdfplumber --break-system-packages

这个命令会安装以下包：

allotropy：核心转换库，支持多种仪器格式
pandas：数据处理库
openpyxl：Excel 文件读取
pdfplumber：PDF 文件解析

安装过程可能需要 1-2 分钟，请耐心等待。

你的第一个转换任务

假设你有一个来自 Beckman Vi-CELL BLU 细胞计数仪的 Excel 文件，名为 viCell_data.xlsx，你想将它转换为 Allotrope 格式。

步骤 1：准备你的数据文件

将你的仪器数据文件放在一个容易找到的位置，比如桌面的 data 文件夹。

~/Desktop/data/viCell_data.xlsx

步骤 2：运行转换脚本

使用工具提供的转换脚本：

python scripts/convert_to_asm.py ~/Desktop/data/viCell_data.xlsx

工具会自动：

检测仪器类型（Vi-CELL BLU）
解析文件内容
生成 ASM JSON 文件
生成扁平化 CSV 文件

步骤 3：查看输出结果

转换完成后，工具会在原文件所在的目录生成以下文件：

~/Desktop/data/
├── viCell_data.xlsx           # 原始文件
├── viCell_data_asm.json       # ASM JSON 格式（完整语义结构）
└── viCell_data_flat.csv       # 扁平化 CSV（可在 Excel 中打开）

步骤 4：验证输出结果

使用验证脚本检查生成的 ASM 文件是否符合标准：

python scripts/validate_asm.py ~/Desktop/data/viCell_data_asm.json

如果一切正常，你会看到"验证通过"的提示。

查看转换结果

打开 CSV 文件（推荐新手）

直接用 Excel 打开 viCell_data_flat.csv，你会看到一个整洁的表格：

sample_identifier	total_value	viable_value	viability_percent	unit
SAMPLE_A1	1.5	1.4	93.3	cells/mL
SAMPLE_A2	1.8	1.7	94.4	cells/mL

这种格式直观易懂，适合快速查看和简单分析。

查看 JSON 文件（高级用户）

用文本编辑器打开 viCell_data_asm.json，你会看到完整的 Allotrope 数据结构：

{
  "measurement-document": {
    "file-analyte-measurement-document": [
      {
        "measurement-identifier": "SAMPLE_A1_MEASUREMENT",
        "sample-identifier": "SAMPLE_A1",
        "measurement-result": {
          "cell-concentration": {
            "value": 1.5,
            "unit": "cells/mL"
          }
        }
      }
    ]
  }
}

这种格式包含完整的元数据和语义信息，适合系统对接和长期存储。

常见问题排查

问题 1：安装失败

症状：pip install 命令报错

解决方法：

确保有网络连接
尝试升级 pip：pip install --upgrade pip
如果权限问题，去掉 --break-system-packages 选项

问题 2：无法检测仪器类型

症状：工具提示"无法自动检测仪器类型"

解决方法：

手动指定仪器类型：

python scripts/convert_to_asm.py your_file.xlsx --vendor VI_CELL_BLU

查看支持的仪器列表确认你的仪器是否在列

问题 3：转换失败

症状：工具报错"解析失败"

解决方法：

检查文件是否损坏，尝试用原始软件打开查看
尝试从仪器导出不同格式（如 CSV 而非 PDF）
查看错误日志获取更多细节

下一步学习

恭喜你完成了第一次数据转换！现在你可以：

了解更多功能：阅读功能详解，了解工具的所有能力
查看实际案例：阅读应用场景，看看其他用户如何使用这个工具
深入了解原理：阅读工作原理，理解工具的技术架构

快速参考卡片

┌─────────────────────────────────────────┐
│  常用命令快速参考                        │
├─────────────────────────────────────────┤
│  转换文件：                               │
│  python scripts/convert_to_asm.py 文件名 │
│                                         │
│  验证输出：                               │
│  python scripts/validate_asm.py 文件名   │
│                                         │
│  扁平化 JSON：                           │
│  python scripts/flatten_asm.py JSON文件  │
│                                         │
│  导出代码：                               │
│  python scripts/export_parser.py 文件名  │
└─────────────────────────────────────────┘

继续探索吧！