Tool

class epiworldpy.Tool(self: epiworldpy._core.Tool, name: str, prevalence: SupportsFloat | SupportsIndex, as_proportion: bool, susceptibility_reduction: SupportsFloat | SupportsIndex = 0.0, transmission_reduction: SupportsFloat | SupportsIndex = 0.0, recovery_enhancer: SupportsFloat | SupportsIndex = 0.0, death_reduction: SupportsFloat | SupportsIndex = 0.0)

Bases: pybind11_object

A tool that changes how a virus affects the agents who carry it.

Tools represent interventions such as vaccines, masks, or treatments. A tool can reduce its carrier’s susceptibility to infection, the chance that its carrier transmits a virus, or its carrier’s chance of dying, and can increase its carrier’s chance of recovering. Add it to a model with Model.add_tool().

As with Virus, each effect can be a constant, a model parameter, or a Python function.

Examples

>>> from epiworldpy import Tool, epimodels
>>> model = epimodels.ModelSIRCONN("COVID-19", n=10000, prevalence=0.01,
...                                contact_rate=5, transmission_rate=0.4,
...                                recovery_rate=0.95)
>>> vaccine = Tool("Vaccine", prevalence=0.5, as_proportion=True,
...                susceptibility_reduction=0.9, transmission_reduction=0.5)
>>> model.add_tool(vaccine)

Create a tool.

Parameters:

• name (str) – Name of the tool.

• prevalence (float) – Proportion or number of agents who receive the tool at the start (see as_proportion).

• as_proportion (bool) – If True, prevalence is a proportion; otherwise, a number of agents.

• susceptibility_reduction (float, default 0.0) – Proportion by which the tool reduces its carrier’s probability of being infected.

• transmission_reduction (float, default 0.0) – Proportion by which the tool reduces the probability that its carrier transmits a virus.

• recovery_enhancer (float, default 0.0) – Proportion by which the tool increases its carrier’s probability of recovery.

• death_reduction (float, default 0.0) – Proportion by which the tool reduces its carrier’s probability of death.

Methods

add_target	Overloaded function.
clear_targets	Remove the targets so that the tool acts on every virus.
distribute	Distribute the tool to agents with its distribution function.
get_date	Get the day the agent carrying this copy of the tool received it.
get_id	Get the tool's ID in the model.
get_name	Get the name of the tool.
get_queue	Get the queue changes set with set_queue().
get_state	Get the states set with set_state().
get_targets	Get the virus lineages the tool acts on.
print	Print information about the tool.
set_date	Set the day the agent carrying this copy of the tool received it.
set_death_reduction	Overloaded function.
set_death_reduction_fun	Compute the death reduction with a Python function.
set_distribution	Set how the tool is distributed to agents at the start of a run.
set_name	Set the name of the tool.
set_queue	Set how acquiring or losing this tool updates the queuing system.
set_recovery_enhancer	Overloaded function.
set_recovery_enhancer_fun	Compute the recovery enhancer with a Python function.
set_state	Set the states agents move to when this tool is acquired or lost.
set_susceptibility_reduction	Overloaded function.
set_susceptibility_reduction_fun	Compute the susceptibility reduction with a Python function.
set_targets	Replace the virus lineages the tool acts on.
set_transmission_reduction	Overloaded function.
set_transmission_reduction_fun	Compute the transmission reduction with a Python function.
targets	Check whether the tool acts on a virus.

add_target(*args, **kwargs)

Overloaded function.

1. add_target(self: epiworldpy._core.Tool, target: typing.SupportsInt | typing.SupportsIndex) -> None

Restrict the tool to a virus lineage.

By default, a tool acts on every virus. Adding targets restricts all of the tool’s effects (susceptibility and transmission reduction, recovery enhancer, and death reduction) to the listed virus lineages. A lineage is a virus added with Model.add_virus() together with all of its mutations, so a tool targeting a virus also acts on its variants. Only lineages 0 to 62 can be targeted. Set the targets before calling Model.add_tool(), which copies the tool.

Parameters:

target (int or Virus) – Lineage ID (see Virus.get_lineage_id()), or a virus already added to the model with Model.add_virus().

2. add_target(self: epiworldpy._core.Tool, target: epiworldpy._core.Virus) -> None

Restrict the tool to a virus lineage.

By default, a tool acts on every virus. Adding targets restricts all of the tool’s effects (susceptibility and transmission reduction, recovery enhancer, and death reduction) to the listed virus lineages. A lineage is a virus added with Model.add_virus() together with all of its mutations, so a tool targeting a virus also acts on its variants. Only lineages 0 to 62 can be targeted. Set the targets before calling Model.add_tool(), which copies the tool.

Parameters:

target (int or Virus) – Lineage ID (see Virus.get_lineage_id()), or a virus already added to the model with Model.add_virus().

clear_targets(self: epiworldpy._core.Tool) → None

Remove the targets so that the tool acts on every virus.

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

Distribute the tool to agents with its distribution function.

Parameters:

model (Model) – The model to distribute the tool in.

get_date(self: epiworldpy._core.Tool) → int

Get the day the agent carrying this copy of the tool received it.

Returns:

Simulation day.

Return type:

int

get_id(self: epiworldpy._core.Tool) → int

Get the tool’s ID in the model.

Returns:

ID of the tool.

Return type:

int

get_name(self: epiworldpy._core.Tool) → str

Get the name of the tool.

Returns:

Name of the tool.

Return type:

str

get_queue(self: epiworldpy._core.Tool) → dict

Get the queue changes set with set_queue().

Returns:

Keys "init" and "post".

Return type:

dict

get_state(self: epiworldpy._core.Tool) → dict

