Virus

Virus#

class epiworldpy.Virus(self: epiworldpy._core.Virus, name: str, prevalence: SupportsFloat | SupportsIndex, as_proportion: bool, prob_infecting: SupportsFloat | SupportsIndex, prob_recovery: SupportsFloat | SupportsIndex, prob_death: SupportsFloat | SupportsIndex, post_immunity: SupportsFloat | SupportsIndex = 0.0, incubation: SupportsFloat | SupportsIndex | None = None)#

Bases: pybind11_object

A virus (or any other contagious condition) that spreads between agents.

A virus sets the probabilities of infection, recovery, and death, and the states infected agents move through. Add it to a model with Model.add_virus(); each infected agent carries its own copy.

Each probability can be a constant (set_prob_infecting(0.3)), a model parameter (set_prob_infecting("Transmission rate"), which follows later changes to the parameter), or a Python function (set_prob_infecting_fun()). The agents’ tools then modify these probabilities (see Tool).

Examples

>>> from epiworldpy import Virus, epimodels
>>> model = epimodels.ModelSEIRCONN("COVID-19", n=10000, prevalence=0.01,
...                                 contact_rate=2, transmission_rate=0.5,
...                                 incubation_days=7, recovery_rate=0.3)
>>> flu = Virus("Flu", prevalence=0.001, as_proportion=True,
...             prob_infecting=0.9, prob_recovery=1 / 7, prob_death=0.0)
>>> model.add_virus(flu)

Create a virus.

Parameters:

name (str) – Name of the virus.
prevalence (float) – Proportion or number of agents infected at the start (see as_proportion).
as_proportion (bool) – If True, prevalence is a proportion; otherwise, a number of agents.
prob_infecting (float) – Probability of transmission per contact.
prob_recovery (float) – Daily probability of recovery.
prob_death (float) – Daily probability of death.
post_immunity (float, default 0.0) – Protection against reinfection after recovery: recovered agents receive a tool that reduces their susceptibility to this virus by this proportion. 0 gives no protection.
incubation (float or None, default None) – Average incubation period in days, used by models with an exposed state.

Methods

`distribute`	Distribute the virus to agents with its distribution function.
`get_date`	Get the day the agent carrying this copy of the virus was infected.
`get_id`	Get the virus's ID in the model.
`get_incubation`	Get the average incubation period for the agent carrying this virus.
`get_lineage_id`	Get the ID of the virus's lineage.
`get_name`	Get the name of the virus.
`get_prob_death`	Get the daily probability of death for the agent carrying this virus.
`get_prob_infecting`	Get the probability of transmission per contact for the agent carrying this virus.
`get_prob_recovery`	Get the daily probability of recovery for the agent carrying this virus.
`get_queue`	Get the queue changes set with `set_queue()`.
`get_state`	Get the states set with `set_state()`.
`mutate`	Run the mutation function (see `set_mutation()`).
`post_recovery`	Run the post-recovery function (see `set_post_recovery()`).
`print`	Print information about the virus.
`set_date`	Set the day the agent carrying this copy of the virus was infected.
`set_distribution`	Set how the virus is distributed to agents at the start of a run.
`set_incubation`	Overloaded function.
`set_incubation_fun`	Compute the incubation period with a Python function.
`set_mutation`	Set the mutation function.
`set_name`	Set the name of the virus.
`set_post_immunity`	Overloaded function.
`set_post_recovery`	Set a function called when an agent recovers from this virus.
`set_prob_death`	Overloaded function.
`set_prob_death_fun`	Compute the probability of death with a Python function.
`set_prob_infecting`	Overloaded function.
`set_prob_infecting_fun`	Compute the probability of transmission with a Python function.
`set_prob_recovery`	Overloaded function.
`set_prob_recovery_fun`	Compute the probability of recovery with a Python function.
`set_queue`	Set how acquiring or losing this virus updates the queuing system.
`set_sequence`	Set the virus's genetic sequence, which identifies its variant.
`set_state`	Set the states agents move to when this virus is acquired or lost.

distribute(self: epiworldpy._core.Virus, model: epiworldpy._core.Model) → None#

Distribute the virus to agents with its distribution function.

Parameters:: model (Model) – The model to distribute the virus in.

get_date(self: epiworldpy._core.Virus) → int#

Get the day the agent carrying this copy of the virus was infected.

Returns:: Simulation day.
Return type:: int

get_id(self: epiworldpy._core.Virus) → int#

Get the virus’s ID in the model.

Returns:: ID of the virus.
Return type:: int

get_incubation(self: epiworldpy._core.Virus, model: epiworldpy._core.Model) → float#

Get the average incubation period for the agent carrying this virus.

Parameters:: model (Model) – The model the virus belongs to.
Returns:: The average incubation period.
Return type:: float

