tlo.methods.healthsystem module
- class HSI_Event(module, *args, **kwargs)[source]
Base HSI event class, from which all others inherit.
Concrete subclasses should also inherit from one of the EventMixin classes defined below, and implement at least an apply and did_not_run method.
Class attributes:
bed_days_allocated_to_this_event : <property object at 0x7ff64ee7a4a0>
Functions (defined or overridden in class HSI_Event):
- __init__(module, *args, **kwargs)[source]
Create a new event.
Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.
- Parameters:
module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
- apply(squeeze_factor=0.0, *args, **kwargs)[source]
Apply this event to the population.
Must be implemented by subclasses.
- did_not_run(*args, **kwargs)[source]
Called when this event is due but it is not run. Return False to prevent the event being rescheduled, or True to allow the rescheduling. This is called each time that the event is tried to be run but it cannot be.
- never_ran()[source]
Called when this event is was entered to the HSI Event Queue, but was never run.
- get_consumables(item_codes: None | integer | int | list | set | dict = None, optional_item_codes: None | integer | int | list | set | dict = None, to_log: bool | None = True, return_individual_results: bool | None = False) bool | dict [source]
Function to allow for getting and checking of entire set of consumables. All requests for consumables should use this function. :param item_codes: The item code(s) (and quantities) of the consumables that are requested and which determine the summary result for availability/non-availability. This can be an int (the item_code needed [assume quantity=1]), a list or set (the collection of item_codes [for each assuming quantity=1]), or a dict (with key:value pairs <item_code>:<quantity>). :param optional_item_codes: The item code(s) (and quantities) of the consumables that are requested and which do
not determine the summary result for availability/non-availability. (Same format as item_codes). This is useful when a large set of items may be used, but the viability of a subsequent operation depends only on a subset.
- Parameters:
return_individual_results – If True returns a dict giving the availability of each item_code requested
(otherwise gives a bool indicating if all the item_codes requested are available). :param to_log: If True, logs the request. :returns A bool indicating whether every item is available, or a dict indicating the availability of each
item.
- Note that disease module can use the get_item_codes_from_package_name and get_item_code_from_item_name
methods in the HealthSystem module to find item_codes.
- make_beddays_footprint(dict_of_beddays)[source]
Helper function to make a correctly-formed ‘bed-days footprint’
- make_appt_footprint(dict_of_appts)[source]
Helper function to make appointment footprint in format expected downstream.
Should be passed a dictionary keyed by appointment type codes with non-negative values.
- initialise()[source]
Initialise the HSI: * Set the facility_info * Compute appt-footprint time requirements
- class HSIEventWrapper(hsi_event, run_hsi=True, *args, **kwargs)[source]
This is wrapper that contains an HSI event.
- It is used:
1) When the healthsystem is in mode ‘disabled=True’ such that HSI events sent to the health system scheduler are passed to the main simulation scheduler for running on the date of topen. (Note, it is run with squeeze_factor=0.0.) 2) When the healthsytsem is in mode diable_and_reject_all=True such that HSI are not run but the never_ran method is run on the date of tclose. 3) When an HSI has been submitted to schedule_hsi_event but the service is not available.
Bases:
tlo.events.Event
Functions (defined or overridden in class HSIEventWrapper):
- __init__(hsi_event, run_hsi=True, *args, **kwargs)[source]
Create a new event.
Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.
- Parameters:
module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)
- class HealthSystem(name: str | None = None, resourcefilepath: Path | None = None, service_availability: List[str] | None = None, mode_appt_constraints: int | None = None, cons_availability: str | None = None, beds_availability: str | None = None, randomise_queue: bool = True, ignore_priority: bool = False, policy_name: str | None = None, capabilities_coefficient: float | None = None, use_funded_or_actual_staffing: str | None = None, disable: bool = False, disable_and_reject_all: bool = False, compute_squeeze_factor_to_district_level: bool = True, hsi_event_count_log_period: str | None = 'month')[source]
This is the Health System Module. The execution of all health systems interactions are controlled through this module.
Bases:
tlo.core.Module
PARAMETERS:
Item
Type
Description
Master_Facilities_List
DATA_FRAME
Listing of all health facilities.
Officer_Types_Table
DATA_FRAME
The names of the types of health workers (“officers”)
Appt_Types_Table
DATA_FRAME
The names of the type of appointments with the health system
Appt_Offered_By_Facility_Level
DATA_FRAME
Table indicating whether or not each appointment is offered at each facility level.
Appt_Time_Table
DATA_FRAME
The time taken for each appointment, according to officer and facility type.
Daily_Capabilities_actual
DATA_FRAME
The capabilities (minutes of time available of each type of officer in each facility) based on the _estimated current_ number and distribution of staff estimated.
Daily_Capabilities_funded
DATA_FRAME
The capabilities (minutes of time available of each type of officer in each facility) based on the _potential_ number and distribution of staff estimated (i.e. those positions that can be funded).
Daily_Capabilities_funded_plus
DATA_FRAME
The capabilities (minutes of time available of each type of officer in each facility) based on the _potential_ number and distribution of staff estimated, with adjustments to permit each appointment type that should be run at facility level to do so in every district.
use_funded_or_actual_staffing
STRING
If actual, then use the numbers and distribution of staff estimated to be available currently; If funded, then use the numbers and distribution of staff that are potentially available. If ‘funded_plus`, then use a dataset in which the allocation of staff to facilities is tweaked so as to allow each appointment type to run at each facility_level in each district for which it is defined. N.B. This parameter is over-ridden if an argument is provided to the module initialiser.
item_and_package_code_lookups
DATA_FRAME
Data imported from the OneHealth Tool on consumable items, packages and costs.
availability_estimates
DATA_FRAME
Estimated availability of consumables in the LMIS dataset.
cons_availability
STRING
Availability of consumables. If ‘default’ then use the availability specified in the ResourceFile; if ‘none’, then let no consumable be ever be available; if ‘all’, then all consumables are always available. When using ‘all’ or ‘none’, requests for consumables are not logged. NB. This parameter is over-riddenif an argument is provided to the module initialiser.
BedCapacity
DATA_FRAME
Data on the number of beds available of each type by facility_id
beds_availability
STRING
Availability of beds. If ‘default’ then use the availability specified in the ResourceFile; if ‘none’, then let no beds be ever be available; if ‘all’, then all beds are always available. NB. This parameter is over-ridden if an argument is provided to the module initialiser.
Service_Availability
LIST
List of services to be available. NB. This parameter is over-ridden if an argument is provided to the module initialiser.
policy_name
STRING
Name of priority policy assumed to have been adopted until policy switch
policy_name_post_switch
STRING
Name of priority policy to be adopted from policy switch year onwards
year_policy_switch
INT
Year in which priority policy switch in enforced
priority_rank
DICT
Data on the priority ranking of each of the Treatment_IDs to be adopted by the queueing system under different policies, where the lower the number the higher the priority, and on which categories of individuals classify for fast-tracking for specific treatments
tclose_overwrite
INT
Decide whether to overwrite tclose variables assigned by disease modules
tclose_days_offset_overwrite
INT
Offset in days from topen at which tclose will be set by the healthsystem for all HSIsif tclose_overwrite is set to True.
mode_appt_constraints
INT
Integer code in {0, 1, 2} determining mode of constraints with regards to officer numbers and time - 0: no constraints, all HSI events run with no squeeze factor, 1: elastic constraints, all HSI events run with squeeze factor, 2: hard constraints, only HSI events with no squeeze factor run. N.B. This parameter is over-ridden if an argument is provided to the module initialiser.
mode_appt_constraints_postSwitch
INT
If considering a mode switch alongside priority policy switch, specify in this parameter. The switch occcurs in the year given in year_policy_switch.
PROPERTIES:
Item
Type
Description
hs_is_inpatient
BOOL
Whether or not the person is currently an in-patient at any medical facility
Class attributes:
INIT_DEPENDENCIES : {‘Demography’}
capabilities_today : <property object at 0x7ff64ed8c590>
hsi_event_counts : <property object at 0x7ff64edd1d60>
never_ran_hsi_event_counts : <property object at 0x7ff64ee7a590>
Functions (defined or overridden in class HealthSystem):
- __init__(name: str | None = None, resourcefilepath: Path | None = None, service_availability: List[str] | None = None, mode_appt_constraints: int | None = None, cons_availability: str | None = None, beds_availability: str | None = None, randomise_queue: bool = True, ignore_priority: bool = False, policy_name: str | None = None, capabilities_coefficient: float | None = None, use_funded_or_actual_staffing: str | None = None, disable: bool = False, disable_and_reject_all: bool = False, compute_squeeze_factor_to_district_level: bool = True, hsi_event_count_log_period: str | None = 'month')[source]
- Parameters:
name – Name to use for module, defaults to module class name if
None
.resourcefilepath – Path to directory containing resource files.
service_availability – A list of treatment IDs to allow.
mode_appt_constraints – Integer code in
{0, 1, 2}
determining mode of constraints with regards to officer numbers and time - 0: no constraints, all HSI events run with no squeeze factor, 1: elastic constraints, all HSI events run with squeeze factor, 2: hard constraints, only HSI events with no squeeze factor run.cons_availability – If ‘default’ then use the availability specified in the ResourceFile; if ‘none’, then
let no consumable be ever be available; if ‘all’, then all consumables are always available. When using ‘all’ or ‘none’, requests for consumables are not logged. :param beds_availability: If ‘default’ then use the availability specified in the ResourceFile; if ‘none’, then let no beds be ever be available; if ‘all’, then all beds are always available. :param randomise_queue ensure that the queue is not model-dependent, i.e. properly randomised for equal topen
and priority
- Parameters:
ignore_priority – If
True
do not use the priority information in HSI event to schedulepolicy_name – Name of priority policy that will be adopted if any
capabilities_coefficient – Multiplier for the capabilities of health officers, if
None
set to ratio of initial population to estimated 2010 population.use_funded_or_actual_staffing – If actual, then use the numbers and distribution of staff estimated to be available currently; If funded, then use the numbers and distribution of staff that are potentially available. If ‘funded_plus`, then use a dataset in which the allocation of staff to facilities is tweaked so as to allow each appointment type to run at each facility_level in each district for which it is defined.
disable – If
True
, disables the health system (no constraints and no logging) and every HSI event runs.disable_and_reject_all – If
True
, disable health system and no HSI events runcompute_squeeze_factor_to_district_level – Whether to compute squeeze_factors to the district level, or the national level (which effectively pools the resources across all districts).
hsi_event_count_log_period – Period over which to accumulate counts of HSI events that have run before logging and reseting counters. Should be on of strings
'day'
,'month'
,'year'
.'simulation'
to log at the end of each day, end of each calendar month, end of each calendar year or the end of the simulation respectively, orNone
to not track the HSI event details and frequencies.
- read_parameters(data_folder)[source]
Read parameter values from file, if required.
Must be implemented by subclasses.
- Parameters:
data_folder – path of a folder supplied to the Simulation containing data files. Typically, modules would read a particular file within here.
- pre_initialise_population()[source]
Generate the accessory classes used by the HealthSystem and pass to them the data that has been read.
- initialise_population(population)[source]
Set our property values for the initial population.
Must be implemented by subclasses.
This method is called by the simulation when creating the initial population, and is responsible for assigning initial values, for every individual, of those properties ‘owned’ by this module, i.e. those declared in its PROPERTIES dictionary.
TODO: We probably need to declare somehow which properties we ‘read’ here, so the simulation knows what order to initialise modules in!
- Parameters:
population – the population of individuals
- initialise_simulation(sim)[source]
Get ready for simulation start.
Must be implemented by subclasses.
This method is called just before the main simulation loop begins, and after all modules have read their parameters and the initial population has been created. It is a good place to add initial events to the event queue.
- on_birth(mother_id, child_id)[source]
Initialise our properties for a newborn individual.
Must be implemented by subclasses.
This is called by the simulation whenever a new person is born.
- Parameters:
mother_id – the person id for the mother of this child (can be -1 if the mother is not identified).
child_id – the person id of new child
- on_simulation_end()[source]
Put out to the log the information from the tracker of the last day of the simulation
- process_human_resources_files(use_funded_or_actual_staffing: str)[source]
Create the data-structures needed from the information read into the parameters.
- format_daily_capabilities(use_funded_or_actual_staffing: str) Series [source]
This will updates the dataframe for the self.parameters[‘Daily_Capabilities’] so as to include every permutation of officer_type_code and facility_id, with zeros against permutations where no capacity is available.
It also give the dataframe an index that is useful for merging on (based on Facility_ID and Officer Type)
(This is so that its easier to track where demands are being placed where there is no capacity)
- update_consumables_availability_to_represent_merging_of_levels_1b_and_2(df_original)[source]
To represent that facility levels ‘1b’ and ‘2’ are merged together under the label ‘2’, we replace the availability of consumables at level 2 with new values.
- get_service_availability() List[str] [source]
Returns service availability. (Should be equal to what is specified by the parameter, but overwrite with what was provided in argument if an argument was specified – provided for backward compatibility/debugging.)
- get_cons_availability() str [source]
Returns consumables availability. (Should be equal to what is specified by the parameter, but overwrite with what was provided in argument if an argument was specified – provided for backward compatibility/debugging.)
- get_beds_availability() str [source]
Returns beds availability. (Should be equal to what is specified by the parameter, but overwrite with what was provided in argument if an argument was specified – provided for backward compatibility/debugging.)
- schedule_to_call_never_ran_on_date(hsi_event: HSI_Event, tdate: datetime)[source]
Function to schedule never_ran being called on a given date
- get_mode_appt_constraints() int [source]
Returns mode_appt_constraints. (Should be equal to what is specified by the parameter, but overwrite with what was provided in argument if an argument was specified – provided for backward compatibility/debugging.)
- get_use_funded_or_actual_staffing() str [source]
Returns use_funded_or_actual_staffing. (Should be equal to what is specified by the parameter, but overwrite with what was provided in argument if an argument was specified – provided for backward compatibility/debugging.)
- get_priority_policy_initial() str [source]
Returns priority_policy. (Should be equal to what is specified by the parameter, but overwrite with what was provided in argument if an argument was specified – provided for backward compatibility/debugging.)
- schedule_hsi_event(hsi_event: HSI_Event, priority: int, topen: datetime, tclose: datetime | None = None, do_hsi_event_checks: bool = True)[source]
Schedule a health system interaction (HSI) event.
- Parameters:
hsi_event – The HSI event to be scheduled.
priority – The priority for the HSI event: 0 (highest), 1 or 2 (lowest)
topen – The earliest date at which the HSI event should run.
tclose – The latest date at which the HSI event should run. Set to one week after
topen
ifNone
.do_hsi_event_checks – Whether to perform sanity checks on the passed
hsi_event
argument to check that it constitutes a valid HSI event. This is intended for allowing disabling of these checks when scheduling multiple HSI events of the sameHSI_Event
subclass together, in which case typically performing these checks for each individual HSI event of the shared type will be redundant.
- _add_hsi_event_queue_item_to_hsi_event_queue(priority, topen, tclose, hsi_event) None [source]
Add an event to the HSI_EVENT_QUEUE.
- enforce_priority_policy(hsi_event) int [source]
Return priority for HSI_Event based on policy under consideration
- static is_treatment_id_allowed(treatment_id: str, service_availability: list) bool [source]
Determine if a treatment_id (specified as a string) can be run (i.e., is within the allowable set of treatments, given by self.service_availability. The rules are as follows:
An empty list means nothing is allowed
A list that contains only an asteriks [‘*’] means run anything
If the list is not empty, then a treatment_id with a first part “FirstAttendance_” is also allowed
An entry in the list of the form “A_B_C” means a treatment_id that matches exactly is allowed
An entry in the list of the form “A_B_*” means that a treatment_id that begins “A_B_” or “A_B” is allowed
- schedule_batch_of_individual_hsi_events(hsi_event_class, person_ids, priority, topen, tclose=None, **event_kwargs)[source]
Schedule a batch of individual-scoped HSI events of the same type.
Only performs sanity checks on the HSI event for the first scheduled event thus removing the overhead of multiple redundant checks.
- Parameters:
hsi_event_class – The
HSI_Event
subclass of the events to schedule.person_ids – A sequence of person ID index values to use as the targets of the HSI events being scheduled.
priority – The priority for the HSI events: 0 (highest), 1 or 2 (lowest). Either a single value for all events or an iterable of per-target values.
topen – The earliest date at which the HSI events should run. Either a single value for all events or an iterable of per-target values.
tclose – The latest date at which the HSI events should run. Set to one week after
topen
ifNone
. Either a single value for all events or an iterable of per-target values.event_kwargs – Any additional keyword arguments to pass to the
hsi_event_class
initialiser in addition toperson_id
.
- appt_footprint_is_valid(appt_footprint)[source]
Checks an appointment footprint to ensure it is in the correct format. :param appt_footprint: Appointment footprint to check. :return: True if valid and False otherwise.
- get_blank_appt_footprint()[source]
This is a helper function so that disease modules can easily create their appt_footprints. It returns an empty Counter instance.
- get_facility_info(hsi_event) FacilityInfo [source]
Helper function to find the facility at which an HSI event will take place based on their district of residence and the level of the facility of the HSI.
- get_appt_footprint_as_time_request(facility_info: FacilityInfo, appt_footprint: dict)[source]
This will take an APPT_FOOTPRINT and return the required appointments in terms of the time required of each Officer Type in each Facility ID. The index will identify the Facility ID and the Officer Type in the same format as is used in Daily_Capabilities. :params facility_info: The FacilityInfo describing the facility at which the appointment occurs :param appt_footprint: The actual appt footprint (optional) if different to that in the HSI event. :return: A Counter that gives the times required for each officer-type in each facility_ID, where this time
is non-zero.
- get_squeeze_factors(footprints_per_event, total_footprint, current_capabilities, compute_squeeze_factor_to_district_level: bool)[source]
This will compute the squeeze factors for each HSI event from the list of all the calls on health system resources for the day. The squeeze factor is defined as (call/available - 1). ie. the highest fractional over-demand among any type of officer that is called-for in the appt_footprint of an HSI event. A value of 0.0 signifies that there is no squeezing (sufficient resources for the EXPECTED_APPT_FOOTPRINT).
- Parameters:
footprints_per_event – List, one entry per HSI event, containing the minutes required from each health officer in each health facility as a Counter (using the standard index)
total_footprint – Counter, containing the total minutes required from each health officer in each health facility when non-zero, (using the standard index)
current_capabilities – Series giving the amount of time available for each health officer in each health facility (using the standard index)
compute_squeeze_factor_to_district_level – Boolean indicating whether the computation of squeeze_factors should be specific to each district (when True), or if the computation of squeeze_factors should be on the basis that resources from all districts can be effectively “pooled” (when `False).
- Returns:
squeeze_factors: an array of the squeeze factors for each HSI event (position in array matches that in the all_call_today list).
- record_hsi_event(hsi_event, actual_appt_footprint=None, squeeze_factor=None, did_run=True, priority=None)[source]
Record the processing of an HSI event. If this is an individual-level HSI_Event, it will also record the actual appointment footprint :param hsi_event: The HSI_Event (containing the initial expectations of footprints) :param actual_appt_footprint: The actual Appointment Footprint (if individual event) :param squeeze_factor: The squeeze factor (if individual event)
- write_to_hsi_log(event_details: HSIEventDetails, person_id: int, facility_id: int | None, squeeze_factor: float, did_run: bool, priority: int)[source]
Write the log HSI_Event and add to the summary counter.
- call_and_record_never_ran_hsi_event(hsi_event, priority=None)[source]
Record the fact that an HSI event was never ran. If this is an individual-level HSI_Event, it will also record the actual appointment footprint :param hsi_event: The HSI_Event (containing the initial expectations of footprints)
- write_to_never_ran_hsi_log(event_details: HSIEventDetails, person_id: int, facility_id: int | None, priority: int)[source]
Write the log HSI_Event and add to the summary counter.
- log_current_capabilities_and_usage()[source]
This will log the percentage of the current capabilities that is used at each Facility Type, according the runnning_total_footprint.
- find_events_for_person(person_id: int)[source]
Find the events in the HSI_EVENT_QUEUE for a particular person. :param person_id: the person_id of interest :returns list of tuples (date_of_event, event) for that person_id in the HSI_EVENT_QUEUE.
NB. This is for debugging and testing only - not for use in real simulations as it is slow
- get_item_codes_from_package_name(package: str) dict [source]
Helper function to provide the item codes and quantities in a dict of the form {<item_code>:<quantity>} for a given package name.
- get_item_code_from_item_name(item: str) int [source]
Helper function to provide the item_code (an int) when provided with the name of the item
- override_availability_of_consumables(item_codes) None [source]
Over-ride the availability (for all months and all facilities) of certain consumables item_codes. :param item_codes: Dictionary of the form {<item_code>: probability_that_item_is_available} :return: None
- on_end_of_year() None [source]
Write to log the current states of the summary counters and reset them.
- class HealthSystemScheduler(module: HealthSystem)[source]
This is the HealthSystemScheduler. It is an event that occurs every day and must be the LAST event of the day. It inspects the calls on the healthsystem and commissions event to occur that are consistent with the healthsystem’s capabilities for the following day, given assumptions about how this decision is made.
N.B. Events scheduled for the same day will occur that day, but after those which were scheduled on an earlier date.
The overall Prioritization algorithm is: * Look at events in order (the order is set by the heapq: see schedule_hsi_event) * Ignore if the current data is before topen * Remove and do nothing if tclose has expired * Run any population-level HSI events * For an individual-level HSI event, check if there are sufficient health system capabilities to run the event
- If the event is to be run, then the following events occur:
The HSI event itself is run.
The occurence of the event is logged
The resources used are ‘occupied’ (if individual level HSI event)
Other disease modules are alerted of the occurence of the HSI event (if individual level HSI event)
Here is where we can have multiple types of assumption regarding how these capabilities are modelled.
Bases:
tlo.events.RegularEvent
,tlo.events.Event
,tlo.events.PopulationScopeEventMixin
Functions (defined or overridden in class HealthSystemScheduler):
- __init__(module: HealthSystem)[source]
Create a new regular event.
- Parameters:
module – the module that created this event
frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)
- class HealthSystemChangeParameters(module: HealthSystem, parameters: Dict)[source]
- Event that causes certain internal parameters of the HealthSystem to be changed; specifically:
mode_appt_constraints
ignore_priority
capabilities_coefficient
cons_availability
beds_availability
Note that no checking is done here on the suitability of values of each parameter.
Bases:
tlo.events.Event
,tlo.events.PopulationScopeEventMixin
Functions (defined or overridden in class HealthSystemChangeParameters):
- __init__(module: HealthSystem, parameters: Dict)[source]
Create a new event.
Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.
- Parameters:
module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)
- class HealthSystemChangePriorityPolicyAndMode(module)[source]
This event exists to change the priority policy adopted by the HealthSystem at a given year.
Bases:
tlo.events.RegularEvent
,tlo.events.Event
,tlo.events.PopulationScopeEventMixin
Functions (defined or overridden in class HealthSystemChangePriorityPolicyAndMode):