ICU data as handled by ricu is mostly comprised of time series data and as such, several utility functions are available for working with time series data in addition to a class dedicated to representing time series data (see ts_tbl()). Some terminology to begin with: a time series is considered to have gaps if, per (combination of) ID variable value(s), some time steps are missing. Expanding and collapsing mean to change between representations where time steps are explicit or encoded as interval with start and end times. For sliding window-type operations, slide() means to iterate over time-windows, slide_index() means to iterate over certain time-windows, selected relative to the index and hop() means to iterate over time-windows selected in absolute terms.

expand(
x,
start_var = index_var(x),
end_var = NULL,
step_size = time_step(x),
new_index = start_var,
keep_vars = NULL,
aggregate = FALSE
)

collapse(
x,
id_vars = NULL,
index_var = NULL,
start_var = "start",
end_var = "end",
env = NULL,
...
)

has_no_gaps(x)

has_gaps(...)

is_regular(x)

fill_gaps(x, limits = collapse(x), start_var = "start", end_var = "end")

remove_gaps(x)

slide(x, expr, before, after = hours(0L), ...)

slide_index(x, expr, index, before, after = hours(0L), ...)

hop(
x,
expr,
windows,
full_window = FALSE,
lwr_col = "min_time",
upr_col = "max_time",
left_closed = TRUE,
right_closed = TRUE,
eval_env = NULL,
...
)

## Arguments

x ts_tbl object to use Name of the columns that represent lower and upper windows bounds Controls the step size used to interpolate between start_var and end_var Name of the new index column Names of the columns to hold onto Function for aggregating values in overlapping intervals ID and index variables Environment used as parent to the environment used to evaluate expressions passes as ... Passed to hop_quo() and ultimately to data.table::[() A table with columns for lower and upper window bounds Expression (quoted for *_quo and unquoted otherwise) to be evaluated over each window Time span to look back/forward A vector of times around which windows are spanned (relative to the index) An icu_tbl defining the windows to span Logical flag controlling how the situation is handled where the sliding window extends beyond available data Names of columns (in windows) of lower/upper window bounds Logical flag indicating whether intervals are closed (default) or open. Environment in which expr is substituted; NULL resolves to the environment in which expr was created

## Value

Most functions return ts_tbl objects with the exception of has_gaps()/has_no_gaps()/is_regular(), which return logical flags.

## Details

A gap in a ts_tbl object is a missing time step, i.e. a missing entry in the sequence seq(min(index), max(index), by = interval) in at least one group (as defined by id_vars(), where the extrema are calculated per group. In this case, has_gaps() will return TRUE. The function is_regular() checks whether the time series has no gaps, in addition to the object being sorted and unique (see is_sorted() and is_unique()). In order to transform a time series containing gaps into a regular time series, fill_gaps() will fill missing time steps with NA values in all data_vars() columns, while remove_gaps() provides the inverse operation of removing time steps that consist of NA values in data_vars() columns.

An expand() operation performed on an object inheriting from data.table yields a ts_tbl where time-steps encoded by columns start_var and end_var are made explicit with values in keep_vars being appropriately repeated. The inverse operation is available as collapse(), which groups by id_vars, represents index_var as group-wise extrema in two new columns start_var and end_var and allows for further data summary using .... An aspect to keep in mind when applying expand() to a win_tbl object is that values simply are repeated for all time-steps that fall into a given validity interval. This gives correct results when a win_tbl for example contains data on infusions as rates, but might not lead to correct results when infusions are represented as drug amounts administered over a given time-span. In such a scenario it might be desirable to evenly distribute the total amount over the corresponding time steps (currently not implemented).

Sliding-window type operations are available as slide(), slide_index() and hop() (function naming is inspired by the CRAN package slider). The most flexible of the three, hop takes as input a ts_tbl object x containing the data, an id_tbl object windows, containing for each ID the desired windows represented by two columns lwr_col and upr_col, as well as an expression expr to be evaluated per window. At the other end of the spectrum, slide() spans windows for every ID and available time-step using the arguments before and after, while slide_index() can be seen as a compromise between the two, where windows are spanned for certain time-points, specified by index.

## Examples

tbl <- ts_tbl(x = 1:5, y = hours(1:5), z = hours(2:6), val = rnorm(5),
index_var = "y")
exp <- expand(tbl, "y", "z", step_size = 1L, new_index = "y",
keep_vars = c("x", "val"))
col <- collapse(exp, start_var = "y", end_var = "z", val = unique(val))
all.equal(tbl, col, check.attributes = FALSE)
#> [1] TRUE
tbl <- ts_tbl(x = rep(1:5, 1:5), y = hours(sequence(1:5)), z = 1:15)

win <- id_tbl(x = c(3, 4), a = hours(c(2, 1)), b = hours(c(3, 4)))
hop(tbl, list(z = sum(z)), win, lwr_col = "a", upr_col = "b")
#> # An id_tbl: 2 ✖ 4
#> # Id var:      x
#>       x b       a           z
#>   <int> <drtn>  <drtn>  <int>
#> 1     3 3 hours 2 hours    11
#> 2     4 4 hours 1 hours    34slide_index(tbl, list(z = sum(z)), hours(c(4, 5)), before = hours(2))
#> # A ts_tbl: 10 ✖ 3
#> # Id var:     x
#> # Index var:  y (1 hours)
#>        x y           z
#>    <int> <drtn>  <int>
#>  1     1 4 hours    NA
#>  2     1 5 hours    NA
#>  3     2 4 hours     3
#>  4     2 5 hours    NA
#>  5     3 4 hours    11
#>  6     3 5 hours     6
#>  7     4 4 hours    27
#>  8     4 5 hours    19
#>  9     5 4 hours    39
#> 10     5 5 hours    42slide(tbl, list(z = sum(z)), before = hours(2))
#> # A ts_tbl: 15 ✖ 3
#> # Id var:     x
#> # Index var:  y (1 hours)
#>        x y           z
#>    <int> <drtn>  <int>
#>  1     1 1 hours     1
#>  2     2 1 hours     2
#>  3     2 2 hours     5
#>  4     3 1 hours     4
#>  5     3 2 hours     9
#>  6     3 3 hours    15
#>  7     4 1 hours     7
#>  8     4 2 hours    15
#>  9     4 3 hours    24
#> 10     4 4 hours    27
#> 11     5 1 hours    11
#> 12     5 2 hours    23
#> 13     5 3 hours    36
#> 14     5 4 hours    39
#> 15     5 5 hours    42
tbl <- ts_tbl(x = rep(3:4, 3:4), y = hours(sequence(3:4)), z = 1:7)
has_no_gaps(tbl)
#> [1] TRUEis_regular(tbl)
#> [1] TRUE
tbl[1, 2] <- hours(2)
has_no_gaps(tbl)
#> [1] TRUEis_regular(tbl)
#> [1] FALSE
tbl[6, 2] <- hours(2)
has_no_gaps(tbl)
#> [1] FALSEis_regular(tbl)
#> [1] FALSE