opentrons 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a694979ecde2e5c60ccc42fb31cd781b696c21b6
-  data.tar.gz: dde63e64ad2ea5c05d45aaf045d687edd1254486
+  metadata.gz: 95cdf5d0184ba33c091182c256d97d90cdd15d59
+  data.tar.gz: b0b638480c593846786765098f61942f05b9fbeb
 SHA512:
-  metadata.gz: 1e552df10640109eab25d0757ed386d47a8048e7d897fd5f9f0fe91a1ebfe5a7c66f8aa324c6b894012b5eaed970642a6c5f2472950ef71743b173867b90df6f
-  data.tar.gz: aa45050996fdd491ab40d78890e551eea07eae02e1805b6ee6a0c72d930e463840aa15b7a27feffdd40f0838de883caf78bbcf5610d0c3c29ee0a409fa1156d0
+  metadata.gz: 6f1cd9e362d4288610f59f7cc19fed1d49b36c0c646876f2386e66332d3f459e3be336eff467014d38fb56ecf0a2f0f7bf2707216a6b43f20c87a18f629dba7a
+  data.tar.gz: 39b157b04679225ba97a5658dd995ea762c2ab13a62eb5221bfdb8c724b712e2f7bac2a052cfe7dedf7896dc91d7d798e2a2edd0a7d9de28ac23c542047fa490

data/lib/opentrons/commands.rb

@@ -0,0 +1,127 @@
+module OpenTrons
+	class Commands
+		attr_accessor :protocol, :command_list
+
+		def initialize(protocol)
+			@protocol = protocol
+			@command_list = []
+		end
+
+		# return a pure list of hashes
+		def to_list
+			return command_list.map {|command| command.to_hash}
+		end
+
+		def to_s
+			"<OpenTron::Commands:0x#{self.__id__.to_s(16)}>"
+		end
+
+		def inspect
+			to_s
+		end
+	end
+
+	class Command
+		attr_accessor :command, :params
+
+		#parent class for all the comands
+		def initialize(command, params)
+			@command = command
+			@params = params
+		end
+
+		def to_hash
+			as_hash = {}
+			as_hash["command"] = command
+			as_hash["params"] = params
+			return as_hash
+		end
+
+		def to_s
+			"<OpenTron::Command:0x#{self.__id__.to_s(16)}>"
+		end
+
+		def inspect
+			to_s
+		end
+	end
+
+	class PipetteCommand < Command
+		attr_accessor :pipette, :location
+
+		def initialize(command, pipette, location)
+			super(command, {})
+
+			pipette_id = pipette.instruments.instrument_hash.key pipette
+			params["pipette"] = pipette_id
+
+			if location.is_a? Array
+				labware_item = location[0].labware_item
+				params["labware"] = labware_item.labware.labware_hash.key labware_item
+				params["well"] = location[0].location
+				params["position"] = location[1]
+			else
+				labware_item = location.labware_item
+				params["labware"] = labware_item.labware.labware_hash.key labware_item
+				params["well"] = location.location
+			end
+		end
+	end
+
+	class VolumeCommand < PipetteCommand
+		attr_accessor :volume
+
+		def initialize(command, pipette, volume, location)
+			super(command, pipette, location)
+			params["volume"] = volume
+		end
+	end
+
+	class Delay < Command
+		def initialize(wait, message)
+			super("delay", {"wait" => wait, "message" => message})
+		end
+	end
+
+	class Aspirate < VolumeCommand
+		def initialize(pipette, volume, location)
+			super("aspirate", pipette, volume, location)
+		end
+	end
+
+	class Dispense < VolumeCommand
+		def initialize(pipette, volume, location)
+			super("dispense", pipette, volume, location)
+		end
+	end
+
+	class AirGap < VolumeCommand
+		def initialize(pipette, volume, location)
+			super("air-gap", pipette, volume, location)
+		end
+	end
+
+	class PickUpTip < PipetteCommand
+		def initialize(pipette, location)
+			super("pick-up-tip", pipette, location)
+		end
+	end
+
+	class DropTip < PipetteCommand
+		def initialize(pipette, location)
+			super("drop-tip", pipette, location)
+		end
+	end
+
+	class TouchTip < PipetteCommand
+		def initialize(pipette, location)
+			super("touch-tip", pipette, location)
+		end
+	end
+
+	class BlowOut < PipetteCommand
+		def initialize(pipette, location)
+			super("blowout", pipette, location)
+		end
+	end
+end

