diseases

diseases

Base classes for diseases

Classes

Name	Description
Disease	Base module class for diseases
Infection	Base class for infectious diseases used in Starsim
InfectionLog	Record infections
NCD	Example non-communicable disease
SIR	Example SIR model
SIS	Example SIS model

Disease

diseases.Disease(self, pars=None, **kwargs)

Base module class for diseases

Methods

Name	Description
init_pre	Link the disease to the sim, create objects, and initialize results; see Module.init_pre() for details
set_prognoses	Set prognoses upon infection/acquisition
step	Handle the main disease updates, e.g. add new cases
step_die	Carry out state changes upon death
step_state	Carry out updates at the start of the timestep (prior to transmission);

init_pre

diseases.Disease.init_pre(sim)

Link the disease to the sim, create objects, and initialize results; see Module.init_pre() for details

set_prognoses

diseases.Disease.set_prognoses(uids, sources=None)

Set prognoses upon infection/acquisition

This function assigns state values upon infection or acquisition of the disease. It would normally be called somewhere towards the end of Disease.make_new_cases(). Infections will optionally be added to the log as part of this operation if logging is enabled (in the Disease parameters)

The sources are relevant for infectious diseases, but would be left as None for NCDs.

Parameters

Name	Type	Description	Default
uids	array	UIDs for agents to assign disease prongoses to	required
sources	array	Optionally specify the infecting agent	None

step

diseases.Disease.step()

Handle the main disease updates, e.g. add new cases

This method is agnostic as to the mechanism by which new cases occur. This could be through transmission (parametrized in different ways, which may or may not use the contact networks) or it may be based on risk factors/seeding, as may be the case for non-communicable diseases.

It is expected that this method will internally call Disease.set_prognoses() at some point.

step_die

diseases.Disease.step_die(uids)

Carry out state changes upon death

This function is triggered after deaths are resolved, and before analyzers are run. See the SIR example model for a typical use case - deaths are requested as an autonomous update, to take effect after transmission on the same timestep. State changes that occur upon death (e.g., clearing an infected flag) are executed in this function. That also allows an intervention to avert a death scheduled on the same timestep, without having to undo any state changes that have already been applied (because they only run via this function if the death actually occurs).

Unlike other methods during the integration loop, this method is not called directly by the sim; instead, it is called by people.step_die(), which reconciles the UIDs of the agents who will die.

Depending on the module and the results it produces, it may or may not be necessary to implement this.

step_state

diseases.Disease.step_state()

Carry out updates at the start of the timestep (prior to transmission); these are typically state changes

Infection

diseases.Infection(self, pars=None, **kwargs)

Base class for infectious diseases used in Starsim

This class contains specializations for infectious transmission (i.e., implements network-based transmission with directional beta values) and defines attributes that connectors operate on to capture co-infection

Attributes

Name	Description
infectious	Generally defined as an alias for infected, although these may differ in some diseases.

Methods

Name	Description
compute_transmission	Compute the probability of a->b transmission for networks (for other routes, the Route handles this)
infect	Determine who gets infected on this timestep via transmission on the network
init_post	Set initial values for states. This could involve passing in a full set of initial conditions,
init_results	Initialize results
step	Perform key infection updates, including infection and setting prognoses
validate_beta	Validate beta and return as a map to match the networks

compute_transmission

diseases.Infection.compute_transmission(
    src,
    trg,
    rel_trans,
    rel_sus,
    beta_per_dt,
    randvals,
)

Compute the probability of a->b transmission for networks (for other routes, the Route handles this)

infect

diseases.Infection.infect()

Determine who gets infected on this timestep via transmission on the network

init_post

diseases.Infection.init_post()

Set initial values for states. This could involve passing in a full set of initial conditions, or using init_prev, or other. Note that this is different to initialization of the Arr objects i.e., creating their dynamic array, linking them to a People instance. That should have already taken place by the time this method is called.

init_results

diseases.Infection.init_results()

Initialize results

step

diseases.Infection.step()

Perform key infection updates, including infection and setting prognoses

validate_beta

diseases.Infection.validate_beta()

Validate beta and return as a map to match the networks

InfectionLog

diseases.InfectionLog()

Record infections

The infection log records transmission events and optionally other data associated with each transmission. Basic functionality is to track transmission with

Disease.infection_log.append(source, target, t)

Seed infections can be recorded with a source of None, although all infections should have a target and a time. Other data can be captured in the log, either at the time of creation, or later on. For example

Disease.infection_log.append(source, target, t, network=‘msm’)

