alterlab-opentrons

Opentrons 連携

概要

Opentrons は、Flex および OT-2 ロボット向けの Python ベースのラボ自動化プラットフォームです。液体ハンドリング用の Protocol API v2 プロトコルを作成し、ハードウェアモジュール（ヒーターシェーカー、サーモサイクラー）を制御し、ラボウェアを管理して、ピペッティングのワークフローを自動化します。

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

次のような場合に、このスキルを使用します。

• Python で Opentrons Protocol API v2 プロトコルを作成する
• Flex または OT-2 ロボットで液体ハンドリングのワークフローを自動化する
• ハードウェアモジュール（温度、磁気、ヒーターシェーカー、サーモサイクラー）を制御する
• ラボウェアの構成とデッキレイアウトを設定する
• 複雑なピペッティング操作（段階希釈、プレート複製、PCR セットアップ）を実装する
• チップの使用を管理し、プロトコルの効率を最適化する
• 96 ウェルプレートの操作にマルチチャンネルピペットを使用する
• ロボットで実行する前にプロトコルをシミュレーションしてテストする

対象外

シナリオ	代わりに使用
Hamilton／Tecan の液体ハンドラー、プレートリーダー、または複数ベンダーの機器を動かす単一のスクリプト	alterlab-pylabrobot
リモートクラウドラボ（Ginkgo Cloud Lab RACs）に実験を送信する	alterlab-ginkgo-cloud
Adaptyv Bio のファウンドリーで実行するタンパク質発現／結合アッセイ	alterlab-adaptyv
作成したウェットラボプロトコルを DOI 付きで公開する	alterlab-protocolsio

主な機能

1. プロトコルの構造とメタデータ

Opentrons のプロトコルはすべて、標準的な構造に従います。

from opentrons import protocol_api

# Metadata (descriptive only here; apiLevel lives in requirements)
metadata = {
    'protocolName': 'My Protocol',
    'author': 'Name <[email protected]>',
    'description': 'Protocol description',
}

# apiLevel goes in exactly ONE of metadata/requirements: opentrons rejects a protocol
# that sets it in both. robotType is required for Flex protocols.
requirements = {
    'robotType': 'Flex',  # or 'OT-2'
    'apiLevel': '2.22'    # lowest level that has every feature you use (see below)
}

# Run function
def run(protocol: protocol_api.ProtocolContext):
    trash = protocol.load_trash_bin('A3')  # Flex: load a trash bin (or waste chute) before any drop_tip
    # Protocol commands go here

主な要素：

• opentrons から protocol_api をインポートします
• metadata には名前／作成者／説明を、requirements には robotType と apiLevel を指定します
• ProtocolContext を受け取る run() を実装します。プロトコルのロジックはすべてその中に記述します
• Flex プロトコル（API 2.16 以降）では固定のトラッシュがありません。protocol.load_trash_bin(slot) または protocol.load_waste_chute() を先に呼び出してください。呼び出さないと drop_tip() が NoTrashDefinedError で失敗します

apiLevel の選び方： 最新は 2.29 です（Flex ロボットソフトウェア 9.1.1 以降。opentrons 9.1.x パッケージはこのバージョンまでシミュレーションできます）。主な最低バージョンは次のとおりです。2.16 はトラッシュビン／廃棄シュートのローダー、2.20 は液体有無の検出、2.21 は吸光プレートリーダー、2.22 は Labware.load_liquid()／load_empty()、2.24 は液体クラス（transfer_with_liquid_class）、2.25 は Flex Stacker、2.27 はモジュールコマンドの同時実行です。古いロボットでもプロトコルを実行できるよう、必要な機能をカバーする最低のレベルを使用し、opentrons_simulate で確認してください。

2. ハードウェアの読み込み

インストゥルメント（ピペット）の読み込み：

def run(protocol: protocol_api.ProtocolContext):
    # Load pipette on specific mount
    left_pipette = protocol.load_instrument(
        'flex_1channel_1000',  # Instrument name (Flex convention)
        'left',                # Mount: 'left' or 'right'
        tip_racks=[tip_rack]   # List of tip rack labware objects
    )

一般的なピペットのロード名（これらは正確な instrument_name 文字列です。p1000_single_flex のような名前を独自に作らないでください。Flex では flex_<channels>_<volume> の形式を使用します）：

• Flex：flex_1channel_50、flex_1channel_1000、flex_8channel_50、flex_8channel_1000、flex_96channel_1000
• OT-2：p20_single_gen2、p300_single_gen2、p1000_single_gen2、p20_multi_gen2、p300_multi_gen2

ラボウェアの読み込み：

# Load labware directly on deck
plate = protocol.load_labware(
    'corning_96_wellplate_360ul_flat',  # Labware API name
    'D1',                                # Deck slot (Flex: A1-D3, OT-2: 1-11)
    label='Sample Plate'                 # Optional display label
)

# Load tip rack
tip_rack = protocol.load_labware('opentrons_flex_96_tiprack_1000ul', 'C1')

