DataBase

class epiworldpy.DataBase

Bases: pybind11_object

The results of a model run.

Get it with Model.get_db() after running the model. The get_* methods return the results as dictionaries of equal-length lists, one entry per row, which convert directly to data frames:

import pandas as pd

model.run(ndays=100, seed=1912)
totals = pd.DataFrame(model.get_db().get_hist_total())

Methods

add_user_data	Overloaded function.
get_active_cases	Get the number of agents with each virus, by day.
get_generation_time	Get the generation time of each infected agent.
get_hist_tool	Get the number of agents with each tool, by state and day.
get_hist_total	Get the number of agents in each state, by day.
get_hist_transition_matrix	Get the number of agents who moved between each pair of states, by day.
get_hist_virus	Get the number of agents with each virus, by state and day.
get_hospitalizations	Get the number of hospitalized agents, by day, virus, and tool.
get_n_tools	Get the number of tools recorded.
get_n_viruses	Get the number of viruses (including variants) recorded.
get_outbreak_size	Get the cumulative number of agents infected with each virus, by day.
get_reproductive_number	Get the number of agents each infected agent went on to infect.
get_today_total	Get the number of agents in each state today.
get_today_transition_matrix	Get the number of agents who moved between each pair of states today.
get_today_virus	Get the number of agents with each virus, by state, today.
get_transition_probability	Estimate the daily probability of moving between each pair of states.
get_transmissions	Get every transmission event.
record	Record the model's current counts.
record_tool	Register a tool, or a new version of one, in the database.
record_transmission	Record a transmission event on the current day.
record_virus	Register a virus, or a new variant of one, in the database.
reset	Clear the recorded results.
size	Get the number of viruses (including variants) recorded.
write_data	Write the results to files.

add_user_data(*args, **kwargs)

Overloaded function.

1. add_user_data(self: epiworldpy._core.DataBase, x: collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex]) -> None

Add a row of user-defined data for the current day.

Parameters:

x (list of float) – One value per user-defined variable.

2. add_user_data(self: epiworldpy._core.DataBase, j: typing.SupportsInt | typing.SupportsIndex, x: typing.SupportsFloat | typing.SupportsIndex) -> None

Set one user-defined variable for the current day.

Starts a new row (filled with zeros) if the current day has none yet.

Parameters:

• j (int) – Index of the variable.

• x (float) – Value.

get_active_cases(self: epiworldpy._core.DataBase) → dict

Get the number of agents with each virus, by day.

Returns:

"dates", "virus_id", and "counts", one entry per row.

Return type:

dict

get_generation_time(self: epiworldpy._core.DataBase) → dict

Get the generation time of each infected agent.

The generation time is the number of days between an agent’s infection and the first infection it caused.

Returns:

"agents" (agent IDs), "viruses" (virus IDs), "times" (days the agents were infected), and "generation_times" (-1 for agents who infected no one), one entry per infected agent.

Return type:

dict

get_hist_tool(self: epiworldpy._core.DataBase) → dict

Get the number of agents with each tool, by state and day.

Returns:

"dates", "ids" (tool IDs), "states" (state labels), and "counts", one entry per row.

Return type:

dict

get_hist_total(self: epiworldpy._core.DataBase) → dict

Get the number of agents in each state, by day.

Returns:

"dates", "states" (state labels), and "counts", one entry per row.

Return type:

dict

get_hist_transition_matrix(self: epiworldpy._core.DataBase, skip_zeros: bool = False) → dict

Get the number of agents who moved between each pair of states, by day.

Parameters:

skip_zeros (bool, default False) – Whether to leave out the rows with a zero count.

Returns:

"state_from", "state_to" (state labels), "dates", and "counts", one entry per row.

Return type:

dict

get_hist_virus(self: epiworldpy._core.DataBase) → dict

Get the number of agents with each virus, by state and day.

Returns:

"dates", "ids" (virus IDs), "states" (state labels), and "counts", one entry per row.

Return type:

dict

get_hospitalizations(self: epiworldpy._core.DataBase) → dict

Get the number of hospitalized agents, by day, virus, and tool.

Only models that track hospitalizations (for example, ModelSEIRNetworkQuarantine) record them.

Returns:

"dates", "virus_id", "tool_id", "count", and "weight", one entry per row.

Return type:

dict

get_n_tools(self: epiworldpy._core.DataBase) → int

Get the number of tools recorded.

Returns:

Number of tools.

Return type:

int

get_n_viruses(self: epiworldpy._core.DataBase) → int

Get the number of viruses (including variants) recorded.

Returns:

Number of viruses.

Return type:

int

get_outbreak_size(self: epiworldpy._core.DataBase) → dict

Get the cumulative number of agents infected with each virus, by day.

Returns:

