Instrumentation

[mapesa]

1. How will the different lab equipment (e.g. FACS Counters, Genexpert, ...) interact with kBLIS?
2. Possible steps:
   • Fetch the data
     • Poll the machine for data
     • Listen on a port/socket for data
     • Read results from a dump file
   • Process the data, bearing in mind the Test from which it was requested
   • Store the data
3. Possible approach:
   • An interface that determines the general flow
   • Implementations define the nitty gritties for particular machines.

[mapesa]

Settled for the following as components of this feature:

1. Configurations for specifying details of available instruments

   • Host machine ip
   • Host machine hostname
   • Name of the instrument
   • Associated Tests (For each test, specify the Test name and the implementing PHP class name)

   For example:

   {
    "ip":"192.168.25.11",
    "hostname":"ndovu",
    "name":"Celtac F",
    "tests":{
        "Full Haemogram":"FullHaemogramInstrumentor",
        "WBC":"WBCInstrumentor",
        "HB":"HBInstrumentor"
     }
    }
   

2. The Instrumentor interface will have the following methods for each associated Test.
   • setInstrumentHost(String ip/hostname) //Receives host identification data
   • public Object[measure_name => value] getResult() // Returns test data from instrument host.
3. Results Entry Form
   • If an instrument is configured for this test, show a button for fetching results

Questions and my answers

• Who's responsible for matching results to particular tests/specimen? The data received does not necessarily have a test/specimen id recognizable by the system. Ultimately the Lab Technician performing the test. (Ideas on better control in this section are highly desirable)
• Can the results be pulled from all locations or restricted to the connected host? Preferably host restricted.
• In case of multiple results, should be provide a results resolution interface? Yes! This is where a Lab Technician working from the 'instrument host' can view multiple results that have been read into the system as a batch and map them to particular tests/specimen.
• How exactly does getResult() fetch data from the instrument? execute a script on instrument host that returns data? read from a file on instrument host? Its up to the implementation.

[briankip]

Configurations

• Hostname can be tricky I think, and since we are doing this in most likely the same subnet, we can reliably rely on the IP address. But we can also set the hostnames.
• For the tests each instrument most likely performs one test, with many measures
• for the instrumentor I also think parsing of the received data is crucial. Connecting and retrieving the data is the same across implementations, a simple get_file_contents(hostname/path/to/file.dump) parsing is the headache, removing nulls, and non printable characters and doing simple validating.

Questions

• In some cases for the celltac in Bungoma and Kapsaet, when they register the sample in the machine they also put the specimen number, and patient name from BLIS, and the dump file has this info, you can use this to improve validation. but in some cases they don't put the details. The most reliable way I have found to ensure data integrity is deleting the dump file when the lab tech is about to retrieve the results. I also suggest that we back up the data somewhere SQL or file, SQL would be better. for audits and stuff. We need to ensure that the data we send is 100% accurate.
• Actually the results can be pulled from anywhere, the catch is that you have to be next to the machine to hit the print button so that the details are dumped.
• It's possible but ensuring that you don't mix results in the current setup is next to impossible, since we are relying on humans to match the data. It would introduce errors.

• getresult() will use a simple get_file_contents as stated above.

  [client] --- retrievefiles()------> [server] ------getFileContents(host_with_celltac)------>[host_with_celltac]

  [host_with_celltac] -----data.dump---> [server | process()] ------clean_data.json----> client------->update_fullhemogram_form(clean_data.json)

[mapesa]

Ready for review

Features

• Instrumentation views under Lab Configuration menu
  • Add/Edit/Delete Instrument
  • Define what tests an instrument can perform and the corresponding instrumentation class name
• Instrumentation Interface and sample implementing class (KBLIS\Instrumentation\CelltacWBC)

Pending

• Tests
• Documentation

[briankip]

• The Celltac machine handles Full Haemogram test, WBC is essentially a measure.
• I don't think one machine can handle 2 or more tests, thus the check boxes should be radio button.
• For something that depends on code, creating a configuration UI is pointless(the place where you put the class name),
• Storing the name of a class in a DB, and executing code based on that user input, points to a design/architectural flaw, may lead to security Issues, errors e.t.c I don't know, it just feels wrong. Nay evil.
• Error when clicking fetch on the seed WBC test {"error":{"type":"Symfony\\Component\\Debug\\Exception\\FatalErrorException","message":"Class 'KBLIS\\Instrumentation\\CelltacWBC' not found","file":"\/var\/www\/larablis\/app\/controllers\/InstrumentController.php","line":197}}
• psr4 versus autoload, you could have put app/kblis in the autoload section,
• you have put the instrumentation stuff in app/kblis/instrumentation and I have put the api stuff in app/api we need to come up with a standard place to put these code, also how to load them. psr4 or autoload.

