instrument-data-to-allotrope

機器データから Allotrope 形式への変換

機器ファイルを標準化された Allotrope Simple Model（ASM）形式に変換し、LIMS へのアップロード、データレイクへの保存、またはデータエンジニアリングチームへの引き渡しに利用できます。

注：これはスキルのサンプルです

このスキルでは、スキーマ変換の自動化、機器の出力の解析、本番環境ですぐに使えるコードの生成など、データエンジニアリングタスクにスキルを活用する方法を紹介します。

組織向けにカスタマイズするには：

• references/ ファイルを変更し、自社固有のスキーマやオントロジーのマッピングを追加します
• MCP サーバーを使って、スキーマを定義するシステム（LIMS、データカタログ、スキーマレジストリなど）に接続します
• scripts/ を拡張し、独自の機器形式や社内のデータ標準に対応します

このパターンは、形式間の変換や組織の標準への適合性の検証が必要な、あらゆるデータ変換ワークフローに応用できます。

ワークフローの概要

1. ファイルの内容から機器の種類を検出します（自動検出またはユーザー指定）
2. allotropy ライブラリ（ネイティブ）または柔軟なフォールバックパーサーを使ってファイルを解析します
3. 出力を生成します：
   • ASM JSON（完全なセマンティック構造）
   • フラット化 CSV（2D の表形式）
   • 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 スキーマに対して検証されます

フラット化 CSV - 2D の表形式

• 最適な用途：簡単な分析、Excel ユーザー、JSON に対応していないシステム
• 各測定値が 1 行になり、メタデータが繰り返されます

両方 - 柔軟性を最大限に高めるため、両方の形式を生成します

計算データの取り扱い

重要： 生の測定値と計算値／導出値は分けてください。

• 生データ → 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

ソフト検証方式： 未知の技術、単位、サンプルの役割については、将来との互換性を保つため、エラーではなく警告を生成します。2024 年 12 月以降に Allotrope が新しい値を追加した場合、バリデーターはそれらを拒否せず、手動確認が必要な項目として警告します。より厳密な検証が必要な場合は、--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

検出と解析の戦略

Tier 1：ネイティブの 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 の一部のベンダーのみを対象としています。

Tier 2：柔軟なフォールバック解析

allotropy が機器に対応していない場合にのみ使用してください。 このフォールバックでは：

• calculated-data-aggregate-document は生成されません
• 完全なトレーサビリティは含まれません
• 簡略化された ASM 構造が生成されます

柔軟なパーサーでは以下を使用します：

• 列名のあいまい検索
• ヘッダーからの単位抽出
• ファイル構造からのメタデータ抽出

Tier 3：PDF 抽出

PDF のみのファイルでは、pdfplumber を使用してテーブルを抽出し、その後 Tier 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" を使用します
すべての測定値を1つのドキュメントにまとめる	ウェル／サンプルの位置ごとにグループ化します
手順のメタデータが不足している	測定ごとにすべての機器設定を抽出します

データエンジニア向けのコードエクスポート

研究者が引き継いで使用できる、スタンドアロンの Python スクリプトを生成します：

# Export parser code
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                          # 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