data/lib/opentrons/instruments.rb

@@ -0,0 +1,243 @@
+module OpenTrons
+	PIPETTE_NAMES = {
+		P10_Single: "p10_single_v1",
+		P10_Multi: "p10_multi_v1",
+		P50_Single: "p50_single_v1",
+		P50_Multi: "p50_multi_v1",
+		P300_Single: "p300_single_v1",
+		P300_Multi: "p300_multi_v1",
+		P1000_Single: "p1000_single_v1",
+		P1000_Multi: "p1000_multi_v1"
+	}
+
+	class Instruments
+		attr_accessor :protocol, :instrument_hash
+
+		def initialize(protocol)
+			@protocol = protocol
+			@instrument_hash = {}
+		end
+
+		# Individual methods to maintain similarities w/ Python API.
+		PIPETTE_NAMES.each do |method_name, pipette_name|
+			define_method(method_name) do |**kwargs|
+
+				mount = kwargs.fetch(:mount, "left")
+				tip_racks = kwargs.fetch(:tip_racks, [])
+				tip_model = kwargs.fetch(:tip_model, nil)
+
+  				return add_pipette(pipette_name, mount: mount, tip_racks: tip_racks, tip_model: tip_model)
+			end
+		end
+
+		def add_pipette(model, mount: "left", tip_racks: [], tip_model: nil)
+			instrument_hash.each do |key, item|
+				if item.mount == mount
+					raise ArgumentError.new "Cannot place #{model} on mount #{mount} (already occupied)."
+				end
+			end
+
+			generated_id = ""
+			loop do
+				generated_id = model + "-" + rand(100000...999999).to_s
+				break if !(instrument_hash.key? generated_id)
+			end
+
+			if model.include? "multi"
+				pipette = MultiPipette.new(protocol, self, model, mount: mount, tip_racks: tip_racks, tip_model: tip_model)
+			else
+				pipette = Pipette.new(protocol, self, model, mount: mount, tip_racks: tip_racks, tip_model: tip_model)
+			end
+
+			instrument_hash[generated_id] = pipette
+
+			return pipette
+		end
+
+		def to_hash
+			as_hash = {}
+			instrument_hash.each do |key, item|
+				as_hash[key] = item.to_hash
+			end
+			return as_hash
+		end
+
+		def to_s
+			"<OpenTron::Instruments:0x#{self.__id__.to_s(16)}>"
+		end
+
+		def inspect
+			to_s
+		end
+	end
+
+	class Pipette
+		attr_accessor :protocol, :instruments, :mount, :model, :tip_racks, :tip_model
+
+		def initialize(protocol, instruments, model, mount: "left", tip_racks: [], tip_model: nil)
+			@protocol = protocol
+			@instruments = instruments
+			@model = model
+
+			@mount = mount
+			@tip_racks = tip_racks
+			@tip_model = tip_model
+		end
+
+		def to_hash
+			as_hash = {}
+			as_hash["mount"] = mount
+			as_hash["model"] = model
+			return as_hash
+		end
+
+		def to_s
+			"<OpenTron::Pipette:0x#{self.__id__.to_s(16)}>"
+		end
+
+		def inspect
+			to_s
+		end
+
+		def aspirate(volume, location)
+			command = Aspirate.new(self, volume, location)
+			protocol.commands.command_list << command
+			return command
+		end
+
+		def dispense(volume, location)
+			command = Dispense.new(self, volume, location)
+			protocol.commands.command_list << command
+			return command
+		end
+
+		# For whatever reason, air gap has no location in Python API but has a location in the JSON schema.
+		# Not implemented for now.
+		# def air_gap(volume, location)
+		# 	command = Aspirate.new(self, volume, location)
+		# 	self.protocol.commands << command
+		# 	return command
+		# end
+
+		def get_next_tip(multi: false)
+			location = nil
+			catch :tip_found do
+				tip_racks.each do |tip_rack|
+					tip_rack.well_list.each do |column|
+						if multi
+							if column.all? {|x| x.tip}
+								location = column[0]
+								throw :tip_found
+							end
+						else
+							column.each do |x|
+								if x.tip
+									location = x
+									throw :tip_found
+								end
+							end
+						end
+					end
+				end
+				return false
+			end
+
+			return location
+		end
+
+		def pick_up_tip(location=false)
+			if !location
+				tip_location = self.get_next_tip()
+				# If no tip found and tip model is provided, create a tip rack.
+				if !tip_location
+					if tip_model
+						tip_racks << protocol.labware.load(tip_model, protocol.labware.free_slots[-1], 'Auto-generated-tip-rack')
+					else
+						raise ArgumentError.new "pick_up_tip called without location and pipette is out of tips."
+					end
+				end
+				tip_location = self.get_next_tip()
+				location = tip_location
+			end
+
+			if location.is_a? Array
+				well = location[0]
+			else
+				well = location
+			end
+
+			if !(well.tip)
+				puts "Warning: Already picked up tip at #{location}."
+			else
+				well.tip = false
+			end
+
+			command = PickUpTip.new(self, location)
+			protocol.commands.command_list << command
+			return command
+		end
+
+		def drop_tip(location=false)
+			location = protocol.trash.wells(0) if !location
+			command = DropTip.new(self, location)
+			protocol.commands.command_list << command
+			return command
+		end
+
+		def touch_tip(location)
+			command = TouchTip.new(self, location)
+			protocol.commands.command_list << command
+			return command
+		end
+
+		def blowout(location)
+			command = Blowout.new(self, location)
+			protocol.commands.command_list << command
+			return command
+		end
+
+		def delay(wait, message: "")
+			command = Delay.new(wait, message)
+			protocol.commands.command_list << command
+			return command
+		end
+	end
+
+	class MultiPipette < Pipette
+		def initialize(protocol, instruments, model, mount: "left", tip_racks: [], tip_model: nil)
+			super(protocol, instruments, model, mount: mount, tip_racks: tip_racks, tip_model: tip_model)
+		end
+
+		def pick_up_tip(location: false)
+			if !location
+				tip_location = self.get_next_tip(multi: true)
+				# If no tip found and tip model is provided, create a tip rack.
+				if !tip_location
+					if tip_model
+						tip_racks += protocol.labware.load(tip_model, protocol.labware.free_slots[-1], 'Auto-generated-tip-rack')
+					else
+						raise ArgumentError.new "pick_up_tip called without location and pipette is out of tips."
+					end
+				end
+				tip_location = self.get_next_tip(multi: true)
+				location = tip_location
+			end
+
+			if location.is_a? Array
+				well = location[0]
+			else
+				well = location
+			end
+
+			column = well.labware_item.well_list.find do |column|
+				column.include? well
+			end
+
+			column.each {|x| x.tip = false}
+			
+			command = PickUpTip.new(self, location)
+			protocol.commands.command_list << command
+			return command
+		end
+	end
+end

