Diagnostic Tests (DxTest) and the Diagnostic Tests Manager (DxManager)

NB. This is a work in progress. See test file here: https://github.com/UCL/TLOmodel/blob/hallett-DiagnosisManager/tests/test_dxmanager.py

What is the Diagnostics Test Manager and when I use it?

During a Health System Interaction Event, you will often need to simulate the process of a clinician using a diagnostic test to determine some hidden status of the patient that is not readily apparent (e.g. their blood pressure, urine glucose concentration or even very complex things like the drug-sensitivity of bacterial infection). There is quite a lot to consider:

• Which tests to use?
• Which consumable codes do these correspond to?
• What if the preferred test is not available?
• Do the test report the true status of the person with perfect accuracy or is there any error?

It will also be the case that the results of many investigations will not be compiled and considered systematically in a 'diagnostic algorithm'. All of this could be very fiddly!

It therefore will often make sense to use the Diagnostic Tests Manager.

Overview

Preparation

The following steps would usually be done at: initialise_simulation()

• The principle is that there is some 'property' of the individual that is not "visible" to the clinician [unlike a symptom, which is] but which is, nevertheless, potentially subject to investigation.

• A particular 'test' is something that can be used to examine that property. This may or may not entail the use consumables, and the reporting of the test may be subject to error. This information is stored in a helper class called a DxTest. Thus, for example:

    # Declare a DxTest
    my_test = DxTest(
        property='mi_status',               # it will return the value of the property 'mi_status
        cons_req_as_item_code=item_code,    # it requires and consumes a particular item
        sensitivity=0.95,                   # it has a 95% chance of returning a positive when the true value is positive
        specificity=0.80,                   # it has an 80% chance of returning a negative when the true value is negative
    )

• The consumables that are required and consumed in the course of performing this test can be:

• Specified as single item_code: use cons_req_as_item_code=. This is an integer value for the consumables code.
• Specified as consumable footprint: use cons_req_as_footprint=. The footprint must be formatted appropriately.
• Nothing: do not specify cons_req_as_item_code or cons_req_as_footprint (or set both to None). For more information about consumables, item codes and footprints, see here

• The test are then registered with the Diagnostic Test Manager, which is a part of the HealthSystem Model: sim.modules['HealthSystem'].dx_manager. They are registered by providing a name for them in the argument that is passed. For example:

   dx_manager.register_dx_test(
                           name_of_my_test_1 = my_test_1,
                           name_of_my_other_test = my_other test
   )

   dx_manager.register_dx_test(
                           name_of_one_more_test = this_is_the_last_test
   )

• 'DxTests' can be assembled into a 'TestLine' - to represent that if one test is not available or returns an inconclusive result, a next test can be tried automatically. This is done by passing in a list of DxTest to the .register_dx_test() method instead of a single DxTest object. The tests are executed in order, with the next only being used if all previous tests have failed (the consumables were not available or a value of None is returned). [NB. When a single DxTest is registered this is equivalent to a TestLine of length 1.]

For example:

    # This test is the first choice
    test_for_mi_first_choice = DxTest(
        cons_req_as_footprint=cons_first_choice_test,
        property='mi_status'
    )

    # This test is the second choice (use only if first choice fails)
    test_for_mi_second_choice = DxTest(
        cons_req_as_footprint=cons_second_choice_test,
        property='mi_status'
    )

    # Register TestLine with DxManager:
    dx_manager.register_dx_test(test_for_mi_status=
                                                   [
                                                       test_for_mi_first_choice,
                                                       test_for_mi_second_choice,
                                                    ])

  

Execution

The following steps will usually be done during an HSI_Event (either within the code of the event itself or a helper function that is called in the course of the HSI_Event).

• A test or testLine can be "used" by calling the run_dx_test() method of the DxManager. It is necessary to declare the HSI_Event of which this test forms a part, and the name(s) of Test/TestLines that should be run. For example:

    dx_manager.run_dx_test(
                    dx_test='test_for_mi_status',
                    hsi_event=self                    # self will typically be the HSI_Event that is calling the DxManager
    )

    dx_manager.run_dx_test(
                    dx_test=[test1, test2, test3],
                    hsi_event=self                    # self will typically be the HSI_Event that is calling the DxManager
    )

• Returns:
• If more than one dx_test is request, then the return will be the a dict() of the form {test_name: test_result}.
• If only one dx_test is requested, then the return will be the value of the test, or None if the test failed (consumable was not available). You can force the output to be in the form of a dict() by passing use_dict=True in run_dx_test(): dx_manager.run_dx_test(dx_test='my_test', hsi_event=self, use_dict=True)

Different Types of Test

TODO: The following types of test are currently supported:

• Direct read of a property The DxTest will read the value of a property and return it exactly as it is in the sim.population.props dataframe

• Read of a bool property with classification errors If the property is dtype=bool, then a sensitivity and specificity parameter can be used. The result returned by the test will reflect this error.

• Read of a continuous property with random errors If the property is dtype=float, then a random_error_stdev parameter can be used. The result returned by the test will be of the form: test_value = true_value + error where error ~ N(0, random_error_stdev)

Notes

• A module must register any Test or TestLine that will be used by any of its associated HSI_Events.
• The DxManager will not allow duplicates of Test to be registered and will issue a warning. Thus, two modules can safely declare the same test without conflict.
• The RandomState used by the DxManager to evaluate tests is that of the HealthSystem module.

Further Features:

What else would be useful here? Let @tbhallett know!