lis 0.2.1 → 0.2.2

data/README.markdown

@@ -1,9 +1,19 @@
 # LIS
 
-A simple interface to medical laboratory instruments. It implments a rough subset of ASTM E1394-97 (or, possibly CLSI LIS02-A2)
+A simple interface to medical laboratory instruments. It implements a rough subset of ASTM E1394-97 (or, possibly CLSI LIS02-A2)
 
 It listens for test requests and results and forwards them via HTTP.  It is intended to interface with the [worklist_manager](http://github.com/levinalex/worklist_manager) web application.
 
+
+Developed for and tested with [DPC Immulite I2500][immulite] ([user manual][manual]) using the LIS specification version **600129-H** (not available online, but a [similar version might be
+available][spec])
+
+[immulite]: http://www.google.com/search?q=dpc+immulite+I2500
+[manual]: http://sky2.ch/Doc/I2500.pdf
+[spec]: http://www.google.com/search?q=dpc+lis+immulite+2000+filetype:pdf
+
+
+
 ## Copyright
 
-Copyright (c) 2010 Levin Alexander. See LICENSE for details.
+Copyright (c) 2010-2011 Levin Alexander. See LICENSE for details.

data/Rakefile

@@ -15,5 +15,8 @@ end
 require 'cucumber/rake/task'
 Cucumber::Rake::Task.new(:features)
 
-task :default => [:test, :features]
+require 'yard'
+YARD::Rake::YardocTask.new
 
+task :doc => :yard
+task :default => [:test, :features]

data/bin/lis2http

@@ -1,6 +1,6 @@
-#!/usr/bin/env ruby1.9
+#!/usr/bin/env ruby
 
-require 'lib/lis.rb'
+require 'lis'
 require 'lis/commands/application.rb'
 
 LIS::Application.new(ARGV).run!

data/features/lis.feature

@@ -1,50 +1,75 @@
 Feature:
-  In order to value
-  As a role
-  I want feature
+  In order to diagnose patients correctly
+  As a doctor
+  I want to be able to receive test results via LIS
+
+  Scenario: LIS asking for pending requests
+    Given LIS Interface listening for messages
+    And the following requests are pending for DPC:
+      | id     | patient_id | last_name | first_name | test_names                   |
+      | 123ABC | 98         | Sierra    | Rudolph    | TSH, FT3, FT4, FOO, BAR, BAZ |
+    When receiving data
+    """
+      1H|\^&||PASSWORD|DPC||Randolph^New^Jersey^07869||(201)927-2828|N81|Your System||P|1|19940407120613 51
+      2Q|1|^123ABC||ALL||||||||O 76
+      3L|1
+    """
+    Then LIS should have sent test orders to client:
+    """
+      1H|\^&|||LIS||||8N1|DPC||P|1|
+      2P|1||||Sierra^Rudolph||||||||
+      3O|1|123ABC||^^^TSH
+      4O|1|123ABC||^^^FT3
+      5O|1|123ABC||^^^FT4
+      6O|1|123ABC||^^^FOO
+      7O|1|123ABC||^^^BAR
+      0O|1|123ABC||^^^BAZ
+      1L|1|N
+    """
 
   Scenario: sending results from Immulite to LIS
     Given LIS Interface listening for messages
-    When receiving
+    When receiving data
     """
-      H|\^||PASSWORD|DPC||||SYSTEM||P|1|19940407085426
-      P|1|119813;TGH|||Last 1^First 1|||F|||||
-      O|1|130000445||^^^TT4|||19950118085700
-      R|1|^^^TT4|10.3|ug/dL|4.5\.4^12.5\24|N|N|F||test|19950119084508|19950119092826|SenderID
-      O|2|130000445||^^^TU|||19950118085700
-      R|1|^^^TU|26.6|Percnt|23\10^35\70|N|N|F||test|19950119084508|19950119092756|SenderID
-      P|2|325031;AH|||Last 2^First 2|||F|||||
-      O|1|130000617||^^^FER|||19950118103000
-      R|1|^^^FER|173.|ng/mL|.5\.5^1500\1500|N|N|F||test|19950119084641|19950119092858|SenderID
-      P|3|326829;AH|||Last 3^First 3|||F|||||
-      O|1|130000722||^^^FER|||19950118102000
-      R|1|^^^FER|490.|ng/mL|.5\.5^1500\1500|N|N|F||test|19950119084741|19950119092928|SenderID
-      P|4|124462;TGH|||Last 4^First 4|||F|||||
-      O|1|130000724||^^^E2|||19950118122000
-      R|1|^^^E2|25.3|pg/mL|12\12^2000\2000|N|N|F||test|19950119084815|19950119100049|SenderID
-      O|2|130000724||^^^FSH|||19950118122000
-      R|1|^^^FSH|60.6|mIU/mL|.1\.1^170\170|N|N|F||test|19950119084815|19950119093030|SenderID
-      O|3|130000724||^^^LH|||19950118122000
-      R|1|^^^LH|24.4|mIU/mL|.7\.7^400\400|N|N|F||test|19950119084815|19950119093101|SenderID
-      P|5|556395;AH|||Last 5^First 5|||M|||||
-      O|1|130000741||^^^FER|||19950118115500
-      R|1|^^^FER|238.|ng/mL|.5\.5^1500\1500|N|N|F||test|19950119084949|19950119093132|SenderID
-      P|6|556357;MB|||Last 6^First 6|||M|||||
-      O|1|130000790||^^^IGE|||19950118120000
-      R|1|^^^IGE|517.|IU/mL|.01\.01^600\600|N|N|F||test|19950119085018|19950119093202|SenderID
-      P|7|141053;TGH|||Last 7^First 7|||F|||||
-      O|1|130000805||^^^FER|||19950118120000
-      R|1|^^^FER|21.0|ng/mL|.5\.5^1500\1500|N|N|F||test|19950119085049|19950119093233|SenderID
-      P|8|320439;TGH|||Last 8^First 8|||F|||||
-      O|1|130000890||^^^FER|||19950118130000
-      R|1|^^^FER|12.9|ng/mL|.5\.5^1500\1500|N|N|F||test|19950119085254|19950119093609|SenderID
-      P|9||||Last 9^First 9||||||||
-      O|1|130000911||^^^E2
-      R|1|^^^E2|71.3|pg/mL|12\12^2000\2000|N|N|F||test|19950119085423|19950119100800|SenderID
-      P|10|358069;TGH|||Last 10^First 10|||F|||||
-      O|1|130000929||^^^FER|||19950118123000
-      R|1|^^^FER|219.|ng/mL|.5\.5^1500\1500|N|N|F||test|19950119085628|19950119093843|SenderID
-      L|1
+      1H|\^||PASSWORD|DPC||||SYSTEM||P|1|19940407085426
+      2P|1|119813;TGH|||Last 1^First 1|||F|||||
+      3O|1|130000445||^^^TT4|||19950118085700
+      4R|1|^^^TT4|10.3|ug/dL|4.5\.4^12.5\24|N|N|F||test|19950119084508|19950119092826|SenderID
+      5O|2|130000445||^^^TU|||19950118085700
+      6R|1|^^^TU|26.6|Percnt|23\10^35\70|N|N|F||test|19950119084508|19950119092756|SenderID
+      7P|2|325031;AH|||Last 2^First 2|||F|||||
+      1O|1|130000617||^^^FER|||19950118103000
+      2R|1|^^^FER|173.|ng/mL|.5\.5^1500\1500|N|N|F||test|19950119084641|19950119092858|SenderID
+      3P|3|326829;AH|||Last 3^First 3|||F|||||
+      4O|1|130000722||^^^FER|||19950118102000
+      5R|1|^^^FER|490.|ng/mL|.5\.5^1500\1500|N|N|F||test|19950119084741|19950119092928|SenderID
+      6P|4|124462;TGH|||Last 4^First 4|||F|||||
+      7O|1|130000724||^^^E2|||19950118122000
+      1R|1|^^^E2|25.3|pg/mL|12\12^2000\2000|N|N|F||test|19950119084815|19950119100049|SenderID
+      2O|2|130000724||^^^FSH|||19950118122000
+      3R|1|^^^FSH|60.6|mIU/mL|.1\.1^170\170|N|N|F||test|19950119084815|19950119093030|SenderID
+      4O|3|130000724||^^^LH|||19950118122000
+      5R|1|^^^LH|24.4|mIU/mL|.7\.7^400\400|N|N|F||test|19950119084815|19950119093101|SenderID
+      6P|5|556395;AH|||Last 5^First 5|||M|||||
+      7O|1|130000741||^^^FER|||19950118115500
+      1R|1|^^^FER|238.|ng/mL|.5\.5^1500\1500|N|N|F||test|19950119084949|19950119093132|SenderID
+      2P|6|556357;MB|||Last 6^First 6|||M|||||
+      3O|1|130000790||^^^IGE|||19950118120000
+      4R|1|^^^IGE|517.|IU/mL|.01\.01^600\600|N|N|F||test|19950119085018|19950119093202|SenderID
+      5L|1
     """
-    Then should have posted results:
-      | device_name | barcode |
+    Then the server should have acknowledged 27 packets
+    And should have posted results:
+      | id            | test_name   | value  | unit   | status | flags | result_timestamp          |
+      | DPC-130000445 | TT4         | 10.3   | ug/dL  | F      | N     | 1995-01-19T09:28:26+00:00 |
+      | DPC-130000445 | TU          | 26.6   | Percnt | F      | N     | 1995-01-19T09:27:56+00:00 |
+      | DPC-130000617 | FER         | 173.   | ng/mL  | F      | N     | 1995-01-19T09:28:58+00:00 |
+      | DPC-130000722 | FER         | 490.   | ng/mL  | F      | N     | 1995-01-19T09:29:28+00:00 |
+      | DPC-130000724 | E2          | 25.3   | pg/mL  | F      | N     | 1995-01-19T10:00:49+00:00 |
+      | DPC-130000724 | FSH         | 60.6   | mIU/mL | F      | N     | 1995-01-19T09:30:30+00:00 |
+      | DPC-130000724 | LH          | 24.4   | mIU/mL | F      | N     | 1995-01-19T09:31:01+00:00 |
+      | DPC-130000741 | FER         | 238.   | ng/mL  | F      | N     | 1995-01-19T09:31:32+00:00 |
+      | DPC-130000790 | IGE         | 517.   | IU/mL  | F      | N     | 1995-01-19T09:32:02+00:00 |
+
+
+

data/features/step_definitions/lis_steps.rb

@@ -0,0 +1,80 @@
+require 'mocha'
+require 'yaml'
+
+
+Given /^LIS Interface listening for messages$/ do
+  @client, @r, @w = PacketIO::Test::MockServer.build
+  @io = PacketIO::IOListener.new(@r, @w)
+  @server = LIS::InterfaceServer.create(@io, "http://localhost/lis/")
+
+  stub_request(:post, /http:\/\/localhost\/lis\/result\/.*/).
+    with(:body => /.*/, :headers => {'Accept'=>'*/*', 'Content-Type'=>'application/x-www-form-urlencoded', 'User-Agent'=>'Ruby'}).
+    to_return(:status => 200, :body => "", :headers => {})
+
+  @t = Thread.new do
+    @server.run!
+  end
+  @t.abort_on_exception = true
+end
+
+When /^receiving data$/ do |string|
+  @client.wait(0.2)
+  @client.write("\005")
+  string.each_line do |l|
+    line, checksum = l.strip.split(/\s*,\s*/)
+    checksum = line.each_byte.inject(16) { |a,b| (a+b) % 0x100 }.to_s(16) if checksum.nil?
+
+    @client.write("\002#{line}\015\003#{checksum}\015\012")
+  end
+  @client.write("\004")
+  @client.eof
+  @t.join
+end
+
+Then /^should have posted results:$/ do |table|
+  table.hashes.each do |row|
+    expected_body = ["test_name", "value", "unit", "status", "flags", "result_timestamp"].inject({}) { |h,k| h[k] = row[k]; h }
+    assert_requested(:post, "http://localhost/lis/result/#{row["id"]}", :times => 1, :body => expected_body)
+  end
+end
+
+Then /^the server should have acknowledged (\d+) packets$/ do |packet_count|
+  @data = @client.read_all
+  assert_equal packet_count.to_i, @data.split(//).length
+  assert @data.match(/^\006{#{packet_count}}$/), "should contain #{packet_count.to_i} ACKs, was #{@data.inspect}"
+end
+
+
+# FIXME: test following redirects
+#
+Given /^the following requests are pending for (\w+):$/ do |device_name, table|
+  table.hashes.each do |patient|
+    p patient
+
+    body = { "patient" => { "last_name" => patient["last_name"],
+                            "first_name" => patient["first_name"],
+                            "id" => patient["patient_id"]},
+             "id" => patient["id"],
+             "types" => patient["test_names"].strip.split(/\s+/) }
+    p body
+
+    stub_request(:get, "http://localhost/lis/find_requests/#{device_name}-#{patient["id"]}").
+      with(:headers => {'Accept'=>'*/*', 'User-Agent'=>'Ruby'}).
+      to_return(:status => 200, :body => body.to_yaml, :headers => {})
+
+  end
+
+end
+
+
+Then /^LIS should have sent test orders to client:$/ do |text|
+  @data = @client.read_all
+  @packets = @data.split("\002").select { |s| s =~ /^\d[A-Z]/ }
+  @packets.zip(text.lines) do |actual, expected|
+    rx =  Regexp.new("^" + Regexp.escape(expected.strip))
+    assert_match(rx, actual.gsub(/\r\003.*$/, "").strip)
+  end
+end
+
+
+

data/features/support/env.rb

@@ -1,6 +1,9 @@
 $LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
 require 'lis'
 
+require 'packet_io/test/mock_server'
 require 'test/unit/assertions'
+require 'webmock/cucumber'
 
 World(Test::Unit::Assertions)
+

data/lib/lis/commands/application.rb

@@ -48,8 +48,8 @@ module LIS
     def run!
       warn "listening on: #{@options[:port]}"
       port = File.open(@options[:port], "w+")
-      LIS::InterfaceServer.new(port, @options[:uri]).run!
+      LIS::InterfaceServer.listen(port, @options[:uri]).run!
     end
   end
 
-end
+end

data/lib/lis/interface_server.rb

@@ -1,16 +1,25 @@
 module LIS
   class InterfaceServer
-    def initialize(port, http_endpoint)
-      @server  = LIS::Transfer::IOListener.new(port)
-      @packets = LIS::Transfer::PacketizedProtocol.new(@server)
+    def self.listen(port, http_endpoint)
+      interface = PacketIO::IOListener.new(port)
+      new(interface, http_endpoint)
+    end
+
+    def self.create(*args)
+      new(*args)
+    end
+
+
+    def initialize(server, http_endpoint, protocol_stack = [LIS::Transfer::ASTM::E1394, LIS::Transfer::ApplicationProtocol])
+      @server = server
+      protocol = protocol_stack.inject(server) { |i,klass| klass.new(i) }
+      interface = WorklistManagerInterface.new(http_endpoint)
 
-      app_protocol = LIS::Transfer::ApplicationProtocol.new(@packets)
-      interface    = WorklistManagerInterface.new(http_endpoint)
 
-      app_protocol.on_request do |device_name, barcode|
+      protocol.on_request do |device_name, barcode|
         interface.load_requests(device_name, barcode)
       end
-      app_protocol.on_result do |*args|
+      protocol.on_result do |*args|
         interface.send_result(*args)
       end
     end
@@ -19,5 +28,11 @@ module LIS
       warn "listener started" if $VERBOSE
       @server.run!
     end
+
+
+    class << self
+      private :new
+    end
   end
 end
+

data/lib/lis/messages/comment.rb

@@ -1,4 +1,7 @@
 module LIS::Message
+
+  # = Comment Message
+  #
   class Comment < Base
     type_id "C"
     has_field 3, :message

data/lib/lis/messages/header.rb

@@ -1,4 +1,30 @@
 module LIS::Message
+
+  # = Header Message
+  #
+  # First message sent in any transaction, contains system information such as sender ID, receiver ID, address, etc.
+  #
+  # == Message Examples
+  #
+  #  1H|\^&||PASSWORD|DPC CIRRUS||Flanders^New^Jersey^07836||973-927-2828|N81|Your System||P|1|19940407120613
+  #
+  # == Message Structure
+  #
+  # 1. Record Type (H)
+  # 2. Delimiter Def.
+  # 3. Message Control ID
+  # 4. Password
+  # 5. Sending systems company name
+  # 6. Sending Systems address
+  # 7. Reserved
+  # 8. Senders Phone#
+  # 9. Communication parameters
+  # 10. Receiver ID
+  # 11. Comments/special instructions
+  # 12. Processing ID
+  # 13. Version#
+  # 14. Message Date + Time
+  #
   class Header < Base
     type_id "H"
     has_field  2, :delimiter_definition, :default => "\\^&"
@@ -21,3 +47,4 @@ module LIS::Message
     end
   end
 end
+

data/lib/lis/messages/order.rb

@@ -1,4 +1,54 @@
 module LIS::Message
+
+  # = Order Message
+  #
+  # Defines which test, such as TSH or HCG, should be performed on the sample for a particular accession number.
+  #
+  # == Message Examples
+  #
+  #  3O|1|1550623||^^^LH|R|19931011091233|19931011091233
+  #
+  #  6O|1|130000724||^^^E2|||19950118122000
+  #
+  #  6O|1|66412558||^^^HCG|||200011081530||||||Normal|||||||||||E0872
+  #
+  #  1O|1|09861081||^^^TSH|R|||||||||||||||||||E0872
+  #
+  # == Message Structure
+  #
+  # 1. Record Type (O)
+  # 2. Sequence#
+  # 3. Specimen ID (Accession#)
+  # 4. Instrument Specimen ID
+  # 5. Universal Test ID
+  # 6. Priority
+  # 7. Order Date/Time
+  # 8. Collection Date/Time
+  # 9. Collection End Time
+  # 10. Collection Volume
+  # 11. Collector ID
+  # 12. Action Code
+  # 13. Danger Code
+  # 14. Relevant Clinical Info
+  # 15. Date/Time Specimen Received
+  # 16. Specimen Descriptor,Specimen Type,Specimen Source
+  # 17. Ordering Physician
+  # 18. Physician's Telephone Number
+  # 19. User Field No.1
+  # 20. User Field No.2
+  # 21. Lab Field No.1
+  # 22. Lab Field No.2
+  # 23. Date/Time results reported or last modified
+  # 24. Instrument Charge to Computer System
+  # 25. Instrument Section ID
+  # 26. Report Types
+  # 27. Reserved Field
+  # 28. Location or ward of Specimen Collection
+  # 29. Nosocomial Infection Flag
+  # 30. Specimen Service
+  # 31. Specimen Institution
+  #
+
   class Order < Base
     type_id "O"
 
@@ -33,3 +83,4 @@ module LIS::Message
     end
   end
 end
+

data/lib/lis/messages/patient.rb

@@ -1,4 +1,60 @@
 module LIS::Message
+
+  # = Patient Message
+  #
+  # Contains patient information, patient ID, name.
+  #
+  # == Message Examples
+  #
+  #  2P|1|101|||Riker^Al||19611102|F|||||Bashere
+  #
+  #  2P|3|326829;AH|||Last 3^First 3|||F|||||
+  #
+  #  2P|1|119813;TGH|||Last 1^First 1|||F|||||
+  #
+  #  5P|2|66412558|||||||||||
+  #
+  # == Message Structure
+  #
+  # 1. Record Type (P)
+  # 2. Sequence #
+  # 3. Practice Assigned Patient ID
+  # 4. Laboratory Assigned Patient ID
+  # 5. Patient ID
+  # 6. Patient Name
+  #      (Last^First^Initial; maximum of 20 characters for Last Name; maximum of 15 characters for First Name)
+  # 7. Mother's Maiden Name
+  # 8. BirthDate
+  #      (YYYYMMDD; maximum of 8 characters)
+  # 9. Patient Sex
+  #      (M or F; maximum of 1 character)
+  # 10. Patient Race
+  # 11. Patient Address
+  # 12. Reserved
+  # 13. Patient Phone #
+  # 14. Attending Physician ID
+  # 15. Special Field 1
+  # 16. Special Field 2
+  # 17. Patient Height
+  # 18. Patient Weight
+  # 19. Patients Known or Suspected Diagnosis
+  # 20. Patient active medications
+  # 21. Patients Diet
+  # 22. Practice Field #1
+  # 23. Practice Field #2
+  # 24. Admission and Discharge Dates
+  # 25. Admission Status
+  # 26. Location
+  # 27. Nature of Alternative Diagnostic Code and Classification
+  # 28. Alternative Diagnostic Code and Classification
+  # 29. Patient Religion
+  # 30. Marital Status
+  # 31. Isolation Status
+  # 32. Language
+  # 33. Hospital Service
+  # 34. Hospital Institution
+  # 35. Dosage Category
+  #
   class Patient < Base
     type_id "P"
 
@@ -21,3 +77,4 @@ module LIS::Message
 
   end
 end
+

data/lib/lis/messages/query.rb

@@ -1,4 +1,41 @@
 module LIS::Message
+
+  # = Query Message
+  #
+  # A request to the LIS for patient information and test orders. Contains the primary tube accession number.
+  #
+  # == Message Examples
+  #
+  #  2Q|1|^1234ABC||ALL|||||||O
+  #
+  # == Message Structure
+  #
+  # 1. Record Type ID (Q)
+  # 2. Sequence #
+  # 3. Starting Range
+  # 4. Ending Range
+  # 5. Test ID
+  # 6. Request Time Limits
+  # 7. Beginning request results date and time
+  # 8. Ending request results date and time
+  # 9. Physician name
+  # 10. Physician Phone Number
+  # 11. User Field 1
+  # 12. User Field 2
+  # 13. Status Codes
+  #      C - Correction of previous results
+  #      P - Preliminary Results
+  #      F - Final Results
+  #      X - Results cannot be done, cancel
+  #      I - Request Results Pending
+  #      S - Request partial results
+  #      M - Result is a MIC level
+  #      R - Result previously transmitted
+  #      A - Abort/cancel last request
+  #      N - Requesting new results only
+  #      O - Requesting orders and demographics
+  #      D - Requesting demographics only
+  #
   class Query < Base
     type_id "Q"
     has_field 3, :starting_range_id_internal
@@ -11,3 +48,4 @@ module LIS::Message
     end
   end
 end
+

data/lib/lis/messages/result.rb

@@ -1,4 +1,30 @@
 module LIS::Message
+
+  # = Result Message
+  #
+  # Contains test results and additional information, such as Test Code and the units in which the results are delivered. This message is sent to the LIS.
+  #
+  # == Message Examples
+  #
+  #  4R|1|^^^LH|8.2|mIU/mL|.7\.7^400\400|N|N|F||test|19931011091233|19931011091233|DPCCIRRUS
+  #
+  # == Message Structure
+  #
+  # 1. Record Type (R)
+  # 2. Sequence #
+  # 3. Universal Test ID
+  # 4. Data (result)
+  # 5. Units
+  # 6. ReferenceRanges
+  # 7. Result abnormal flags
+  # 8. Nature of Abnormality Testing
+  # 9. Result Status
+  # 10. Date of change in instruments normal values or units
+  # 11. Operator ID
+  # 12. Date/Time Test Started
+  # 13. Date/Time Test Completed
+  # 14. Instrument ID
+  #
   class Result < Base
     type_id "R"
     has_field  3, :universal_test_id_internal
@@ -18,3 +44,4 @@ module LIS::Message
     end
   end
 end
+

data/lib/lis/messages/terminator.rb

@@ -1,4 +1,19 @@
 module LIS::Message
+
+  # = Terminator Message
+  #
+  # Last message sent in a transaction, contains termination codes.
+  #
+  # == Message Examples
+  #
+  #  5L|1|N
+  #
+  # == Message Structure
+  #
+  # 1. Record Type ID (L)
+  # 2. Sequence Number
+  # 3. Termination Code
+  #
   class Terminator < Base
     TERMINATION_CODES = {
       "N" => "Normal termination",
@@ -14,3 +29,4 @@ module LIS::Message
     has_field 3, :termination_code, :default => "N"
   end
 end
+