Using Consumables

Definitions

• Consumables are used in the provision of a service in the healthcare system (e.g. (e.g. medicines and other necessary materials)
• Consumables are referred to by an item_code.
• A 'request' for consumables is made during a during an HSI event and can be for one or many items at once.

---

There are a number of steps to using Consumables;

1) Find the item_code

There are two helper function that can assist in finding them item_code you need.

If you have the name of an item use get_item_code_from_item_name

This will return the int that is the item_code for that item.

e.g.

item_code = sim.modules['HealthSystem'].get_item_code_from_item_name("Tenofovir (TDF)/Emtricitabine (FTC), tablet, 300/200 mg")

If you have the name a "package" use get_item_codes_from_package_name

This will return a dict of the form {<item_code>: <quantity>} that corresponds to that package.

e.g.

item_code = sim.modules['HealthSystem'].get_item_codes_from_package_name("HIV Testing Services")

It is common to store all the item_codes in a convenient structure and to create a method on the disease module called find_cons_item_codes or similar, which contains the routines needed to find the item_code for each consumable that is needed. This can be called at initialise_simulation(). A common format would be:

def `get_item_code`(self) --> dict:
   get_item_code = self.sim.modules['HealthSystem'].get_item_codes_from_package_name
   rtn = dict()
   rtn['treatment_A'] = get_item_code("item_name_for_treatment_A")
   rtn['treatment_B'] = [get_item_code("item_name_for_treatment_B")] + [get_item_code("item_name_something_else")]
   rtn['treatment_C'] = get_item_code("item_name_for_treatment_C")

Do:

• • Group all the requests in one place: e.g. factorize the looking-up of the item_codes into a method and call it at initialise_simulation.
• Use the helper functions in HealthSystem : get_item_code_from_item_name and get_item_codes_from_package_name

Do not:

• Look-up the item_code at run-time in the HSI (this will cause the look-up to happen every time the HSI is created, which could be a lot!)
• Scatter looking up of consumables throughout the code.
• Look-up the codes manually using the internal data of the HealthSystem module.

---

2) Make the Request

All request for consumables are done using get_consumables, which is a method on the HSI_Event base-class. So, within an HSI it's accessed with self.get_consumable(). It's signature is:

    def get_consumables(self,
                        item_codes: Union[np.integer, int, list, set, dict],
                        to_log=True,
                        return_individual_results=False
                        ) -> Union[bool, dict]:

Note that:

• The argument item_code can be provided as:

  • an int, representing the single item_code requested (and for which a quantity of 1 is assumed);
  • a list or set, representing the collection of item_codes that are needed (for each of a which a quantity of 1 is assumed);
  • a dict of the form {<item_code>: <quantity>}, in which the quantity of each item_code is specified;

• The argument to_log, determines if the request (whatever its outcome) is logged (to ['tlo.methods.healthsystem']['Consumables']). The defaults to True but can over-ridden (e.g. to query availability only).

• The method return either a bool [default] (indicating that all the items requested are available) or a dict (indicating the availability of each requested item_code).

  • The default is always to return a bool but this can be over-ridden with the argument return_individual_results=True

Examples:

if self.get_consumables(self.module.cons_codes['treatment_A']):
   # do the treatment

# Construct request for ten of each item_code used in treatment_B
cons = {_i: 10 for _i in self.module.cons_codes['treatment_B']}

# Check availability (getting individual results)
avail = self.get_consumables(cons, return_individual_results=True)

# Check if most of the items are available
most_avail = sum(a.values())/len(a) > 0.5

Notes:

• Use the same formats for item_code, when specifying the consumable requirement of a DxTest.

---

3) Control behaviour of the HealthSystem

The following options (parsed to the HealthSystem) are relevant:

• cons_availability: This can be none (no consumable is available) all (all consumables are available) or default[default] (consumables are available according to a probability specified in a the relevant ResourceFile).

• disable: In this mode, all consumables are considered to be available but there is no logging.