agents_to_aggregate: generalized method to convert raw agent based data to...

In skgallagher/EpiCompare: A Pipeline to Analyze and Compare Infectious Disease Epidemics

Description

This function converts data on an agent-based level (1 row = 1 agent) relative when an agent is in each state and aggregates it, so that the user can know how many agents are in each state at a given time point (integer based). This function can take standard data.frames and grouped_df data.frames (from dplyr). For the later, this function aggregates within grouping parameters and also provides the columns associated with the grouping.

Usage

agents_to_aggregate(
  agents,
  states,
  death = NULL,
  birth = NULL,
  min_max_time = c(0, NA),
  integer_time_expansion = TRUE
)

Arguments

agents	data frame style object (currently either of class data.frame or grouped_df)
states	time entered state. Do not include column for original state. These need to be ordered, for example: for an SIR model, with columns "tI" and "tR" expressing the time the individual became infected and recovered (respectively), we want "states = c("tI", "tR")". See details for more information.
death	string for column with death time information (default NULL)
birth	string for column with birth time information (default NULL)
min_max_time	vector (length 2) of minimum and maximum integer time, the second value can be NA - and if so, we estimate maximum time from the data. Note that if this is done relative to a grouped_df then NA means we take the maximum from all groups and give that to each subgroup.
integer_time_expansion	boolean if every integer time point in the range of min_max_time should be presented in the aggregation output. If FALSE (default is TRUE), then lines will only include those time points where

Details

This function converts data on an agent-based level (1 row = 1 agent) relative when an agent is in each state and aggregates it, so that the user can know how many agents are in each state at a given time point (integer based). This function can take standard data.frames and grouped_df data.frames (from dplyr). For the later, this function aggregates within grouping parameters and also provides the columns associated with the grouping.

D.1. What each column should have (NAs, orderings, births & deaths,...)

The parameters state, death, birth, and min_max_time provide the user with the flexibility to capture any potential structure related to agent's progression to through the epidemic (and life).

As mentioned in the states parameter details, we expect a set of column names X1, X2, ..., XK that contain information on when an individual enters each state. Also mentioned in the parameter details is that the function assumes that each agent is in the initial state X0 until X1 (except if min_max_time[1] >= X1, which means the agent starts out at state X1).

This function expects transition in an ordered fashion, i.e. X(I+1) >= X(I), but does allow agents to jump states. This can either be recorded with a value at the jumped state the same as the next non-jumped state or an NA (and the authors of this package believe this is a cleaner approach - and matches expectation in birth and death).

Specifically, birth and death can contain NA values, which the function interprets as an individual not being born (or dying respectively) in the given time interval.

The time interval (defined by min_max_time) can be moved, which abstractly just shifts the rows (or time points) the user gets at the end.

D.2. Changing time points

Beyond defining the time interval with min_max_time, if a user wishes to have more minute (smaller) time steps than integers, we recommend they just multiple all values by 1/s where s is the length of the desired time steps. A transformation of the output's t column by s would get the time back to the standard time.

Value

dataset with aggregated information, we label classes X{i} for i in 0:(length(states)). Potentially calculated per group of a grouped_df (and retains grouping columns).

Examples

###
# for standard data.frame objects (agents_to_aggregate.grouped_df)
###
library(dplyr)
agents <- EpiCompare::hagelloch_raw
# making babies
set.seed(5)
babies <- sample(nrow(agents),size = 5)
agents$tBIRTH <- NA
agents$tBIRTH[babies] <- agents$tI[babies] - 5

aggregate_b <- agents_to_aggregate(agents, states = c(tI, tR),
                                   death = NULL, birth = tBIRTH)

# looking at when babies where born:
agents %>% dplyr::filter(!is.na(.data$tBIRTH)) %>%
  dplyr::pull(.data$tBIRTH) %>% ceiling() %>% sort
# vs:
data.frame(counts = 1:nrow(aggregate_b),
           num_people = aggregate_b %>% select(-t) %>% apply(1, sum))


# including death
aggregate_d <- agents_to_aggregate(agents, states = c(tI, tR),
                                   death = tDEAD, birth = NULL)

# looking at when people died:
agents %>% dplyr::filter(!is.na(.data$tDEAD)) %>%
  dplyr::pull(.data$tDEAD) %>% ceiling() %>% sort
# vs:
data.frame(counts = 1:nrow(aggregate_d),
           num_people = aggregate_d %>% select(-t) %>% apply(1, sum))

###
# for grouped_df objects (agents_to_aggregate.grouped_df)
###


max_time <- 100
agents_g <- hagelloch_raw %>%
  filter(SEX %in% c("female", "male")) %>% group_by(SEX)
sir_group <- agents_to_aggregate(agents_g, states = c(tI, tR),
                                 min_max_time = c(0, max_time))
agents <- agents_g %>%
  filter(SEX == "female") %>% ungroup()
sir_group1 <- agents_to_aggregate(agents, states = c(tI, tR),
                                 min_max_time = c(0, max_time))
sir_group_1 <- sir_group %>% filter(SEX == "female")
assertthat::are_equal(sir_group1,
                      sir_group_1 %>% ungroup %>% select(t, X0, X1, X2))

skgallagher/EpiCompare documentation built on Sept. 14, 2021, 5:45 a.m.