TITLE: OT-2 Protocol to transfer volume from several  plates to a single plate 
AUTHORS: Ana Mariya Anhel, Lorea Alejaldre, Ángel Goñi-Moreno

[DESCRIPTION]
This protocol is meant to transfer samples from different plates to a single or fewer final plates than the source number, in other words, merge samples of different source plates in a final plate.
The output of running this script will be the final plate(s) with samples and a reactive (optional), and the corresponding map(s) with the original identities of the samples which will be given by the user in the input file.

This protocol uses a python script for an Opentrons 2 robot and an excel file containing the required variables to set the number of samples, volumes of transfer, type of plates, etc... 

In our laboratory, this protocol has been used as part of the "High-throughput workflow for the genotypic characterization of transposon library variants" also available in protocols.io

This protocol is a set of instructions or description of the LAP repository entry LAP-NplateMerging-OT2-1.0.0



[BEFORE_START]
It is important to annotate the location of the source plate in the OT-2 slots, the identity of the samples is provided by excel sheets in the input variable and if 2 samples, within a plate or between different source plates has the same name, they will be indistinguishable in the final plate (s)

[GUIDELINES]
This protocol was developed with python 3.7.1, OT App Software Version 6.3.1 and API level version 2.14 in a Linux 4.14.74 system (these are the OT-2 specifications).
In the script several packages are used:  pandas (0.25.3), openpyxl (3.1.2), math, random and numpy (1.15.1)

It has been tested with cultures from Pseudomonas putida KT2440 as part of the High-throughput workflow for the genotypic characterization of transposon library variants.

The maximum number of 96-well plates per run is 8 source plates to 1 final plates dispensing some media (need of 1 falcon tube rack), 1 pipette is required for all the volumes and the replace of tip racks is allowed (set as True in the input variable file)

[STEPS]
SECTION: Files Preparation
1. Preparing Customized Template

Preparing the template (a .xlsx) with the specific variables for each experiment.

Attached there is a template of the variable file with several sheets and a PDF file explaining each variable:
GeneralVariables: variables related to the labware to be used
PipetteVariables: variables related to the pipettes to be used
PerPlateVariables: variables related to the specifications of each source plate
Maps (Optional): sheet(s) with the names of the samples in the source plates. These will be reflected in the final plate map --> not included in the template but needs to be included and have the same names as established in the variable Name Sheet Map Identifiers from the PerPlateVariablesSheet

  
  

SECTION: Running Protocol
None. Setting Labware
SECTION: After-running
None. Retrieve labware from the OT
SECTION: Example
None. We are going to transfer 30, 45 and 15 samples from 3 different source plates to a single plate with the variables set in the Example of the Template_MergingSamplesPlates.xlsx attached in Step 1.

We will use a computer with an Ubuntu system connected via USB to the robot
SECTION: Files Preparation
2. Transferring VariablesMergeSamples.xlsx  file to Robot

Transfer the VariablesMergeSamples.xlsx to the directory /data/user_storage of the OT robot
 that we are going to use to perform the protocol.

 


 

Here, we present a summary of how to transfer the files in 3 Operative Systems: Windows, MacOS and Linux


MacOS/Linux
We will use the command line with scp to transfer the fileVariablesMergeSamples.xlsx to the OT system.

We need to perform the following command
 

 


Windows
There are several ways to send files from a Windows to a Linux (for example, with a virtual machine or Windows Powershell in the latest versions of Windows).

