RMSTpowerBoost: Interactive Power and Sample Size Calculator

This repository documents and assembles the RMSTpowerBoost Shiny application as an engineering system.
This README is for contributors and maintainers: architecture, module boundaries, data flow, and quality wiring.

---

Purpose and Audience

• Audience: maintainers extending modeling methods, simulation logic, reporting, and QA/CI integration.
• Scope: internal system structure and component interactions.
• Out of scope: end-user operation and launch walkthroughs.

---

Repository Architecture

• app.R: single-file Shiny shell, UI layout, server orchestration, validation, report hooks, and integration with method engines.
• R/: modeling and simulation engines (analytical engines and their shared estimation helpers, recipe simulator, recipe set generation/loading).
• data/: packaged datasets consumed by app methods and tests.
• data-raw/: source material and scripts used to regenerate bundled data assets.
• tests/testthat/: coverage harness and targeted simulation/branch correctness tests.
• .github/workflows/: CI automation for coverage upload and package sync.
• coverage/: locally generated coverage artifacts; CI generates its own report for every commit.
• tools/: local engineering utilities (for example, coverage artifact generation/upload helper).
• codecov.yml: Codecov policy (thresholds, precision, rounding, ignore patterns).
• DESCRIPTION and NAMESPACE: package metadata/imports and exported function surface.

---

Application Composition (app.R)

app.R is a coordinator layer around method modules in R/:

• Package loading guard: validates all required UI/report/data packages before app object creation.
• Repo-root guard: verifies execution context is the repository root/workspace and resolves app-relative paths.
• Dynamic module loading: sources all R/*.R files at startup so method engines are available to the server layer.
• Helper/validation layer: coercion and schema guards for time/status/arm inputs, formatting helpers, plotting adapters, and UI reset helpers.
• UI assembly: central fluid-page layout with method selection, data source controls, diagnostics, plots, tables, and report export controls.
• Server orchestration: state management (reactiveValues), input/event handlers, method dispatch, diagnostics execution, and rendering.
• Report generation hooks: inline report template construction and HTML/PDF export paths integrated with computed results.

Design note: app.R intentionally keeps orchestration in one file and delegates statistical computation/simulation to dedicated files under R/.

---

Core Engine Modules (R/)

Method families

• R/linear_ipcw_analytical_app.R
  • linear IPCW analytical power/sample-size functions.
• R/additive_stratified_analytical_app.R
  • additive stratified analytical functions.
• R/multiplicative_stratified_analytical_app.R
  • multiplicative stratified analytical method implementations.
• R/dependent_censoring_analytical_app.R
  • dependent-censoring analytical estimation and power/sample-size functions.
• R/estimation_helpers_app.R
  • shared machinery: data preparation, Cox censoring weights, the Wald power formula, the sample-size search, and plotting.

The estimators, censoring weights and power formulas are ported from the RMSTpowerBoost package (R/estimation-helpers.R), so for the same pilot data the app and the package give identical estimates, power and required sample sizes. IPCW weights come from conditional Cox censoring models and are used as fitted, with no cap or floor. The power functions take a test argument with the package defaults: the weighted-least-squares t-test for the linear and dependent-censoring models, and the sandwich Wald test for the multiplicative model. The additive model has a single sandwich Wald test.

The Repeated calculation method resamples the pilot data inside app.R (repeated_power_from_pilot) and reuses the .estimate_*_params helpers of the selected model, so both methods share one estimator per model. Each replicate applies the same test the Analytical method reports, so the two agree within Monte Carlo error. The two-arm models resample per arm; the stratified models resample per stratum with arms pooled, so N is per stratum in both methods.

Simulation and recipe infrastructure

• R/recipe_sim.R
  • recipe validation, covariate generation, treatment assignment, linear predictor construction, survival-time simulation, and convenience recipe constructors.
• R/generate_sets.R
  • recipe grid/set expansion and metadata collection for reusable simulation suites.
• R/load_sets.R
  • manifest loading and manifest rebuild utilities for recipe-set assets.

Exported API surface (high-level)

Exports (from NAMESPACE) are grouped as:

• Analytical power and sample-size methods:
  • linear.power.analytical.app, linear.ss.analytical.app
  • additive.power.analytical.app, additive.ss.analytical.app
  • MS.power.analytical.app, MS.ss.analytical.app
  • DC.power.analytical.app, DC.ss.analytical.app
• Simulation and recipe APIs:
  • simulate_from_recipe, validate_recipe, recipe_quick_aft, recipe_grid
  • generate_recipe_sets, load_recipe_sets, rebuild_manifest
• Internal estimators exposed for package-level composition:
  • .estimate_*_params

---

Data and Control Flow

1. Source selection:

• server receives either uploaded pilot data or simulated data definitions.

2. Schema and cleaning validation:

• type coercion/consistency checks are applied (time/status/arm and covariate structures).
• missingness and compatibility checks gate method execution.

3. Model selection and parameter assembly:

• server builds method-specific parameter objects from UI + data context.
• covariate definitions and allocation settings are normalized for engines.

4. Engine invocation:

• app.R dispatches to R/ modules:
  • simulation path: simulate_from_recipe(...)
  • method paths: *.power.analytical.app / *.ss.analytical.app functions across linear/additive/multiplicative/dependent-censoring families, and the model-aware repeated_power_from_pilot resampling method
  • diagnostics path: inline log-rank/KM summary in app.R

5. Result materialization:

• tabular summaries, figures, diagnostics objects, and downloadable report payloads are created.

6. Report export:

• report inputs are assembled, inline template is rendered, and HTML/PDF outputs are generated from computed state.

Recipe-set path:

• sets are generated with generate_recipe_sets(...) / recipe_grid(...), persisted with metadata, then loaded with load_recipe_sets(...) for simulation execution.

---

Testing and Quality Map

• tests/testthat/test-coverage-app.R
  • app harness and broad integration coverage paths.
• tests/testthat/test-coverage-targeted.R
  • targeted branch and edge-condition coverage for high-risk logic.
• tests/testthat/test-recipe-sim.R
  • recipe simulation correctness and invariants for synthetic data generation.

Coverage policy context (codecov.yml):

• project and patch status thresholds are enabled (target: auto, threshold: 1%).
• precision/rounding are configured (precision: 2, round: down).
• selected paths are excluded (for example renv/**, rsconnect/**, and data-generation-specific files).

---

Coverage and Codecov Artifacts

Artifacts generated in coverage/:

• coverage/cobertura.xml
• coverage/coverage.rds
• coverage/summary.txt

Local artifact generation/upload helper:

source("tools/run_codecov_local.R")

Workflow behavior in .github/workflows/codecov_sync.yml:

• On every push to main and every pull request, CI installs the dependencies listed in DESCRIPTION, runs covr::package_coverage(), and writes a fresh coverage/cobertura.xml.
• CI uploads that fresh report to Codecov using repository secret CODECOV_TOKEN.
• CI never uploads the committed coverage/ files. Codecov discards a report whose timestamp is more than 12 hours old, so re-uploading a committed report records 0% for the new commit.
• The renv autoloader is disabled in CI (RENV_CONFIG_AUTOLOADER_ENABLED=false), and .Rprofile skips its git pull when the CI variable is set.

---

External References

• Live application: https://arnab96.shinyapps.io/uthsc-app/
• RMSTpowerBoost package docs/source: https://uthsc-zhang.github.io/RMSTpowerBoost-Package/articles/RMSTpowerBoost-Main.html
• Project issues: https://github.com/UTHSC-Zhang/RMSTpowerBoost-Package/issues