VilhelmKMoller
diff --git a/Diff for: ‎.github/img/logo.png
457 KB b/Diff for: ‎.github/img/logo.png
457 KB
diff --git a/Diff for: ‎.github/workflows/lint.yml
+5-1 b/Diff for: ‎.github/workflows/lint.yml
+5-1
diff --git a/Diff for: ‎.github/workflows/test.yml
+5-1 b/Diff for: ‎.github/workflows/test.yml
+5-1
diff --git a/Diff for: ‎.github/workflows/typecheck.yml
+5-1 b/Diff for: ‎.github/workflows/typecheck.yml
+5-1
diff --git a/Diff for: ‎.gitignore
+3-3 b/Diff for: ‎.gitignore
+3-3
diff --git a/Diff for: ‎.pylintrc
+2-1 b/Diff for: ‎.pylintrc
+2-1
diff --git a/Diff for: ‎.vscode/settings.json
+3 b/Diff for: ‎.vscode/settings.json
+3
diff --git a/Diff for: ‎CHANGELOG.md
+47 b/Diff for: ‎CHANGELOG.md
+47
diff --git a/Diff for: ‎CONTRIBUTING.md
+2-2 b/Diff for: ‎CONTRIBUTING.md
+2-2
diff --git a/Diff for: ‎Makefile
+7-1 b/Diff for: ‎Makefile
+7-1
diff --git a/Diff for: ‎README.md
+104-27 b/Diff for: ‎README.md
+104-27
diff --git a/Diff for: ‎docs/_static/logo.png
364 KB b/Diff for: ‎docs/_static/logo.png
364 KB
diff --git a/Diff for: ‎docs/_templates/autosummary/class.rst
+2-2 b/Diff for: ‎docs/_templates/autosummary/class.rst
+2-2
@@ -1,6 +1,10 @@
 name: Linting
 
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - main
+  pull_request:
 
 jobs:
   lint:
 
@@ -1,6 +1,10 @@
 name: Unit Tests
 
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - main
+  pull_request:
 
 jobs:
   test:
 
@@ -1,6 +1,10 @@
 name: Type checking
 
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - main
+  pull_request:
 
 jobs:
   typecheck:
 
@@ -2,12 +2,12 @@
 *__pycache__
 *.DS_store
 *.swp
+*.swo
 build/pdf-intermediate.md
 pyhamilton/LAY-BACKUP
 .ipynb_checkpoints
 *.egg-info
 *.log
 build/lib
