IndivCtstm: Individual-level continuous time state transition model
In hesim-dev/hesim: Health Economic Simulation Modeling and Decision Analysis
IndivCtstm R Documentation
Individual-level continuous time state transition model
Description
Simulate outcomes from an individual-level continuous time state transition
model (CTSTM). The class supports "clock-reset"
(i.e., semi-Markov), "clock-forward" (i.e., Markov), and mixtures of
clock-reset and clock-forward multi-state models as described in
IndivCtstmTrans.
Format
An R6::R6Class object.
Public fields
trans_modelThe model for health state transitions. Must be an object
of class IndivCtstmTrans.
utility_modelThe model for health state utility. Must be an object of
class StateVals.
cost_modelsThe models used to predict costs by health state.
Must be a list of objects of class StateVals, where each element of the
list represents a different cost category.
disprog_An object of class disprog.
stateprobs_An object of class stateprobs simulated using $sim_stateprobs().
qalys_An object of class qalys simulated using $sim_qalys().
costs_An object of class costs simulated using $sim_costs().
Methods
Public methods
-
-
-
-
-
-
-
Method new()
Create a new IndivCtstm object.
Usage
IndivCtstm$new(trans_model = NULL, utility_model = NULL, cost_models = NULL)
Arguments
trans_modelThe trans_model field.
utility_modelThe utility_model field.
cost_modelsThe cost_models field.
Returns
A new IndivCtstm object.
Method sim_disease()
Simulate disease progression (i.e., individual trajectories through a multi-state
model) using IndivCtstmTrans$sim_disease().
Usage
IndivCtstm$sim_disease(max_t = 100, max_age = 100, progress = NULL)
Arguments
max_tA scalar or vector denoting the length of time to simulate the model.
If a vector, must be equal to the number of simulated patients.
max_ageA scalar or vector denoting the maximum age to simulate each patient until.
If a vector, must be equal to the number of simulated patients.
progressAn integer, specifying the PSA iteration (i.e., sample) that should be
printed every progress PSA iterations. For example, if progress = 2,
then every second PSA iteration is printed. Default is NULL,
in which case no output is printed.
Returns
An instance of self with simulated output stored in disprog_.
Method sim_stateprobs()
Simulate health state probabilities as a function of time using the
simulation output stored in disprog.
Usage
IndivCtstm$sim_stateprobs(t)
Arguments
tA numeric vector of times.
Returns
An instance of self with simulated output of class stateprobs
stored in stateprobs_.
Method sim_qalys()
Simulate quality-adjusted life-years (QALYs) as a function of disprog_ and
utility_model.
Usage
IndivCtstm$sim_qalys(
dr = 0.03,
type = c("predict", "random"),
lys = TRUE,
by_patient = FALSE
)
Arguments
drDiscount rate.
type"predict" for mean values or "random" for random samples
as in $sim() in StateVals.
lysIf TRUE, then life-years are simulated in addition to QALYs.
by_patientIf TRUE, then QALYs and/or costs are computed at the patient level.
If FALSE, then they are averaged across patients by health state.
Returns
An instance of self with simulated output of
class qalys stored in qalys_.
Method sim_costs()
Simulate costs as a function of disprog_ and cost_models.
Usage
IndivCtstm$sim_costs(
dr = 0.03,
type = c("predict", "random"),
by_patient = FALSE,
max_t = Inf
)
Arguments
drDiscount rate.
type"predict" for mean values or "random" for random samples
as in $sim() in StateVals.
by_patientIf TRUE, then QALYs and/or costs are computed at the patient level.
If FALSE, then they are averaged across patients by health state.
max_tMaximum time duration to compute costs once a patient has
entered a (new) health state. By default, equal to Inf,
so that costs are computed over the entire duration that a patient is in
a given health state. If time varies by each cost category, then time
can also be passed as a numeric vector of length equal to the number of
cost categories (e.g., c(1, 2, Inf, 3) for a model with four cost categories).
Returns
An instance of self with simulated output of class costs
stored in costs_.
Method summarize()
Summarize costs and QALYs so that cost-effectiveness analysis can be performed.
See summarize_ce().
Usage
IndivCtstm$summarize(by_grp = FALSE)
Arguments
by_grpIf TRUE, then costs and QALYs are computed by subgroup. If
FALSE, then costs and QALYs are aggregated across all patients (and subgroups).
Method clone()
The objects of this class are cloneable with this method.
Usage
IndivCtstm$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
References
Incerti and Jansen (2021).
See Section 2.2 for a mathematical description of an individual-level CTSTM and Section 4.1 for
an example in oncology.
See Also
The IndivCtstmTrans documentation
describes the class for the transition model and the StateVals documentation
describes the class for the cost and utility models. An IndivCtstmTrans
object is typically created using create_IndivCtstmTrans().
There are currently two relevant vignettes. vignette("mstate") shows how to
parameterize IndivCtstmTrans objects in cases where patient-level data is
available by fitting a multi-state models. vignette("markov-inhomogeneous-indiv")
shows how the time inhomogeneous Markov cohort model in
vignette("markov-inhomogeneous-cohort") can be developed as an individual
patient simulation; in doing so, it shows how IndivCtstm models can be
used even without access to patient-level data.
Examples
library("flexsurv")
# Treatment strategies, target population, and model structure
strategies <- data.frame(strategy_id = c(1, 2))
patients <- data.frame(patient_id = seq(1, 3),
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)
# Parameter estimation
## Multi-state model
tmat <- rbind(c(NA, 1, 2),
c(3, NA, 4),
c(NA, NA, NA))
fits <- vector(length = max(tmat, na.rm = TRUE), mode = "list")
surv_dat <- data.frame(mstate3_exdata$transitions)
for (i in 1:length(fits)){
fits[[i]] <- flexsurvreg(Surv(years, status) ~ factor(strategy_id),
data = surv_dat,
subset = (trans == i),
dist = "weibull")
}
fits <- flexsurvreg_list(fits)
## Utility
utility_tbl <- stateval_tbl(data.frame(state_id = states$state_id,
mean = mstate3_exdata$utility$mean,
se = mstate3_exdata$utility$se),
dist = "beta")
## Costs
drugcost_tbl <- stateval_tbl(data.frame(strategy_id = strategies$strategy_id,
est = mstate3_exdata$costs$drugs$costs),
dist = "fixed")
medcost_tbl <- stateval_tbl(data.frame(state_id = states$state_id,
mean = mstate3_exdata$costs$medical$mean,
se = mstate3_exdata$costs$medical$se),
dist = "gamma")
# Economic model
n_samples = 2
## Construct model
### Transitions
transmod_data <- expand(hesim_dat)
transmod <- create_IndivCtstmTrans(fits, input_data = transmod_data,
trans_mat = tmat,
n = n_samples)
### Utility
utilitymod <- create_StateVals(utility_tbl, n = n_samples, hesim_data = hesim_dat)
### Costs
drugcostmod <- create_StateVals(drugcost_tbl, n = n_samples, hesim_data = hesim_dat)
medcostmod <- create_StateVals(medcost_tbl, n = n_samples, hesim_data = hesim_dat)
costmods <- list(drugs = drugcostmod,
medical = medcostmod)
### Combine
ictstm <- IndivCtstm$new(trans_model = transmod,
utility_model = utilitymod,
cost_models = costmods)
## Simulate outcomes
head(ictstm$sim_disease()$disprog_)
head(ictstm$sim_stateprobs(t = c(0, 5, 10))$stateprobs_[t == 5])
ictstm$sim_qalys(dr = .03)
ictstm$sim_costs(dr = .03)
### Summarize cost-effectiveness
ce <- ictstm$summarize()
head(ce)
format(summary(ce), pivot_from = "strategy")
hesim-dev/hesim documentation built on Feb. 14, 2024, 1:18 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| IndivCtstm | R Documentation |
Individual-level continuous time state transition model
Description
Simulate outcomes from an individual-level continuous time state transition
model (CTSTM). The class supports "clock-reset"
(i.e., semi-Markov), "clock-forward" (i.e., Markov), and mixtures of
clock-reset and clock-forward multi-state models as described in
IndivCtstmTrans.
Format
An R6::R6Class object.
Public fields
trans_modelThe model for health state transitions. Must be an object of class
IndivCtstmTrans.utility_modelThe model for health state utility. Must be an object of class
StateVals.cost_modelsThe models used to predict costs by health state. Must be a list of objects of class
StateVals, where each element of the list represents a different cost category.disprog_An object of class
disprog.stateprobs_An object of class
stateprobssimulated using$sim_stateprobs().qalys_An object of class
qalyssimulated using$sim_qalys().costs_An object of class
costssimulated using$sim_costs().
Methods
Public methods
Method new()
Create a new IndivCtstm object.
Usage
IndivCtstm$new(trans_model = NULL, utility_model = NULL, cost_models = NULL)
Arguments
trans_modelThe
trans_modelfield.utility_modelThe
utility_modelfield.cost_modelsThe
cost_modelsfield.
Returns
A new IndivCtstm object.
Method sim_disease()
Simulate disease progression (i.e., individual trajectories through a multi-state
model) using IndivCtstmTrans$sim_disease().
Usage
IndivCtstm$sim_disease(max_t = 100, max_age = 100, progress = NULL)
Arguments
max_tA scalar or vector denoting the length of time to simulate the model. If a vector, must be equal to the number of simulated patients.
max_ageA scalar or vector denoting the maximum age to simulate each patient until. If a vector, must be equal to the number of simulated patients.
progressAn integer, specifying the PSA iteration (i.e., sample) that should be printed every
progressPSA iterations. For example, ifprogress = 2, then every second PSA iteration is printed. Default isNULL, in which case no output is printed.
Returns
An instance of self with simulated output stored in disprog_.
Method sim_stateprobs()
Simulate health state probabilities as a function of time using the
simulation output stored in disprog.
Usage
IndivCtstm$sim_stateprobs(t)
Arguments
tA numeric vector of times.
Returns
An instance of self with simulated output of class stateprobs
stored in stateprobs_.
Method sim_qalys()
Simulate quality-adjusted life-years (QALYs) as a function of disprog_ and
utility_model.
Usage
IndivCtstm$sim_qalys(
dr = 0.03,
type = c("predict", "random"),
lys = TRUE,
by_patient = FALSE
)Arguments
drDiscount rate.
type"predict"for mean values or"random"for random samples as in$sim()inStateVals.lysIf
TRUE, then life-years are simulated in addition to QALYs.by_patientIf
TRUE, then QALYs and/or costs are computed at the patient level. IfFALSE, then they are averaged across patients by health state.
Returns
An instance of self with simulated output of
class qalys stored in qalys_.
Method sim_costs()
Simulate costs as a function of disprog_ and cost_models.
Usage
IndivCtstm$sim_costs(
dr = 0.03,
type = c("predict", "random"),
by_patient = FALSE,
max_t = Inf
)Arguments
drDiscount rate.
type"predict"for mean values or"random"for random samples as in$sim()inStateVals.by_patientIf
TRUE, then QALYs and/or costs are computed at the patient level. IfFALSE, then they are averaged across patients by health state.max_tMaximum time duration to compute costs once a patient has entered a (new) health state. By default, equal to
Inf, so that costs are computed over the entire duration that a patient is in a given health state. If time varies by each cost category, then time can also be passed as a numeric vector of length equal to the number of cost categories (e.g.,c(1, 2, Inf, 3)for a model with four cost categories).
Returns
An instance of self with simulated output of class costs
stored in costs_.
Method summarize()
Summarize costs and QALYs so that cost-effectiveness analysis can be performed.
See summarize_ce().
Usage
IndivCtstm$summarize(by_grp = FALSE)
Arguments
by_grpIf
TRUE, then costs and QALYs are computed by subgroup. IfFALSE, then costs and QALYs are aggregated across all patients (and subgroups).
Method clone()
The objects of this class are cloneable with this method.
Usage
IndivCtstm$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
References
Incerti and Jansen (2021). See Section 2.2 for a mathematical description of an individual-level CTSTM and Section 4.1 for an example in oncology.
See Also
The IndivCtstmTrans documentation
describes the class for the transition model and the StateVals documentation
describes the class for the cost and utility models. An IndivCtstmTrans
object is typically created using create_IndivCtstmTrans().
There are currently two relevant vignettes. vignette("mstate") shows how to
parameterize IndivCtstmTrans objects in cases where patient-level data is
available by fitting a multi-state models. vignette("markov-inhomogeneous-indiv")
shows how the time inhomogeneous Markov cohort model in
vignette("markov-inhomogeneous-cohort") can be developed as an individual
patient simulation; in doing so, it shows how IndivCtstm models can be
used even without access to patient-level data.
Examples
library("flexsurv")
# Treatment strategies, target population, and model structure
strategies <- data.frame(strategy_id = c(1, 2))
patients <- data.frame(patient_id = seq(1, 3),
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)
# Parameter estimation
## Multi-state model
tmat <- rbind(c(NA, 1, 2),
c(3, NA, 4),
c(NA, NA, NA))
fits <- vector(length = max(tmat, na.rm = TRUE), mode = "list")
surv_dat <- data.frame(mstate3_exdata$transitions)
for (i in 1:length(fits)){
fits[[i]] <- flexsurvreg(Surv(years, status) ~ factor(strategy_id),
data = surv_dat,
subset = (trans == i),
dist = "weibull")
}
fits <- flexsurvreg_list(fits)
## Utility
utility_tbl <- stateval_tbl(data.frame(state_id = states$state_id,
mean = mstate3_exdata$utility$mean,
se = mstate3_exdata$utility$se),
dist = "beta")
## Costs
drugcost_tbl <- stateval_tbl(data.frame(strategy_id = strategies$strategy_id,
est = mstate3_exdata$costs$drugs$costs),
dist = "fixed")
medcost_tbl <- stateval_tbl(data.frame(state_id = states$state_id,
mean = mstate3_exdata$costs$medical$mean,
se = mstate3_exdata$costs$medical$se),
dist = "gamma")
# Economic model
n_samples = 2
## Construct model
### Transitions
transmod_data <- expand(hesim_dat)
transmod <- create_IndivCtstmTrans(fits, input_data = transmod_data,
trans_mat = tmat,
n = n_samples)
### Utility
utilitymod <- create_StateVals(utility_tbl, n = n_samples, hesim_data = hesim_dat)
### Costs
drugcostmod <- create_StateVals(drugcost_tbl, n = n_samples, hesim_data = hesim_dat)
medcostmod <- create_StateVals(medcost_tbl, n = n_samples, hesim_data = hesim_dat)
costmods <- list(drugs = drugcostmod,
medical = medcostmod)
### Combine
ictstm <- IndivCtstm$new(trans_model = transmod,
utility_model = utilitymod,
cost_models = costmods)
## Simulate outcomes
head(ictstm$sim_disease()$disprog_)
head(ictstm$sim_stateprobs(t = c(0, 5, 10))$stateprobs_[t == 5])
ictstm$sim_qalys(dr = .03)
ictstm$sim_costs(dr = .03)
### Summarize cost-effectiveness
ce <- ictstm$summarize()
head(ce)
format(summary(ce), pivot_from = "strategy")
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.