Claudeのbio-researchプラグインで機器データをASM JSONに変換する

instrument-data-to-allotropeは、Anthropicのknowledge-work-pluginsにあるbio-researchプラグインのスキルです。ラボ機器が吐き出すPDF・CSV・Excel・TXTを、Allotrope Simple Model(ASM)のJSON、または1測定1行の平坦なCSVに変換します。LIMSやデータレイクに入れる前の「機器ごとにバラバラな出力を揃える」工程を、Claudeに任せるための仕組みです。

結論から言うと、このスキルの中身はClaudeが自由に整形する作業ではありません。オープンソースのPythonライブラリallotropyを第一選択にした、変換・検証・コード書き出しのスクリプト群です。Claudeは機器の判定とスクリプトの実行を受け持ちます。

bio-researchプラグインの中でのinstrument-data-to-allotropeの位置

bio-researchプラグインは、文献検索やゲノム解析などの前臨床研究向けツールをまとめたものです。READMEには、11のMCPサーバー連携と5つの分析スキルを1つにまとめたと書かれています。5つのスキルのうちの1つがこのスキルです。

READMEの説明では、PDF・CSV・Excel・TXTの機器出力をASMに変換し、細胞カウンター、分光光度計、プレートリーダー、qPCR、クロマトグラフィーなど40以上の機器に対応するとされています。

Claude Codeに入れる手順は、リポジトリ直下のREADMEにある2コマンドです。

claude plugin marketplace add anthropics/knowledge-work-plugins
claude plugin install bio-research@knowledge-work-plugins

bio-researchのREADMEには/install anthropics/knowledge-work-plugins bio-researchという書き方も載っています。2つの書き方が並んでいるため、手元のバージョンで通るほうを使ってください。Coworkなら、claude.com/pluginsから入れます。プラグインの入れ方そのものはマーケットプレイス追加時の注意にまとめています。

変換は三段構えで進む

SKILL.mdは、変換を3つの段階に分けています。どの段階で変換されたかで、出力の情報量が変わります。

違いが出るのは、第2段以降の出力です。SKILL.mdには、フォールバックはcalculated-data-aggregate-documentを作らず、完全なトレーサビリティも持たない簡略化したASM構造になると明記されています。つまり、同じ「ASM JSON」でも、ネイティブパーサーの出力とフォールバックの出力は同格ではありません。

さらにSKILL.mdは、独自のパーサーを書く前に必ずallotropyの対応を確認するよう求めています。同梱のconvert_to_asm.pyが自動判定できるのは、allotropyの対応ベンダーの一部にとどまるとも書かれています。

対応機器をどう確かめるか

references/supported_instruments.mdに、機器ごとのVendor列挙値とファイル形式が表になっています。たとえば次のとおりです。

この表にない機器でも、サンプルID・測定値・単位・日時といった認識できる項目があれば、フォールバックで変換できるとreferencesには書かれています。ただし前節のとおり、情報量は減ります。

ライブラリ側の対応状況は、Pythonで直接確かめられます。SKILL.mdにある書き方は次のとおりです。

pip install allotropy pandas openpyxl pdfplumber --break-system-packages
python -c "from allotropy.parser_factory import Vendor; print([v.name for v in Vendor])"

requirements.txtはバージョンを固定しています。allotropyが0.1.55、pandasが2.0.3、openpyxlが3.1.2、pdfplumberが0.9.0です。ファイルのコメントによると、同じ入力から同じASMが出るようにするための固定で、固定した日付は2025-01-05と記されています。最新のallotropyを入れると、対応機器や出力が変わる可能性があるため、再現性を優先するなら固定版を使います。

コマンドラインで変換から検証まで通す

スキルを使わず、スクリプトを直接動かすこともできます。convert_to_asm.pyの引数は次のとおりです。

python scripts/convert_to_asm.py viCell_Results.csv \
  --vendor BECKMAN_VI_CELL_BLU --flatten
python scripts/validate_asm.py viCell_Results_asm.json --strict

ここで押さえたいのは、自動判定の挙動です。--vendorを省くと機器を推定し、その信頼度が30%未満ならエラーで止まります。30%以上60%未満なら警告を出して止まり、--forceを付けた場合だけ先へ進みます。誤判定のままASMを作ってしまうことを、スクリプト側で防いでいる形です。

--vendorを指定した場合の信頼度は100として扱われ、この判定は行われません。機器が分かっているなら、指定したほうが確実です。

計算値と生の測定値を分ける

このスキルがもっとも強く求めているのは、生データと計算値の区別です。SKILL.mdは、直接の機器読み取り値をmeasurement-documentに、導出値をcalculated-data-aggregate-documentに入れるよう定めています。

計算値には、元データへの参照(data-source-aggregate-document)が必須です。機器別の計算値の例として、SKILL.mdは次を挙げています。