Here, we will use FileZilla (https://filezilla-project.org/download.php?type=client).

Go to File -> Site Manager -> New Site -> Change Protocol to SFTP. Then, introduce in Host the OT IP, change the Logon Type to key file, change User to root and give the directory where the ot key is. It should look something like this

 
Then press Connect, and we will have a connection between our computer and the robot.

After this connection, we should be able to move the file VariablesMergeSamples.xlsx (in our computer) to the directory /data/user_storage in the robot.

This method can be used as well in some Linux and MacOS

 


SECTION: Files Preparation
3. Adding the custom labware

There is only a need to do this step when the labware that you are using is not OT official or is not included in the OT app
SECTION: Running Protocol
None. Load script in OT-App

Now that we have made sure that the protocol is going to work we import the python script in the OT-App.
 

SECTION: Running Protocol
None. Run Protocol in OT
SECTION: After-running
None. Importing maps from robot

This can be done if in Step 1 the variable Optional Map was set to True

There will be as many maps as source plates with the following structure of names: VariableNameMap_PositionSlot.csv

To retrieve we can   and reproduce it with transfering the files to the computer. 

They will be in the directory /data/user_storage

 

SECTION: Example
None. Excel template filled and exported to csv with the name Variables-SamplesMerging-OT.csv

  

SECTION: Example
None. Export the variables and source plates maps (for the creation of the final map) csv to /data/user_storage

 
 
SECTION: Example
None. We have never used a 96 tisue plate labware with the API name vwrblueprintdepth105_96_wellplate_390ul, so we must pass the directory regarding this labware to the robot

 
SECTION: Example
None. Pass the scipt that I have downloaded from https://github.com/Biocomputation-CBGP/OT2/tree/main/MergingSamplesSourcePlates (I named it PlateMerging-Example.py), connect to OT computer, simulate, exit OT system, store the output in instructions_examplePlateMerging.txt and import it to the computer

 
 
  

SECTION: Example
None. Prepare all reactives and labwares

Initial Labware Setup and falcon tuberack(s) setup should look like the following picture
 

 

SECTION: Example
None. Load to OT-App the PlateMerging-Example.py > Run > Select robot in which we are going to run the protocol

The window and tabs of the OT-App should look like the following pictures

 
 

SECTION: Example
None. Desinfect OT
SECTION: Example
None. Load protocol labware as instructed in Step 10.6
SECTION: Example
None. Run protocol

The final results should look like the following pictures
 


 

SECTION: Files Preparation
1.1. Fill the template with the corresponding values
SECTION: Files Preparation
1.2. Save it with the name VariablesMergeSamples.xlsx

 


SECTION: Files Preparation
3.1. Creation of .json file

The description file can be obtained by describing the labware dimensions at https://labware.opentrons.com/create/
SECTION: Files Preparation
3.2. Uploading files to the OT App

In the OT app, we need to perform the following route: Labware -> Import -> Choose File -> Select file we have created in step 3.1

 

SECTION: Running Protocol
5. Load script in OT-App

Now that we have transferred the variable files to the robot, we can import the script and run it in the selected robot

 

 

SECTION: Running Protocol
6. Run Protocol in OT
SECTION: Example
9. We want to merge 16 samples from 5 source plates in a different way, 1 of them selecting samples from back to front, 2 in a random way and 2 from front to back.
Our final plate will have half the plate already occupied by other samples, and we want to add to all the samples water, so we need to take into account those details

We will use a computer with a Windows 10 system
SECTION: Prepare RobotOS
4. Install needed packages

This script needs the package openpyxl, which is not installed by default in the OT-2 robots

 

SECTION: After-Running
7. Retrieve labware from the OT
SECTION: After-Running
8. Import map from robot

There will be a map with the name set in the variable Name File Final Map set in the sheet GeneralVariables followed by the extension .xlsx: [Name File Final Map].xlsx

This file will be located in the directory /data/user_storage in the robot where the script has been run.

To retrieve the file, we can   and reproduce it by transferring the files from the robot to the computer. 
 


 

SECTION: Prepare RobotOS
4.1. Connect to the robot

   to find the IP of the robot in which you want to run the script

To connect to the robot, you can do it via ssh with the following command
 
In Windows you can do this command in Windows Powershell

 

SECTION: Prepare RobotOS
4.2. Install the package

Once inside the robot's system, you need to run the following command
 

 

SECTION: Running Protocol
5.1. Load the script in the App

Protocols -> Import -> Drag Python script

 

 

 

SECTION: Running Protocol
5.2. Select Robot to Perform Script

Click in the protocol -> Start setup -> Choose the OT where the file VariablesMergeSamples.xlsx is -> Proceed To Setup

After clicking on Proceed to Setup, you should obtain, the positions of the labware in the Labware tab and in the Liquids tab, the reagents and their corresponding volume.

 

 

 

SECTION: Running Protocol
6.1. Make sure the needed calibrations are done

Pipettes, tip racks and tip length calibrations need to be done for the items used in this run
SECTION: Running Protocol
6.2. Labware position check is performed (if required)
SECTION: Running Protocol
6.3. Clean the surface of the robot with 70% ethanol to clean and disinfect the surfaces

 

SECTION: Running Protocol
6.4. Set the labware and reagents as shown in the OT-App
SECTION: Running Protocol
6.5. Start Run

The procedure that the robot is going to do is mainly divided into 3 parts:

Select which samples, taking into account the variable Type of Sample Selection
(Optional) Distribute reactive(s)
Distribute selected samples

 

SECTION: Example
9.1. Prepare variable file

Excel template that we can find    filled and saved with the name 
VariablesMergeSamples.xlsx

  

SECTION: Example
9.2. Upload custom labware to app

We are using a custom labware called vwrblueprintdepth105_96_wellplate_390ul that has been created with the labware creator that opentrons offers (https://labware.opentrons.com/create/)

  

Upload it to the labware and make sure it is loaded in the app

 
SECTION: Example
9.3. Export the variable file to the /data/user_storage folder  in the robot

 
SECTION: Example
9.5. Import the script that we have downloaded from the step    (I named it Example-ScriptMergePlates.py) to the OT-App

  

 
As we can see, we have an error, but that is programmed because the script is meant to work in the robot but not in your computer
SECTION: Example
9.6. Run the protocol in the robot that we have transferred the Excel file

Example-ScriptMergePlates.py -> Start setup -> Select the robot in which we are going to run the protocol

If we do not have any errors, the output should look similar to the following pictures

  
 
 
SECTION: Example
9.8. Clean platform of the robot that we are going to perform the protocol
SECTION: Example
9.9. Prepare all reagents and labware in the places the App is showing and take into account the notes in step   
SECTION: Example
9.10. Start run

 

SECTION: Example
9.11. Retrieve labwares from the OT
SECTION: Example
9.12. Retrieve the final maps, in this case, the map file will be called example-mapMerge.xlsx (name that is stated in the variable file in the variable Name File Final Map)
 
 
  

SECTION: Example
9.7. Turn the HEPA filter module
SECTION: Files Preparation
3.3. Transfer labware files to the robot

If you are using the entry LAP-NplateMerging-OT2-1.0.0 and custom labware, an additional step is needed, which is transferring a folder with the custom labware

We need to create for our custom labware a folder with the API name containing the description file (.json) called 1.json and then transfer that folder to the robot's folder /data/labware/v2/custom_definitions/custom_beta in a similar way as in the Step 2 but with the difference that is a directory that needs to be transferred and not a file.
 

 

SECTION: Example
9.4. Because we are using version 1.0.0 of the script in this example, we will transfer the directory of the labware as well (here we have attached a zip, but it is the folder that must be transferred, not the zip)