episodes: Link events to chronological episodes.

Description

Create temporal links between dated events. Each set of linked records are assigned a unique identifier with relevant group-level information.

Usage

episodes(
  date,
  case_length = Inf,
  episode_type = "fixed",
  recurrence_length = case_length,
  episode_unit = "days",
  strata = NULL,
  sn = NULL,
  episodes_max = Inf,
  rolls_max = Inf,
  case_overlap_methods = 8,
  recurrence_overlap_methods = case_overlap_methods,
  skip_if_b4_lengths = FALSE,
  data_source = NULL,
  data_links = "ANY",
  custom_sort = NULL,
  skip_order = Inf,
  reference_event = "last_record",
  case_for_recurrence = FALSE,
  from_last = FALSE,
  group_stats = FALSE,
  display = "none",
  case_sub_criteria = NULL,
  recurrence_sub_criteria = case_sub_criteria,
  case_length_total = 1,
  recurrence_length_total = case_length_total,
  skip_unique_strata = TRUE
)

Value

epid; list

Arguments

date: [date|datetime|integer|number_line]. Event date or period.
case_length: [integer|number_line]. Duration from index event distinguishing one "Case" from another.
episode_type: [character]. Options are "fixed" (default), "rolling" or "recursive". See Details.
recurrence_length: [integer|number_line]. Duration from an event distinguishing a "Recurrent" event from its index event.
episode_unit: [character]. Time units for case_length and recurrence_length. Options are "seconds", "minutes", "hours", "days" (default), "weeks", "months" or "years". See diyar::episode_unit.
strata: [atomic]. Subsets of the dataset. Episodes are created separately for each strata.
sn: [integer]. Unique record identifier. Useful for creating familiar epid identifiers.
episodes_max: [integer]. The maximum number of episodes permitted within each strata.
rolls_max: [integer]. Maximum number of times the index event recurs. Only used if episode_type is "rolling" or "recursive".
case_overlap_methods: [character|integer]. Accepted overlaps method for "Case" and "Duplicate" events. Relevant when date is a period (number_line). See (overlaps).
recurrence_overlap_methods: [character|integer]. Accepted overlaps method for "Recurrent" and "Duplicate" events. Relevant when date is a period (number_line). See (overlaps).
skip_if_b4_lengths: [logical]. If TRUE (default), events before a lagged case_length or recurrence_length are skipped.
data_source: [character]. Data source identifier. Adds the list of data sources in each episode to the epid. Useful when the data is from multiple sources.
data_links: [list|character]. A set of data_sources required in each epid. A record-group without records from these data_sources will be unlinked. See Details.
custom_sort: [atomic]. Preferential order for selecting index events. See custom_sort.
skip_order: [integer]. "nth" level of custom_sort. Episodes with index events beyond this level of preference are skipped.
reference_event: [character]. Specifies which events are used as index events for a subsequent case_length or recurrence_length. Options are "last_record" (default), "last_event", "first_record" or "first_event".
case_for_recurrence: [logical]. If TRUE, both "Case" and "Recurrent" events will have a case_length. If FALSE (default), only case events will have a case window. Only used if episode_type is "rolling" or "recursive".
from_last: [logical]. Chronological order of episode tracking i.e. ascending (TRUE) or descending (FALSE).
group_stats: [logical]. If TRUE (default), episode-specific information like episode start and end dates are returned.
display: [character]. Display or produce a status update. Options are; "none" (default), "progress", "stats", "none_with_report", "progress_with_report" or "stats_with_report".
case_sub_criteria: [sub_criteria]. Additional matching criteria for events in a case_length.
recurrence_sub_criteria: [sub_criteria]. Additional matching criteria for events in a recurrence_length.
case_length_total: [integer|number_line]. Minimum number of matched case_lengths required for an episode.
recurrence_length_total: [integer|number_line]. Minimum number of matched recurrence_lengths required for an episode.
skip_unique_strata: [logical]. If TRUE, a strata with a single event are skipped.

Details

episodes() links dated records (events) that are within specified durations of each other. In each iteration, an index event is selected and compared against every other event.

Every event is linked to a unique group (episode; epid object). These episodes represent occurrences of interest as defined by the rules and conditions specified in the function's arguments.

By default, this process occurs in ascending order; beginning with the earliest event and proceeding to the most recent one. This can be changed to a descending (from_last) or custom order (custom_sort). Ties are always broken by the chronological order of events.

In general, three type of episodes are possible;

"fixed" - An episode where all events are within fixed durations of one index event.
"rolling" - An episode where all events are within recurring durations of one index event.
"recursive" - An episode where all events are within recurring durations of multiple index events.

Every event in each episode is categorise as;

"Case" - Index event of the episode (without matching sub_criteria).
"Case_CR" - Index event of the episode (with matching sub_criteria).
"Duplicate_C" - Duplicate of the index event.
"Recurrent" - Recurrence of the index event (without matching sub_criteria).
"Recurrent_CR" - Recurrence of the index event (with matching sub_criteria).
"Duplicate_R" - Duplicate of the recurrent event.
"Skipped" - Records excluded from the episode tracking process.

If data_links is supplied, every element of the list must be named "l" (links) or "g" (groups). Unnamed elements are assumed to be "l".

If named "l", only groups with records from every listed data_source will be unlinked.
If named "g", only groups with records from any listed data_source will be unlinked.

Records with a missing (NA) strata are excluded from the episode tracking process.

See vignette("episodes") for further details.

Examples

Run this code

data(infections); db_1 <- infections
data(hospital_admissions) ; db_2 <- hospital_admissions

db_1$patient_id <- c(rep("PID 1",8), rep("PID 2",3))

# Fixed episodes
# One 16-day (15-day difference) episode per patient
db_1$ep1 <- episodes(date = db_1$date,
                     strata = db_1$patient_id,
                     case_length = 15,
                     episodes_max = 1)
# Rolling episodes
# 16-day episodes with recurrence periods of 11 days
db_1$ep2 <- episodes(date = db_1$date,
                     case_length = 15,
                     recurrence_length = 10,
                     episode_type = "rolling")

# Interval grouping
db_2$admin_period <- number_line(db_2$admin_dt,
                                 db_2$discharge_dt)
# Episodes of hospital stays
db_2$ep3 <- episodes(date = db_2$admin_period,
                     case_length = index_window(db_2$admin_period),
                     case_overlap_methods = "inbetween")