alterlab-pylabrobot

PyLabRobot

概要

PyLabRobot（PLR）は、ラボの自動化向けのハードウェアに依存しない Python SDK です。各デバイスはフロントエンド（LiquidHandler、PlateReader、HeaterShaker など）と、特定の装置向けのバックエンドで構成されるため、バックエンドを1行切り替えるだけで、同じプロトコルコードをシミュレーター、Hamilton STAR、Opentrons OT-2 のいずれでも実行できます。デバイスの呼び出しはすべてasyncで、イベントループ内でawaitする必要があります（asyncio.run(main())を使用するか、Jupyter のセルから直接実行します）。

このスキルを使用する場面

• Hamilton STAR／STARlet／Vantage、Tecan EVO、Opentrons OT-2 向けの液体ハンドリングプロトコルを Python で作成またはデバッグするとき
• ハードウェアに触れる前にプロトコルをシミュレーションするとき（chatterbox バックエンド、チップ／容量の追跡、ブラウザーのビジュアライザー）
• デッキのレイアウトを定義するとき：キャリア、チップラック、プレート、トラフ、チューブ、カスタムラボウェア
• プレートリーダー、ヒーターシェーカー、インキュベーター、遠心分離機、ポンプ、電子天秤、サーマルサイクラーを1つのワークフローに統合するとき
• あるロボットベンダー向けのプロトコルを別のベンダー向けに移植するとき

該当しない場面

場面	代わりに使用
公式の Opentrons Python API（apiLevel、opentrons_simulate）を使用して Opentrons OT-2／Flex プロトコルを作成する	alterlab-opentrons
自分のロボットを実行する代わりに、リモートのクラウドラボに作業を依頼する	alterlab-ginkgo-cloud
Adaptyv Bio のファウンドリーにタンパク質結合／発現アッセイを注文する	alterlab-adaptyv
DOI 付きの人が読めるプロトコルを探す、作成する、または公開する	alterlab-protocolsio

主な機能

分野	内容	リファレンス
液体ハンドリング	aspirate、dispense、transfer、チップ、マルチチャンネル移動、段階希釈、エラー処理	references/liquid-handling.md
リソース	デッキ、キャリア、プレート、チップラック、トラフ、インデックス付け、追跡、レイアウトの保存、カスタムラボウェア	references/resources.md
ハードウェアバックエンド	STAR、Vantage、EVO、OT-2、chatterbox、バックエンドの切り替え	references/hardware-backends.md
分析機器	プレートリーダー（CLARIOstar、BioTek、SpectraMax、Byonoy）、電子天秤	references/analytical-equipment.md
マテリアルハンドリング	ヒーターシェーカー、温度コントローラー、インキュベーター、遠心分離機、ポンプ、サーマルサイクラー	references/material-handling.md
可視化	ブラウザーのビジュアライザー、シミュレーションを活用したテスト	references/visualization.md

クイックスタート（シミュレーション）

import asyncio

from pylabrobot.liquid_handling import LiquidHandler
from pylabrobot.liquid_handling.backends import LiquidHandlerChatterboxBackend  # STARBackend() on a real STAR
from pylabrobot.resources import (
    PLT_CAR_L5AC_A00,                   # plate carrier (5 sites)
    STARLetDeck,
    TIP_CAR_480_A00,                    # tip carrier (5 sites)
    cor_96_wellplate_360uL_Fb,
    hamilton_96_tiprack_1000uL_filter,
    set_tip_tracking,
    set_volume_tracking,
)


async def main():
    set_tip_tracking(True)      # catch missing tips and over-aspiration in simulation
    set_volume_tracking(True)

    lh = LiquidHandler(backend=LiquidHandlerChatterboxBackend(), deck=STARLetDeck())
    await lh.setup()
    try:
        # Labware goes into carrier sites; carriers go on deck rails.
        tip_car = TIP_CAR_480_A00(name="tip_carrier")
        tip_car[0] = tip_rack = hamilton_96_tiprack_1000uL_filter(name="tips_01")
        lh.deck.assign_child_resource(tip_car, rails=3)

        plt_car = PLT_CAR_L5AC_A00(name="plate_carrier")
        plt_car[0] = source = cor_96_wellplate_360uL_Fb(name="source")
        plt_car[1] = dest = cor_96_wellplate_360uL_Fb(name="dest")
        lh.deck.assign_child_resource(plt_car, rails=15)

        for well in source.get_all_items():
            well.tracker.set_liquids([(None, 300)])

        # 8-channel column copy: "A1:H1" is column 1 (8 wells), one tip per channel
        await lh.pick_up_tips(tip_rack["A1:H1"])
        await lh.aspirate(source["A1:H1"], vols=[100] * 8)
        await lh.dispense(dest["A1:H1"], vols=[100] * 8)
        await lh.discard_tips()         # to the deck's trash; return_tips() puts them back

        print(dest.get_well("A1").tracker.get_used_volume())  # 100.0
    finally:
        await lh.stop()


asyncio.run(main())

ハードウェアで実行するには、バックエンド（STARBackend()、VantageBackend()、EVOBackend()、OpentronsOT2Backend(host="<robot IP>")）とデッキ（STARDeck()、VantageDeck(size=1.3)、EVO150Deck()、OTDeck()）を置き換えます。デッキの位置を除き、プロトコル本体はそのままです。

