tlo.methods.individual_history_tracker module

class IndividualHistoryTracker(name: str | None = None, modules_of_interest: List[str] | None = None, events_to_ignore: List[str] | None = None)

Construct a new disease module ready to be included in a simulation.

Initialises an empty parameters dictionary and module-specific random number generator.

Parameters:

name – the name to use for this module. Defaults to the concrete subclass’ name.

Bases: tlo.core.Module

PARAMETERS:

Item	Type	Description
modules_of_interest	LIST	Restrict the events collected to specific modules. If *, print for all modules
events_to_ignore	LIST	Events to be ignored when collecting chains

PROPERTIES:

Item	Type	Description
iht_track_history	BOOL	Whether the individual should be tracked bythe individual history tracker or not

Class attributes:

INIT_DEPENDENCIES : {‘Demography’}

__annotations__ : {}

Functions (defined or overridden in class IndividualHistoryTracker):

__init__(name: str | None = None, modules_of_interest: List[str] | None = None, events_to_ignore: List[str] | None = None)

Construct a new disease module ready to be included in a simulation.

Initialises an empty parameters dictionary and module-specific random number generator.

Parameters:

name – the name to use for this module. Defaults to the concrete subclass’ name.

initialise_simulation(sim)

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.

read_parameters(resourcefilepath: Path | None = None)

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.

df_to_eav(df, date, event_name)

Function to convert entire population dataframe into custom EAV

convert_chain_links_into_eav(chain_links)

Function to convert chain links into custom EAV

initialise_population(population)

Set our property values for the initial population.

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.

By default, all Property``s in ``self.PROPERTIES will have their columns in the population dataframe set to the default value.

Modules that wish to implement this behaviour do not need to implement this method, it will be inherited automatically. Modules that wish to perform additional steps during the initialise_population stage should reimplement this method and call

`python super().initialise_population(population=population) `

at the beginning of the method, then proceed with their additional steps. Modules that do not wish to inherit this default behaviour should re-implement initialise_population without the call to super() above.

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 in the simulation.

on_birth(mother, child)

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

copy_of_pop_dataframe()

copy_of_pop_dataframe_row(person_ID)

copy_of_mni()

Function to safely copy entire mni dictionary, ensuring that series attributes are safely copied too.

copy_of_mni_row(person_ID)

Function to safely copy mni entry for single individual, ensuring that series attributes are safely copied too.

log_eav_dataframe_to_individual_histories(df)

on_simulation_post_initialise(data)

on_simulation_post_do_birth(data)

on_consumable_request(data)

Do this when notified that an individual has accessed consumables

on_event_pre_run(data)

Do this when notified that an event is about to run. This function checks whether this event should be logged as part of the event chains, a nd if so stored required information before the event has occurred.

on_event_post_run(data)

If print_chains=True, this function logs the event and identifies and logs the any property changes that have occured to one or multiple individuals as a result of the event taking place.

mni_values_differ(v1, v2)

compare_entire_mni_dicts(entire_mni_before, entire_mni_after, set_of_tracked_individuals)

compare_population_dataframe_and_mni(df_before, df_after, entire_mni_before, entire_mni_after, event_name)

This function compares the population dataframe and mni dictionary before/after a population-wide e vent has occurred. It allows us to identify the individuals for which this event led to a significant (i.e. property) change, and to store the properties which have changed as a result of it.