incidents {constellation}R Documentation

Identify incident events separated by a minimum time window


A function that reads in a time series data frame along with a specified time window and identifies incident events that are separated in time. The user must specify the number of hours over which events are considered to be the same episode, the time stamp variable, and an optional variable to group episodes. This function was motivated by examples where there may be multiple observations of the same illness episode combined with observations of distinct illness episodes and there is a need to distinguish between episodes. This function assumes that the duration of an episode is non-zero. If every non-equal instant is a distinct episode, there is no need to use this function. Two ways to distinguish between episodes with non-zero duration over time are: (1) bucket observations over a pre-fixed time frame that is applied to all observation; (2) bucket observations over a fixed window of time. An example of (1) is considering observations in the same month to be the same episode and observations in different months to be distinct episodes. The incident() function addresses (2) by specifying a time window and identifying the first observation of each episode. The use can also specify a 'join_key' variable (person, encounter, etc.) to group episodes. The 'window_hours' argument serves as the lower bound to separate observations that are considered the same episode versus distinct episodes.


incidents(data, window_hours, time_var, join_key = NULL)



A time series data frame that includes the columns 'join_key' and 'time_var'


A numeric value specifying the number of hours to separate contiguous episodes and distinct episodes


A string name of the time stamp column in the time series data frame


An optional string name of the column to group observations


A data.frame, data.table with the time stamps of distinct, incident episodes separated by at least 'window_hours'

Imported functions

general data.table syntax


This function returns errors for:


systolic_bp <-[VARIABLE == "SYSTOLIC_BP"])
  format = "%Y-%m-%dT%H:%M:%SZ", tz = "UTC")]

# Identify systolic blood pressure measurements for each patient that are
 # separated by at least 24 hours
incidents(systolic_bp, window_hours = 24, join_key = "PAT_ID",
 time_var = "RECORDED_TIME")

# Identify systolic blood pressure measurements that are separated by at
 # least 24 hours
incidents(systolic_bp, window_hours = 24, time_var = "RECORDED_TIME")

[Package constellation version 0.2.0 Index]