Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .Rprofile
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
source("renv/activate.R")
63 changes: 63 additions & 0 deletions .github/workflows/check.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Runs the unit tests and the full tutorial analysis on every push and pull
# request to main, using the package versions pinned in renv.lock.
name: check

on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:

permissions:
contents: read

# Cancel superseded runs on the same branch or pull request
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
check:
name: ${{ matrix.os }} (R ${{ matrix.r }})
runs-on: ${{ matrix.os }}
timeout-minutes: 60
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest]
r: ['4.5.3'] # keep in sync with the R version in renv.lock

env:
GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

steps:
- uses: actions/checkout@v4

- uses: r-lib/actions/setup-r@v2
with:
r-version: ${{ matrix.r }}
use-public-rspm: true

# CRAN only ships macOS binaries for the latest package versions, so
# renv compiles older pinned versions from source. Some (e.g.,
# data.table) need gettext, installed from CRAN's macOS library recipes.
# Run outside the project with --vanilla so the project's .Rprofile does
# not activate renv as root (which leaves root-owned renv lock files).
- name: Install macOS system libraries
if: runner.os == 'macOS'
working-directory: ${{ runner.temp }}
run: |
sudo Rscript --vanilla -e 'source("https://mac.R-project.org/bin/install.R"); install.libs("gettext")'

- uses: r-lib/actions/setup-renv@v2

- name: Run unit tests
run: |
res <- testthat::test_dir("tests/testthat", reporter = "summary",
stop_on_failure = TRUE)
shell: Rscript {0}

- name: Run tutorial analysis end to end
run: source("analysis/cSTM_time_indep.R")
shell: Rscript {0}
77 changes: 77 additions & 0 deletions CITATION.cff
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
cff-version: 1.2.0
message: >-
If you use this code, please cite both the article and the software
using the metadata below.
type: software
title: >-
R Code for An Introductory Tutorial on Cohort State-Transition Models
in R Using a Cost-Effectiveness Analysis Example
version: 0.3.0
date-released: "2026-11-10"
license: MIT
repository-code: "https://github.com/DARTH-git/cohort-modeling-tutorial-intro"
doi: 10.5281/zenodo.5223092
identifiers:
- type: doi
value: 10.5281/zenodo.5223092
description: Zenodo concept DOI (resolves to the latest version)
keywords:
- cohort state-transition model
- Markov model
- cost-effectiveness analysis
- decision analysis
- within-cycle correction
- R
authors:
- family-names: Alarid-Escudero
given-names: Fernando
email: falarid@stanford.edu
- family-names: Krijkamp
given-names: Eline
orcid: "https://orcid.org/0000-0003-3970-2205"
- family-names: Enns
given-names: Eva A.
orcid: "https://orcid.org/0000-0003-0693-7358"
- family-names: Yang
given-names: Alan
- family-names: Hunink
given-names: M.G. Myriam
orcid: "https://orcid.org/0000-0002-2942-2798"
- family-names: Pechlivanoglou
given-names: Petros
orcid: "https://orcid.org/0000-0001-5090-7936"
- family-names: Jalal
given-names: Hawre
orcid: "https://orcid.org/0000-0002-8224-6834"
preferred-citation:
type: article
title: >-
An Introductory Tutorial on Cohort State-Transition Models in R Using a
Cost-Effectiveness Analysis Example
journal: Medical Decision Making
year: 2023
volume: 43
issue: 1
start: 3
end: 20
doi: 10.1177/0272989X221103163
authors:
- family-names: Alarid-Escudero
given-names: Fernando
- family-names: Krijkamp
given-names: Eline
orcid: "https://orcid.org/0000-0003-3970-2205"
- family-names: Enns
given-names: Eva A.
orcid: "https://orcid.org/0000-0003-0693-7358"
- family-names: Yang
given-names: Alan
- family-names: Hunink
given-names: M.G. Myriam
orcid: "https://orcid.org/0000-0002-2942-2798"
- family-names: Pechlivanoglou
given-names: Petros
orcid: "https://orcid.org/0000-0001-5090-7936"
- family-names: Jalal
given-names: Hawre
orcid: "https://orcid.org/0000-0002-8224-6834"
47 changes: 47 additions & 0 deletions DESCRIPTION
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
Type: Project
Package: cohortModelingTutorialIntro
Title: R Code for An Introductory Tutorial on Cohort State-Transition Models in R
Version: 0.3.0
Date: 2026-11-10
Authors@R: c(
person("Fernando", "Alarid-Escudero", email = "falarid@stanford.edu",
role = c("aut", "cre")),
person("Eline", "Krijkamp", role = "aut",
comment = c(ORCID = "0000-0003-3970-2205")),
person("Eva A.", "Enns", role = "aut",
comment = c(ORCID = "0000-0003-0693-7358")),
person("Alan", "Yang", role = "aut"),
person("M.G. Myriam", "Hunink", role = "aut",
comment = c(ORCID = "0000-0002-2942-2798")),
person("Petros", "Pechlivanoglou", role = "aut",
comment = c(ORCID = "0000-0001-5090-7936")),
person("Hawre", "Jalal", role = "aut",
comment = c(ORCID = "0000-0002-8224-6834")))
Description: Code accompanying Alarid-Escudero et al. (2023)
<doi:10.1177/0272989X221103163>, which shows how to implement a
time-independent cohort state-transition model (cSTM) of the Sick-Sicker
model in R and use it for a cost-effectiveness analysis, including
within-cycle correction, probabilistic sensitivity analysis and
value-of-information analysis. This file records the project version and
dependencies; the repository is not an installable R package.
License: MIT + file LICENSE
URL: https://github.com/DARTH-git/cohort-modeling-tutorial-intro
BugReports: https://github.com/DARTH-git/cohort-modeling-tutorial-intro/issues
Depends:
R (>= 4.1.0)
Imports:
data.table,
dplyr,
ellipse,
ggplot2 (>= 3.4.0),
ggrepel,
ggthemes,
reshape2,
scales,
stringr,
tidyr
Suggests:
rmarkdown,
testthat (>= 3.0.0)
Config/testthat/edition: 3
Encoding: UTF-8
126 changes: 126 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
# cohort-modeling-tutorial-intro 0.3.0 (2026-11-10)

