Skip to content

Vignette overhaul and "Get started" vignette #216

Open

Description

@feralaes

Suggested owner: Eva Enns (an author and a second reviewer per vignette) · Plan: Phase 4

Goal

Vignettes that teach the methods correctly and build quickly. Fix the errors the audit found.

Scope

  • New vignettes/dampack.Rmd ("Get started"): a 5-minute end-to-end example covering ICERs, the PSA object, CEAC/ELC and EVPI. It becomes the pkgdown "Get started" page.
  • Reading order: Get started → basic_cea → psa_analysis → voi → psa_generation → dsa_generation.
  • Every vignette:
    • Learning objectives.
    • Methods with formulas: dominance, extended dominance, ICER, NMB/NHB, CEAC versus ELC and the frontier, EVPI/EVPPI/EVSI with the metamodel approach.
    • Interpretation.
    • References from a shared vignettes/references.bib.
    • set.seed() and DARTH naming in the example code.
  • Fix the audit's errors:
    • basic_cea: says the class is "icer" (it is icers); says "cdiff_psa" (the data is psa_cdiff); has an icer_diff typo; never shows print.icers or calculate_icers_psa.
    • psa_analysis:
      • The NMB/NHB formula text says "added to" where it should say subtracted.
      • The tornado text describes a median split, but the code uses the range min/max.
    • psa_generation:
      • Points to the wrong vignette.
      • Relies on partial argument matching (n = 100, effect =).
      • Says "Effect" where it should say "QALY".
      • Ends without any analysis.
    • dsa_generation: l_twsa_det$owsa_NMB typo; add the tornado diagram (Add tornado diagram as additional visualization to OWSA vignette #185).
    • voi: wrong help links ?make_psa_object and ?calculate_outcomes; says "adjusted r-squared" but lm reports the unadjusted value; cite Strong et al. 2014 in the vignette text.
  • Remove the unreferenced vignettes/icer_cdiff.png (186 KB) and vignettes/cdiff_icers.csv.
  • Speed: cut the 10,000-sample metamodel runs, or move heavy material to pkgdown-only articles (vignettes/articles/, build-ignored).
  • Close Resolve scope of DSA vignettes #147: dsa_visualization no longer exists. File a v1.2 issue for a "bring your own DSA data" section.

Acceptance

  • All vignettes build from a clean install, without load_all, in under 2 minutes total.
  • Each vignette has been reviewed by someone other than its author.

Activity

  1. added this to the v1.1.0 milestone on Nov 12, 2026
  2. feralaes commented on Nov 12, 2026

    @feralaes
    CollaboratorAuthor

    Found while debugging a flaky CI failure (PR #230 adds a seed as a stopgap). In psa_generation.Rmd, the example model samples the competing transitions out of Sick independently: p_S1H ~ Beta(12, 12) (to Healthy) and p_S1S2 ~ Beta(15, 133) (to Sicker). Their sum can exceed 1 (about 1 in 100,000 samples, so about 1 vignette build in 300). The S1→S1 entry (1 - p_S1D) * (1 - (p_S1H + p_S1S2)) is then negative and the model stops with "This is not a valid transition matrix".

    Since the vignette teaches PSA generation, it may be worth showing the more defensible approach as part of the overhaul. Options:

    • Dirichlet: sample the exits from Sick jointly with a Dirichlet distribution. gen_psa_samp() already supports "dirichlet".
    • Rates: parameterize the two exits as rates and convert them to probabilities with competing risks.

    This is a content decision, so I've left it for the vignette work.

  3. feralaes commented on Nov 12, 2026

    @feralaes
    CollaboratorAuthor

    @evaenns, here is a summary of the v1.1.0 items that are yours, so you can pick them up when you have time. Target: everything merged by the Dec 4 feature freeze (CRAN submission is planned for about Dec 11).

    Vignettes (this issue, #216)

    Two small checks from #205

    • ?cancer_psa_data (R/data_cancer_psa_data.R): please confirm the parameter descriptions (pFailChemo, pDieSurg, muDieCancer, …). They were written from the parameter names.
    • PSA vignette title (vignettes/psa_analysis.Rmd): the YAML title is "Probabilistic Sensitivity Analysis", but line 7's \VignetteIndexEntry{} still says "Probabilistic Sensitivity Analysis: Analysis". pkgdown warns about the mismatch, so please choose one.

    Related issues where you're the suggested owner

    Workflow reminder (details in CONTRIBUTING): one branch per issue from main, a PR into main with Closes #<issue>, and one approving review. The rendered site, including the current vignettes, is at https://darth-git.github.io/dampack/.

  4. added a commit that references this issue on Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationVignettes, Rd, README, NEWS, paper

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions