Entity

class epiworldpy.Entity(self: epiworldpy._core.Entity, name: str, fun: collections.abc.Callable[[epiworldpy._core.Entity, epiworldpy._core.Model], None] = None)

Bases: pybind11_object

A group of agents, such as a household, school, or age group.

Mixing models (for example, ModelSIRMixing) use entities as the groups of their contact matrix. Add an entity to a model with Model.add_entity(); its distribution function assigns agents to it when the model is run.

Examples

>>> from epiworldpy import Entity
>>> # Agents 0-4999 in one group, 5000-9999 in the other.
>>> young = Entity("Young", Entity.distribute_to_range(0, 5000))
>>> old = Entity("Old", Entity.distribute_to_range(5000, 10000))

Create an entity.

Parameters:

• name (str) – Name of the entity.

• fun (callable or None, default None) – Function fun(entity, model) -> None that assigns agents to the entity, for example one from distribute_randomly(), distribute_to_range(), or distribute_to_set().

Methods

distribute	Assign agents to the entity with its distribution function.
distribute_randomly	Get a distribution function that assigns random agents to the entity.
distribute_to_range	Get a distribution function that assigns a range of agents to the entity.
distribute_to_set	Get a distribution function that assigns given agents to the entity.
get_agents_ids	Get the agents in the entity.
get_id	Get the entity's ID in the model.
get_location	Get the entity's location.
get_name	Get the name of the entity.
new_entity_to_agent_fun	Wrap a Python function as a distribution function.
print	Print information about the entity.
set_distribution	Set how agents are assigned to the entity at the start of a run.
set_location	Set the entity's location.
set_queue	Set how joining or leaving the entity updates the queuing system.
set_state	Set the states agents move to when they join or leave the entity.
size	Get the number of agents in the entity.

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

Assign agents to the entity with its distribution function.

Parameters:

model (Model) – The model the entity belongs to.

static distribute_randomly(prevalence: SupportsFloat | SupportsIndex, as_proportion: bool = True, to_unassigned: bool = False) → collections.abc.Callable[[epiworldpy._core.Entity, epiworldpy._core.Model], None]

Get a distribution function that assigns random agents to the entity.

Parameters:

• prevalence (float) – Proportion or number of agents to assign (see as_proportion).

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

• to_unassigned (bool, default False) – If True, only pick agents that do not belong to any entity yet.

Returns:

The distribution function, for Entity or set_distribution().

Return type:

callable

static distribute_to_range(from_: SupportsInt | SupportsIndex, to_: SupportsInt | SupportsIndex) → collections.abc.Callable[[epiworldpy._core.Entity, epiworldpy._core.Model], None]

Get a distribution function that assigns a range of agents to the entity.

Parameters:

• from (int) – ID of the first agent.

• to (int) – ID after the last agent (the range is [from_, to_)).

Returns:

The distribution function, for Entity or set_distribution().

Return type:

callable

static distribute_to_set(ids: collections.abc.Sequence[SupportsInt | SupportsIndex]) → collections.abc.Callable[[epiworldpy._core.Entity, epiworldpy._core.Model], None]

Get a distribution function that assigns given agents to the entity.

Parameters:

ids (list of int) – IDs of the agents.

Returns:

The distribution function, for Entity or set_distribution().

Return type:

callable

get_agents_ids(self: epiworldpy._core.Entity) → list[int]

Get the agents in the entity.

Returns:

IDs of the agents.

Return type:

list of int

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

Get the entity’s ID in the model.

Returns:

ID of the entity.

Return type:

int

get_location(self: epiworldpy._core.Entity) → list[float]

Get the entity’s location.

Returns:

Coordinates of the entity.

Return type:

list of float

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

Get the name of the entity.

Returns:

Name of the entity.

Return type:

str

static new_entity_to_agent_fun(fun: collections.abc.Callable[[epiworldpy._core.Entity, epiworldpy._core.Model], None]) → collections.abc.Callable[[epiworldpy._core.Entity, epiworldpy._core.Model], None]

Wrap a Python function as a distribution function.

Parameters:

fun (callable) – Function fun(entity, model) -> None that assigns agents to entity.

Returns:

The distribution function, for Entity or set_distribution().

Return type:

callable

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

Print information about the entity.

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

Set how agents are assigned to the entity at the start of a run.

Parameters:

fun (callable) – Function fun(entity, model) -> None, for example one from distribute_randomly(), distribute_to_range(), or distribute_to_set().

set_location(self: epiworldpy._core.Entity, location: collections.abc.Sequence[SupportsFloat | SupportsIndex]) → None

Set the entity’s location.

Parameters:

location (list of float) – Coordinates of the entity.

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

Set how joining or leaving the entity updates the queuing system.

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

Parameters:

• init (int) – Queue change when an agent joins the entity.

• post (int) – Queue change when an agent leaves the entity.

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

Set the states agents move to when they join or leave the entity.

Parameters:

• init (int) – State of an agent when it joins the entity.

• post (int) – State of an agent when it leaves the entity.

size(self: epiworldpy._core.Entity) → int

Get the number of agents in the entity.

Returns:

Number of agents.

Return type:

int