stateval_tbl: Table to store state value parameters

Description

Create a table for storing parameter estimates used to simulate costs or utility in an economic model by treatment strategy, patient, health state, and (optionally) time interval.

Usage

stateval_tbl(
  tbl,
  dist = c("norm", "beta", "gamma", "lnorm", "unif", "fixed", "custom"),
  hesim_data = NULL
)

Arguments

tbl

A data.frame or data.table for storing parameter values. See "Details" for specifics.

dist

Probability distribution used to sample parameters for a probabilistic sensitivity analysis (PSA).

hesim_data

A hesim_data object. Required to specify treatment strategies , patients, and/or health states not included as columns in tbl, or, to match patients in tbl to groups. Not required if tbl includes one row for each treatment strategy, patient, and health state combination. Patients are matched to groups by specifying both a patient_id and a grp_id column in the patients table; if hesim_data = NULL but grp_id is included as a column in tbl, then each group is assumed to be a unique patient.

Value

An object of class "stateval_tbl", which is a data.table of parameter values with attributes for dist and optionally strategy_id, patients, and state_id. tbl is in the same format as described in "Details". patients is a data.table with one column containing patient_id and optionally a second column containing grp_id.

Details

tbl is a data.table containing columns for treatment strategies (strategy_id), patient subgroups (grp_id), health states (state_id), and/or the start of time intervals (time_start). The table must contain at least one column named strategy_id, grp_id, or state_id, but does not need to contain all of them. Each row denotes a unique treatment strategy, patient subgroup, health state, and/or time interval pair.

tbl must also contain columns summarizing the state values for each row, which depend on the probability distribution selected with dist. Available distributions include the normal (norm), beta (beta), gamma (gamma), lognormal (lnorm), and uniform (unif) distributions. In addition, the option fixed can be used if estimates are known with certainty and custom can be used if parameter values for a PSA have been previously sampled from an arbitrary probability distribution. The columns in tbl that must be included, by distribution, are:

norm: mean and sd
beta: mean and se or shape1 and shape2
gamma: mean and se, shape and rate, or shape and scale
lnorm: meanlog or sdlog
unif: min and max
fixed: est
custom: sample and value

Note that if dist = "custom", then tbl must include a column named sample (an integer vector denoting a unique random draw) and value (denoting the value of the randomly sampled parameter). In this case, there is a unique row in tbl for each random draw (sample) and each combination of strategies, patients, health states, and/or time intervals. Again, tbl must contain at least one column named strategy_id, grp_id, or state_id, but does not need to contain them all.

Examples

Run this code

# NOT RUN {
strategies <- data.frame(strategy_id = c(1, 2))
patients <- data.frame(patient_id = seq(1, 3),
                       grp_id = c(1, 1, 2),
                       age = c(45, 50, 60),
                       female = c(0, 0, 1))
states <- data.frame(state_id = c(1, 2))
hesim_dat <- hesim_data(strategies = strategies,
                        patients = patients,
                        states = states)

# Utility varies by health state and patient group
utility_tbl <- stateval_tbl(data.frame(state_id = rep(states$state_id, 2),
                                       grp_id = rep(rep(c(1, 2)), each = nrow(states)), 
                                       mean = c(.8, .7, .75, .55),
                                       se = c(.18, .12, .10, .06)),
                            dist = "beta",
                            hesim_data = hesim_dat)
print(utility_tbl)
utilmod <- create_StateVals(utility_tbl, n = 2)

# Costs vary by treatment strategy
cost_tbl <- stateval_tbl(data.frame(strategy_id = strategies$strategy_id,
                                    mean = c(5000, 3000),
                                    se = c(200, 100)),
                         dist = "gamma",
                         hesim_data = hesim_dat)
print(cost_tbl)
costmod <- create_StateVals(cost_tbl, n = 2)


# }