could be used by a module to track the network in which transmission took place. Modules can optionally add per-infection outcomes later as well, for example

Disease.infection_log.add_data(source, t_dead=2024.25)

This would be equivalent to having specified the data at the original time the log entry was created - however, it is more useful for tracking events that may or may not occur after the infection and could be modified by interventions (e.g., tracking diagnosis, treatment, notification etc.)

A table of outcomes can be returned using InfectionLog.line_list()

Methods

Name	Description
add_data	Record extra infection data
to_df	Return a tabular representation of the log as a line list dataframe

add_data

diseases.InfectionLog.add_data(uids, **kwargs)

Record extra infection data

This method can be used to add data to an existing transmission event. The most recent transmission event will be used

Parameters

Name	Type	Description	Default
uids	array	The UIDs of the target nodes (the agents that were infected)	required
kwargs	dict	Remaining arguments are stored as edge data	{}

to_df

diseases.InfectionLog.to_df()

Return a tabular representation of the log as a line list dataframe

This function returns a dataframe containing columns for all quantities recorded in the log. Note that the log will contain NaN for quantities that are defined for some edges and not others (and which are missing for a particular entry)

NCD

diseases.NCD(self, pars=None, initial_risk=_, dur_risk=_, prognosis=_, **kwargs)

Example non-communicable disease

This class implements a basic NCD model with risk of developing a condition (e.g., hypertension, diabetes), a state for having the condition, and associated mortality.

Parameters

Name	Type	Description	Default
initial_risk	float/ss.bernoulli	initial prevalence of risk factors	_
dur_risk	float/ss.dur/ss.Dist	how long a person is at risk for	_
prognosis	float/ss.dur/ss.Dist	time in years between first becoming affected and death	_

Methods

Name	Description
init_post	Set initial values for states. This could involve passing in a full set of initial conditions,
init_results	Initialize results

init_post

diseases.NCD.init_post()

Set initial values for states. This could involve passing in a full set of initial conditions, or using init_prev, or other. Note that this is different to initialization of the State objects i.e., creating their dynamic array, linking them to a People instance. That should have already taken place by the time this method is called.

init_results

diseases.NCD.init_results()

Initialize results

SIR

diseases.SIR(
    self,
    pars=None,
    beta=_,
    init_prev=_,
    dur_inf=_,
    p_death=_,
    **kwargs,
)

Example SIR model

This class implements a basic SIR model with states for susceptible, infected/infectious, and recovered. It also includes deaths, and basic results.

Parameters

Name	Type	Description	Default
beta	float/ss.prob	the infectiousness	_
init_prev	float/ss.bernoulli	the fraction of people to start of being infected	_
dur_inf	float/ss.dur/ss.Dist	how long (in years) people are infected for	_
p_death	float/ss.bernoulli	the probability of death from infection	_

Methods

Name	Description
plot	Default plot for SIR model
set_prognoses	Set prognoses
step_die	Reset infected/recovered flags for dead agents

plot

diseases.SIR.plot(**kwargs)

Default plot for SIR model

set_prognoses

diseases.SIR.set_prognoses(uids, sources=None)

Set prognoses

step_die

diseases.SIR.step_die(uids)

Reset infected/recovered flags for dead agents

SIS

diseases.SIS(
    self,
    pars=None,
    beta=_,
    init_prev=_,
    dur_inf=_,
    waning=_,
    imm_boost=_,
    **kwargs,
)

Example SIS model

This class implements a basic SIS model with states for susceptible, infected/infectious, and back to susceptible based on waning immunity. There is no death in this case.

Parameters

Name	Type	Description	Default
beta	float/ss.prob	the infectiousness	_
init_prev	float/ss.bernoulli	the fraction of people to start of being infected	_
dur_inf	float/ss.dur/ss.Dist	how long (in years) people are infected for	_
waning	float/ss.rate	how quickly immunity wanes	_
imm_boost	float	how much an infection boosts immunity	_

Methods

Name	Description
init_results	Initialize results
plot	Default plot for SIS model
set_prognoses	Set prognoses
step_state	Progress infectious -> recovered
update_results	Store the population immunity (susceptibility)

init_results

diseases.SIS.init_results()

Initialize results

plot

diseases.SIS.plot(**kwargs)

Default plot for SIS model

set_prognoses

diseases.SIS.set_prognoses(uids, sources=None)

Set prognoses

step_state

diseases.SIS.step_state()

Progress infectious -> recovered

update_results

diseases.SIS.update_results()

Store the population immunity (susceptibility)