prepare_data {TwoTimeScales} | R Documentation |
Prepare raw data by binning them in 1d or 2d
Description
prepare_data()
prepares the raw individual time-to-event data
for hazard estimation in 1d or 2d.
Given the raw data, this function first constructs the bins over one or two time axes and then computes the aggregated (or individual) vectors or matrices of exposure times and events indicators. A data.frame with covariates values can be provided by the user.
Usage
prepare_data(
data = NULL,
t_in = NULL,
t_out = NULL,
u = NULL,
s_in = NULL,
s_out,
events,
min_t = NULL,
max_t = NULL,
min_u = NULL,
max_u = NULL,
min_s = NULL,
max_s = NULL,
dt = NULL,
du = NULL,
ds,
individual = FALSE,
covs = NULL
)
Arguments
data |
A data frame. |
t_in |
(optional) A vector of entry times on the time scale |
t_out |
(optional) A vector of exit times on the time scale |
u |
(optional) A vector of fixed-times at entry in the process. |
s_in |
(optional) A vector of entry times on the time scale |
s_out |
A vector of exit times on the time scale |
events |
A vector of event's indicators (possible values 0/1). |
min_t |
(optional) A minimum value for the bins over |
max_t |
(optional) A maximum value for the bins over |
min_u |
(optional) A minimum value for the bins over |
max_u |
(optional) A maximum value for the bins over |
min_s |
(optional) A minimum value for the bins over |
max_s |
(optional) A maximum value for the bins over |
dt |
(optional) A scalar giving the length of the intervals on the |
du |
(optional) A scalar giving the length of the intervals on the |
ds |
A scalar giving the length of the intervals on the |
individual |
A Boolean. Default is |
covs |
A data.frame with the variables to be used as covariates.
The function will create dummy variables for any factor variable passed as argument in |
Details
A few words about constructing the grid of bins.
Bins are containers for the individual data. There is no 'golden rule' or
optimal strategy for setting the number of bins over each time axis, or deciding
on the bins' width. It very much depends on the data structure, however, we
try to give some directions here. First, in most cases, more bins is better
than less bins. A good number is about 30 bins.
However, if data are scarce, the user might want to find a compromise between
having a larger number of bins, and having many bins empty.
Second, the chosen width of the bins (that is du
and ds
) does depend on
the time unit over which the time scales are measured. For example, if the time
is recorded in days, as in the example below, and several years of follow-up
are available, the user can split the data in bins of width 30 (corresponding
to about one month), 60 (about two months), 90 (about three months), etc.
If the time scale is measured in years, then appropriate width could be 0.25
(corresponding to a quarter of a year), or 0.5 (that is half year). However,
in some cases, time might be measure in completed years, as is often the case
for age. In this scenario, an appropriate bin width is 1.
Finally, it is always a good idea to plot the data first, and explore the range
of values over which the time scale(s) are recorded. This will give insight
about reasonable values for the arguments min_s
, min_u
, max_s
and max_u
(that in any case are optional).
Regarding names of covariates or levels of categorical covariates/factors: When using "LMMsolver" to fit a model with covariates that which have names (or factor labels) including a symbol such as "+", "-", "<" or ">" will result in an error. To avoid this, the responsible names (labels) will be rewritten without mathematical symbols. For example: "Lev+5FU" (in the colon cancer data) is replaced by "Lev&5FU".
Value
A list with the following elements:
-
bins
a list:-
bins_t
ift_out
is provided, this is a vector of bins extremes for the time scalet
. -
mid_t
ift_out
is provided, this is a vector with the midpoints of the bins overt
. -
nt
ift_out
is provided, this is the number of bins overt
. -
bins_u
ifu
is provided, this is a vector of bins extremes foru
axis. -
midu
ifu
is provided, this is a vector with the midpoints of the bins overu
. -
nu
ifu
is provided, this is the number of bins overu
. -
bins_s
is a vector of bins extremes for the time scales
. -
mids
is a vector with the midpoints of the bins overs
. -
ns
is the number of bins overs
.
-
-
bindata
:-
r
orR
an array of exposure times: if binning the data over one time scale only this is a vector. If binning the data over two time scales and ifindividual == TRUE
thenR
is an array of dimension nu by ns by n, otherwise it is an array of dimension nu by ns -
y
orY
an array of event counts: if binning the data over one time scale only this is a vector. If binning the data over two time scales and ifindividual == TRUE
thenY
is an array of dimension nu by ns by n, otherwise it is an array of dimension nu by ns -
Z
A matrix of covariates' values to be used in the model, of dimension n by p
-
Author(s)
Angela Carollo carollo@demogr.mpg.de
Examples
# Bin data over s = time since recurrence only, with intervals of length 30 days
# aggregated data (no covariates)
# The following example provide the vectors of data directly from the dataset
binned_data <- prepare_data(s_out = reccolon2ts$timesr, events = reccolon2ts$status, ds = 30)
# Visualize vector of event counts
print(binned_data$bindata$y)
# Visualize midpoints of the bins
print(binned_data$bins$mids)
# Visualize number of bins
print(binned_data$bins$ns)
# Now, the same thing is done by providing a dataset and the name of all relevant variables
binned_data <- prepare_data(data = reccolon2ts, s_out = "timesr", events = "status", ds = 30)
# Visualize vector of event counts
print(binned_data$bindata$y)
# Now using ds = .3 and the same variable measured in years
binned_data <- prepare_data(s_out = reccolon2ts$timesr_y, events = reccolon2ts$status, ds = .3)
# Visualize vector of exposure timess
print(binned_data$bindata$r)
# Bin data over u = time at recurrence and s = time since recurrence, measured in days
# aggregated data (no covariates)
# Note that if we do not provide du this is taken to be equal to ds
binned_data <- prepare_data(
u = reccolon2ts$timer, s_out = reccolon2ts$timesr,
events = reccolon2ts$status, ds = 30
)
# Visualize matrix of event counts
print(binned_data$bindata$Y)
# Visualize midpoints of bins over u
print(binned_data$bins$midu)
# Bin data over u = time at recurrence and s = time since recurrence, measured in day
# individual-level data required
# we provide two covariates: nodes (numerical) and rx (factor)
covs <- subset(reccolon2ts, select = c("nodes", "rx"))
binned_data <- prepare_data(
u = reccolon2ts$timer, s_out = reccolon2ts$timesr,
events = reccolon2ts$status, ds = 30, individual = TRUE, covs = covs
)
# Visualize structure of binned data
print(str(binned_data$bindata))
# Alternatevely:
binned_data <- prepare_data(
data = reccolon2ts,
u = "timer", s_out = "timesr",
events = "status", ds = 30, individual = TRUE, covs = c("nodes", "rx")
)