In the AbstractInstumentor->setIp you are using a varaible $id instead of $ip

• 2 days review ???

[mapesa]

@briankip, excellent calls especially about the evil security hole. I'll rework the implementation and get back ... and yes, in 2 days

Minor issues:

• I'd still say machines can carry out more than 1 test type. Its evident that Full Haemogram is really a panel of tests comprising of 3 evaluations:
  • white blood cells (WBC),
  • red blood cells (RBC, HB, HCT, MCV, MCH, MCHC, RDW)
  • platelets (count, MPV, PDW)
• At times a test request may be a subset of the Full Haemogram e.g. just the platelet count test. Nothing stops the lab staff from using the Celltac machine to perform these test.
• psr4 vs autload? I'll research.
• On the error, it must be an auto-loading issues.
• Location of files: I think api is too generic a name. Further I think we should be using packages/name spaces. Probably tied to the psr4 issue. I'll do more research.

[mapesa]

Quick update!

• Still working on a plugin model as I explained to you the other day
• On autoload vs psr-4, there are some subtle efficiency gains but apparently these are unlikely relevant given the size of our application. Here's an explanation. Answer 3 gives a summary that I find most appropriate to this case:
  • After making changes to a class files you need to do the following:
  • classmap: composer dumpautoload -o
  • psr-0: composer dumpautoload -o
  • psr-4: nothing

Disclaimer: I'm still trying to correlate these answers with my personal coding experience.

[mapesa]

@briankip, I've streamlined the way to import plugins (really php class files extending KBLIS\instrumentation\Abstract) into the system. See if you like it any better.

Pending

• Make Fetch button pick the results. I propose to do the following:
  • If there is only one machine configured for the test, attempt fetch results from it
  • If there more than one machine configured for the test, provide a popup where the user can select which to use.

[mapesa]

@briankip, nimemaliza kwa sasa. Please review!

• Pop-up for handling multiple machines is an overkill for now. Wont do! I'm picking the first one.

[briankip]

• enterResults.blade.php:16 you could use @forelse
• I am slowly adding helper functions so instead of $test->test_status_id != Test::VERIFIED we can do $test->isVerified(), more readable and easier to understand. I urge us all @kitsao @ereng to add these useful helpers and use them
• Is the new driver supposed to be attached to a specific instrument, if so, its confusing that there are two buttons for adding the equipment and driver on the same page, the driver addition should be in the view equipment page.
• Add equipment does not allow you to add, there's a drop down instead of a text box.
• If I add a driver that does not extend AbstractInstrumentor or does not implement the abstract methods, it fails with fatal error. You could try and check first.
• What is the $plugs array used for. I just see it hanging around.
• Also we are supposed to unify the way we do these plugins and other, you can do a Wiki or something.
• driver_name in lieu of class name, :joy:

Otherwise it looks good for a merge.

[mapesa]

• From what I've seen, @forelse is a looping structure. In enterResults.blade.php:16, all I want to do is ensure that there is at least 1 machine that can this test. If so, I show the Fetch button.
• I explained why the 2 buttons and why the drop-down. I've added docs on the wiki to explain.
• Fixed fatal errors due to invalid class file. Its hard to catch all these. That's why we warn the user.
• driver_name/class_name. I had to try to fool you one way or another :joy:

@briankip, please check again.

[briankip]

This is OK.

We just need to put it to a semi-actual test, we set up a machine on the Lan, make a small web app that dumps dummy data to file, and then we try to pick it and parse it. Pretty much like in the actual case.

[voleche09]

Does kblis have any api to integrate to other systems?

[ereng]

Does kblis have any api to integrate to other systems?

https://github.com/ilabafrica/Blis-V3/releases/tag/v3.0-alpha does to EMR, to Automated Machine Client.... this is the Automated Machine Client

[voleche09]

Thanks for the quick response.Is there any documentation to start me up quickly on how to use these?