Package: combination-builder
Echo Combination BuilderA Python module for creating large-scale combination work list files.SummaryThe intended purpose of this module is to provide a framework for easily constructing work list files for import to Echo acoustic liquid handlers (Beckman Coulter) that create combinations of substances for high throughput screening assays.  The original application was for small molecule screening, but additional applications should be possible without modification.  There are a series of steps involved in creating the work list files and this module provides the methods needed to perform these steps.AcknowledgementIf this software is helpful to you please acknowledge the source in your publications.  Please use the following acknowledgement:
"The authors would like to thank Duane Currier and Taosheng Chen of St Jude Children's Research Hospital for the use of the Combination Builder module (https://github.com/StJude-HTB/Echo-Combination-Builder)."InstallationDependency:Python 3.8+Install from pip:python -m pip install combination-builderUse And ExamplesFrom the Python prompt the following commands will import the example files and produce example outputs.  The examples files referenced below can be downloaded by cloning this repository or downloading them from the Example_Files directory.Import Combinations Moduleimport combination-builder as Combine1. Set Values and Initialize a Combinations ObjectSet variables to indicate locations of input and output files:
Setting these variables here make setting all the variables easier since they are in one place, but the values can be substituted below in the actual calls to the methods if that is preferable.
Themap_filepathis the path to the platemap file in either basic or 'Mosaic' formatmap_filepath = "Example_Files\\ExamplePlatemap.txt"Theconcentration_fileis the path to the file containing assay concentrations for each substanceconcentration_file = "Example_Files\\Example_Final_Concs.csv"Thesave_filepathis the path where the Echo work list CSV file will be savedsave_filepath = "Example_Files\\ExampleOutput3.csv"Thecmt_filepathis the path where the Screener cmt mapping file will be savedcmt_filepath = "Example_Files\\ExampleOutput4.cmt"Set variables to control the locations of special wells:Settingbackfill_wellshere allows for easier reference to the well range to use for backfill wells.  Similar to thecontrol_wells,backfill_wellsis an array of well coordinates that can be extended or appended for discontinuous ranges.backfill_wells = Combine.generate_well_range("A21", "P24")Settingcontrol_wellshere makes it easier to reference the well range later.  This range is an array of well coordinates that can be extended or appended for discontinuous ranges.  This is an exmple of creating two discontinuous control well ranges.  Please note that control substances are not currently handled by this module.  Use an alternate means to manually set control well transfers.control_wells = Combine.generate_well_range("A1","P2")control_wells.extend(Combine.generate_well_range("A13","P14"))Set varaibles that specify assay conditions:Settingstatic_transfer_volumewill force all transfers to be the same volumestatic_transfer_volume = 100Settingassay_volumeis required and enables calculation of the assay concentrationassay_volume = 30Settingcombination_maxis required and sets the maximum number of substances in each combinationcombination_max = 3Settingsubstance_id_regexis required and enables identification of the substance identifier in the plate map filesubstance_id_regex = r'SJ[0-9-]+'Initialize the object - This creates the bucket to store all the data inexp = Combine.Combinations()2. Load the plate mapImport the source plate map - were the source substances are on the source plateexp.load_platemap(map_filepath, substance_id_regex)3. Setup the backfill wells - Comment/Uncomment as neededThere are two ways to set the backfill source wells: manually createOption 1:Manually supply a list of wells this is fine for a small number of wellswells = ["A21", "A22", "A23", "A24", "B21", "B22", "B23", "B24"]Option 2:Generate well list from start and stop wells this option is good for a large number of wells list comprehension is required to get well alphaswells = [x[0] for x in backfill_wells]Set backfill wells is specific to individual platesRepeat for all plates with backfill wellsexp.platemap.plates["E3P00000776"].set_backfill_wells(wells)4. Set up Combinations - Comment/Uncomment as neededOption 1:Supply a manually curated list of combinations list compounds in separate columns, any number of columns is supported, header and any compound not in the platemap are skippedcombinations_filepath = "Combination Template.csv"exp.load_platemap(combinations_filepath)Option 2:Calculate all permutations in the script specify how many compounds to include in each combinationexp.generate_combinations(combination_max)5. Set transfer volume or assay conditionsOption 1:Set a static volume for all substances volume is in nanoliters - All combinations will be the 1:1:1 volume ratiosexp.set_transfer_volume(static_transfer_volume)Option 2:Set assay volume and assay concentration assay volume is in microliters assay concentration(s) must be suppliedexp.set_assay_volume(assay_volume)Set a constant concentration for all substancesexp.set_assay_concentration(conc=50, unit="mM")Or set each concentration idependently with a csv fileexp.set_assay_concentration(file=concentration_file)6. Configure assay plate layoutexp.reserve_control_wells([w[0] for w in control_wells])7. Create the transfer listexp.create_transfers()8. Sort transfer list for optimized transfer speedexp.sort_transfers()9. Save transfer list - Echo formatted CSV fileexp.save_transfers(save_filepath)10. Save *.cmt file - Screener Mapping FileOPTIONAL- Set replicate number to create replicate plates with the same plate mapping and concentrationsexp.save_cmt(cmt_filepath, 3)IN A NEW SESSIONThis must be done after using the Echo CSV to transfer samples11. Update CMT with barcodes after performing transfersThis is a new python session - initialize the module againimport Combinations as Combinecmt_filepath = "Example_Files\\ExampleOutput4.cmt"barcode_filepath = "Example_Files\\Barcode_List.csv"Update barcodesCombine.update_CMT_barcodes(cmt_filepath, barcode_filepath)