A Tutorial on Time-Dependent Cohort State-Transition Models in R using a Cost-Effectiveness Analysis Example
This GitHub repository has the R code for a tutorial on implementing time-dependent cohort state-transition models (cSTMs) in R, using a cost-effectiveness analysis (CEA) example. The tutorial is the following article:
- Alarid-Escudero F, Krijkamp EM, Enns EA, Yang A, Hunink MGM, Pechlivanoglou P, Jalal H. A Tutorial on Time-Dependent Cohort State-Transition Models in R using a Cost-Effectiveness Analysis Example. Medical Decision Making. 2023;43(1):21-41. https://doi.org/10.1177/0272989X221121747
and its preprint:
- Alarid-Escudero F, Krijkamp EM, Enns EA, Yang A, Hunink MGM, Pechlivanoglou P, Jalal H. A Tutorial on Time-Dependent Cohort State-Transition Models in R using a Cost-Effectiveness Analysis Example. arXiv:2108.13552v2. 2022:1-37.
Every release of the code is archived in Zenodo: https://doi.org/10.5281/zenodo.5338818 (this DOI always resolves to the latest version).
Correction (v0.3.0): Versions up to v0.2.0, and the published article, assigned Simpson’s 1/3rd within-cycle correction weights by vector position instead of by time. They used
1/3, 2/3, 4/3, …instead of1/3, 4/3, 2/3, …. v0.3.0 fixes this. With the fix, base-case QALYs are about 0.32 higher per strategy and ICERs change by less than 0.6%; the conclusions are unchanged. v0.3.0 also fixes the probabilistic sensitivity analysis of the state-residence model, which stopped with an error. SeeNEWS.mdfor details and a before/after table. We thank Lauren N. Steimle and ambtnhlr for finding and reporting this error in the introductory tutorial, which shares the code (see Acknowledgements).Erratum in the published parameter table: Table 2 of the article lists the cost of Treatment B (
c_trtB) as $12,000. The correct value is $13,000, as stated in the article’s text and used in the code, the PSA distribution (gamma(86.2, 150.8), mean $13,000) and the published results. We thank conallaque for reporting it.
# 1. Clone the repository (or download it as a ZIP from GitHub) and open
# `cohort-modeling-tutorial-timedep.Rproj` in RStudio, or set the working
# directory to the repository's root folder.
# 2. Install the exact package versions used by the tutorial
install.packages("renv")
renv::restore()
# 3. Run the tutorial: base case, CEA, PSA and epidemiological outcomes
source("analysis/cSTM_time_dep_simulation.R") # simulation-time dependence
source("analysis/cSTM_time_dep_state_residence.R") # state-residence time dependence
# 4. (Optional) Run the unit tests
testthat::test_dir("tests/testthat")The tutorial was most recently checked with R 4.5.3. Package versions
are pinned in renv.lock. If you would rather not use
renv, install the packages listed under Imports in
DESCRIPTION with install.packages(). MethylCapSig,
used to sample correlated Weibull parameters in the state-residence PSA,
has been archived on CRAN; renv::restore() installs it from the CRAN
archive, or you can run install.packages("geepack") followed by
remotes::install_version("MethylCapSig", "1.0.1").
├── analysis/
│ ├── cSTM_time_dep_simulation.R # Simulation-time-dependent Sick-Sicker cSTM, CEA, PSA,
│ │ # epidemiological outcomes
│ └── cSTM_time_dep_state_residence.R # State-residence-time-dependent (tunnel states) cSTM,
│ # CEA, PSA, epidemiological outcomes
├── R/
│ ├── Functions.R # Epidemiological outputs, within-cycle correction,
│ │ # rate-to-probability conversion, array checks,
│ │ # and CEA/PSA functions (copies from dampack)
│ ├── Functions_cSTM_time_dep_simulation.R # Model wrapper, CEA outputs, PSA inputs
│ └── Functions_cSTM_time_dep_state_residence.R # Model wrapper, CEA outputs, PSA inputs
├── data/ # US life table used for age-specific mortality
├── tests/testthat/ # Unit and regression tests
├── manuscript/ # Archival sources of the published article (see manuscript/README.md)
├── DESCRIPTION # Project version and dependencies
├── renv.lock # Pinned package versions
├── NEWS.md # Changelog
└── CITATION.cff # Citation metadata
The manuscript folder includes the R Markdown files
cSTM_Tutorial_TimeDep.Rmd and
Appendix_table_Markov_Tutorial_Part2.Rmd
with the text and code of the tutorial and the Supplementary table,
respectively. The manuscript R Markdown file does not include all the
code for the analyses of both types of time dependence; the
analysis scripts do.
The repository is self-contained: R/Functions.R includes local copies
of the functions it uses from two DARTH packages:
dampack: Decision-Analytic Modeling Package, an R package for analyzing and visualizing the health economic outputs of decision models.darthtools: helper functions for the within-cycle correction, rate conversion and transition-array checks.
You don’t need to install either package to run the tutorial. To use them anyway:
install.packages("dampack") # from CRAN
# install.packages("remotes")
remotes::install_github("DARTH-git/darthtools") # from GitHubNote: darthtools up to v0.4.0 has the same Simpson’s 1/3rd
indexing error as this repository had. It is fixed in darthtools
v0.4.1. If
you use darthtools::gen_wcc(), update to v0.4.1 or later.
We recommend reading our introductory tutorial on time-independent cSTMs in R:
- Alarid-Escudero F, Krijkamp EM, Enns EA, Yang A, Hunink MGM, Pechlivanoglou P, Jalal H. An Introductory Tutorial on Cohort State-Transition Models in R Using a Cost-Effectiveness Analysis Example. Medical Decision Making, 2023;43(1):3-20. https://doi.org/10.1177/0272989X221103163 (code)
understanding the use of multidimensional arrays to represent cSTM dynamics in R, described in:
- Krijkamp EM, Alarid-Escudero F, Enns EA, Pechlivanoglou P, Hunink MGM, Yang A, Jalal HJ. A multidimensional array representation of state-transition model dynamics. Medical Decision Making, 2020;40(2):242-248. https://doi.org/10.1177/0272989X19893973
and becoming familiar with the DARTH coding framework described in:
- Alarid-Escudero F, Krijkamp EM, Pechlivanoglou P, Jalal HJ, Kao SYZ, Yang A, Enns EA. A Need for Change! A Coding Framework for Improving Transparency in Decision Modeling. PharmacoEconomics, 2019;37(11):1329–1339. https://doi.org/10.1007/s40273-019-00837-x
You can cite the R code in this repository like this: “we based our
analysis on the R code from Alarid-Escudero F et al. (2023)”. Include
both of the following references in your reference list. Update the
version, version DOI and ‘last accessed’ date to match the release you
used. Each version’s DOI is listed on the Zenodo
record, and the GitHub “Cite
this repository” button gives the metadata from
CITATION.cff.
Alarid-Escudero F, Krijkamp EM, Enns EA, Yang A, Hunink MGM, Pechlivanoglou P, Jalal H. A Tutorial on Time-Dependent Cohort State-Transition Models in R using a Cost-Effectiveness Analysis Example. Medical Decision Making. 2023;43(1):21-41. https://doi.org/10.1177/0272989X221121747
Alarid-Escudero F, Krijkamp EM, Enns EA, Yang A, Hunink MGM, Pechlivanoglou P, Jalal H. R Code for A Tutorial on Time-Dependent Cohort State-Transition Models in R using a Cost-Effectiveness Analysis Example (Version v0.3.0). Zenodo. 10.5281/zenodo.5338818. Last accessed DD Month YYYY.
If you adapted the code, write “Adapted from:” or “Based on” so readers know you modified it. For more on how and when to cite computer code, see Writing Code (from the MIT Academic Integrity Handbook).
Found a bug or have a suggestion? Please open an
issue.
Include a minimal reproducible example and the output of
sessionInfo().
Pull requests are welcome. Before you submit one, please:
- Add or update tests in
tests/testthat/that cover the change. - Make sure
testthat::test_dir("tests/testthat")passes and that both scripts inanalysis/run end to end. Continuous integration checks this on every pull request. - If you add or update packages, run
renv::snapshot(). - Describe the change in
NEWS.md.
We are grateful to the users who have helped improve this code:
- Lauren N. Steimle (Georgia Institute of Technology) and
ambtnhlr each independently found
and reported the indexing error in the Simpson’s 1/3rd within-cycle
correction (
gen_wcc()) of the introductory tutorial and proposed a correction (DARTH-git/cohort-modeling-tutorial-intro#2). Their reports led to the fix here in v0.3.0. - conallaque found, while replicating both tutorials independently in Python, that the published parameter tables list the cost of Treatment B as $12,000 instead of the $13,000 used in the text, code and results (DARTH-git/cohort-modeling-tutorial-intro#1).
If you find an error, please let us know.