In epidemiological analyses an exact distinction between temporal events is not always possible. Therefore, static but reasonable cut-offs are used to distinguish one occurrence of an event from another. This is an important aspect of most case definitions. For example, distinguishing repeat or recurrent infections from the first occurrence of that infection.
This vignette provides a brief introduction to how this is done with episodes().
We begin by reviewing event_dt below. This is a sample dataset of 11 infection events and includes data on the location and type of infection.
event_dt <- seq(from = as.Date("2021-01-01"), to = as.Date("2021-01-11"), by = 1)
event_dt <- data.frame(date = event_dt)
event_dt$attr_1 <- c("BSI", "UTI", "RTI", "RTI", "BSI", "BSI", "BSI", "RTI", "RTI", "BSI", "RTI")
event_dt$attr_2 <- c("Ward 1", "Ward 1", "Ward 3", "Ward 3", "Ward 2", "Ward 2",
"Ward 1", "Ward 1", "Ward 3","Ward 3", "Ward 2")
event_dt
#> date attr_1 attr_2
#> 1 2021-01-01 BSI Ward 1
#> 2 2021-01-02 UTI Ward 1
#> 3 2021-01-03 RTI Ward 3
#> 4 2021-01-04 RTI Ward 3
#> 5 2021-01-05 BSI Ward 2
#> 6 2021-01-06 BSI Ward 2
#> 7 2021-01-07 BSI Ward 1
#> 8 2021-01-08 RTI Ward 1
#> 9 2021-01-09 RTI Ward 3
#> 10 2021-01-10 BSI Ward 3
#> 11 2021-01-11 RTI Ward 2The simplest kind of case definitions are those where only one event is retained making every other event a duplicate (D) of the index event (C).
event_dt$ep1 <- episodes(event_dt$date, episode_type = "fixed")
event_dt
#> date attr_1 attr_2 ep1
#> 1 2021-01-01 BSI Ward 1 E.1 (C)
#> 2 2021-01-02 UTI Ward 1 E.1 (D)
#> 3 2021-01-03 RTI Ward 3 E.1 (D)
#> 4 2021-01-04 RTI Ward 3 E.1 (D)
#> 5 2021-01-05 BSI Ward 2 E.1 (D)
#> 6 2021-01-06 BSI Ward 2 E.1 (D)
#> 7 2021-01-07 BSI Ward 1 E.1 (D)
#> 8 2021-01-08 RTI Ward 1 E.1 (D)
#> 9 2021-01-09 RTI Ward 3 E.1 (D)
#> 10 2021-01-10 BSI Ward 3 E.1 (D)
#> 11 2021-01-11 RTI Ward 2 E.1 (D)As seen above, we can use episodes() to create a group identifier unique to each occurrence. Each group is referred to as an episode. The identifier is stored as an S4 (epid) class with useful information about each group in its slots. These information can be accessed with as.data.frame() or as.list().
We can build on this case definition by adding a temporal boundary within which events are considered part of the same occurrence. For example, we can specify that only events within 4 days (3 day-difference) of an index are considered part of the same occurrence.
event_dt$ep2 <- episodes(event_dt$date, 3, episode_type = "fixed")
event_dt
#> date attr_1 attr_2 ep1 ep2
#> 1 2021-01-01 BSI Ward 1 E.1 (C) E.1 (C)
#> 2 2021-01-02 UTI Ward 1 E.1 (D) E.1 (D)
#> 3 2021-01-03 RTI Ward 3 E.1 (D) E.1 (D)
#> 4 2021-01-04 RTI Ward 3 E.1 (D) E.1 (D)
#> 5 2021-01-05 BSI Ward 2 E.1 (D) E.5 (C)
#> 6 2021-01-06 BSI Ward 2 E.1 (D) E.5 (D)
#> 7 2021-01-07 BSI Ward 1 E.1 (D) E.5 (D)
#> 8 2021-01-08 RTI Ward 1 E.1 (D) E.5 (D)
#> 9 2021-01-09 RTI Ward 3 E.1 (D) E.9 (C)
#> 10 2021-01-10 BSI Ward 3 E.1 (D) E.9 (D)
#> 11 2021-01-11 RTI Ward 2 E.1 (D) E.9 (D)We can see that every event after the fourth day has now been assigned to a different episode, each with its own index event. This type of episode is referred to as a "fixed" episode.
episodes() can also produce two additional type of episodes - "rolling" and "recursive". See examples of each below.
event_dt$ep3 <- episodes(event_dt$date, 3, episode_type = "rolling")
event_dt$ep4 <- episodes(event_dt$date, 3, episode_type = "recursive")
event_dt
#> date attr_1 attr_2 ep1 ep2 ep3 ep4
#> 1 2021-01-01 BSI Ward 1 E.1 (C) E.1 (C) E.1 (C) E.1 (C)
#> 2 2021-01-02 UTI Ward 1 E.1 (D) E.1 (D) E.1 (D) E.1 (D)
#> 3 2021-01-03 RTI Ward 3 E.1 (D) E.1 (D) E.1 (D) E.1 (D)
#> 4 2021-01-04 RTI Ward 3 E.1 (D) E.1 (D) E.1 (D) E.1 (D)
#> 5 2021-01-05 BSI Ward 2 E.1 (D) E.5 (C) E.1 (R) E.1 (R)
#> 6 2021-01-06 BSI Ward 2 E.1 (D) E.5 (D) E.1 (D) E.1 (D)
#> 7 2021-01-07 BSI Ward 1 E.1 (D) E.5 (D) E.1 (D) E.1 (D)
#> 8 2021-01-08 RTI Ward 1 E.1 (D) E.5 (D) E.1 (R) E.1 (R)
#> 9 2021-01-09 RTI Ward 3 E.1 (D) E.9 (C) E.1 (D) E.1 (D)
#> 10 2021-01-10 BSI Ward 3 E.1 (D) E.9 (D) E.1 (D) E.1 (D)
#> 11 2021-01-11 RTI Ward 2 E.1 (D) E.9 (D) E.1 (R) E.1 (R)Here, we see the creation (or rather categorisation) of recurrent events (R). These are recurrence of index events as opposed to their duplicates. For example, ep3 initially ends on 2021-01-04. However, for rolling and recursive episodes, the function takes the additional step of looking for other events within 4 days of 2021-01-04. Records within this period are then categorised as recurrent events of the 2021-01-04 event, which itself is a duplicate of the 2021-01-01 event. This chaining process continues indefinitely until there are no more events within the period of recurrence or it’s stop by the rolls_max argument.
Even though ep1 has the same outcome (one episode) as ep3 and ep4, they are very different case definitions hence, the structure of their episodes are different. This is demonstrated below by using schema() to visualise the identifiers.
schema(event_dt$ep1, seed = 2, show_labels = c("case_nm", "length_arrow"))
schema(event_dt$ep3, seed = 2, show_labels = c("case_nm", "length_arrow"))
schema(event_dt$ep4, seed = 2, show_labels = c("case_nm", "length_arrow"))
You may have noticed that this process starts from the earliest event and proceeds forward in time. If the from_last argument is changed, the process will happen in the opposite direction.
event_dt$ep5 <- episodes(event_dt$date, 3, episode_type = "rolling", from_last = TRUE)
event_dt
#> date attr_1 attr_2 ep1 ep2 ep3 ep4 ep5
#> 1 2021-01-01 BSI Ward 1 E.1 (C) E.1 (C) E.1 (C) E.1 (C) E.11 (R)
#> 2 2021-01-02 UTI Ward 1 E.1 (D) E.1 (D) E.1 (D) E.1 (D) E.11 (D)
#> 3 2021-01-03 RTI Ward 3 E.1 (D) E.1 (D) E.1 (D) E.1 (D) E.11 (D)
#> 4 2021-01-04 RTI Ward 3 E.1 (D) E.1 (D) E.1 (D) E.1 (D) E.11 (R)
#> 5 2021-01-05 BSI Ward 2 E.1 (D) E.5 (C) E.1 (R) E.1 (R) E.11 (D)
#> 6 2021-01-06 BSI Ward 2 E.1 (D) E.5 (D) E.1 (D) E.1 (D) E.11 (D)
#> 7 2021-01-07 BSI Ward 1 E.1 (D) E.5 (D) E.1 (D) E.1 (D) E.11 (R)
#> 8 2021-01-08 RTI Ward 1 E.1 (D) E.5 (D) E.1 (R) E.1 (R) E.11 (D)
#> 9 2021-01-09 RTI Ward 3 E.1 (D) E.9 (C) E.1 (D) E.1 (D) E.11 (D)
#> 10 2021-01-10 BSI Ward 3 E.1 (D) E.9 (D) E.1 (D) E.1 (D) E.11 (D)
#> 11 2021-01-11 RTI Ward 2 E.1 (D) E.9 (D) E.1 (R) E.1 (R) E.11 (C)We can now see that in ep5 the last record is now the index of the episode.
So far, we’ve discussed the different type of episodes and the direction of time in which they are tracked. The next important part of the tracking process is the selection of index events. This determines which record is used as the reference point when checking for other events within its window of occurrence. By default, this will be the earliest record from the direction of the tracking process but this can be changed to a custom preference using the custom_sort argument.
To demonstrate this, let’s preferentially use "RTI" infection events as index events for episodes.
custom_pref <- ifelse(event_dt$attr_1 == "RTI", 1, 2)
event_dt$ep6 <- episodes(event_dt$date, 3, custom_sort = custom_pref,
skip_order = 1)
event_dt$ep7 <- episodes(event_dt$date, 3, custom_sort = custom_pref,
skip_order = 1, from_last = TRUE)schema(event_dt$ep6, seed = 2, show_labels = c("length_arrow"),
custom_label = paste0(decode(event_dt$ep6@case_nm), " (", event_dt$attr_1, ")"))
schema(event_dt$ep7, seed = 2, show_labels = c("length_arrow"),
custom_label = paste0(decode(event_dt$ep7@case_nm), " (", event_dt$attr_1, ")"))
Another main aspect of the tracking process is the duration between events. This is handled by the case_length and recurrence_length arguments. A length of 3 means that events within 4 days (3-day difference) of the of the index event will be linked together as part of the same occurrence. Note that this is 4 days towards the direction of the tracking process therefore, events in the opposite direction will not be considered. We can see this above in the schema for ep6.
If records in both directions need to be considered, then a range can be provided as shown with ep_8. Additionally, multiple periods from the index event can be specified by providing a list of lengths or ranges as shown in ep_9.
event_dt$ep8 <- episodes(event_dt$date, number_line(-3, 3), episode_type = "fixed",
custom_sort = custom_pref, skip_order = 1)
event_dt$ep9 <- episodes(event_dt$date, list(number_line(-2, -1),
number_line(4, 5),
number_line(7, 9)), episode_type = "fixed",
custom_sort = custom_pref,
skip_order = 1,
skip_if_b4_lengths = TRUE)schema(event_dt$ep8, seed = 2, show_labels = c("length_arrow"),
custom_label = paste0(decode(event_dt$ep8@case_nm), " (", event_dt$attr_1, ")"))
schema(event_dt$ep9, seed = 2, show_labels = c("length_arrow", "length_label"))
It’s possible to track episodes among events with known start and end points, instead of those occurring at a single point in time. It is worth noting that the reference point for such events is their end point. Therefore, using a case_length of 1 when working with such events is interpreted as 2 days (1-day difference) after the end point of the interval. By default, other events that occur on or after the start point but before the end point of the index event will not be captured. If this is required, use index_window() to get the range required to capture such events, and supply it to the case_length or recurrence_length arguments. See the examples below.
# Dummy data of hospital stays
data(hospital_admissions)
dfr <- hospital_admissions[c("admin_dt", "discharge_dt")]
dfr$admin_period <- number_line(dfr$admin_dt, dfr$discharge_dt)
# Group overlapping hospital stays
dfr$ep_len1 <- index_window(dfr$admin_period)
dfr$ep1 <- episodes(date = dfr$admin_period, case_length = dfr$ep_len1)
# Group overlapping hospital stays and those within 21 days of the end point of an index hospital stay
dfr$ep_len2 <- expand_number_line(index_window(dfr$admin_period), 20, "right")
dfr$ep2 <- episodes(date = dfr$admin_period, case_length = dfr$ep_len2)dfr[c("admin_period", "ep_len1", "ep_len2", "ep1", "ep2")]
#> admin_period ep_len1 ep_len2 ep1 ep2
#> 1 2019-01-01 == 2019-01-01 0 == 0 0 -> 20 E.2 (D) E.2 (D)
#> 2 2019-01-01 -> 2019-01-10 -9 -> 0 -9 -> 20 E.2 (C) E.2 (C)
#> 3 2019-01-10 -> 2019-01-13 -3 -> 0 -3 -> 20 E.2 (D) E.2 (D)
#> 4 2019-01-05 -> 2019-01-06 -1 -> 0 -1 -> 20 E.2 (D) E.2 (D)
#> 5 2019-01-05 -> 2019-01-15 -10 -> 0 -10 -> 20 E.2 (D) E.2 (D)
#> 6 2019-01-07 -> 2019-01-15 -8 -> 0 -8 -> 20 E.2 (D) E.2 (D)
#> 7 2019-01-04 -> 2019-01-13 -9 -> 0 -9 -> 20 E.2 (D) E.2 (D)
#> 8 2019-01-20 -> 2019-01-30 -10 -> 0 -10 -> 20 E.8 (C) E.2 (D)
#> 9 2019-01-26 -> 2019-01-31 -5 -> 0 -5 -> 20 E.8 (D) E.2 (D)
#> 10 2019-01-01 -> 2019-01-10 -9 -> 0 -9 -> 20 E.2 (D) E.2 (D)
#> 11 2019-01-20 -> 2019-01-30 -10 -> 0 -10 -> 20 E.8 (D) E.2 (D)
schema(dfr$ep1, seed = 2, show_labels = "length_arrow")
schema(dfr$ep2, seed = 2, show_labels = "length_arrow")
Currently, the diyar packages recognises 7 mutually exclusive and 2 mutually inclusive ways a pair of intervals can overlap. Please see vignette("number_line") for more details about this. Using case_overlap_methods and recurrence_overlap_methods, the episode tracking process can be made to only capture intervals that overlap by specific methods. See the example below.
# Wrapper function for a fixed episode
episodes_wf <- function(x){
epids <- episodes(date = dfr$admin_period,
sn = dfr$rd_id,
case_length = index_window(dfr$admin_period),
case_overlap_methods = x)
return(epids)
}
# Methods
methods <- list(
# Identical intervals
exact = "exact",
# Intervals with their start or end points within another
across = "across",
# Intervals with aligned start points
aligns_start = "aligns_start",
# Intervals with aligned end points
aligns_end = "aligns_end",
# Intervals with start points that align with the end point of another, and vice versa
chain = "chain",
# Intervals occurring completely within others
inbetween = "inbetween",
# A combination of `chain` and `inbetween` methods
cb1 = "chain|inbetween",
# A combination of `exact`, `chain` and `inbetween` methods
cb2 = "exact|chain|inbetween",
# A combination of `across`, `chain` and `aligns_end` methods
cb3 = "across|chain|aligns_end"
)
epids <- lapply(methods, episodes_wf)
names(epids) <- methods
# Use `schema()` to visualise each.
epids
#> $exact
#> [1] "E.1 (C)" "E.2 (C)" "E.3 (C)" "E.4 (C)" "E.5 (C)" "E.6 (C)" "E.7 (C)"
#> [8] "E.8 (C)" "E.9 (C)" "E.2 (D)" "E.8 (D)"
#>
#> $across
#> [1] "E.01 (C)" "E.02 (C)" "E.03 (C)" "E.04 (C)" "E.02 (D)" "E.02 (D)"
#> [7] "E.02 (D)" "E.08 (C)" "E.08 (D)" "E.10 (C)" "E.11 (C)"
#>
#> $aligns_start
#> [1] "E.02 (D)" "E.02 (C)" "E.03 (C)" "E.05 (D)" "E.05 (C)" "E.06 (C)"
#> [7] "E.07 (C)" "E.08 (C)" "E.09 (C)" "E.10 (C)" "E.11 (C)"
#>
#> $aligns_end
#> [1] "E.01 (C)" "E.02 (C)" "E.07 (D)" "E.04 (C)" "E.05 (C)" "E.05 (D)"
#> [7] "E.07 (C)" "E.08 (C)" "E.09 (C)" "E.10 (C)" "E.11 (C)"
#>
#> $chain
#> [1] "E.01 (C)" "E.02 (C)" "E.02 (D)" "E.04 (C)" "E.05 (C)" "E.06 (C)"
#> [7] "E.07 (C)" "E.08 (C)" "E.09 (C)" "E.10 (C)" "E.11 (C)"
#>
#> $inbetween
#> [1] "E.01 (C)" "E.02 (C)" "E.05 (D)" "E.02 (D)" "E.05 (C)" "E.06 (C)"
#> [7] "E.07 (C)" "E.08 (C)" "E.09 (C)" "E.10 (C)" "E.11 (C)"
#>
#> $`chain|inbetween`
#> [1] "E.01 (C)" "E.02 (C)" "E.02 (D)" "E.02 (D)" "E.05 (C)" "E.06 (C)"
#> [7] "E.07 (C)" "E.08 (C)" "E.09 (C)" "E.10 (C)" "E.11 (C)"
#>
#> $`exact|chain|inbetween`
#> [1] "E.1 (C)" "E.2 (C)" "E.2 (D)" "E.2 (D)" "E.5 (C)" "E.6 (C)" "E.7 (C)"
#> [8] "E.8 (C)" "E.9 (C)" "E.2 (D)" "E.8 (D)"
#>
#> $`across|chain|aligns_end`
#> [1] "E.01 (C)" "E.02 (C)" "E.02 (D)" "E.04 (C)" "E.02 (D)" "E.02 (D)"
#> [7] "E.02 (D)" "E.08 (C)" "E.08 (D)" "E.10 (C)" "E.11 (C)"See overlap_methods$options for a list of supported options.
Additional matching criteria (separate from temporal links) can be implemented by passing a sub_criteria object to the case_sub_criteria and recurrence_sub_criteria arguments. See the vignette("links") for more details about sub_criteria objects. In the example below, we specify that only index events that are an RTI or occurred in Ward 3 can start an episode.
match_funx1 <- function(x, y) y == "RTI"
match_funx2 <- function(x, y) y == "Ward 2"
# Sub-criteria 1 - Matching source of infection OR patient location
sub_cri_1 <- sub_criteria(event_dt$attr_1, event_dt$attr_2,
operator = "or",
match_funcs = c(match_funx1, match_funx2))
event_dt$ep10 <- episodes(event_dt$date, case_length = 5, case_sub_criteria = sub_cri_1)schema(event_dt$ep10, seed = 2, show_labels = c("length_arrow"),
custom_label = paste0(event_dt$attr_1, " in ", event_dt$attr_2))
Alternatively, we can specify that BSI events or those that occurred in Ward 1 should not be linked to any episode. Note that they will be able to start episodes unless specified otherwise (y) as with event_dt$ep10.
match_funx3 <- function(x, y) !(x$attr_1 == "BSI" | x$attr_2 == "Ward 1")
equal_funx <- function(x, y) TRUE
# Sub-criteria 1 - Matching source of infection OR patient location
sub_cri_2 <- sub_criteria(attrs(attr_1 = event_dt$attr_1,
attr_2 = event_dt$attr_2),
operator = "and",
match_funcs = match_funx3,
equal_funcs = equal_funx)
event_dt$ep11 <- episodes(event_dt$date, case_length = 5, case_sub_criteria = sub_cri_2)schema(event_dt$ep11, seed = 2, show_labels = c("length_arrow"),
custom_label = paste0(event_dt$attr_1, " in ", event_dt$attr_2))
We can even combine both conditions into a nested condition.
combined_sub_cri <- sub_criteria(sub_cri_1, sub_cri_2, operator = "and")
event_dt$ep12 <- episodes(event_dt$date, case_length = 5,
case_sub_criteria = combined_sub_cri)schema(event_dt$ep12, seed = 2, show_labels = c("length_arrow"),
custom_label = paste0(event_dt$attr_1, " in ", event_dt$attr_2))
A sub_criteria can be very useful when complex rules are required as part of the case definition.
Finally, everything we’ve just discussed can be done separately for different subsets of the dataset by using the strata argument. data_source lets us keep track of the source of records in each episode. data_links places limits on episode creation based on their data_source. The group_stats argument creates useful information for each episode which are stored in the epid object. To demonstrate these, we’ll modify our first example.
event_dt$ep13 <- episodes(event_dt$date, episode_type = "fixed",
strata = event_dt$attr_2, data_source = event_dt$attr_1,
group_stats = TRUE)
as.data.frame(event_dt$ep13)
#> epid sn wind_nm case_nm dist_wind_index dist_epid_index epid_total
#> 1 1 1 Case Case 0 days 0 days 4
#> 2 1 2 Case Duplicate_C 1 days 1 days 4
#> 3 3 3 Case Case 0 days 0 days 4
#> 4 3 4 Case Duplicate_C 1 days 1 days 4
#> 5 5 5 Case Case 0 days 0 days 3
#> 6 5 6 Case Duplicate_C 1 days 1 days 3
#> 7 1 7 Case Duplicate_C 6 days 6 days 4
#> 8 1 8 Case Duplicate_C 7 days 7 days 4
#> 9 3 9 Case Duplicate_C 6 days 6 days 4
#> 10 3 10 Case Duplicate_C 7 days 7 days 4
#> 11 5 11 Case Duplicate_C 6 days 6 days 3
#> iteration wind_id1 epid_start epid_end epid_length epid_dataset
#> 1 1 1 2021-01-01 2021-01-08 7 days BSI,RTI,UTI
#> 2 1 1 2021-01-01 2021-01-08 7 days BSI,RTI,UTI
#> 3 1 3 2021-01-03 2021-01-10 7 days BSI,RTI
#> 4 1 3 2021-01-03 2021-01-10 7 days BSI,RTI
#> 5 1 5 2021-01-05 2021-01-11 6 days BSI,RTI
#> 6 1 5 2021-01-05 2021-01-11 6 days BSI,RTI
#> 7 1 1 2021-01-01 2021-01-08 7 days BSI,RTI,UTI
#> 8 1 1 2021-01-01 2021-01-08 7 days BSI,RTI,UTI
#> 9 1 3 2021-01-03 2021-01-10 7 days BSI,RTI
#> 10 1 3 2021-01-03 2021-01-10 7 days BSI,RTI
#> 11 1 5 2021-01-05 2021-01-11 6 days BSI,RTI