hesim (version 0.5.5)

input_mats: Input matrices for a statistical model

Description

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.

Usage

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

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