alterlab-opentrons

Opentrons 集成

概览

Opentrons 是一个基于 Python 的实验室自动化平台，适用于 Flex 和 OT-2 机器人。使用 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 的 foundry 开展的蛋白表达/结合检测	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 堆栈器；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 上，启用的磁力模块由无源磁力模块（magneticBlockV1）取代。

各模块的完整代码示例（温度模块、磁力模块与 Flex 磁力块、加热振荡模块、热循环仪 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 套件。