alterlab-pylabrobot

PyLabRobot

概述

PyLabRobot（PLR）是一个与硬件无关的实验室自动化 Python SDK。每种设备都由一个前端（LiquidHandler、PlateReader、HeaterShaker，等等）和一个针对特定仪器的后端组成，因此，只需替换一行后端代码，同一份协议代码就能在模拟器、Hamilton STAR 或 Opentrons OT-2 上运行。所有设备调用都是 async，必须在事件循环中等待完成（asyncio.run(main())，或直接在 Jupyter 单元格中运行）。

何时使用此技能

• 使用 Python 为 Hamilton STAR/STARlet/Vantage、Tecan EVO 或 Opentrons OT-2 编写或调试液体处理协议
• 在操作硬件前模拟协议（chatterbox 后端、吸头/体积跟踪、浏览器可视化工具）
• 定义载台布局：载架、吸头架、板、储液槽、试管和自定义实验器材
• 将酶标仪、加热振荡器、培养箱、离心机、泵、天平或热循环仪整合到同一工作流中
• 将协议从一种机器人厂商的平台移植到另一种

不适用场景

场景	改用
使用官方 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"] 是包含一个元素的列表；plate["A1:H1"] 是第 1 列，plate["A1:A12"] 是 A 行。要获取单个对象（例如访问 .tracker），请使用 plate.get_well("A1") 或 tip_rack.get_item("A1")。
• 体积以列表表示。 单个通道使用 vols=[100]，八个通道使用 vols=[100] * 8；每通道选项（flow_rates、liquid_height、blow_out_air_volume）也使用列表。
• 吸头。 使用 pick_up_tips(spots) 拾取吸头，然后调用 discard_tips()（丢弃）、return_tips()（放回吸头架）或 drop_tips(spots)（指定位置——没有默认位置）。
• transfer 是一对多操作。 lh.transfer(source.get_well("A1"), dest["A1:H1"], target_vols=[50] * 8) 只吸液一次，然后用 0 号通道的吸头向每个目标分液。source_vol= 是总体积，会在各目标之间分配（平均分配或按 ratios 分配），而不是每个目标的体积。
• 实验器材名称。 使用当前的小写工厂函数（cor_96_wellplate_360uL_Fb）；Cor_96_wellplate_360ul_Fb 等首字母大写的旧名称会发出警告，并将被移除。
• 始终在 finally: 中调用 stop()，以便在发生错误后释放 USB/串行连接。

常见工作流

一对多分液和系列稀释

# 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(...)]]	需要单个孔位时传入了列表（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 套件的一部分。