ほとんどのエラーを防ぐ API ルール

• インデックス付けの戻り値はリストです。 plate["A1"]は1要素のリストです。plate["A1:H1"]は1列目、plate["A1:A12"]はA行です。単一のオブジェクト（たとえば.trackerへのアクセス）が必要な場合は、plate.get_well("A1")またはtip_rack.get_item("A1")を使用します。
• 容量はリストで指定します。 1チャンネルの場合はvols=[100]、8チャンネルの場合はvols=[100] * 8です。チャンネルごとのオプション（flow_rates、liquid_height、blow_out_air_volume）もリストで指定します。
• チップ。 pick_up_tips(spots)でチップをピックアップし、その後discard_tips()（廃棄）、return_tips()（ラックに戻す）、またはdrop_tips(spots)（明示した位置にドロップ。デフォルト値はありません）を実行します。
• transferは1対多です。 lh.transfer(source.get_well("A1"), dest["A1:H1"], target_vols=[50] * 8)は1回吸引し、チャンネル0のチップを使って各ターゲットに分注します。source_vol=は合計容量で、ターゲット間で（均等に、またはratiosに従って）分割されます。ターゲットごとの容量ではありません。
• ラボウェアの名前。 現行の小文字のファクトリー（cor_96_wellplate_360uL_Fb）を使用してください。Cor_96_wellplate_360ul_Fbのような大文字始まりの旧名は警告が表示され、削除される予定です。
• 必ずfinally:でstop()を実行してください。 エラー発生後に USB／シリアル接続を解放できます。

よくあるワークフロー

1対多の分注と段階希釈

# 50 uL of diluent into each of A2..A5 from one source well (single channel)
await lh.pick_up_tips(tip_rack["A2"])
await lh.transfer(source.get_well("H12"), dest["A2:A5"], target_vols=[50] * 4)
await lh.discard_tips()

# 2-fold dilution along row A (A1 -> A5): move 50 uL to the next well and mix
await lh.pick_up_tips(tip_rack["A3"])
for col in range(1, 5):
    await lh.aspirate(dest[f"A{col}"], vols=[50])
    await lh.dispense(dest[f"A{col + 1}"], vols=[50])
    for _ in range(3):  # mix
        await lh.aspirate(dest[f"A{col + 1}"], vols=[40])
        await lh.dispense(dest[f"A{col + 1}"], vols=[40])
await lh.discard_tips()

プレートの読み取り

from pylabrobot.plate_reading import CLARIOstarBackend, PlateReader

reader = PlateReader(name="clariostar", size_x=0, size_y=0, size_z=0,
                     backend=CLARIOstarBackend())   # needs pylabrobot[ftdi]
await reader.setup()
await reader.open()
reader.assign_child_resource(dest)                   # or move the plate there with the robot's gripper
await reader.close()
result = await reader.read_absorbance(wavelength=450, use_new_return_type=True)
od450 = result[0]["data"]                            # 8 x 12 nested list
await reader.stop()

PlateReader に温度設定メソッドはありません。加熱に対応したリーダーでは、バックエンドで温度を設定できます（たとえば、BioTek および Molecular Devices のバックエンドでは await reader.backend.set_temperature(37) を実行します）。ほかのリーダーやスケールについては、references/analytical-equipment.md を参照してください。

ベストプラクティス

1. まずシミュレーションします。 チップと液量の追跡を有効にした LiquidHandlerChatterboxBackend でプロトコル全体を実行し、最初の実機での実行前に Visualizer で動作を確認します。
2. 実機でドライランを行います。 最初の実機での実行では、水を使うか液体を使わず、液量を減らして実施し、停止ボタンにすぐ手が届くようにしておきます。
3. レイアウトはファイルに保存します。 lh.deck.save("deck.json") でデッキを保存し、プロトコルと一緒にコミットして、pylabrobot のバージョンを記録します。
4. ラボウェアの定義を確認します。 吸引高さを信頼する前に、カスタムまたは使用頻度の低いラボウェアの形状を確認します。
5. 時間のかかる装置は早めに開始します。 加熱やインキュベーターの設定温度に達するまで数分かかるため、その間に液体ハンドリングを行います。
6. 公式ドキュメント。 https://docs.pylabrobot.org （ユーザーガイドと API）、https://github.com/PyLabRobot/pylabrobot、フォーラム https://discuss.pylabrobot.org。

トラブルシューティング

症状	考えられる原因
TypeError: Resources must be Containers, got [[Well(...)]]	1 つのウェルが必要な箇所（transfer のソース）にリストが渡されています。plate.get_well("A1") を使用してください
TypeError: drop_tips() missing ... 'tip_spots'	discard_tips() を使うか、スポットを明示的に指定してください
トラッキング有効時の NoTipError / HasTipError	プロトコルでチップスポットを再利用しているか、チップを保持したままピックアップしています。チップの管理を確認してください
RuntimeError: ... is not installed. Install with: pip install pylabrobot[...]	メッセージに記載された接続用エクストラをインストールしてください
pylabrobot.temperature_control、pylabrobot.incubation、Trough_100ml に対する ImportError	古い名称です。0.2.2 のモジュールとラボウェアについては、references/material-handling.md および references/resources.md を参照してください

AlterLab Academic Skills スイートの一部です。