tlo.methods.symptommanager module

The Symptom Manager: * Manages presence of symptoms for all disease modules * Manages a set of generic symptoms * Creates occurrences of generic symptom (representing that being caused by diseases not included in the TLO model)

The write-up for the origin of the estimates for the effect of each symptom is:

Health-seeking behaviour estimates for adults and children.docx

Outstanding issues * The probability of spurious symptoms is not informed by data.

class SymptomManager(name=None, resourcefilepath=None, spurious_symptoms=None)

This module is used to track the symptoms of persons. The addition and removal of symptoms by disease modules is

handled here. This module can also causes symptoms that are not related to any disease module (representing those caused by conditions not represented explicitly in the model).

Bases: tlo.core.Module

PARAMETERS:

Item	Type	Description
generic_symptoms_spurious_occurrence	DATA_FRAME	probability and duration of spurious occureneces of generic symptoms
spurious_symptoms	BOOL	whether or not there will be the spontaneous occurrence of generic symptoms. NB. This is over-ridden if a module key-word argument is provided.

Class attributes:

INIT_DEPENDENCIES : {‘Demography’}

METADATA : {}

Functions (defined or overridden in class SymptomManager):

__init__(name=None, resourcefilepath=None, spurious_symptoms=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.

get_column_name_for_symptom(symptom_name)

get the column name that corresponds to the symptom_name

read_parameters(data_folder)

Read in the generic symptoms and register them

register_symptom(*symptoms_to_register: Symptom)

Stores the symptom classes that are passed. Registration must be done before ‘pre-initialise population’ is called. The disease module associated with each symptom is also stored. :param symptoms_to_register: instance(s) of class Symptom :return:

register_generic_symptoms()

Register the genric symptoms, using information read in from the ResourceFile.

pre_initialise_population()

Register the generic symptoms and define the properties for each symptom

initialise_population(population)

Establish the Properties and the BitSetHandler for each of the symptoms:

initialise_simulation(sim)

Schedule SpuriousSymptomsOnset/Resolve if the parameter ‘spurious_symptoms’ is True

on_birth(mother_id, child_id)

Give a value of 0 for each symptom. NB. This will over-write any symptom that has already been set on the child, so is only safe is SymptomManager is registered before any Disease Module.

change_symptom(person_id, symptom_string, add_or_remove, disease_module, duration_in_days=None, date_of_onset=None)

This is how disease module report that a person has developed a new symptom or an existing symptom has resolved. The sy_ property contains a set of of the disease_module names that currently cause the symptom. Check if the set is empty or not to determine if the symptom is currently present.

Parameters:

• date_of_onset – Date for the symptoms to start

• duration_in_days – If self-resolving, duration of symptoms

• person_id – The person_id (int or list of int) for whom the symptom changes

• symptom_string – The string for the symptom or list of multiple symptom strings

• add_or_remove – ‘+’ to add the symptom or ‘-’ to remove the symptom

• disease_module – pointer to the disease module that is reporting this change in symptom

who_has(list_of_symptoms)

This is a helper function to look up who has a particular symptom or set of symptoms. It returns a list of indicies for person that have all of the symptoms specified

Param:

list_of_symptoms : string or list of strings for the symptoms of interest

Returns:

list of person_ids for those with all of the symptoms in list_of_symptoms who are alive

who_not_have(symptom_string: str) → Index

Get person IDs of individuals who are alive and do not have a symptom.

Parameters:

symptom_string – The string of the symptom.

Returns:

Index corresponding to individuals which are alive and do not have symptom.

has_what(person_id: int | None = None, individual_details: IndividualProperties | None = None, disease_module: Module | None = None) → List[str]

This is a helper function that will give a list of strings for the symptoms that a _single_ person is currently experiencing.

If working in a tlo.population.IndividualProperties context, one can pass the context object instead of supplying the person’s DataFrame index. Note that at least one of these inputs must be passed as a keyword argument however. In the event that both arguments are passed, the individual_details argument takes precedence over the person_id.

Optionally can specify disease_module_name to limit to the symptoms caused by that disease module.

Parameters:

• person_id – the person_of of interest.

• individual_details – tlo.population.IndividualProperties object for the person of interest.

• disease_module – (optional) disease module of interest.

Returns:

list of strings for the symptoms that are currently being experienced.

have_what(person_ids: Sequence[int])

Find the set of symptoms for a list of person_ids. NB. This is a fast implementation without the same amount checking as ‘has_what’

causes_of(person_id: int, symptom_string)

This is a helper function that will give a list of the disease modules causing a particular symptom for a particular person. :param person_id: :param disease_module: :return: list of strings for the disease module name

clear_symptoms(person_id: int | Sequence[int], disease_module: Module)

Remove all the symptoms for one or more persons caused by a specified disease module

Parameters:

• person_id – IDs for one or more persons to clear symptoms for.

• disease_module_name – Name of disease module to clear symptoms for.

caused_by(disease_module: Module)

Find the persons experiencing symptoms due to a particular module. Returns a dict of the form {<<person_id>>, <<list_of_symptoms>>}.

get_persons_with_newly_onset_symptoms()

reset_persons_with_newly_onset_symptoms()

class SymptomManager_AutoOnsetEvent(module, person_id, symptom_string, disease_module, duration_in_days)

This utility function will add symptoms. It is scheduled by the SymptomManager to let symptoms ‘auto-onset’ on a particular date.

Bases: tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class SymptomManager_AutoOnsetEvent):

__init__(module, person_id, symptom_string, disease_module, duration_in_days)

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)

apply(population)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:

target – the target of the event

class SymptomManager_AutoResolveEvent(module, person_id, symptom_string, disease_module)

This utility function will remove symptoms. It is scheduled by the SymptomManager to let symptoms ‘auto-resolve’

Bases: tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class SymptomManager_AutoResolveEvent):

__init__(module, person_id, symptom_string, disease_module)

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)

apply(population)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:

target – the target of the event

class SymptomManager_SpuriousSymptomOnset(module)

This event gives the occurrence of generic symptoms that are not caused by a disease module in the TLO model.

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class SymptomManager_SpuriousSymptomOnset):

__init__(module)

This event occurs every day

get_generic_symptoms_dict(generic_sympoms_df)

Helper function to store contents of the generic_symptoms dataframe as dicts

apply(population)

Determine who will be onset which which symptoms today

class SymptomManager_SpuriousSymptomResolve(module)

This event resolves the generic symptoms that have been onset by this module.

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class SymptomManager_SpuriousSymptomResolve):

__init__(module)

This event occurs every day

schedule_symptom_resolve(person_id, date_of_resolution, symptom_string)

Store information to allow symptoms to be resolved for groups of persons each day

apply(population)

Resolve the symptoms when due; a whole group of persons with the same symptoms at once