Skip to contents

Take the union of overlapping or near-contiguous treatment intervals

Source: R/events_helpers.R
union_events.Rd

Within each patient and treatment, combines intervals belonging to the same treatment episode into a single interval spanning the earliest start and latest stop. Two intervals are considered the same episode when the gap between them does not exceed gap days. Intervals are treated as inclusive: [start, end].

Usage

union_events(
  events,
  med_levels = NULL,
  id_var = "patient_id",
  tx_name = "tx_name",
  tx_start = "tx_start",
  tx_stop = "tx_stop",
  gap = 0L
)

Arguments

events

A data frame with columns for treatment name, treatment start and stop dates, plus a column for unique patient identifiers.

med_levels

An optional named list mapping treatment classes to their constituent treatment levels.

Example:

med_levels = list("statin" = c( "low_intensity_statin", "moderate_intensity_statin", "high_intensity_statin" ) )

Default value: NULL

id_var

A string specifying the patient identifier column in events.

Default value: "patient_id".

tx_name

A string specifying the column in events holding treatment names.

Default value: "tx_name"

tx_start

A string specifying the column in events with treatment start dates. Must be a Date or numeric column.

Default value: "tx_start"

tx_stop

A string specifying the column in events with treatment stop dates. Stop dates themselves are interpreted as the last day a patient is ON treatment (as opposed to first day OFF treatment). Must be a Date or numeric column.

Default value: "tx_stop"

gap

Maximum number of days between intervals before they are considered distinct episodes. Intervals separated by gap or fewer days are merged into a single contiguous episode.

Default value: 0L

Value

A tibble with exactly four columns: the patient identifier (id_var, same type as input), interval start (tx_start, same type as input), interval stop (tx_stop, same type as input), and either the treatment name column (tx_name, character) when med_levels = NULL, or a trt_class column (character) when med_levels is supplied. Rows are sorted by id_var, the name column (tx_name or trt_class), then tx_start.

Details

When med_levels is provided, intervals are unioned at the treatment class level, not the individual treatment level. For example, overlapping intervals of low_intensity_statin and high_intensity_statin would be merged into a single statin episode. As a result, the output contains a trt_class column in place of tx_name, and treatment level information is not retained.

See also

The Data Overview vignette for worked examples of all three interval-resolution functions.