get_lineage_id(self: epiworldpy._core.Virus) → int#

Get the ID of the virus’s lineage.

The lineage ID is the ID that Model.add_virus() assigns to the founding virus. Mutations change the virus ID but keep the lineage ID, so all variants of a virus share it. Tools target viruses by lineage (see Tool.add_target()).

Returns:: The lineage ID, or -99 if the virus has not been added to a model.
Return type:: int

get_name(self: epiworldpy._core.Virus) → str#

Get the name of the virus.

Returns:: Name of the virus.
Return type:: str

get_prob_death(self: epiworldpy._core.Virus, model: epiworldpy._core.Model) → float#

Get the daily probability of death for the agent carrying this virus.

Parameters:: model (Model) – The model the virus belongs to.
Returns:: The daily probability of death.
Return type:: float

get_prob_infecting(self: epiworldpy._core.Virus, model: epiworldpy._core.Model) → float#

Get the probability of transmission per contact for the agent carrying this virus.

Parameters:: model (Model) – The model the virus belongs to.
Returns:: The probability of transmission per contact.
Return type:: float

get_prob_recovery(self: epiworldpy._core.Virus, model: epiworldpy._core.Model) → float#

Get the daily probability of recovery for the agent carrying this virus.

Parameters:: model (Model) – The model the virus belongs to.
Returns:: The daily probability of recovery.
Return type:: float

get_queue(self: epiworldpy._core.Virus) → dict#

Get the queue changes set with set_queue().

Returns:: Keys "init", "end", and "removed".
Return type:: dict

get_state(self: epiworldpy._core.Virus) → dict#

Get the states set with set_state().

Returns:: Keys "init", "end", and "removed".
Return type:: dict

mutate(self: epiworldpy._core.Virus, model: epiworldpy._core.Model) → None#

Run the mutation function (see set_mutation()).

Parameters:: model (Model) – The model the virus belongs to.

post_recovery(self: epiworldpy._core.Virus, model: epiworldpy._core.Model) → None#

Run the post-recovery function (see set_post_recovery()).

Parameters:: model (Model) – The model the virus belongs to.

print(self: epiworldpy._core.Virus) → None#: Print information about the virus.

set_date(self: epiworldpy._core.Virus, date: SupportsInt | SupportsIndex) → None#

Set the day the agent carrying this copy of the virus was infected.

Parameters:: date (int) – Simulation day.

set_distribution(self: epiworldpy._core.Virus, fun: collections.abc.Callable[[epiworldpy._core.Virus, epiworldpy._core.Model], None]) → None#

Set how the virus is distributed to agents at the start of a run.

By default, the virus infects a random prevalence of the agents.

Parameters:: fun (callable) – Function fun(virus, model) -> None that infects the initial agents, for example with Agent.set_virus().

set_incubation(*args, **kwargs)#

Overloaded function.

set_incubation(self: epiworldpy._core.Virus, incubation: typing.SupportsFloat | typing.SupportsIndex) -> None

Set the average incubation period.

Parameters:: incubation (float) – Average number of days in the exposed state.

set_incubation(self: epiworldpy._core.Virus, param: str) -> None

Read the average incubation period from a model parameter.

The virus reads the parameter’s current value each time, so later changes to the parameter (see Model.set_param()) take effect.

Parameters:: param (str) – Name of the model parameter.

set_incubation_fun(self: epiworldpy._core.Virus, fun: collections.abc.Callable[[epiworldpy._core.Agent, epiworldpy._core.Virus, epiworldpy._core.Model], SupportsFloat | SupportsIndex]) → None#

Compute the incubation period with a Python function.

Parameters:: fun (callable) – Function fun(agent, virus, model) -> float returning the incubation period for agent.

set_mutation(self: epiworldpy._core.Virus, fun: collections.abc.Callable[[epiworldpy._core.Agent, epiworldpy._core.Virus, epiworldpy._core.Model], bool]) → None#

Set the mutation function.

The function is called on each copy of the virus at every step (see mutate()).

Parameters:: fun (callable) – Function fun(agent, virus, model) -> bool that may change virus (for example, with set_sequence()) and returns True if it mutated, so the new variant is recorded in the database.

set_name(self: epiworldpy._core.Virus, name: str) → None#

Set the name of the virus.

Parameters:: name (str) – New name.

set_post_immunity(*args, **kwargs)#

Overloaded function.

set_post_immunity(self: epiworldpy._core.Virus, prob: typing.SupportsFloat | typing.SupportsIndex) -> None

Protect recovered agents against reinfection.

Recovered agents receive a tool that reduces their susceptibility to this virus. Cannot be combined with set_post_recovery().

Parameters:: prob (float) – Susceptibility reduction between 0 and 1; 1 gives full immunity.

