input_mats function

Input matrices for a statistical model

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::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 class 'input_mats'
as.data.table(x, ...)

## S3 method for class '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 data.table::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.

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
as.data.table(survmod$input_data) # Convert "input_mats" object to data.table

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.