import pylabrobot
print(pylabrobot.__version__) # 0.2.2The PyLabRobot Cookbook
Liquid handling, resource definition, and lab automation in Python
A task-indexed manual for PyLabRobot 0.2.2. Broad coverage of the everyday surface, then two guided builds: define your own labware, and write your own liquid handler backend.
A task-indexed manual for PyLabRobot 0.2.2.
0.1 Introduction to PyLabRobot
PyLabRobot is an open-source, hardware-agnostic Python interface to liquid-handling robots and other lab automation instruments. PyLabRobot allows for unlimited flexibility and productivity in programming lab automation far beyond what is possible in proprietary interfaces. This cookbook is intended to give new users an easy way to learn and get started in lab automation. Even if you don’t know Python at all, you may be surprised at how quickly you pick up this material.
0.2 What is this Cookbook For?
This cookbook is meant to explain some basic patterns and workflow compositions that can help you write PyLabRobot code. The principles of logic and orchestration extend beyond PyLabRobot, but PyLabRobot is arguably one of the most efficient ways of implementing these patterns in the world of lab automation. In fact, many labs spend thousands of dollars on software and consultants to address the same problems we take on succinctly in this book.
PyLabRobot is meant primarily to communicate with physical instruments, but we don’t cover details of physical process implementation in this book, and the lessons are written for simulation alongside the visualizer. We expect that the logic of process design and orchestration will be broadly useful across different platforms, which is enabled by the platform-agnostic nature of PyLabRobot code.
Given that this cookbook explains how to control powerful and potentially dangerous machines, the reader acknowledges that it is their responsibility to operate these machines only after recieving appropriate training. PyLabRobot, like any other automation interface, acts on a model of the world that may not be fully accurate and depends on the user’s own measurements and instrument calibration. The user must ensure that their instruments are fully calibrated before running a protocol.
0.3 Why PyLabRobot?
PyLabRobot is popular in lab automation for several reasons. Most interfaces to automation hardware are built on deprecated frameworks such as ActiveX and have little to no public documentation. Companies even charge their customers money for software interfaces to hardware they already own. This has resulted in a highly fractured and inefficient software ecosystem for lab automation. Tasks that would seem basic in a normal software context often require paying a great deal of money in lab automation because of the highly idiosyncratic nature of the software.
PyLabRobot overcomes these myriad difficulties by building the interface layer from the ground up on the basis of good software design and open source contributions. This has resulted in a highly scalable and comprehensible architecture that many find to be far easier to use than the tools of the proprietary ecosystem. This is unsurprising given how effective open source collaboration is in the world of software development - almost all of the most widely used software products in the world today are open source.
0.4 How to read this
- Recipe index — every recipe in the book, indexed by task and searchable by the API it uses.
- Cheat sheet — flat lookup: function, signature, one line.
- Parts I–II — broad coverage of PLR’s everyday surface. Read straight through once.
- Part III — the cross-cutting concerns: logging, run data, SQLite state, decorators, simulation.
- Part IV — two guided builds, start to finish, every step given.
0.5 Everything here runs without a robot
Every snippet executes against LiquidHandlerChatterboxBackend, which simulates a liquid handler by narrating what it would do. Nothing in Parts I–III needs hardware.
ImportantThis book targets 0.2.2 specifically
PLR changes across minor versions, sometimes by deleting things. Liquid identity tracking and the cross-contamination tracker were removed before 0.2.2; the main branch has since moved the entire liquid handling stack under pylabrobot.legacy as part of the v1b1 migration.
Recipes are written and executed against 0.2.2. Pin it:
pip install "pylabrobot==0.2.2"