jubiotech/robotools

Pythonic in-silico liquid handling and creation of Tecan FreedomEVO worklists.

robotools

This is a package for debugging and planning liquid handling operations, writing worklist files for the Tecan FreedomEVO and Tecan Fluent platform on the fly.

You can visit the documentation at https://robotools.readthedocs.io, where the notebooks are rendered next to auto-generated API documentation.

Installation

robotools is available through PyPI:

pip install robotools

Contributing

The easiest way to contribute is to report bugs by opening Issues.

We apply automated code style normalization using black. This is done with a pre-commit, which you can set up like this:

1. pip install pre-commit
2. pre-commit install
3. pre-commit run --all

Step 2.) makes sure that the pre-commit runs automatically before you make a commit.

Step 3.) runs it manually.

Usage and Citing

robotools is licensed under the GNU Affero General Public License v3.0.

When using robotools in your work, please cite the corresponding software version.

@software{robotools,
  author       = {Michael Osthege and
                  Laura Helleckes},
  title        = {JuBiotech/robotools: v1.3.0},
  month        = nov,
  year         = 2021,
  publisher    = {Zenodo},
  version      = {v1.3.0},
  doi          = {10.5281/zenodo.5745938},
  url          = {https://doi.org/10.5281/zenodo.5745938}
}

Head over to Zenodo to generate a BibTeX citation for the latest release.

robotools's Issues

Refactor internal functions to use dicts or namedtuples instead of long lists of args

Some internal functions take a vera long list of args as inputs, only to return another long list of args.
This makes the code really hard to read.

We should refactor these to use dicts or namedtuples.

Candidates:

• robotools/robotools/evotools/__init__.py

  Lines 39 to 50 in 06f6bc0

  	def _prepare_aspirate_dispense_parameters(
  	rack_label: str,
  	position: int,
  	volume: float,
  	liquid_class: str = "",
  	tip: typing.Union[Tip, int, collections.abc.Iterable] = Tip.Any,
  	rack_id: str = "",
  	tube_id: str = "",
  	rack_type: str = "",
  	forced_rack_type: str = "",
  	max_volume: typing.Optional[int] = None,
  	) -> typing.Tuple[str, int, float, str, typing.Union[Tip, int, collections.abc.Iterable], str, str, str, str]:

• _prepare_evo_wash_parameters from #21

Add pre-commit to normalize code style

Why is there a Labwares() class and a Labware() class?

robotools/liquidhandling/init.py has a Labware() class (~line 141) that contains the general object for defining labware. This makes sense to me.

robotools/evotools/init.py has a Labwares() class (~line 17) that only contains:

SystemLiquid = "Systemliquid"

I don't understand why this is a separate class. Could this be combined with the Labware() class? Or should this stay separate?
If it should be separate, I think we should rename this class to something more distinct to avoid confusion. The only reference to Labwares() that I see in this library is in tests.py (line 591):

def test_aspirate_systemliquid(self) -> None: with evotools.Worklist() as wl: wl.aspirate_well(evotools.Labwares.SystemLiquid, 1, 200) self.assertEqual(wl[-1], "A;Systemliquid;;;1;;200.00;;;;") return

Is SystemLiquid just a specific default location on the Tecan?

Thanks,
Clay

Use `from typing import ...` imports to reduce code verbosity

Expose the `robotools.transform.make_well_array` function as part of the public API

`WellRotator` can't take sets, but could just autoconvert them

Make `Worklist` accept `Path` filepaths

Dilution plan string representation is missing a +1 in the source column for serial dilutions

Mention examples of optional kwargs in `Worklist.transfer` and related methods

The docstring for the **kwargs refers to Worklist.aspirate, but there it further refers to Worklist.aspirate_well.

Split `tests.py` to align with submodule structure

depends on #20

Write tests for `evo_aspirate`, `evo_dispense`, `evo_wash`

Add usage example for tip subsets

Robotools limits EVOware flexibility for specifying multiple tip usage

This worklist is an example of how the EVOware can actually use the binary tip logic to assign a subset of tips for usage. Here, we use the first 6 tips (1+2+4+8+16+32=63):

D;96flat;;;25;;100.00;;;63;
W1;
A;Trough;;;2;;100.00;;;63;
D;96flat;;;26;;100.00;;;63;
W1;
A;Trough;;;3;;100.00;;;63;
D;96flat;;;27;;100.00;;;63;
W1;
A;Trough;;;4;;100.00;;;63;
D;96flat;;;28;;100.00;;;63;
W1;
A;Trough;;;5;;100.00;;;63;
D;96flat;;;29;;100.00;;;63;
W1;
A;Trough;;;6;;100.00;;;63;
D;96flat;;;30;;100.00;;;63;
W1;
A;Trough;;;1;;100.00;;;63;
D;96flat;;;33;;100.00;;;63;
W1;
A;Trough;;;2;;100.00;;;63;
D;96flat;;;34;;100.00;;;63;
W1;
A;Trough;;;3;;100.00;;;63;
D;96flat;;;35;;100.00;;;63;
W1;
A;Trough;;;4;;100.00;;;63;
D;96flat;;;36;;100.00;;;63;
W1;
A;Trough;;;5;;100.00;;;63;
D;96flat;;;37;;100.00;;;63;
W1;
A;Trough;;;6;;100.00;;;63;
D;96flat;;;38;;100.00;;;63;
W1;

This WL transfers 100 microlitre from the trough to the first six wells of two columns in a 96-MTP using only the first six tips.
It would be great if robotools allow for the logic to specifify this as:

mtp = robotools.Labware(
    "96flat",
    8, 12,
    min_volume=0,
    max_volume=300,
    initial_volumes=0
)
trough = robotools.Trough(
    "Trough",
    8, 1,
    min_volume=200,
    max_volume=100*1000,
    initial_volumes=100*1000
)
with robotools.Worklist("test_wl.gwl") as wl:
    wl.transfer(
        trough, robotools.get_trough_wells(len(mtp.wells[0:6, 3:4].flatten()), trough.wells),
        mtp, mtp.wells[0:6, 3:4],
        100,
        tip=63
    )

pandas is not required

Hello,

thanks a lot for this awesome package!

In the requirements pandas is listed, but it seems to me that it is not used anywhere, is it?

Are you interested in using poetry for dependency management? This is quite useful to manage dependency only used during development e.g. pytest, mypy, pre-commit. If so I could provide a PR for it, that also fixes the unnecessary dependency to pandas as well.

fin swimmer

Add usage examples to docstrings of `WellRotator` and `WellShifter`

Derandomize method of WellRandomizer is wrong

Found this yesterday, fix is on the way

Compatability with DiTi Evos

Hey everyone,
I encountered an issue while using evos that mount disposable tips.
Unlike the Fluent, it does not understand a "W1;" as a "Eject Tips", but it has to be a ""W;". However, this is currently forbidden by the .wash method of the base worklist. What I'd suggest is the following

    def wash(self, scheme: int = 1) -> None:
        """Washes fixed tips or replaces DiTis.

        Washes/replaces the tip that was used by the preceding aspirate record(s).

        Parameters
        ----------
        scheme : int
            Number indicating the wash scheme (default: 1)
        """
        if not scheme in {0, 1, 2, 3, 4}:
            raise ValueError("scheme must be either 0, 1, 2, 3 or 4")
        
        if scheme == 0:
            self.append("W;")
        else:
            self.append(f"W{scheme};")
        return

What do you guys think? I'd create a PR myself but I do not have write access.

Move code from `__init__.py` files into proper submodules

Documentation shows outdated version number

Same bug as JuBiotech/calibr8#40

Compatibility with TecanFluent?

Hi, I am graduate student at UT Austin working on developing liquid handling protocols to validate our deep learning models for protein engineering (https://mutcompute.com). We have a TecanFreedom and a TecanFluent that are being underutilized, and I want to get these up and running. I am currently looking for a Python library that can control the machines, and came across yours by recommendation of Sandor (said he's a former colleague of yours).

I am wondering if you guys know if this software will work out of the box for the TecanFluent (I already know it works for the Freedom). If it doesn't, do you know what/where changes I would need to make to adapt/extend this library to work on a TecanFluent?

I would be more than happy to fork the repo, implement the necessary changes, and PR them back. I would greatly appreciate if you guys can provide some initial guidance to get me started. (Just found the repo and am looking through it now).

Thanks,
Clay Kosonocky