hesim (version 0.2.3)

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_reset = 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_reset

If TRUE, then time intervals reset each time a patient enters a new health state. This is relevant if, for example, costs vary over time within health states. If FALSE then time intervals are based on time since the start of the simulation.

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)
# }