An object of class input_mats contains input matrices for simulating a statistical model. Consists of (i) input matrices, X, and (ii) metadata used to index each matrix in X.

Once created, an input_mats object can be converted to a data.table with as.data.table(), which is a helpful way to check that the object is as expected. The print() method summarizes the object and prints it to the console.

More details are provided under "Details" below.

input_mats(X, ...)

# S3 method for input_mats
as.data.table(x, ...)

# S3 method for input_mats
print(x, ...)

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()).

...

For input_mats(), arguments to pass to id_attributes(). For print(), arguments to pass to print.data.table().

x

An input_mats object.

Details

input_mats objects are used with params objects to simulate disease models, cost models, and/or utility models. Each column of $X contains variables from the params object and a given row corresponds to a combination of the ID variables. An input matrix must always have rows for the treatment strategies (strategy_id) and patients (patient_id); it may optionally have rows for health variables (state_id or transition_id) and time intervals (time_id). The rows must be sorted by prioritizing (i) strategy_id, (ii) patient_id, (iii) the health related ID variable (either state_id or transition_id) and (iv) time_id.

While input_mats objects can be created directly with input_mats(), it is rarely a good idea to do so. They are typically created as the input_data field when creating model objects (e.g., with create_IndivCtstmTrans(), create_CohortDtstmTrans(), and create_PsmCurves()). Internally, these functions create the input matrices using create_input_mats() methods, which ensure that they are in the correct format. Users may also use create_input_mats() methods, but there is not usually a good reason to do so.

as.data.table.input_mats() will convert input matrices into a single data.table() that column binds the ID variables and the unique combinations of variables contained in the elements of $X. print.input_mats() prints a call to as.data.table() and provides additional information about the ID variables.

See also

See IndivCtstmTrans() and PsmCurves() for examples in which the input_data field of an instance of a model class is an input_mats object.

Examples

library("data.table") # Input matrices are typically created as part of model objects # Let's illustrate with a partitioned survival model (PSM) ## Model setup strategies <- data.frame(strategy_id = c(1, 2), new_strategy = c(0, 1)) 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) ## Create survival models for PSM ### Parameters n <- 2 survmod_params <- params_surv_list( # Progression free survival (PFS) pfs = params_surv( coefs = list( rate = data.frame(intercept = rnorm(n, log(1/5), 1), new_strategy = rnorm(n, log(.8), 1)) ), dist = "exp" ), # Overall survival (OS) os = params_surv( coefs = list( rate = data.frame(intercept = rnorm(n, log(1/10), 1)) ), dist = "exp" ) ) ### Input data survmod_input_data <- expand(hesim_dat)[, intercept := 1] ### Model object survmod <- create_PsmCurves(survmod_params, input_data = survmod_input_data) ## Inspect input data survmod$input_data # Print "input_mats" object to console
#> An "input_mats" object #> #> Column binding the ID variables with all variables contained in the X matrices: #> strategy_id patient_id intercept new_strategy #> 1: 1 1 1 0 #> 2: 1 2 1 0 #> 3: 1 3 1 0 #> 4: 2 1 1 1 #> 5: 2 2 1 1 #> 6: 2 3 1 1 #> #> Number of unique values of ID variables: #> n_strategies n_patients #> 2 3 #>
as.data.table(survmod$input_data) # Convert "input_mats" object to data.table
#> strategy_id patient_id intercept new_strategy #> 1: 1 1 1 0 #> 2: 1 2 1 0 #> 3: 1 3 1 0 #> 4: 2 1 1 1 #> 5: 2 2 1 1 #> 6: 2 3 1 1