"dates", "virus_id", and "size", one entry per row.

Return type:

dict

get_reproductive_number(self: epiworldpy._core.DataBase) → numpy.typing.NDArray[numpy.int64]

Get the number of agents each infected agent went on to infect.

Returns:

Integer array with one row per infected agent and four columns: the virus ID, the day the agent was infected, the agent’s ID, and the number of agents it infected (its reproductive number).

Return type:

numpy.ndarray

get_today_total(self: epiworldpy._core.DataBase) → dict

Get the number of agents in each state today.

Returns:

"states" (state labels) and "counts", one entry per state.

Return type:

dict

get_today_transition_matrix(self: epiworldpy._core.DataBase) → dict

Get the number of agents who moved between each pair of states today.

Returns:

"counts": a flattened S x S matrix, where S is the number of states, stored by columns: entry i + j * S counts the agents who moved from state i to state j.

Return type:

dict

get_today_virus(self: epiworldpy._core.DataBase) → dict

Get the number of agents with each virus, by state, today.

Returns:

"states" (state labels), "ids" (virus IDs), and "counts", one entry per row.

Return type:

dict

get_transition_probability(self: epiworldpy._core.DataBase, print: bool = False, normalize: bool = True) → list[float]

Estimate the daily probability of moving between each pair of states.

Parameters:

• print (bool, default False) – Whether to also print the matrix.

• normalize (bool, default True) – Whether to divide the counts by the number of agents in each origin state, giving probabilities; otherwise, return the counts.

Returns:

A flattened S x S matrix, where S is the number of states, stored by columns: entry i + j * S is the probability of moving from state i to state j.

Return type:

list of float

get_transmissions(self: epiworldpy._core.DataBase) → dict

Get every transmission event.

Returns:

"dates", "sources" (IDs of the infecting agents, -1 for the initial cases), "targets" (IDs of the infected agents), "viruses" (virus IDs), and "source_exposure_dates" (days the infecting agents were infected), one entry per event.

Return type:

dict

record(self: epiworldpy._core.DataBase) → None

Record the model’s current counts. Called by the model at every step.

record_tool(self: epiworldpy._core.DataBase, t: epiworldpy._core.Tool) → None

Register a tool, or a new version of one, in the database.

Parameters:

t (Tool) – The tool.

record_transmission(self: epiworldpy._core.DataBase, i: SupportsInt | SupportsIndex, j: SupportsInt | SupportsIndex, virus: SupportsInt | SupportsIndex, i_expo_date: SupportsInt | SupportsIndex) → None

Record a transmission event on the current day.

Called by the model; only needed by custom update functions that infect agents themselves.

Parameters:

• i (int) – ID of the agent who transmitted the virus, or -1 if unknown.

• j (int) – ID of the agent who was infected.

• virus (int) – ID of the virus.

• i_expo_date (int) – Day the transmitting agent was infected.

record_virus(self: epiworldpy._core.DataBase, v: epiworldpy._core.Virus, founder: bool = False) → None

Register a virus, or a new variant of one, in the database.

Parameters:

• v (Virus) – The virus.

• founder (bool, default=False) – Whether this virus was registered directly with the model as a founding variant.

reset(self: epiworldpy._core.DataBase) → None

Clear the recorded results. Called by Model.reset().

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

Get the number of viruses (including variants) recorded.

Returns:

Number of viruses.

Return type:

int

write_data(self: epiworldpy._core.DataBase, fn_virus_info: str, fn_virus_hist: str, fn_tool_info: str, fn_tool_hist: str, fn_total_hist: str, fn_transmission: str, fn_transition: str, fn_reproductive_number: str, fn_generation_time: str, fn_active_cases: str = '', fn_outbreak_size: str = '', fn_hospitalizations: str = '') → None

Write the results to files.

Each argument is the path of a file to write; files with an empty path are skipped. See Model.write_data(), which has defaults for all of them.

Parameters:

• fn_virus_info (str) – Information about each virus.

• fn_virus_hist (str) – History of each virus (see get_hist_virus()).

• fn_tool_info (str) – Information about each tool.

• fn_tool_hist (str) – History of each tool (see get_hist_tool()).

• fn_total_hist (str) – Totals per state and day (see get_hist_total()).

• fn_transmission (str) – Transmission events (see get_transmissions()).

• fn_transition (str) – Transition counts (see get_hist_transition_matrix()).

• fn_reproductive_number (str) – Reproductive numbers (see get_reproductive_number()).

• fn_generation_time (str) – Generation times (see get_generation_time()).

• fn_active_cases (str, default "") – Active cases (see get_active_cases()).

• fn_outbreak_size (str, default "") – Outbreak sizes (see get_outbreak_size()).

• fn_hospitalizations (str, default "") – Hospitalizations (see get_hospitalizations()).