hesim (version 0.2.0)

input_mats: Input matrices for a statistical model

Description

Create an object of class "input_mats", which contains inputs matrices for simulating a statistical model. Consists of (i) input matrices, X, (ii) ID variables indexing the rows of each matrix in X, and (iii) the dimensions of the X matrices. More details are provided under "Details" below. Note that an "input_mats" object should be created using create_input_mats.

Usage

input_mats(X, strategy_id, n_strategies, patient_id, n_patients,
  line = NULL, n_lines = NULL, state_id = NULL, n_states = NULL,
  transition_id = NULL, n_transitions = NULL, time_id = NULL,
  time_intervals = NULL, n_times = NULL, time_fun = NULL)

Arguments

X

A list of input matrices for predicting the values of each parameter in a statistical model. May also be a list of lists of input matrices when a list of separate models is fit (e.g., with flexsurvreg_list).

strategy_id

A numeric vector of integers denoting the treatment strategy represented by each row in X.

n_strategies

A scalar denoting the number of unique treatment strategies.

patient_id

A numeric vector of integers denoting the patient represented by each row in X.

n_patients

A scalar denoting the number of unique patients.

line

A numeric vector of integers denoting the treatment line represented by each row in X. Not supported by currently available models.

n_lines

A data.table denoting the number of treatment lines associated with each treatment strategy. Should contain a column, "strategy_id", and a column, "N". Not supported by currently available models.

state_id

A numeric vector of integers denoting the health state represented by each row in X.

n_states

A scalar denoting the number of unique health states.

transition_id

A numeric vector denoting the health state transition represented by each row in X. This must only be specified when estimating the health state transitions with a joint likelihood function. If independent models are fit for each transition, then separate X matrices must be specified for each transition. Note that this is not currently supported but will be supported once hesim provides support for state transition modeling.

n_transitions

A scalar denoting the number of unique transitions. Not supported by currently available models.

time_id

A numeric vector of integers denoting a unique time interval.

time_intervals

A data.table denotes unique time intervals. Must contain the columns time_id, time_start, and time_stop. time_start is the starting time of an interval and time_stop is the stopping time of an interval. Time intervals are closed on the left and open on the right, and in the final interval, time_stop is equal to infinity.

n_times

A scalar denoting the number of time intervals. Equal to the number of rows in time_intervals.

time_fun

A pointer to a C++ functor that can be used to update X as a function of time in a simulation model. Not currently supported.

Details

Each row of each matrix X is an input vector, \(x_{hijk}\), where \(h\) denotes a health-related index, \(i\) indexes a patient, \(j\) indexes a treatment line, and \(k\) is a treatment strategy. A health-related index is either a health state (e.g., state_id) or a transition between health states (e.g., transition_id). In some cases, the health-related index \(h\) can be suppressed and separate models can be fit for each health index. This is, for instance, the case in a partitioned survival model where separate models are fit for each survival endpoint. Likewise, models can be fit without multiple treatment lines as would, again, be the case in a partitioned survival analysis where sequential treatment would be incorporated by adding additional health states rather than by using the index \(j\).

The rows of the matrices in X must be sorted in a manner consistent with the ID variables. The sorting order should be the same as specified in expand.hesim_data; that is, the rows of X must be sorted by: (i) strategy_id, (ii) line, (iii) patient_id, and (iv) the health-related ID variable (either state_id or transition_id).

See Also

create_input_mats

Examples

# NOT RUN {
strategies <- data.frame(strategy_id = c(1, 2))
patients <- data.frame(patient_id = seq(1, 3), 
                          age = c(45, 47, 60),
                          female = c(1, 0, 0),
                          group = factor(c("Good", "Medium", "Poor")))
hesim_dat <- hesim_data(strategies = strategies,
                        patients = patients)

dat <- expand(hesim_dat, by = c("strategies", "patients"))
input_mats <- input_mats(X = list(mu = model.matrix(~ age, dat)),
                         strategy_id = dat$strategy_id,
                         n_strategies = length(unique(dat$strategy_id)),
                         patient_id = dat$patient_id,
                        n_patients = length(unique(dat$patient_id)))
print(input_mats)
# }