Get the states set with set_state().

Returns:

Keys "init" and "post".

Return type:

dict

get_targets(self: epiworldpy._core.Tool) → list[int]

Get the virus lineages the tool acts on.

Returns:

Lineage IDs. Empty if the tool acts on every virus.

Return type:

list of int

print(self: epiworldpy._core.Tool) → None

Print information about the tool.

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

Set the day the agent carrying this copy of the tool received it.

Parameters:

date (int) – Simulation day.

set_death_reduction(*args, **kwargs)

Overloaded function.

1. set_death_reduction(self: epiworldpy._core.Tool, death_reduction: typing.SupportsFloat | typing.SupportsIndex) -> None

Set the reduction in the carrier’s probability of death.

Parameters:

death_reduction (float) – Proportion between 0 and 1.

2. set_death_reduction(self: epiworldpy._core.Tool, param: str) -> None

Read the death reduction from a model parameter.

The tool 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_death_reduction_fun(self: epiworldpy._core.Tool, fun: collections.abc.Callable[[epiworldpy._core.Tool, epiworldpy._core.Agent, epiworldpy._core.Virus, epiworldpy._core.Model], SupportsFloat | SupportsIndex]) → None

Compute the death reduction with a Python function.

Parameters:

fun (callable) – Function fun(tool, agent, virus, model) -> float returning the death reduction for agent against virus.

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

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

By default, the tool goes to a random prevalence of the agents.

Parameters:

fun (callable) – Function fun(tool, model) -> None that gives the tool to the initial agents, for example with Agent.add_tool().

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

Set the name of the tool.

Parameters:

name (str) – New name.

set_queue(self: epiworldpy._core.Tool, init: SupportsInt | SupportsIndex, post: SupportsInt | SupportsIndex) → None

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

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

Parameters:

• init (int) – Queue change when an agent receives the tool.

• post (int) – Queue change when an agent loses the tool.

set_recovery_enhancer(*args, **kwargs)

Overloaded function.

1. set_recovery_enhancer(self: epiworldpy._core.Tool, recovery_enhancer: typing.SupportsFloat | typing.SupportsIndex) -> None

Set the increase in the carrier’s probability of recovery.

Parameters:

recovery_enhancer (float) – Proportion between 0 and 1.

2. set_recovery_enhancer(self: epiworldpy._core.Tool, param: str) -> None

Read the recovery enhancer from a model parameter.

The tool 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_recovery_enhancer_fun(self: epiworldpy._core.Tool, fun: collections.abc.Callable[[epiworldpy._core.Tool, epiworldpy._core.Agent, epiworldpy._core.Virus, epiworldpy._core.Model], SupportsFloat | SupportsIndex]) → None

Compute the recovery enhancer with a Python function.

Parameters:

fun (callable) – Function fun(tool, agent, virus, model) -> float returning the recovery enhancer for agent against virus.

set_state(self: epiworldpy._core.Tool, init: SupportsInt | SupportsIndex, post: SupportsInt | SupportsIndex) → None

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

Parameters:

• init (int) – State of an agent when it receives the tool.

• post (int) – State of an agent when it loses the tool.

set_susceptibility_reduction(*args, **kwargs)

Overloaded function.

1. set_susceptibility_reduction(self: epiworldpy._core.Tool, susceptibility_reduction: typing.SupportsFloat | typing.SupportsIndex) -> None

Set the reduction in the carrier’s probability of being infected.

Parameters:

susceptibility_reduction (float) – Proportion between 0 and 1.

2. set_susceptibility_reduction(self: epiworldpy._core.Tool, param: str) -> None

Read the susceptibility reduction from a model parameter.

The tool 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_susceptibility_reduction_fun(self: epiworldpy._core.Tool, fun: collections.abc.Callable[[epiworldpy._core.Tool, epiworldpy._core.Agent, epiworldpy._core.Virus, epiworldpy._core.Model], SupportsFloat | SupportsIndex]) → None

Compute the susceptibility reduction with a Python function.

Parameters:

fun (callable) – Function fun(tool, agent, virus, model) -> float returning the susceptibility reduction for agent against virus.

set_targets(self: epiworldpy._core.Tool, lineage_ids: collections.abc.Sequence[SupportsInt | SupportsIndex]) → None

Replace the virus lineages the tool acts on.

Parameters:

lineage_ids (list of int) – Lineage IDs (see Virus.get_lineage_id()). An empty list makes the tool act on every virus.

set_transmission_reduction(*args, **kwargs)

Overloaded function.

1. set_transmission_reduction(self: epiworldpy._core.Tool, transmission_reduction: typing.SupportsFloat | typing.SupportsIndex) -> None

Set the reduction in the probability that the carrier transmits a virus.

Parameters:

transmission_reduction (float) – Proportion between 0 and 1.

2. set_transmission_reduction(self: epiworldpy._core.Tool, param: str) -> None

Read the transmission reduction from a model parameter.

The tool 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_transmission_reduction_fun(self: epiworldpy._core.Tool, fun: collections.abc.Callable[[epiworldpy._core.Tool, epiworldpy._core.Agent, epiworldpy._core.Virus, epiworldpy._core.Model], SupportsFloat | SupportsIndex]) → None

Compute the transmission reduction with a Python function.

Parameters:

fun (callable) – Function fun(tool, agent, virus, model) -> float returning the transmission reduction for agent against virus.

targets(self: epiworldpy._core.Tool, v: epiworldpy._core.Virus) → bool

Check whether the tool acts on a virus.

Parameters:

v (Virus) – The virus.

Returns:

True if the tool acts on the virus’s lineage.

Return type:

bool