# Load labware on adapter
adapter = protocol.load_adapter('opentrons_flex_96_tiprack_adapter', 'B1')
tips = adapter.load_labware('opentrons_flex_96_tiprack_200ul')

モジュールの読み込み：

# Temperature module (Flex + OT-2)
temp_module = protocol.load_module('temperature module gen2', 'D3')
temp_plate = temp_module.load_labware('corning_96_wellplate_360ul_flat')

# Heater-Shaker module (Flex + OT-2)
hs_module = protocol.load_module('heaterShakerModuleV1', 'D1')
hs_plate = hs_module.load_labware('corning_96_wellplate_360ul_flat')

# Thermocycler module (takes up specific slots automatically)
tc_module = protocol.load_module('thermocyclerModuleV2')
tc_plate = tc_module.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')

# Magnetic Module (OT-2 ONLY) — an active, motorized module. Flex does not
# support it; on Flex use the unpowered Magnetic Block instead (see below).
mag_module = protocol.load_module('magnetic module gen2', '1')  # OT-2 numeric slot
mag_plate = mag_module.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')

# Magnetic Block (Flex ONLY) — unpowered; labware is moved on/off it with the
# Gripper. There is no engage/disengage; it has no motors.
mag_block = protocol.load_module('magneticBlockV1', 'C2')
block_plate = mag_block.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')

3. 液体ハンドリング操作

基本操作：

# Pick up tip
pipette.pick_up_tip()

# Aspirate (draw liquid in)
pipette.aspirate(
    volume=100,           # Volume in µL
    location=source['A1'] # Well or location object
)

# Dispense (expel liquid)
pipette.dispense(
    volume=100,
    location=dest['B1']
)

# Drop tip
pipette.drop_tip()

# Return tip to rack
pipette.return_tip()

複雑な操作：

# Transfer (combines pick_up, aspirate, dispense, drop_tip)
pipette.transfer(
    volume=100,
    source=source_plate['A1'],
    dest=dest_plate['B1'],
    new_tip='always'  # 'always', 'once', or 'never'
)

# Distribute (one source to multiple destinations)
pipette.distribute(
    volume=50,
    source=reservoir['A1'],
    dest=[plate['A1'], plate['A2'], plate['A3']],
    new_tip='once'
)

# Consolidate (multiple sources to one destination)
pipette.consolidate(
    volume=50,
    source=[plate['A1'], plate['A2'], plate['A3']],
    dest=reservoir['A1'],
    new_tip='once'
)

高度な手法：

# Mix (aspirate and dispense in same location)
pipette.mix(
    repetitions=3,
    volume=50,
    location=plate['A1']
)

# Air gap (prevent dripping)
pipette.aspirate(100, source['A1'])
pipette.air_gap(20)  # 20µL air gap
pipette.dispense(120, dest['A1'])

# Blow out (expel remaining liquid)
pipette.blow_out(location=dest['A1'].top())

# Touch tip (remove droplets on tip exterior)
pipette.touch_tip(location=plate['A1'])

流量制御：

# Set flow rates (µL/s)
pipette.flow_rate.aspirate = 150
pipette.flow_rate.dispense = 300
pipette.flow_rate.blow_out = 400

4. ウェルと位置へのアクセス

ウェルへのアクセス方法：

# By name
well_a1 = plate['A1']

# By index
first_well = plate.wells()[0]

# All wells
all_wells = plate.wells()  # Returns list

# By rows
rows = plate.rows()  # Returns list of lists
row_a = plate.rows()[0]  # All wells in row A

# By columns
columns = plate.columns()  # Returns list of lists
column_1 = plate.columns()[0]  # All wells in column 1

# Wells by name (dictionary)
wells_dict = plate.wells_by_name()  # {'A1': Well, 'A2': Well, ...}

位置の指定方法：

# Passing a Well aspirates 1 mm above its bottom by default
pipette.aspirate(100, well)

# top()/bottom() are exact: z=0 is the top rim / the well bottom itself
pipette.dispense(100, well.top())        # at the rim
pipette.aspirate(100, well.top(z=-2))    # 2 mm below the rim
pipette.aspirate(100, well.bottom(z=2))  # 2 mm above the bottom (z=0 would touch it)

# Center of well
pipette.aspirate(100, well.center())

5. ハードウェアモジュールの制御

温度、磁気、ヒーターシェーカー、サーモサイクラー、吸光プレートリーダーの各モジュールを制御します。各モジュールコンテキストには、独自の設定／待機／停止メソッドと状態プロパティが用意されています（例：temp_module.set_temperature、hs_module.set_and_wait_for_shake_speed、tc_module.execute_profile）。Flex では、通電式の磁気モジュールの代わりに、非通電式の Magnetic Block（magneticBlockV1）を使用します。

モジュールごとのコード例（温度、Magnetic Module と Flex Magnetic Block の比較、ヒーターシェーカー、サーモサイクラーによる PCR サイクル、吸光プレートリーダー）については、references/hardware_modules.md を参照してください。対応するメソッド／プロパティの一覧は references/api_reference.md にあります。

