StateVals: Model for state values

In hesim: Health Economic Simulation Modeling and Decision Analysis

Model for state values

Description

Simulate values (i.e., utility or costs) associated with health states in a state transition or partitioned survival model.

Public fields

params

Parameters for simulating state values. Currently supports objects of class tparams_mean or params_lm.

input_data

An object of class input_mats. Only used for params_lm objects.

method

The method used to simulate costs and quality-adjusted life-years (QALYs) as a function of state values. If wlos, then costs and QALYs are simulated by weighting state values by the length of stay in a health state. If starting, then state values represent a one-time value that occurs when a patient enters a health state. When starting is used in a cohort model, the state values only accrue at time 0; in contrast, in an individual-level model, state values accrue each time a patient enters a new state and are discounted based on time of entrance into that state.

time_reset

If FALSE then time intervals are based on time since the start of the simulation. If TRUE, then time intervals reset each time a patient enters a new health state. This is relevant if, for example, costs vary over time within health states. Only used if method = wlos.

Methods

Public methods

• StateVals$new()

• StateVals$sim()

• StateVals$check()

• StateVals$clone()

---

Method new()

Create a new StateVals object.

Usage

StateVals$new(
  params,
  input_data = NULL,
  method = c("wlos", "starting"),
  time_reset = FALSE
)

Arguments

params

The params field.

input_data

The input_data field.

method

The method field.

time_reset

The time_reset field.

Returns

A new StateVals object.

---

Method sim()

Simulate state values with either predicted means or random samples by treatment strategy, patient, health state, and time t.

Usage

StateVals$sim(t, type = c("predict", "random"))

Arguments

t

A numeric vector of times.

type

"predict" for mean values or "random" for random samples.

Returns

A data.table of simulated state values with columns for sample, strategy_id, patient_id, state_id, time, and value.

---

Method check()

Input validation for class. Checks that fields are the correct type.

Usage

StateVals$check()

---

Method clone()

The objects of this class are cloneable with this method.

Usage

StateVals$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# Simple sick-sicker example where drug costs vary by treatment strategy
# and over time. Prior to time = 5, costs are $10,000 for treatment strategy 
# 1 and $5,000 for treatment strategy 2. After time = 5, costs are $2,000
# for both treatment strategies

## Setup the model
hesim_dat <- hesim_data(
  strategies = data.frame(strategy_id = c(1, 2)),
  patients = data.frame(patient_id = 1:3),
  states = data.frame(state_id = c(1, 2), # Non-death states
                      state_name = c("sick", "sicker")) 
)

## Drug costs vary by health state and time interval
drugcost_tbl <- stateval_tbl(
  data.frame(
    strategy_id = c(1, 1, 2, 2),
    time_start = c(0, 5, 0, 5),
    est = c(10000, 2000, 5000, 2000)
  ),
  dist = "fixed"
)
drugcost_tbl

## Create drug cost model
drugcostmod <- create_StateVals(drugcost_tbl, n = 1, hesim_data = hesim_dat)
      
## Explore predictions from the drug cost model
drugcostmod$sim(t = c(2, 6), type = "predict")
 

hesim documentation built on Nov. 5, 2025, 6:52 p.m.