• 細胞カウンター: 生存率、希釈補正後の細胞密度
• 分光光度計: 吸光度からの濃度、260/280比
• プレートリーダー: 標準曲線からの濃度、%CV
• 電気泳動: DINやRIN、領域ごとの濃度、平均サイズ
• qPCR: 相対定量値、倍率変化

迷う項目は、推測せずユーザーに確認するようSKILL.mdが指示しています。生データか計算値か、装置設定か環境条件かが曖昧なときの判断基準は、references/field_classification_guide.mdにまとまっています。たとえば、機種名やシリアル番号のように実行ごとに変わらないものはdevice-system-document、ソフトウェア名やファイル名はdata-system-document、サンプルIDやウェル位置はsample-documentという振り分けです。

検証スクリプトが見る項目

validate_asm.pyは、変換結果を渡す前に必ず通すようSKILL.mdが求めている検証です。確認する項目は次のとおりです。

• 技術(technique)の選択が正しいか。たとえば、マルチアナライト測定とプレートリーダーの取り違え
• 項目名の表記規則。ハイフンではなくスペース区切り
• 計算値にトレーサビリティがあるか
• 測定値と計算値に一意の識別子があるか
• 必須のメタデータがあるか
• 単位とサンプルの役割が妥当か

検証ルールの基準はAllotrope ASM仕様の2024年12月版で、スクリプト内の最終更新は2026-01-07と書かれています。未知の技術・単位・役割は、エラーではなく警告になります。仕様が更新されても新しい値を弾かないためですが、警告を見逃したくない場合は--strictで警告をエラー扱いにできます。--referenceに既知の正解ファイルを渡せば、出力との比較もできます。

平坦CSVとコードの書き出し

ASMは階層構造のため、LIMSへの取り込みや表計算には向きません。flatten_asm.pyは1測定を1行にし、メタデータを各行に繰り返します。列名はsnake_caseで、たとえばviable-cell-densityはviable_cell_density、単位は_unitが付く列になります。

平坦化の対象は、技術ごとの集約ドキュメントの内側です。flattening_guide.mdによれば、$asm.manifestのようなスキーマのバージョン情報は意図的に落とされます。監査や規制対応でスキーマのバージョンを追う必要があるなら、元のASM JSONを平坦CSVと一緒に保管するか、スクリプトを改造します。

データエンジニアへの引き継ぎ用には、export_parser.pyが単体で動くPythonスクリプトかノートブックを書き出します。

python scripts/export_parser.py --list-vendors
python scripts/export_parser.py --vendor BECKMAN_VI_CELL_BLU \
  --output parser_script.py

ドキュメントと実装でずれている点

スクリプトを読むと、SKILL.mdの説明と実装で食い違う箇所がいくつかあります。そのまま写すとつまずくため、先に挙げておきます。

• コード書き出しの例: SKILL.mdの例は--vendor "VI_CELL_BLU"ですが、export_parser.pyが持つ機器表のキーはBECKMAN_VI_CELL_BLUです。表にない名前を渡すと、機器名や技術が汎用の値で埋まります。--list-vendorsで表のキーを確かめてから指定します。
• 平坦CSVのファイル名: SKILL.mdの例はviCell_Results_flat.csvですが、flatten_asm.pyの既定の出力名は.flat.csvです。名前を固定したい場合は-oで指定します。
• 位置づけ: SKILL.mdの冒頭に「Example Skill」と書かれています。組織のスキーマや独自フォーマットに合わせてreferences/とscripts/を直す前提の見本で、そのまま本番のパイプラインに載せる完成品とは位置づけられていません。

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

冒頭の注記は、カスタマイズの方向を3つ示しています。references/に自社のスキーマやオントロジーのマッピングを足す。LIMS、データカタログ、スキーマレジストリを定義するシステムにMCPサーバーでつなぐ。scripts/を拡張して、社内独自の機器フォーマットを扱う。

同じ型の作り込みは、data-context-extractorのように、会社固有の知識をスキルに落とす別のスキルでも見られます。機器の出力形式が社内で決まっているなら、references/に参照用のASMファイルを置いておくと、SKILL.mdの事前確認(参照ASMを探してvalidate_asm.py --referenceで比較する)がそのまま効きます。

使い始める前の確認

使い始める前に見ておく点を、読者の状況別に挙げます。

• 機器がネイティブ対応の一覧にある: --vendorを明示し、--strictで検証します。出力は最も情報量が多い形になります。
• 一覧にない機器・PDFだけ: フォールバックになるため、計算値とトレーサビリティが欠けます。可能なら、機器側で別形式のエクスポートを選べないか確認するのが、SKILL.mdの勧めです。
• LIMSに直接入れたい: 平坦CSVの列が取り込み先の要件に合うかは、スキルが保証しません。取り込み前に列名と単位を突き合わせます。
• 機器データをクラウドに出せない: 変換自体はローカルのPythonで動きますが、Claudeにファイルの内容を読ませるかどうかは、自組織の情報管理ルールで判断します。