tlo.core module

Core framework classes.

This contains things that didn’t obviously go in their own file, such as specification for parameters and properties, and the base Module class for disease modules.

class Types(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Possible types for parameters and properties.

This lets us hide the details of numpy & Pandas dtype strings and give users an easy list to reference instead.

Most of these should be intuitive. The CATEGORICAL type is useful for things like sex where there are a fixed number of options to choose from. The LIST type is used for properties where the value is a collection, e.g. the set of children of a person.

DATE = 1

BOOL = 2

INT = 3

REAL = 4

CATEGORICAL = 5

LIST = 6

SERIES = 7

DATA_FRAME = 8

STRING = 9

DICT = 10

class Specifiable(type_, description, categories=None)

Bases: object

Base class for Parameter and Property.

PANDAS_TYPE_MAP = {Types.BOOL: <class 'bool'>, Types.CATEGORICAL: 'category', Types.DATA_FRAME: <class 'object'>, Types.DATE: 'datetime64[ns]', Types.DICT: <class 'object'>, Types.INT: 'int64', Types.LIST: <class 'object'>, Types.REAL: <class 'float'>, Types.SERIES: <class 'object'>, Types.STRING: <class 'object'>}

PYTHON_TYPE_MAP = {Types.BOOL: <class 'bool'>, Types.CATEGORICAL: <class 'pandas.core.arrays.categorical.Categorical'>, Types.DATA_FRAME: <class 'pandas.core.frame.DataFrame'>, Types.DATE: <class 'pandas._libs.tslibs.timestamps.Timestamp'>, Types.DICT: <class 'dict'>, Types.INT: <class 'int'>, Types.LIST: <class 'list'>, Types.REAL: <class 'float'>, Types.SERIES: <class 'pandas.core.series.Series'>, Types.STRING: <class 'object'>}

property python_type

Return the Python type corresponding to this Specifiable.

property pandas_type

Return the Pandas type corresponding to this Specifiable.

class Parameter(type_, description, categories=None)

Bases: Specifiable

Used to specify parameters for disease modules etc.

class Property(type_, description, categories=None, *, ordered=False)

Bases: Specifiable

Used to specify properties of individuals.

PANDAS_TYPE_DEFAULT_VALUE_MAP = {'category': nan, 'datetime64[ns]': NaT, 'int64': 0, <class 'bool'>: False, <class 'float'>: nan, <class 'object'>: nan}

create_series(name, size)

Create a Pandas Series for this property.

The values will be left uninitialised.

Parameters:

• name – The name for the series.

• size – The length of the series.

class Module(name=None)

Bases: object

The base class for disease modules.

This declares the methods which individual modules must implement, and contains the core functionality linking modules into a simulation. Useful properties available on instances are:

name

The unique name of this module within the simulation.

parameters

A dictionary of module parameters, derived from specifications in the PARAMETERS class attribute on a subclass.

rng

A random number generator specific to this module, with its own internal state. It’s an instance of numpy.random.RandomState

sim

The simulation this module is part of, once registered.

INIT_DEPENDENCIES = frozenset({})

OPTIONAL_INIT_DEPENDENCIES = frozenset({})

ADDITIONAL_DEPENDENCIES = frozenset({})

ALTERNATIVE_TO = frozenset({})

METADATA = {}

CAUSES_OF_DEATH = {}

CAUSES_OF_DISABILITY = {}

PARAMETERS = {}

PROPERTIES = {}

property healthsystem: HealthSystem

parameters

load_parameters_from_dataframe(resource: DataFrame)

Automatically load parameters from resource dataframe, updating the class parameter dictionary

Goes through parameters dict self.PARAMETERS and updates the self.parameters with values Automatically updates the values of data types: - Integers - Real numbers - Lists - Categorical - Strings - Dates (Any numbers will be converted into dated without warnings) - Booleans (An value in the csv ‘0’, 0, ‘False’, ‘false’, ‘FALSE’, or None will be interpreted as False;

everything else as True)

Will also make the parameter_name the index of the resource DataFrame.

Parameters:

resource (DataFrame) – DataFrame with a column of the parameter_name and a column of value

read_parameters(data_folder)

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.

initialise_population(population)

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)

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.

pre_initialise_population()

Carry out any work before any populations have been initialised

This optional method allows access to all other registered modules, before any of the modules have initialised a population. This is expected to be useful for when a module’s properties rely upon information from other modules.

on_birth(mother_id, child_id)

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()

This is called after the simulation has ended. Modules do not need to declare this.

do_at_generic_first_appt(patient_id: int, patient_details: PatientDetails | None, symptoms: List[str] | None, diagnosis_function: DiagnosisFunction | None, consumables_checker: ConsumablesChecker | None, facility_level: str | None, treatment_id: str | None, random_state: RandomState | None) → IndividualPropertyUpdates | None

Actions to be take during a NON-emergency generic HSI.

Derived classes should overwrite this method so that they are compatible with the HealthSystem module, and can schedule HSI events when a patient presents symptoms indicative of the corresponding illness or condition.

When overwriting, arguments that are not required can be left out of the definition. If done so, the method MUST take a **kwargs input to avoid errors when looping over all disease modules and running their generic HSI methods.

HSI_Events should be scheduled by the Module implementing this method using the Module.healthsystem.schedule_hsi() method. However, they should not write updates back to the population DataFrame in this method - these values should be returned as a dictionary as described below:

The return value of this function should be a dictionary containing any changes that need to be made to the individual’s row in the population DataFrame. Key/value pairs should be the column name and the new value to assign to the patient. In the event no updates are required; return an object that evaluates to False when cast to a bool. Your options are: - Omit a return statement and value (preferred). - Return an empty dictionary. Use this case when patient details might need updating conditionally, on EG patient symptoms or consumable availability. In which case, an empty dictionary should be created and key-value pairs added to this dictionary as such conditionals are checked. If no conditionals are met, the empty dictionary will be returned. - Use a return statement with no values (use if the logic of your module-specific method necessitates the explicit return). - Return None (not recommended, use “return” on its own, as above).

Parameters:

• patient_id – Row index (ID) of the individual target of the HSI event in the population DataFrame.

• patient_details – Patient details as provided in the population DataFrame.

• symptoms – List of symptoms the patient is experiencing.

• diagnosis_function – A function that can run diagnosis tests based on the patient’s symptoms.

• consumables_checker – A function that can query the HealthSystem to check for available consumables.

• facility_level – The level of the facility that the patient presented at.

• treatment_id – The treatment id of the HSI event triggering the generic appointment.

• random_state – Random number generator to be used when making random choices during event creation.

do_at_generic_first_appt_emergency(patient_id: int, patient_details: PatientDetails | None = None, symptoms: List[str] | None = None, diagnosis_function: DiagnosisFunction | None = None, consumables_checker: ConsumablesChecker | None = None, facility_level: str | None = None, treatment_id: str | None = None, random_state: RandomState | None = None) → IndividualPropertyUpdates | None

Actions to be take during an EMERGENCY generic HSI. Call signature and return values are identical to the do_at_generic_first_appt() method. Derived classes should overwrite this method so that they are compatible with the HealthSystem module, and can schedule HSI events when a patient presents symptoms indicative of the corresponding illness or condition.