6. 液体の追跡とラベリング

液体を定義する：

# Define liquid types
water = protocol.define_liquid(
    name='Water',
    description='Ultrapure water',
    display_color='#0000FF'  # Hex color code
)

sample = protocol.define_liquid(
    name='Sample',
    description='Cell lysate sample',
    display_color='#FF0000'
)

ウェルに液体をロードする（API 2.22以降）：

# Mark starting contents per labware (volumes in µL)
reservoir.load_liquid(wells=['A1'], volume=50000, liquid=water)
plate.load_liquid(wells=['A1', 'A2'], volume=100, liquid=sample)
plate.load_liquid_by_well({'A3': 50, 'A4': 75}, liquid=sample)

# Mark wells as empty
plate.load_empty(['B1', 'B2'])

Well.load_liquid(liquid, volume)も引き続き使用できますが、2.22以降では非推奨です。Well.load_empty()はありません。

7. プロトコル制御とユーティリティ

実行制御：

# Pause protocol
protocol.pause(msg='Replace tip box and resume')

# Delay
protocol.delay(seconds=60)
protocol.delay(minutes=5)

# Comment (appears in logs)
protocol.comment('Starting serial dilution')

# Home robot
protocol.home()

条件分岐：

# Check if simulating
if protocol.is_simulating():
    protocol.comment('Running in simulation mode')
else:
    protocol.comment('Running on actual robot')

レールライト（OT-2およびFlex、API 2.5以降）：

# Turn lights on
protocol.set_rail_lights(on=True)

# Turn lights off
protocol.set_rail_lights(on=False)

8. マルチチャンネルおよび8チャンネルのピペッティング

マルチチャンネルピペットを使用する場合：

# Load 8-channel pipette
multi_pipette = protocol.load_instrument(
    'p300_multi_gen2',
    'left',
    tip_racks=[tips]
)

# Access entire column with single well reference
multi_pipette.transfer(
    volume=100,
    source=source_plate['A1'],  # Accesses entire column 1
    dest=dest_plate['A1']       # Dispenses to entire column 1
)

# Column-wise with an 8-channel: target the row-A well of each column
for column_top in plate.rows()[0]:        # A1, A2, ... A12
    multi_pipette.transfer(100, reservoir['A1'], column_top)

8チャンネルピペットでは、行Aのウェルのみを指定してください。B1～H1を指定すると、ほかのノズルがプレートから外れてしまいます。

9. よく使われるプロトコルパターン

再利用可能なエンドツーエンドのテンプレートで、最も一般的なワークフローをカバーします。段階希釈（希釈液の分注と、行全体での混合後の連続分注）、プレートの複製（プレート全体のwells()からwells()へのコピー）、PCRのセットアップ（マスターミックスの分注、サンプルごとの移送、サーモサイクラーでのサイクリング）などがあります。

各パターンの詳しい実行例プロトコルについては、references/protocol_patterns.mdを参照してください。実行可能な.py版は（scripts/ディレクトリ内にあります（serial_dilution_template.py、basic_protocol_template.py、pcr_setup_template.py）。

ベストプラクティス

1. APIレベルを必ず指定する：使用する機能をサポートし、ロボットのソフトウェアで受け入れられる最も低いapiLevelを指定します（opentrons_simulateで確認してください）
2. わかりやすいラベルを使用する：ログで識別しやすいようにラボウェアにラベルを付けます
3. チップの残数を確認する：プロトコルの完了に十分なチップがあることを確認します
4. コメントを追加する：デバッグとログ記録にはprotocol.comment()を使用します
5. 最初にシミュレーションする：ロボットで実行する前に、必ずシミュレーションでプロトコルをテストします
6. エラーに適切に対処する：必要に応じて、手動での対応のために一時停止を追加します
7. 所要時間を考慮する：プロトコルにインキュベーション時間が必要な場合は、遅延を使用します
8. 液体を追跡する：セットアップの検証精度を高めるため、液体追跡を使用します
9. チップの使用を最適化する：適切な場合はnew_tip='once'を使用して、チップを節約します
10. 流量を調整する：粘性の高い液体や揮発性の液体には、流量を調整します

トラブルシューティング

よくある問題：

• チップ切れ：チップラックの容量がプロトコルの要件を満たしていることを確認します
• ラボウェアの衝突：デッキの配置に空間的な干渉がないか確認します
• 容量エラー：容量がウェルまたはピペットの容量を超えていないことを確認します
• モジュールが応答しない：モジュールが正しく接続され、ファームウェアが更新されていることを確認します
• 容量が不正確：ピペットを校正し、気泡がないか確認します
• シミュレーションでプロトコルが失敗する：APIバージョンとの互換性とラボウェアの定義を確認します

リソース

APIドキュメントの詳細については、このスキルディレクトリ内のreferences/api_reference.mdを参照してください。

プロトコルテンプレートの例については、scripts/ディレクトリを参照してください。

AlterLab Academic Skills suiteの一部です。