This release fixes a bug in the Simpson's 1/3rd within-cycle correction (WCC).
**It changes the numerical results reported in the published article**, but
not its conclusions.

## Bug fixes

* `gen_wcc(method = "Simpson1/3")` (`R/Functions.R`) assigned the 4/3 and 2/3
weights by position in the 1-based R vector instead of by time
t = 0, 1, ..., n. It returned `1/3, 2/3, 4/3, 2/3, ..., 1/3` instead of
`1/3, 4/3, 2/3, 4/3, ..., 1/3`, so the weights summed to n - 2/3 instead
of n. For example, `gen_wcc(4)` integrated f(t) = 1 over [0, 4] as 3.33
instead of 4. Weights are now indexed by time (closes #2).

The same error is in the WCC description, the equation and the
`within-cycle-vector` code chunk of the published manuscript. The files in
`manuscript/` are kept unchanged as the archival source of the article (see
`manuscript/README.md`).

Effect on the base case of the time-independent Sick-Sicker model
(`analysis/cSTM_time_indep.R`, 75 annual cycles, 3% discount):

| Strategy | QALYs v0.2.1 | QALYs v0.3.0 | Costs v0.2.1 | Costs v0.3.0 | ICER v0.2.1 | ICER v0.3.0 |
|------------------|-------------:|-------------:|-------------:|-------------:|------------:|------------:|
| Standard of care | 20.71 | 21.03 | $151,580 | $152,282 | -- | -- |
| Strategy B | 22.18 | 22.50 | $259,100 | $260,222 | $72,988 | $73,279 |
| Strategy AB | 23.14 | 23.46 | $378,875 | $380,378 | $125,764 | $125,302 |
| Strategy A | 21.50 | 21.83 | $284,805 | $285,889 | Dominated | Dominated |

QALYs increase by about 0.32 per strategy and ICERs change by about 0.4%.
The efficient frontier and the dominance of Strategy A are unchanged.

* The PSA model wrapper (`calculate_ce_out()` in
`R/Functions_cSTM_time_indep.R`) now uses the corrected local `gen_wcc()`.
It used to call `darthtools::gen_wcc()`, which has the same bug in
darthtools <= 0.4.0. The deterministic and probabilistic analyses now use
the same WCC, and the repository no longer needs `darthtools`.

* `calculate_ce_out()` had the discount rates swapped: costs were discounted
with `d_e` and QALYs with `d_c`. This had no effect on the results because
both rates are 3%, but it would have mattered for differential discounting.

* In `analysis/cSTM_time_indep.R`, the state costs under Strategy A
(`v_c_strA`) were not scaled by `cycle_length`, unlike every other reward
vector. This had no effect with annual cycles but would have mattered with
monthly cycles.

## Changes in behaviour

* `gen_wcc(method = "Simpson1/3")` now supports an odd number of cycles, like
the tutorial's 75 cycles. Simpson's 1/3rd rule needs an even number of
intervals, so for odd `n_cycles` the composite 1/3 rule is applied over the
first n - 3 cycles and Simpson's 3/8 rule over the last three. Both cases
integrate polynomials up to degree three exactly, and the weights always
sum to `n_cycles`.
* `gen_wcc()` validates its input. It now errors when `n_cycles` is not a
single positive integer (it used to truncate, e.g., 7.5 to 7) and when
`n_cycles = 1` is used with Simpson's rule.

## Infrastructure and reproducibility

* Added unit tests (`tests/testthat/`) for `gen_wcc()`: exact weights, exact
integration of polynomials of degree 0-3 for odd and even n, and input
validation. Added a regression test for the base-case CEA. Run them with
`testthat::test_dir("tests/testthat")`.
* Added a GitHub Actions workflow (`.github/workflows/check.yaml`). It runs the
tests and the full tutorial analysis on Ubuntu and macOS for every push and
pull request.
* Added `renv` (`renv.lock`) to pin package versions. Run `renv::restore()` to
reproduce the computational environment.
* Added a `DESCRIPTION` file that records the project version and
dependencies (the repository is not an installable package).
* Added `CITATION.cff` with all authors and the preferred citation (the MDM
article). This enables GitHub's "Cite this repository" button and complete
Zenodo metadata.
* Added this `NEWS.md` changelog.
* Replaced deprecated `ggplot2` arguments (`size` -> `linewidth` in
`geom_line()`, `..density..` -> `after_stat(density)`).
* Removed a stray, unnamed copy of `rate_to_prob()` from `R/Functions.R`.

## Documentation

* Rewrote the `gen_wcc()` documentation to describe the weights by time
("entries at odd times t = 1, 3, ... get 4/3") and to document the odd-n
extension.
* Updated and expanded the README: a corrections notice, quick start with
`renv`, repository structure, testing, how to report issues, and fixed
typos and citation details (including the Zenodo DOIs).
* Added `manuscript/README.md` explaining how the archival manuscript sources
differ from the corrected code.

## Acknowledgements

This bug was found by two attentive users of the tutorial, and we are very
grateful to both:

* **Lauren N. Steimle** (H. Milton Stewart School of Industrial and Systems
Engineering, Georgia Institute of Technology) found the indexing error while
preparing lecture notes on within-cycle corrections for her graduate course.
She reported it by email in January 2025, with a proposed correction.
* **[@ambtnhlr](https://github.com/ambtnhlr)** independently reported the same
error in #2. The report included a reproducible example showing that the
weights did not integrate a constant correctly, a time-indexed fix, a
suggested rewording of the documentation, and the observation that 75
cycles is an odd number of intervals for Simpson's 1/3rd rule.

Their careful reports made this release possible.

# cohort-modeling-tutorial-intro 0.2.1 (2022-03-31)

* Second Zenodo release (DOI: 10.5281/zenodo.6400119), accompanying the
revised manuscript accepted in *Medical Decision Making*.
* Code, manuscript text and references were updated in response to peer
review. Rewards are scaled by `cycle_length` throughout.
* Added `rate_to_prob()`, `gen_wcc()` and the transition-matrix checks from
`darthtools` to `R/Functions.R`, so the tutorial runs without `darthtools`.
* Added the matrix-algebra appendix.

# cohort-modeling-tutorial-intro 0.1.1 (2021-08-19)

* First Zenodo release (DOI: 10.5281/zenodo.5223093).

# cohort-modeling-tutorial-intro 0.1.0 (2021-08-19)

* First public release, accompanying the submitted manuscript.
Loading
Loading