data/lib/opentrons/labware.rb

@@ -0,0 +1,156 @@
+module OpenTrons
+	class Labware
+		attr_accessor :protocol, :labware_hash, :labware_definitions
+
+		def initialize(protocol)
+			@protocol = protocol
+			@labware_hash = {}
+
+			#TODO: Better system for dealing with labware defs, including user-specified.
+			@labware_definitions = []
+			directory = File.expand_path(File.dirname(__FILE__))
+			directory = File.join(directory, "..", "..", "definitions")
+			Dir[directory + "/*.json"].each do |filename|
+				labware_definitions << JSON.parse(File.read(filename))
+			end
+		end
+
+		def load(model, slot, display_name="")
+			generated_id = ""
+			loop do
+				generated_id = display_name + "-" + rand(100000...999999).to_s
+				break if !(labware_hash.key?(generated_id))
+			end
+
+			labware_item = LabwareItem.new(self, model, slot, display_name)
+
+			labware_hash[generated_id] = labware_item
+
+			return labware_item
+		end
+
+		def free_slots
+			slots = (1..12).to_a.map{|x| x.to_s}
+			taken_slots = labware_hash.map {|key, item| item.slot}
+			return slots.select{|x| !(taken_slots.include? x)}
+		end
+
+		# Returns a pure hash of hashes.
+		def to_hash
+			as_hash = {}
+			labware_hash.each do |key, item|
+				as_hash[key] = item.to_hash
+			end
+			return as_hash
+		end
+
+		def to_s
+			"<OpenTron::Labware:#{object_id}>"
+		end
+
+		def inspect
+			to_s
+		end
+	end
+
+	class LabwareItem
+		attr_accessor :labware, :well_list, :model, :slot, :display_name, :definition
+
+		def initialize(labware, model, slot, display_name)
+			if labware.labware_hash.map {|key, item| item.slot}.include? slot
+				raise ArgumentError.new "Cannot place #{display_name} in slot #{slot} (already occupied)."
+			end
+
+			@labware = labware
+			@model = model
+			@slot = slot
+			@display_name = display_name
+			@definition = labware.labware_definitions.find{|x| x["metadata"]["name"] == model}
+			@well_list = []
+			definition["ordering"].each do |column|
+				well_list << column.map {|x| Well.new(self, x)}
+			end
+
+		end
+
+		def wells(location=nil)
+			if location.is_a? String
+				well_list.each do |column|
+					column.each do |x|
+						if x.location == location
+							return x
+						end
+					end
+				end
+				return ArgumentError.new "Well #{location} is out of range."
+			elsif location.is_a? Integer
+				i = location
+				well_list.each do |column|
+					column.each do |x|
+						if i == 0
+							return x
+						end
+						i -= 1
+					end
+				end
+				return ArgumentError.new "Well #{location} is out of range."
+			else
+				return well_list
+			end
+		end
+
+		def to_hash
+			as_hash = {}
+			as_hash["model"] = model
+			as_hash["slot"] = slot
+			as_hash["display-name"] = display_name
+			return as_hash
+		end
+
+		def to_s
+			"<OpenTron::LabwareItem:0x#{self.__id__.to_s(16)}>"
+		end
+
+		def inspect
+			to_s
+		end
+	end
+
+	class Well
+		attr_accessor :labware_item, :location, :tip
+
+		def initialize(labware_item, location)
+			@labware_item = labware_item
+			@location = location
+			@tip = true
+		end
+
+		def top(z)
+			position = {
+				"anchor" => "top",
+				"offset" => {
+					"z" => z
+				}
+			}
+			return [self, position]
+		end
+
+		def bottom(z)
+			position = {
+				"anchor" => "bottom",
+				"offset" => {
+					"z" => z
+				}
+			}
+			return [self, position]
+		end
+
+		def to_s
+			"<OpenTron::Well:0x#{self.__id__.to_s(16)}>"
+		end
+
+		def inspect
+			to_s
+		end
+	end
+end

