popEpi (version 0.4.12)

splitLexisDT: Split case-level observations

Description

Split a Lexis object along one time scale (as splitLexis) with speed

Usage

splitLexisDT(lex, breaks, timeScale, merge = TRUE, drop = TRUE)

Value

A data.table or data.frame

(depending on options("popEpi.datatable"); see ?popEpi) object expanded to accommodate split observations.

Arguments

lex

a Lexis object, split or not

breaks

a vector of [a,b) breaks to split data by

timeScale

a character string; name of the time scale to split by

merge

logical; if TRUE, retains all variables from the original data - i.e. original variables are repeated for all the rows by original subject

drop

logical; if TRUE, drops all resulting rows after expansion that reside outside the time window defined by the given breaks

Author

Joonas Miettinen

Details

splitLexisDT is in essence a data.table version of splitLexis or survSplit for splitting along a single time scale. It requires a Lexis object as input, which may have already been split along some time scale.

Unlike splitLexis, splitLexisDT drops observed time outside the roof and floor of breaks by default - with drop = FALSE the functions have identical behaviour.

The Lexis time scale variables can be of any arbitrary format, e.g. Date, fractional years (see cal.yr) and get.yrs, or other. However, using date variables (from package date) are not recommended, as date variables are always stored as integers, whereas Date variables (see ?as.Date) are typically stored in double ("numeric") format. This allows for breaking days into fractions as well, when using e.g. hypothetical years of 365.25 days.

See Also

Other splitting functions: lexpand(), splitMulti()

Examples

library(Epi)
data("sire", package = "popEpi")
x <- Lexis(data=sire[1000:1100, ], 
           entry = list(fot=0, per=get.yrs(dg_date), age=dg_age), 
           exit=list(per=get.yrs(ex_date)), exit.status=status)
BL <- list(fot=seq(0, 5, by = 3/12), per=c(2008, 2013))

x2 <- splitMulti(x, breaks = BL, drop = FALSE)

x3 <- splitLexisDT(x, breaks = BL$fot, timeScale = "fot", drop = FALSE)
x3 <- splitLexisDT(x3, breaks = BL$per, timeScale = "per", drop = FALSE)

x4 <- splitLexis(x,  breaks = BL$fot, time.scale = "fot")
x4 <- splitLexis(x4, breaks = BL$per, time.scale = "per")
## all produce identical results

## using Date variables
x <- Lexis(data=sire[1000:1100, ], 
           entry = list(fot=0, per=dg_date, age=dg_date-bi_date), 
           exit=list(per=ex_date), exit.status=status)
BL <- list(fot = 0:5*365.25, per = as.Date(c("2008-01-01", "2013-01-01")))

x2 <- splitMulti(x, breaks = BL, drop = FALSE)

x3 <- splitLexisDT(x, breaks = BL$fot, timeScale = "fot", drop = FALSE)
x3 <- splitLexisDT(x3, breaks = BL$per, timeScale = "per", drop = FALSE)

## splitLexis may not work when using Dates