update vignettes after "gbsg superseded"

Author: larry-leon

NEWS.md

@@ -5,42 +5,42 @@
 ### New functions
 
 * `generate_aft_dgm_flex()` — general data-generating model (DGM) builder.
-  Replaces the GBSG-specific `create_gbsg_dgm()` as the primary DGM
-  constructor. Accepts any survival dataset and fits an accelerated failure
-  time (AFT) super-population model with user-specified treatment effect
-  heterogeneity parameters.
+  Accepts any survival dataset and fits an accelerated failure time (AFT)
+  super-population model with user-specified treatment effect heterogeneity
+  parameters. This is the recommended starting point when building a DGM
+  based on a dataset other than GBSG.
 
 * `simulate_from_dgm()` — general simulator for drawing trial replicates from
-  an `aft_dgm_flex` DGM. Replaces `simulate_from_gbsg_dgm()`. Column names
-  in the returned data frame use underscore notation (`y_sim`, `event_sim`,
-  `treat_sim`, `flag_harm`).
+  an `aft_dgm_flex` DGM. Supersedes `simulate_from_gbsg_dgm()` for new code.
+  Column names in the returned data frame use underscore notation (`y_sim`,
+  `event_sim`, `treat_sim`, `flag_harm`).
 
 * `run_simulation_analysis()` (general version) — simulation wrapper that
   calls `simulate_from_dgm()` and accepts explicit column-name parameters,
-  making it applicable to any DGM built with `generate_aft_dgm_flex()`. The
-  GBSG dataset is now one application of this general pipeline rather than a
-  separate code path.
-
-* `setup_gbsg_dgm()` — convenience bridge function. Wraps
-  `create_gbsg_dgm()` (see Deprecated below) and reshapes its output to the
-  `aft_dgm_flex` class expected by `simulate_from_dgm()` and
-  `run_simulation_analysis()`. Existing GBSG-based simulation scripts can
-  adopt the general pipeline with a one-line change:
+  making it applicable to any DGM built with `generate_aft_dgm_flex()` or
+  `setup_gbsg_dgm()`. The GBSG dataset is one application of this general
+  pipeline rather than a separate code path.
+
+* `setup_gbsg_dgm()` — the recommended entry point for all GBSG-based
+  simulation work. Encodes the data preparation and subgroup definition from
+  León et al. (2024) and returns an `aft_dgm_flex`-compatible object accepted
+  by `simulate_from_dgm()` and `run_simulation_analysis()`. Existing scripts
+  using `create_gbsg_dgm()` can migrate with a one-line change:
   `dgm <- setup_gbsg_dgm(model = "alt", k_inter = k, seed = seed)`.
 
-### Deprecated functions
+### Superseded functions
 
-The following functions are retained and fully functional but will be removed
-in a future version. Each emits a deprecation warning on first call with a
-concrete migration example.
+`create_gbsg_dgm()` is superseded by `setup_gbsg_dgm()`. It remains fully
+functional and continues to produce correct results; no existing GBSG
+simulation scripts need to change. The distinction is that `setup_gbsg_dgm()`
+returns an object of class `c("aft_dgm_flex", "gbsg_dgm")` compatible with
+the general pipeline, whereas `create_gbsg_dgm()` returns only `"gbsg_dgm"`.
+A `.Deprecated()` signal is emitted to encourage migration in new code.
 
-* `create_gbsg_dgm()` → use `generate_aft_dgm_flex()` or `setup_gbsg_dgm()`.
-
-* `simulate_from_gbsg_dgm()` → use `simulate_from_dgm(analysis_time = Inf)`.
-  Note: the new function defaults to `analysis_time = 48` (staggered-entry
-  administrative censoring); pass `analysis_time = Inf` to match the legacy
-  `max_follow = Inf` behaviour. Column names in the result also change — see
-  the mapping table below.
+`simulate_from_gbsg_dgm()` is superseded by `simulate_from_dgm()` for new
+code. Column names in the output change from dot-notation to underscore
+notation — see the mapping table below. Pass `analysis_time = Inf` to match
+the legacy `max_follow = Inf` behaviour.
 
   | Legacy column | General column |
   |---------------|----------------|
@@ -49,13 +49,13 @@ concrete migration example.
   | `treat`       | `treat_sim`    |
   | `flag.harm`   | `flag_harm`    |
 
-### Deprecated parameters
+### Superseded parameters
 
 * `run_simulation_analysis(max_follow)` → use `analysis_time`. If supplied,
-  `max_follow` is silently forwarded to `analysis_time` with a warning.
+  `max_follow` is forwarded to `analysis_time` with a warning.
 
 * `run_simulation_analysis(muC_adj)` → use `cens_adjust`. If supplied,
-  `muC_adj` is silently forwarded to `cens_adjust` with a warning.
+  `muC_adj` is forwarded to `cens_adjust` with a warning.
 
 ### Bug fixes
 
@@ -92,9 +92,9 @@ migration. All affected code paths were exercised by GBSG factor variables
 
 * `create_gbsg_dgm()` and `simulate_from_gbsg_dgm()` are now thin public
   wrappers that call `.create_gbsg_dgm_()` and `.simulate_from_gbsg_dgm_()`
-  internally. This prevents deprecation-warning spam in functions that call
-  these internally in loops or binary searches (`calibrate_k_inter()`,
-  `get_dgm_with_output()`, `validate_k_inter_effect()`).
+  internally. This prevents warning spam in functions that call these
+  in loops or binary searches (`calibrate_k_inter()`, `get_dgm_with_output()`,
+  `validate_k_inter_effect()`).
 
 * `compute_dgm_cde()` now resolves the super-population data frame from
   `dgm$df_super_rand` (GBSG DGMs) or `dgm$df_super` (general `aft_dgm_flex`

R/setup_gbsg_dgm.R

@@ -64,7 +64,6 @@
 #' sim <- simulate_from_dgm(dgm, n = 400, seed = 1)
 #' }
 #'
-#' @importFrom survival gbsg
 #' @export
 setup_gbsg_dgm <- function(
     model           = c("alt", "null"),

dev/devtools_package.R

@@ -144,7 +144,6 @@ devtools::install(quick = TRUE)
 
 devtools::install(dependencies = FALSE)
 
-
 # In RStudio, from the forestsearch project directory:
 devtools::clean_dll()
 devtools::document()

vignettes/articles/extreme_subgroups.Rmd

@@ -34,7 +34,7 @@ knitr::opts_chunk$set(
 
 # Number of null-DGM simulated trials — the primary result quantity
 # Set to>= 1000 for publication-quality results
-n_sims_null <- 99L  
+n_sims_null <- 133L  
 
 
 ```