-venv/
-venv/*
-venv\
+
+myenv
@@ -148,7 +148,8 @@ disable=abstract-method,
         zip-builtin-not-iterating,
         missing-module-docstring,  # added
         missing-function-docstring,  # added
-        C0103  # added, invalid module name
+        C0103,  # added, invalid module name
+        too-many-positional-arguments, # backends take many arguments
 
 
 [REPORTS]
 
@@ -5,8 +5,11 @@
     "agrow",
     "agrowpumps",
     "coro",
+    "decalibrate",
     "Defaultable",
+    "Deprecated",
     "frontmost",
+    "hepa",
     "Inheco",
     "iswap",
     "jsonify",
 
@@ -28,6 +28,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Merge `height_functions.py` and `volume_functions.py` into `height_volume_functions.py` (https://github.com/PyLabRobot/pylabrobot/pull/200)
 - Type checking for `lh.pick_up_tips`, `lh.drop_tips`, `lh.aspirate`, and `lh.dispense` and 96-channel versions.
 - `ChatterBoxBackend` outputs are now pretty (https://github.com/PyLabRobot/pylabrobot/pull/208)
+- `liquid_height` now defaults to 0 instead of 1 (https://github.com/PyLabRobot/pylabrobot/pull/205/)
+- `material_z_thickness` of a `Container` is used in computing its bottom (https://github.com/PyLabRobot/pylabrobot/pull/205/)
+- Default `pickup_distance_from_top` in `LiquidHandler.{move_plate,move_lid}` were lowered by 3.33 (https://github.com/PyLabRobot/pylabrobot/pull/205/)
+- `PlateCarrierSite` can now take `ResourceStack` as a child, as long as the children are `Plate`s (https://github.com/PyLabRobot/pylabrobot/pull/226)
+- `Resource.get_size_{x,y,z}` now return the size of the resource in local space, not absolute space (https://github.com/PyLabRobot/pylabrobot/pull/235)
+- `Resource.center` now returns the center of the resource in local space, not absolute space (https://github.com/PyLabRobot/pylabrobot/pull/235)
+- Rename `ChatterBoxBackend` to `LiquidHandlerChatterboxBackend` (https://github.com/PyLabRobot/pylabrobot/pull/242)
+- Move `LiquidHandlerChatterboxBackend` from `liquid_handling.backends.chatterbox_backend` to `liquid_handling.backends.chatterbox` (https://github.com/PyLabRobot/pylabrobot/pull/242)
+- Changed `pedestal_size_z=-5` to `pedestal_size_z=-4.74` for `PLT_CAR_L5AC_A00` (https://github.com/PyLabRobot/pylabrobot/pull/255)
+- rename `homogenization_` parameters in `STAR` to `mix_` (https://github.com/PyLabRobot/pylabrobot/pull/261)
+- Lids no longer get special treatment when assigned to a ResourceStack. Assign them to a plate directly (https://github.com/PyLabRobot/pylabrobot/pull/267)
 
 ### Added
 
@@ -47,13 +58,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - `adapter_hole_size_z` and `plate_z_offset` parameters to `PlateAdapter` (https://github.com/PyLabRobot/pylabrobot/pull/215)
 - `wide_high_volume_tip_with_filter` and `HTF_L_WIDE` (https://github.com/PyLabRobot/pylabrobot/pull/222)
 - Serialize code cells and closures (https://github.com/PyLabRobot/pylabrobot/pull/220)
+- `Container.get_anchor()` now supports `"cavity_bottom"` as an argument for `z` (https://github.com/PyLabRobot/pylabrobot/pull/205/)
+- `pylabrobot.resources.utils.query` for basic querying (https://github.com/PyLabRobot/pylabrobot/commit/4a07f6a32a9a33d0370eb9c29015567c98aea002)
+- `HamiltonLiquidHandler.allow_firmware_planning` to allow STAR/Vantage to plan complex liquid handling operations automatically (may break hardware agnosticity unexpectedly) (https://github.com/PyLabRobot/pylabrobot/pull/224)
+- `size_z` and `nesting_z_height` for `Cor_96_wellplate_360ul_Fb_Lid` (https://github.com/PyLabRobot/pylabrobot/pull/226)
+- `NestedTipRack` (https://github.com/PyLabRobot/pylabrobot/pull/228)
+- `HTF_L_ULTRAWIDE`, `ultrawide_high_volume_tip_with_filter` (https://github.com/PyLabRobot/pylabrobot/pull/229/)
+- `get_absolute_size_x`, `get_absolute_size_y`, `get_absolute_size_z` for `Resource` (https://github.com/PyLabRobot/pylabrobot/pull/235)
+- `Cytation5Backend` for plate reading on BioTek Cytation 5 (https://github.com/PyLabRobot/pylabrobot/pull/238)
+- More chatterboxes (https://github.com/PyLabRobot/pylabrobot/pull/242)
+  - `FanChatterboxBackend`
+  - `PlateReaderChatterboxBackend`
+  - `PowderDispenserChatterboxBackend`
+  - `PumpChatterboxBackend`
+  - `PumpArrayChatterboxBackend`
+  - `ScaleChatterboxBackend`
+  - `ShakerChatterboxBackend`
+  - `TemperatureControllerChatterboxBackend`
+- Add fluorescence reading to Cytation 5 (https://github.com/PyLabRobot/pylabrobot/pull/244)
+- Add `F.linear_tip_spot_generator` and `F.randomized_tip_spot_generator` for looping over tip spots, with caching (https://github.com/PyLabRobot/pylabrobot/pull/256)
+- Add `skip_autoload`, `skip_iswap`, and `skip_core96_head` flags to `STAR.setup` (https://github.com/PyLabRobot/pylabrobot/pull/263)
+- Add `skip_autoload`, `skip_iswap`, and `skip_core96_head` flags to `Vantage.setup` (https://github.com/PyLabRobot/pylabrobot/pull/263)
 
 ### Deprecated
 
 - All VENUS-imported Corning-Costar plates, because they don't have unique and usable identifiers, and are probably wrong.
 - Passing single values to LiquidHandler `pick_up_tips`, `drop_tips`, `aspirate`, and `dispense` methods. These methods now require a list of values.
 - `utils.positions`: `string_to_position`, `string_to_index`, `string_to_indices`, `string_to_pattern`.
 - `ThermoScientific_96_DWP_1200ul_Rd` in favor of `Thermo_TS_96_wellplate_1200ul_Rb` (https://github.com/PyLabRobot/pylabrobot/pull/215)
+- `Azenta4titudeFrameStar_96_wellplate_skirted` in favor of `Azenta4titudeFrameStar_96_wellplate_200ul_Vb` (https://github.com/PyLabRobot/pylabrobot/pull/205/)
+- `Cos_96_DWP_2mL_Vb` in favor of `Cos_96_wellplate_2mL_Vb (https://github.com/PyLabRobot/pylabrobot/pull/205/)`
 
 ### Fixed
 
@@ -62,9 +96,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Fix Opentrons backend resource definitions: Opentrons takes well locations as ccc instead of lfb
 - Fix ThermoScientific_96_DWP_1200ul_Rd to ThermoScientific_96_wellplate_1200ul_Rd (https://github.com/PyLabRobot/pylabrobot/pull/183).
 - `libusb_package` is now an optional dependency.
+- Plates with a skirt are now correctly lowered when placed on plate carriers with a pedestal (https://github.com/PyLabRobot/pylabrobot/pull/205/)
+- `minimum_height` in `STAR` and `Vantage` now correctly refer to a `Container`s bottom instead of being a function of liquid height (https://github.com/PyLabRobot/pylabrobot/pull/205/)
+- `aspirate96` and `dispense96` type check
+- fix angles computed by grip directions (https://github.com/PyLabRobot/pylabrobot/pull/234)
+- picking up rotated resources in `STAR` (https://github.com/PyLabRobot/pylabrobot/pull/233)
+- picking up rotated resources in `Vantage` (https://github.com/PyLabRobot/pylabrobot/pull/268)
+- assigning rotated resources to `PlateReader` now have the correct location (https://github.com/PyLabRobot/pylabrobot/pull/233)
+- use local sizes in computing anchor (https://github.com/PyLabRobot/pylabrobot/pull/233)
+- don't raise a blow out air volume error when requesting 0, or when volume tracking is disabled (https://github.com/PyLabRobot/pylabrobot/pull/262)
+- fix get_child_location for resources rotated by 180 degrees (https://github.com/PyLabRobot/pylabrobot/pull/269)
+- volume tracking on channel 1-n (https://github.com/PyLabRobot/pylabrobot/pull/273)
 
 ### Removed
 
 - HamiltonDeck.load_from_lay_file
 - `hamilton_parse` module and the VENUS labware database parser.
 - `PLT_CAR_L4_SHAKER` was removed in favor of `MFX_CAR_L5_base` (https://github.com/PyLabRobot/pylabrobot/pull/188/).
+- `items`, `num_items_x` and `num_items_y` attributes of `ItemizedResource` (https://github.com/PyLabRobot/pylabrobot/pull/231)
+- `report` is no longer a parameter of `PlateReader.read_absorbance` (default is now OD) (https://github.com/PyLabRobot/pylabrobot/pull/238)
@@ -8,7 +8,7 @@ See the installation instructions [here](docs/installation.md). For contributing
 
 If this is your first time contributing to open source, check out [How to Open Source](./docs/how-to-open-source.md) for an easy introduction.
 
-It's highly appreciated by the PyLabRobot developers if you communicate what you want to work on, to minimize any duplicate work. You can do this on the [forum](https://forums.pylabrobot.org/c/pylabrobot-development/23).
+It's highly appreciated by the PyLabRobot developers if you communicate what you want to work on, to minimize any duplicate work. You can do this on the [forum](https://discuss.pylabrobot.org).
 
 ## Development Tips
 
@@ -71,4 +71,4 @@ Backends are the primary objects used to communicate with hardware. If you want
 
 ## Support
 
-If you have any questions, feel free to reach out using the [PyLabRobot forum](https://forums.pylabrobot.org).
+If you have any questions, feel free to reach out using the [PyLabRobot forum](https://discuss.pylabrobot.org).
@@ -6,11 +6,17 @@ endif
 .PHONY: docs lint test
 
 docs:
-	sphinx-build -b html docs docs/build/ -j 1 -W
+	sphinx-build -b html docs docs/build/ -j 16 -W
+
+docs-fast:
+	echo "building docs without api for speed"
+	sphinx-build -t no-api -b html docs docs/build/ -j 16 -W
 
 clean-docs:
 	rm -rf docs/build
 	rm -rf docs/_autosummary
+	rm -rf docs/jupyter_execute
+	rm -rf docs/user_guide/jupyter_execute
 
 lint:
 	$(BIN)python -m pylint pylabrobot
 
@@ -1,17 +1,31 @@
 <div style="text-align: center" align="center">
 <img width="400" src=".github/img/logo.png" />
-<h1>PyLabRobot</h1>
 </div>
 
-[**Docs**](https://docs.pylabrobot.org) | [**Forum**](https://forums.pylabrobot.org) | [**Installation**](https://docs.pylabrobot.org/installation.html) | [**Getting started**](https://docs.pylabrobot.org/basic.html)
+<div style="text-align: center" align="center">
+<a href="https://docs.pylabrobot.org"><strong>Docs</strong></a> | 
+<a href="https://discuss.pylabrobot.org"><strong>Forum</strong></a> | 
+<a href="https://docs.pylabrobot.org/installation.html"><strong>Installation</strong></a> | 
+<a href="https://docs.pylabrobot.org/basic.html"><strong>Getting started</strong></a>
+</div>
 
 ## What is PyLabRobot?
 
-PyLabRobot is a hardware agnostic, pure Python library for liquid handling robots and other lab automation equipment. Read [the paper](<https://www.cell.com/device/fulltext/S2666-9986(23)00170-9>) in Device.
+PyLabRobot is a hardware agnostic, pure Python library for liquid handling robots, plate readers, pumps, scales, heater shakers, and other lab automation equipment. Read [the paper](<https://www.cell.com/device/fulltext/S2666-9986(23)00170-9>) in Device.
+
+Advantages over proprietary software:
 
-### Liquid handling robots
+- **Cross-platform**: PyLabRobot works on Windows, macOS, and Linux. Many other interfaces are Windows-only.
+- **Universal**: PyLabRobot works with any supported liquid handling robot, plate reader, pump, scale, heater shaker, etc. through a single interface.
+- **Fast iteration**: PyLabRobot enables rapid development of protocols using atomic commands run interactively in Jupyter notebooks or the Python REPL. This decreases iteration time from minutes to seconds.
+- **Open-source**: PyLabRobot is open-source and free to use.
+- **Control**: With Python, you have ultimate flexibility to control your lab automation equipment. You can write Turing-complete protocols that include feedback loops.
+- **Modern**: PyLabRobot is built on modern Python 3.8+ features and async/await syntax.
+- **Fast support**: PyLabRobot has [an active community forum](https://discuss.pylabrobot.org) for support and discussion, and most pull requests are merged within a day.
 
-PyLabRobot provides a layer of general-purpose abstractions over robot functions, with various device drivers for communicating with different kinds of robots. Right now we only have drivers for Hamilton, Tecan and Opentrons liquid handling robots, but we will soon have drivers for many more. The Hamiton and Tecan backends provide an interactive firmware interface that works on Windows, macOS and Linux. The Opentrons driver is based on the [Opentrons HTTP API](https://github.com/rickwierenga/opentrons-python-api). We also provide a browser-based Visualizer which can visualize the state of the deck during a run, and testing backends which do not require access to a robot.
+### Liquid handling robots ([docs](https://docs.pylabrobot.org/basic.html))
+
+PyLabRobot enables the use of any liquid handling robot through a single universal interface, that works on any modern operating system (Windows, macOS, Linux). We currently support Hamilton STAR, Hamilton Vantage, Tecan Freedom EVO, and Opentrons OT-2 robots, but we will soon support many more.
 
 Here's a quick example showing how to move 100uL of liquid from well A1 to A2 using firmware on **Hamilton STAR** (this will work on any operating system!):
 
@@ -30,40 +44,34 @@ await lh.dispense(lh.deck.get_resource("plate")["A2"], vols=100)
 await lh.return_tips()
 ```
 
-To run the same procedure on an **Opentrons**, change the following lines:
-
-```diff
-- from pylabrobot.liquid_handling.backends import STAR
-+ from pylabrobot.liquid_handling.backends import OpentronsBackend
-
-- deck = Deck.load_from_json_file("hamilton-layout.json")
-+ deck = Deck.load_from_json_file("opentrons-layout.json")
+To run the same protocol on an **Opentrons**, use the following:
 
-- lh = LiquidHandler(backend=STAR(), deck=deck)
-+ lh = LiquidHandler(backend=OpentronsBackend(host="x.x.x.x"), deck=deck)
+```python
+from pylabrobot.liquid_handling.backends import OpentronsBackend
+deck = Deck.load_from_json_file("opentrons-layout.json")
+lh = LiquidHandler(backend=OpentronsBackend(host="x.x.x.x"), deck=deck)
 ```
 
 Or **Tecan** (also works on any operating system!):
 
-```diff
-- from pylabrobot.liquid_handling.backends import STAR
-+ from pylabrobot.liquid_handling.backends import EVO
+```python
+from pylabrobot.liquid_handling.backends import EVO
+deck = Deck.load_from_json_file("tecan-layout.json")
+lh = LiquidHandler(backend=EVO(), deck=deck)
+```
 
-- deck = Deck.load_from_json_file("hamilton-layout.json")
-+ deck = Deck.load_from_json_file("tecan-layout.json")
+We also provide a browser-based Visualizer which can visualize the state of the deck during a run, and can be used to develop and test protocols without a physical robot.
 
-- lh = LiquidHandler(backend=STAR(), deck=deck)
-+ lh = LiquidHandler(backend=EVO(), deck=deck)
-```
+![Visualizer](.github/img/visualizer.png)
 
-### Plate readers
+### Plate readers ([docs](https://docs.pylabrobot.org/plate_reading.html))
 
-PyLabRobot also provides a layer of general-purpose abstractions for plate readers, currently with just a driver for the ClarioStar. This driver works on Windows, macOS and Linux. Here's a quick example showing how to read a plate using the ClarioStar:
+Moving a plate to a ClarioStar using a liquid handler, and reading luminescence:
 
 ```python
 from pylabrobot.plate_reading import PlateReader, ClarioStar
 
-pr = PlateReader(name="plate reader", backend=ClarioStar())
+pr = PlateReader(name="plate reader", backend=ClarioStar(), size_x=1, size_y=1, size_z=1)
 await pr.setup()
 
 # Use in combination with a liquid handler
@@ -73,6 +81,75 @@ lh.move_plate(lh.deck.get_resource("plate"), pr)
 data = await pr.read_luminescence()
 ```
 
+For Cytation5, use the `Cytation5` backend.
+
+### Centrifuges
+
+Centrifugation at 800g for 60 seconds:
+
+```python
+from pylabrobot.centrifuge import Centrifuge, VSpin
+cf = Centrifuge(name = 'centrifuge', backend = VSpin(bucket_1_position=0), size_x= 1, size_y=1, size_z=1)
+await cf.setup()
+
+await cf.start_spin_cycle(g = 800, duration = 60)
+```
+
+### Pumps ([docs](https://docs.pylabrobot.org/pumps.html))
+
+Pumping at 100 rpm for 30 seconds using a Masterflex pump:
+
+```python
+from pylabrobot.pumps import Pump
+from pylabrobot.pumps.cole_parmer.masterflex import Masterflex
+
+p = Pump(backend=Masterflex())
+await p.setup()
+await p.run_for_duration(speed=100, duration=30)
+```
+
+### Scales ([docs](https://docs.pylabrobot.org/scales.html))
+
+Taking a measurement from a Mettler Toledo scale:
+
+```python
+from pylabrobot.scales import Scale
+from pylabrobot.scales.mettler_toledo import MettlerToledoWXS205SDU
+
+backend = MettlerToledoWXS205SDU(port="/dev/cu.usbserial-110")
+scale = Scale(backend=backend, size_x=0, size_y=0, size_z=0)
+await scale.setup()
+
+weight = await scale.get_weight()
+```
+
+### Heater shakers ([docs](https://docs.pylabrobot.org/heater_shakers.html))
+
+Setting the temperature of a heater shaker to 37&deg;C:
+
+```python
+from pylabrobot.heating_shaking import HeaterShaker
+from pylabrobot.heating_shaking import InhecoThermoShake
+
+backend = InhecoThermoShake()
+hs = HeaterShaker(backend=backend, name="HeaterShaker", size_x=0, size_y=0, size_z=0)
+await hs.setup()
+await hs.set_temperature(37)
+```
+
+### Fans ([docs](https://docs.pylabrobot.org/fans.html))
+
+Running a fan at 100% intensity for one minute:
+
+```python
+from pylabrobot.only_fans import Fan
+from pylabrobot.only_fans import HamiltonHepaFan
+
+fan = Fan(backend=HamiltonHepaFan(), name="my fan")
+await fan.setup()
+await fan.turn_on(intensity=100, duration=60)
+```
+
 ## Resources
 
 ### Documentation
@@ -86,7 +163,7 @@ data = await pr.read_luminescence()
 
 ### Support
 
-- [forums.pylabrobot.org](https://forums.pylabrobot.org) for questions and discussions.
+- [discuss.pylabrobot.org](https://discuss.pylabrobot.org) for questions and discussions.
 - [GitHub Issues](https://github.com/pylabrobot/pylabrobot/issues) for bug reports and feature requests.
 
 ## Citing
 
@@ -11,7 +11,7 @@
    .. autosummary::
       :toctree: .
    {% for item in attributes %}
-      ~{{ fullname }}.{{ item }}
+      ~{{ objname }}.{{ item }}
    {%- endfor %}
    {% endif %}
    {% endblock %}
@@ -23,7 +23,7 @@
    .. autosummary::
       :toctree: .
    {% for item in methods %}
-      ~{{ fullname }}.{{ item }}
+      ~{{ objname }}.{{ item }}
    {%- endfor %}
    {% endif %}
    {% endblock %}