episodes: Group dated events into episodes.

Description

Dated events (records) within a certain duration of an index event are assigned to a unique group. Each group has unique ID and are described as "episodes". "episodes" can be "fixed" or "rolling" ("recurring"). Each episodes has a "Case" and/or "Recurrent" record while all other records within the group are either "Duplicates" of the "Case" or "Recurrent" event.

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 = c("case_nm", "wind", "epid_interval"),
  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,
  splits_by_strata = 1,
  batched = "semi"
)
links_wf_episodes(
  date,
  case_length = Inf,
  episode_type = "fixed",
  strata = NULL,
  sn = NULL,
  display = "none"
)
episodes_af_shift(
  date,
  case_length = Inf,
  sn = NULL,
  strata = NULL,
  group_stats = FALSE,
  episode_type = "fixed",
  data_source = NULL,
  episode_unit = "days",
  data_links = "ANY",
  display = "none"
)

Value

epid; list

Arguments

date: [date|datetime|integer|number_line]. Record date or period.
case_length: [integer|number_line]. Duration from an index event distinguishing one "Case" from another.
episode_type: [character]. Options are "fixed" (default) or "rolling". See Details.
recurrence_length: [integer|number_line]. Duration from an index event distinguishing a "Recurrent" event from its "Case" or prior "Recurrent" event.
episode_unit: [character]. Unit of time 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 by each strata.
sn: [integer]. Unique record ID.
episodes_max: [integer]. Maximum number of episodes permitted within each strata.
rolls_max: [integer]. Maximum number of times an index event can recur. Only used if episode_type is "rolling".
case_overlap_methods: [character|integer]. Specific ways a period (record) most overlap with a "Case" event. See (overlaps).
recurrence_overlap_methods: [character|integer]. Specific ways a period (record) most overlap with a "Recurrent" event. See (overlaps).
skip_if_b4_lengths: [logical]. If TRUE (default), events before a lagged case_length or recurrence_length are skipped.
data_source: [character]. Source ID for each record. If provided, a list of all sources in each episode is returned. See epid_dataset slot.
data_links: [list|character]. data_source required in each epid. An episode 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]. End episode tracking in a strata when the an index event's custom_sort order is greater than the supplied skip_order.
reference_event: [character]. Specifies which of the records are used as index events. Options are "last_record" (default), "last_event", "first_record" or "first_event".
case_for_recurrence: [logical]. If TRUE, a case_length is applied to both "Case" and "Recurrent" events. If FALSE (default), a case_length is applied to only "Case" events.
from_last: [logical]. Track episodes beginning from the earliest to the most recent record (FALSE) or vice versa (TRUE).
group_stats: [character]. A selection of group metrics to return for each episode. Most are added to slots of the epid object. Options are NULL or any combination of "case_nm", "wind" and "epid_interval".
display: [character]. Display progress update and/or generate a linkage report for the analysis. Options are; "none" (default), "progress", "stats", "none_with_report", "progress_with_report" or "stats_with_report".
case_sub_criteria: [sub_criteria]. Additional nested match criteria for events in a case_length.
recurrence_sub_criteria: [sub_criteria]. Additional nested match 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 is skipped.
splits_by_strata: [integer]. Split analysis into n parts. This typically lowers max memory usage but increases run time.
batched: [character]. Create and compare records in batches. Options are "yes", "no", and "semi". typically, the ("semi") option will have a higher max memory and shorter run-time while ("no") will have a lower max memory but longer run-time

Details

episodes() links dated records (events) that are within a set duration of each other in iterations. Every record is linked to a unique group (episode; epid object). These episodes represent occurrences of interest as specified by function's arguments and defined by a case definition.

Two main type of episodes are possible;

"fixed" - An episode where all events are within a fixed duration of an index event.
"rolling" - An episode where all events are within a recurring duration of an index event.

Every record in each episode is categorised as one of the following;

"Case" - Index event of the episode (without a nested match criteria).
"Case_CR" - Index event of the episode (with a nested match criteria).
"Duplicate_C" - Duplicate of the index event.
"Recurrent" - Recurrence of the index event (without a nested match criteria).
"Recurrent_CR" - Recurrence of the index event (with a nested match criteria).
"Duplicate_R" - Duplicate of the recurrent event.
"Skipped" - Skipped records.

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", groups without records from every listed data_source will be unlinked.
If named "g", groups without records from any listed data_source will be unlinked.

All records with a missing (NA) strata or date are skipped.

Wrapper functions or alternative implementations of episodes() for specific use cases or benefits:

episodes_wf_splits() - Identical records are excluded from the main analysis.
episodes_af_shift() - A mostly vectorised approach.
links_wf_episodes() - The same functionality achieved with links.

See vignette("episodes") for further details.

Examples

Run this code

data(infections)
data(hospital_admissions)

# One 16-day (15-day difference) fixed episode per type of infection
episodes(date = infections$date,
         strata = infections$infection,
         case_length = 15,
         episodes_max = 1,
         episode_type = "fixed")

# Multiple 16-day episodes with an 11-day recurrence period
episodes(date = infections$date,
         strata = NULL,
         case_length = 15,
         episodes_max = Inf,
         episode_type = "rolling",
         recurrence_length = 10)

# Overlapping periods of hospital stays
dfr <- hospital_admissions[2:3]

dfr$admin_period <-
  number_line(dfr$admin_dt,dfr$discharge_dt)

dfr$ep <-
  episodes(date = dfr$admin_period,
           strata = NULL,
           case_length = index_window(dfr$admin_period),
           case_overlap_methods = "inbetween")

dfr
as.data.frame(dfr$ep)