set_post_immunity(self: epiworldpy._core.Virus, param: str) -> None

Protect recovered agents against reinfection, reading the protection from a model parameter.

Parameters:: param (str) – Name of the model parameter with the susceptibility reduction.

set_post_recovery(self: epiworldpy._core.Virus, fun: collections.abc.Callable[[epiworldpy._core.Agent, epiworldpy._core.Virus, epiworldpy._core.Model], None]) → None#

Set a function called when an agent recovers from this virus.

Cannot be combined with set_post_immunity(), which uses this hook.

Parameters:: fun (callable) – Function fun(agent, virus, model) -> None.

set_prob_death(*args, **kwargs)#

Overloaded function.

set_prob_death(self: epiworldpy._core.Virus, prob_death: typing.SupportsFloat | typing.SupportsIndex) -> None

Set the daily probability of death.

Parameters:: prob_death (float) – Probability between 0 and 1.

set_prob_death(self: epiworldpy._core.Virus, param: str) -> None

Read the daily probability of death from a model parameter.

The virus reads the parameter’s current value each time, so later changes to the parameter (see Model.set_param()) take effect.

Parameters:: param (str) – Name of the model parameter.

set_prob_death_fun(self: epiworldpy._core.Virus, fun: collections.abc.Callable[[epiworldpy._core.Agent, epiworldpy._core.Virus, epiworldpy._core.Model], SupportsFloat | SupportsIndex]) → None#

Compute the probability of death with a Python function.

Parameters:: fun (callable) – Function fun(agent, virus, model) -> float returning the probability of death for agent.

set_prob_infecting(*args, **kwargs)#

Overloaded function.

set_prob_infecting(self: epiworldpy._core.Virus, prob_infecting: typing.SupportsFloat | typing.SupportsIndex) -> None

Set the probability of transmission per contact.

Parameters:: prob_infecting (float) – Probability between 0 and 1.

set_prob_infecting(self: epiworldpy._core.Virus, param: str) -> None

Read the probability of transmission per contact from a model parameter.

The virus reads the parameter’s current value each time, so later changes to the parameter (see Model.set_param()) take effect.

Parameters:: param (str) – Name of the model parameter.

set_prob_infecting_fun(self: epiworldpy._core.Virus, fun: collections.abc.Callable[[epiworldpy._core.Agent, epiworldpy._core.Virus, epiworldpy._core.Model], SupportsFloat | SupportsIndex]) → None#

Compute the probability of transmission with a Python function.

Parameters:: fun (callable) – Function fun(agent, virus, model) -> float returning the probability of transmission for agent.

set_prob_recovery(*args, **kwargs)#

Overloaded function.

set_prob_recovery(self: epiworldpy._core.Virus, prob_recovery: typing.SupportsFloat | typing.SupportsIndex) -> None

Set the daily probability of recovery.

Parameters:: prob_recovery (float) – Probability between 0 and 1.

set_prob_recovery(self: epiworldpy._core.Virus, param: str) -> None

Read the daily probability of recovery from a model parameter.

The virus reads the parameter’s current value each time, so later changes to the parameter (see Model.set_param()) take effect.

Parameters:: param (str) – Name of the model parameter.

set_prob_recovery_fun(self: epiworldpy._core.Virus, fun: collections.abc.Callable[[epiworldpy._core.Agent, epiworldpy._core.Virus, epiworldpy._core.Model], SupportsFloat | SupportsIndex]) → None#

Compute the probability of recovery with a Python function.

Parameters:: fun (callable) – Function fun(agent, virus, model) -> float returning the probability of recovery for agent.

set_queue(self: epiworldpy._core.Virus, init: SupportsInt | SupportsIndex, end: SupportsInt | SupportsIndex, removed: SupportsInt | SupportsIndex) → None#

Set how acquiring or losing this virus updates the queuing system.

Values follow Agent.change_state()’s queue argument.

Parameters:

init (int) – Queue change when an agent acquires the virus.
end (int) – Queue change when an agent loses the virus.
removed (int) – Queue change when an agent is removed by the virus.

set_sequence(self: epiworldpy._core.Virus, sequence: SupportsInt | SupportsIndex) → None#

Set the virus’s genetic sequence, which identifies its variant.

Parameters:: sequence (int) – The sequence.

set_state(self: epiworldpy._core.Virus, init: SupportsInt | SupportsIndex, end: SupportsInt | SupportsIndex, removed: SupportsInt | SupportsIndex) → None#

Set the states agents move to when this virus is acquired or lost.

Parameters:

init (int) – State of an agent when it acquires the virus.
end (int) – State of an agent when it loses the virus (for example, on recovery).
removed (int) – State of an agent removed by the virus (for example, on death).

Virus

Contents

Virus#