data/lib/opentrons/otprotocol.rb

@@ -0,0 +1,81 @@
+module OpenTrons
+	# This gem is not a product of OpenTrons.
+	# 
+	# This version of the gem provides some basic functionality for creating and editing OpenTrons JSON-format 
+	# protocols in Ruby. The organization of the methods should be familiar to anyone who has used
+	# the official OpenTrons Python API.
+	# 
+	# Examples:
+	#     Import the gem: require 'opentrons'
+	#     Create a protocol: p = OpenTrons::OTProtocol.new
+	#     Create a labware item: block = p.labware.load('96-deep-well', '2', 'culture_block')
+	#     Create a tiprack: tip_rack_1 = p.labware.load('tiprack-10ul', '3', 'tiprack-10ul')
+	#     Create a pipette: p10 = p.instruments.P10_Single(mount: 'left', tip_racks: [tip_rack_1])
+	#     Pick up a tip: p10.pick_up_tip()
+	#     Add an aspirate command: p10.aspirate(10, block.wells(0))
+	#     Add a dispense command: p10.dispense(10, block.wells(1).top(2))
+	#     Discard tip: p10.drop_tip()
+	# 
+	# Examples for saving protocols:
+	#     Generate a hash of the protocol: p.to_hash
+	#     Generate a JSON string of the protocol: p.to_json
+	#     Save a protocol as a JSON file: File.open("protocol.json", 'w') {|f| f.write(p.to_json)}
+	# 
+	# Limitations of current version:
+	#     -Built for OT protocol JSON schema 1.0 (which is not the final version).
+	#         https://github.com/Opentrons/opentrons/blob/391dcebe52411c432bb6f680d8aa5952a11fe90f/shared-data/protocol-json-schema/protocol-schema.json
+	#     -Custom containers yet supported
+	#     -Modules (heat and magnetic) not yet supported
+	#     -Complex liquid handling shortcuts not yet supported
+	#     -Loading and editing existing protocols from JSON not yet supported.
+	#     -Error checking not very robust
+	#     -And more...
+	class OTProtocol
+		attr_accessor :protocol_schema, :robot, :designer_application, :metadata, :labware, :instruments, :commands, :trash
+		
+		def initialize(params: {})
+			@protocol_schema = params.fetch(:protocol_schema, "1.0.0")
+			@robot = params.fetch(:robot, {"model" => "OT-2 Standard"})
+			@designer_application = params.fetch(:designer_application, {})
+			@metadata = params.fetch(:metadata, {})
+
+			@labware = params.fetch(:labware, Labware.new(self))
+			@trash = labware.load('fixed-trash', '12', 'Trash')
+
+			@instruments = params.fetch(:instruments, Instruments.new(self))
+
+			@commands = params.fetch(:commands, Commands.new(self))
+		end
+
+		def to_hash(check_validity: true)
+			# Returns entire protocol as an OT-protocol-format hash (which can then be converted to json).
+			protocol_hash = {}
+
+			protocol_hash["protocol-schema"] = protocol_schema
+			protocol_hash["robot"] = robot
+			protocol_hash["designer_application"] = designer_application
+			protocol_hash["metadata"] = metadata
+
+			protocol_hash["labware"] = labware.to_hash
+
+			protocol_hash["pipettes"] = instruments.to_hash
+
+			protocol_hash["procedure"] = [{"subprocedure" => commands.to_list}]
+
+			return protocol_hash
+		end
+
+		def to_json(check_validity: true)
+			#converts protocol to a JSON-formatted string
+			return self.to_hash.to_json
+		end
+
+		def to_s
+			"<OpenTron::OTProtocol:0x#{self.__id__.to_s(16)}>"
+		end
+
+		def inspect
+			to_s
+		end
+	end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentrons
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Nick Emery
@@ -18,6 +18,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/opentrons.rb
+- lib/opentrons/commands.rb
+- lib/opentrons/instruments.rb
+- lib/opentrons/labware.rb
+- lib/opentrons/otprotocol.rb
 homepage: https://github.com/emernic/opentrons_gem
 licenses:
 - LICENSE.txt