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, ...)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().
An input_mats object.
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 IndivCtstmTrans() and PsmCurves() for examples in which the
input_data field of an instance of a model class is an input_mats object.
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
#> <num> <int> <num> <num>
#> 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
#> <num> <int> <num> <num>
#> 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