improved help documentation

Author: n8thangreen

R/blendsurv.R

@@ -9,13 +9,13 @@
 #' @param obs_Surv,ext_Surv Observed and external data survival curves.
 #'    These can come from \pkg{survHE}, \pkg{INLA} or \pkg{flexsurv} fits.
 #' @param blend_interv Maximum and minimum values for the blending interval.
-#' @param beta_params coefficients of a beta distribution
+#' @param beta_params Coefficients of a beta distribution.
 #' @param times A vector of times for which the survival curves
-#'              are to be computed; optional
+#'              are to be computed; optional.
 #' @param nsim The number of simulations from the distribution of
-#'             the survival curves; default 100
+#'             the survival curves; default 100.
 #'
-#' @return List of S for observed, external and blended curves.
+#' @return List of survival probabilities for observed, external and blended curves, with other relevant data.
 #' @importFrom stats pbeta
 #' @export
 #'
@@ -30,22 +30,25 @@
 #' data_sim <- ext_surv_sim(t_info = 144,
 #'                          S_info = 0.05,
 #'                          T_max = 180)
-#'
+#' # observed survival times
 #' obs_Surv <- fit.models(formula = Surv(death_t, death) ~ 1,
 #'                        data = dat_FCR,
 #'                        distr = "exponential",
 #'                        method = "hmc")
 #'
+#' # external survival times
 #' ext_Surv <- fit.models(formula = Surv(time, event) ~ 1,
 #'                        data = data_sim,
 #'                        distr = "exponential",
 #'                        method = "hmc")
 #'
+#' # blending parameter values
 #' blend_interv <- list(min = 48, max = 150)
 #' beta_params <- list(alpha = 3, beta = 3)
 #'
 #' ble_Surv <- blendsurv(obs_Surv, ext_Surv, blend_interv, beta_params)
 #'
+#' # all survival curves
 #' plot(ble_Surv)
 #'
 blendsurv <- function(obs_Surv, ext_Surv,

R/ext_surv_sim.R

@@ -1,29 +1,53 @@
 
 #' Create an external survival data based on expert opinion
 #'
-#' Generally, the sampling is done is two steps
+#' @description
+#' Generates an individual patient-level survival dataset from aggregate survival
+#' probabilities that might be elicited from expert opinion.
+#'
+#' The function creates a synthetic dataset of event times for `n` patients,
+#' consistent with a piecewise-constant hazard rate implied by the expert-provided
+#' survival probabilities.
+#'
+#' @details
+#' The simulation uses a two-step sampling process based on partitioning the time
+#' horizon from `0` to `T_max`. First, the total number of patients `n` is
+#' allocated to different time intervals `[t_i, t_{i+1}]`. The probability of an
+#' event occurring in an interval is derived from the drop in the survival curve
+#' over that interval. This allocation is done via a multinomial distribution:
 #' \deqn{
-#'    p(T) = p(T | interval i) p(interval i)
+#'     i \sim \text{Multinomial}(\pi)
 #' }
+#' where $\pi_i = S(t_{i-1}) - S(t_i)$ is the probability of an event in interval `i`.
 #'
-#' In particular
-#' \eqn{T ~ U(x_{i}, x_{i+1})}
-#' \eqn{i ~ multinomial(\hat{\pi})}
+#' Second, for the patients assigned to each interval, a specific event time is
+#' simulated from a uniform distribution covering that interval:
+#' \deqn{
+#'     T | i \sim U(t_{i-1}, t_i)
+#' }
 #'
-#' @param t_info A vector of times for which expert opinion is elicited
-#' @param S_info A vector of mean survival probabilities estimated by experts
-#'               corresponding to time points in `t_info`
-#' @param T_max  The maximum survival time to be used
-#' @param n      The number of patients to construct the artificial external data set; default 100
+#' @param t_info A numeric vector of time points for which expert opinion is elicited.
+#' @param S_info A numeric vector of mean survival probabilities estimated by experts
+#'               corresponding to time points in `t_info`.
+#' @param T_max  The maximum survival time for the simulation, at which the
+#'   survival probability is assumed to be 0.
+#' @param n      The total number of patients to construct the artificial external data set; default 100
 #' @importFrom stats runif rmultinom
-#' @return Dataframe of times and censoring status
+#'
+#' @return A data frame with `n` rows and two columns:
+#'   \itemize{
+#'     \item **time**: The simulated event time for each patient.
+#'     \item **event**: The event indicator, which is always `1` as this function does not simulate censoring.
+#'   }
+#'
 #' @export
 #'
 #' @examples
 #' dat <- ext_surv_sim(t_info = c(10,20,50),
 #'                     S_info = c(0.9, 0.8, 0.2),
 #'                     T_max = 100, n = 100)
 #' if (require(survival)) {
+#'     # Kaplan-Meier curve
 #'     km_fit <- survfit(Surv(time, event) ~ 1, data = dat)
 #'     plot(km_fit)
 #' }

R/fit_inla_pw.R

@@ -1,22 +1,50 @@
 
-#' Generate survival estimates with a piecewise exponential Cox model (using INLA)
+#' Fit a Piecewise Exponential Survival Model using INLA
 #'
-#' @param inla.formula The formula for PEM which must be an `inla.surv` object
-#' @param data A dataframe for survival data with time (`death_t`) and
-#'    event (`death`)
-#' @param cutpoints A sequence of cut points for intervals in the baseline hazard
-#' @param nsim The number of simulations from posteriors; default 100
-#' @param ... Additional arguments
+#' @description
+#' A convenience wrapper to fit a Bayesian piecewise exponential model (PEM) for
+#' survival data using the `INLA` package. This function simplifies the process by
+#' automatically handling the necessary data transformation from a standard
+#' survival format to the Poisson regression format that `INLA` requires.
+#'
+#' @details
+#' This function models the baseline hazard rate as a piecewise constant function.
+#' The `cutpoints` define the time intervals within which the hazard is assumed
+#' to be constant.
+#'
+#' Internally, the function first uses `INLA::inla.coxph` to convert the survival
+#' data into the long format suitable for a Poisson generalized linear model (GLM).
+#' It then fits this model using `INLA::inla`, applying a random walk of order 1
+#' (`rw1`) prior to the log-hazards for each interval. This prior provides a
+#' flexible and smoothed estimate of the baseline hazard over time.
+#'
+#' @param inla.formula A formula specifying the survival model. The response must
+#'   be an `INLA::inla.surv` object (e.g., `inla.surv(time, event)`). The right-hand
+#'   side specifies the linear predictor. The default fits a baseline-hazard-only model.
+#' @param data A data frame containing the time-to-event data, including the
+#'   variables named in the `inla.formula`.
+#' @param cutpoints A numeric vector of cut points used to partition the time
+#'   axis into intervals for the piecewise constant hazard.
+#' @param ... Additional arguments to be passed directly to the `INLA::inla`
+#'   function (e.g., `control.predictor`, `control.family`).
+#'
+#' @return An object of class `inla`, which contains the full results of the
+#'   fitted Bayesian model.
 #'
-#' @return INLA object
 #' @export
 #'
 #' @examples
 #' \donttest{
+#' # INLA may require configuration on your system.
+#' # See: https://www.r-inla.org/download-install
 #'  if (requireNamespace("INLA", quietly = TRUE)) {
 #'   data("TA174_FCR", package = "blendR")
 #'   head(dat_FCR)
+#'
+#'   # Fit a simple piecewise model with intervals every 5 time units
 #'   obs_Surv <- fit_inla_pw(data = dat_FCR, cutpoints = seq(0, 180, by = 5))
+#'
+#'   # summary(obs_Surv)
 #'  }
 #' }
 #'

R/make_surv.R

@@ -2,39 +2,118 @@
 #' @title Create survival probabilities
 #' @name make_surv_methods
 #'
-#' @description These function are version of the [survHE::make.surv()] function
-#'    from \pkg{survHE}. These are needed prior to blending.
+#' @description
+#' A generic S3 function and methods to generate a standardized matrix of survival
+#' probabilities from various fitted survival model objects.
+#'
+#' This function standardizes the output from different survival modelling packages
+#' into a consistent format: a matrix where rows represent discrete time points
+#' and columns represent simulations from the model's posterior distribution. This
+#' standardized format is essential for use in downstream evidence blending
+#' functions. The methods are inspired by the [survHE::make.surv()] function.
+#'
+#' @param Surv A fitted survival model object or a matrix/vector of survival
+#'   probabilities. Supported classes include `survHE`, `flexsurvreg`, `inla`,
+#'   `matrix`, and `numeric`.
+#' @param ... Additional arguments passed to specific methods (e.g., `t`, `nsim`).
+#' @return A matrix with `length(t)` rows and `nsim` columns. Each element `[i, j]`
+#'   is the survival probability at time `t[i]` for simulation `j`.
+#'
+#' @seealso [survHE::make.surv()]
 #'
-#' @param Surv  survival analysis object
-#' @param ... Additional arguments
-#' @return Matrix of survival probabilities
 #' @export
 #'
-#' @examplesIf rlang::is_installed("survHEhmc")
-#' library(survHE)
+#' @examples
+#' # Define common time points and number of simulations for examples
+#' time_points <- 1:100
+#' n_sim <- 50
+#'
+#' #--------------------------------------
+#' ## Method for a 'survHE' object
+#' #--------------------------------------
+#' if (rlang::is_installed("survHE") && rlang::is_installed("survival")) {
+#'   library(survHE)
+#'   library(survival)
+#'   data(ovarian)
+#'
+#'   # Fit a Weibull model using survHE (with MLE for speed)
+#'   fit_she <- fit.models(
+#'     formula = Surv(futime, fustat) ~ 1,
+#'     data = ovarian,
+#'     distr = "weibull",
+#'     method = "mle"
+#'   )
+#'
+#'   # Generate survival probability matrix
+#'   surv_matrix_she <- make_surv(fit_she, t = time_points, nsim = n_sim)
+#'   cat("survHE method output dimensions:", dim(surv_matrix_she), "\n")
+#' }
+#'
+#' #--------------------------------------
+#' ## Method for a 'flexsurvreg' object
+#' #--------------------------------------
+#' if (rlang::is_installed("flexsurv") && rlang::is_installed("survival")) {
+#'   library(flexsurv)
+#'   library(survival)
+#'
+#'   # Fit a log-logistic model using flexsurv
+#'   fit_fsr <- flexsurvreg(
+#'     formula = Surv(futime, fustat) ~ 1,
+#'     data = ovarian,
+#'     dist = "llogis"
+#'   )
 #'
-#' ## trial data
-#' data("TA174_FCR", package = "blendR")
+#'   # Generate survival probability matrix
+#'   surv_matrix_fsr <- make_surv(fit_fsr, t = time_points, nsim = n_sim)
+#'   cat("flexsurvreg method output dimensions:", dim(surv_matrix_fsr), "\n")
+#' }
 #'
-#' ## externally estimated data
-#' data_sim <- ext_surv_sim(t_info = 144,
-#'                          S_info = 0.05,
-#'                          T_max = 180)
+#' #--------------------------------------
+#' ## Default method for a numeric vector (e.g., from a Kaplan-Meier curve)
+#' #--------------------------------------
+#' if (rlang::is_installed("survival")) {
+#'   library(survival)
+#'   km_fit <- survfit(Surv(futime, fustat) ~ 1, data = ovarian)
+#'   # Extract survival probabilities at our time points
+#'   km_summary <- summary(km_fit, times = time_points)
 #'
-#' ext_Surv <- fit.models(formula = Surv(time, event) ~ 1,
-#'                        data = data_sim,
-#'                        distr = "exponential",
-#'                        method = "hmc")
+#'   # Generate matrix by replicating the single survival curve
+#'   surv_matrix_vec <- make_surv(km_summary$surv, t = 0:(length(km_summary$surv) - 1), nsim = n_sim)
+#'   cat("Default (vector) method output dimensions:", dim(surv_matrix_vec), "\n")
+#' }
 #'
-#' S_ext <- make_surv(ext_Surv, t = 1:100, nsim = 100)
+#' #--------------------------------------
+#' ## Default method for a matrix (pre-simulated curves)
+#' #--------------------------------------
+#' # Create a sample matrix of survival probabilities (500 time points, 50 simulations)
+#' pre_sim_matrix <- sapply(1:n_sim, function(i) 1 - pweibull(1:500, shape = 1.5, scale = 100 + i))
 #'
+#' # Use make_surv to subset the matrix for our desired time points
+#' surv_matrix_mat <- make_surv(pre_sim_matrix, t = time_points)
+#' cat("Default (matrix) method output dimensions:", dim(surv_matrix_mat), "\n")
+#'
+#' #--------------------------------------
+#' ## Method for 'inla' objects (conceptual example)
+#' #--------------------------------------
+#' \dontrun{
+#' if (rlang::is_installed("INLA")) {
+#'   # This method requires a fitted 'inla' object, typically from a
+#'   # piecewise exponential model (poisson likelihood).
+#'
+#'   # Assuming 'fit_inla' is a valid model object from INLA:
+#'   # surv_matrix_inla <- make_surv(fit_inla, t = time_points, nsim = n_sim)
+#'   # print(dim(surv_matrix_inla))
+#' }
+#' }
 make_surv <- function(Surv, ...)
   UseMethod("make_surv", Surv)
 
 
 #' @rdname make_surv_methods
-#' @param t Time
-#' @param nsim Number of simulations
+#' @param t A numeric vector of time points at which to calculate survival
+#'   probabilities. The behaviour for `NULL` varies by method.
+#' @param nsim The number of simulations to generate from the model's posterior
+#'   distribution. Defaults to 100.
 #' @importFrom survHE make.surv
 #' @export
 #'
@@ -45,8 +124,10 @@ make_surv.survHE <- function(Surv, t, nsim = 100, ...) {
 
 
 #' @rdname make_surv_methods
-#' @param t Time
-#' @param nsim Number of simulations
+#' @details For `flexsurvreg` objects, parameters are sampled from the asymptotic
+#'   normal distribution of the maximum likelihood estimates using
+#'   `flexsurv::normboot.flexsurvreg()`. If `t` is `NULL`, the unique
+#'   event/censoring times from the model's source data are used.
 #' @importFrom survHE make.surv
 #' @importFrom flexsurv normboot.flexsurvreg
 #' @export
@@ -67,8 +148,18 @@ make_surv.flexsurvreg <- function(Surv, t = NULL, nsim = 100, ...) {
 
 
 #' @rdname make_surv_methods
-#' @param t Time points; vector
-#' @param nsim Number of simulations; integer
+#'
+#' @details
+#' ### INLA Method
+#' The `inla` method requires the **INLA** package. As it is not available on CRAN,
+#' you must install it from its own repository:
+#' `install.packages("INLA", repos = c(getOption("repos"), INLA = "https://inla.r-inla-download.org/R/stable"), dep = TRUE)`
+#'
+#' This method is designed for `inla` objects fitted with a `poisson` likelihood
+#' for piecewise exponential models. It samples from the joint posterior of the
+#' baseline hazard to calculate survival probabilities. If `t` is `NULL`, the
+#' interval cut-points for the baseline hazard from the model are used.
+#'
 #' @import sn
 #' @importFrom tibble as_tibble
 #' @importFrom dplyr select contains
@@ -144,6 +235,19 @@ make_surv.inla <- function(Surv, t = NULL, nsim = 100, ...) {
 
 #' @rdname make_surv_methods
 #'
+#' @details
+#' ### Default Method
+#' The default method handles pre-computed survival probabilities.
+#'   - If `Surv` is a **vector**, it is treated as a single survival curve (e.g.,
+#'     from a Kaplan-Meier estimate). The function replicates this curve `nsim`
+#'     times to form the output matrix.
+#'   - If `Surv` is a **matrix**, it is assumed to already be in the desired
+#'     (time x simulations) format. The function will simply subset rows based on `t`.
+#'
+#' If `t` is `NULL`, a sequence `0, 1, 2, ...` is generated based on the length
+#' or number of rows of `Surv`. Note that time points are used as 1-based indices,
+#' so `t = 0` corresponds to the first row/element.
+#'
 #' @export
 make_surv.default <- function(Surv,
                               t = NULL,

R/plot.R

@@ -1,14 +1,27 @@
 
-#' Blended survival curve based on short-term data and external information
+#' @title Plot Blended Survival Curves
+#'
+#' @description
+#' S3 method for plotting objects of class `blended`. This function generates a
+#' `ggplot2` visualization that displays the mean survival curves and 95%
+#' credible intervals for three components:
+#'
+#' 1.  The curve fitted to the original trial data (`Data fitting`).
+#' 2.  The curve representing external information (`External info`).
+#' 3.  The final, combined blended curve (`Blended curve`).
+#'
+#' @param x An object of class `blended`, typically the output of [blendsurv()].
+#' @param alpha A numeric vector of length two specifying the opacity for the
+#'   credible interval ribbons. The first value (`alpha[1]`) is for the blended
+#'   curve, and the second (`alpha[2]`) is for the trial and external curves.
+#' @param ... Additional graphical arguments passed to the plot, such as `xlim`,
+#'   `xlab`, or `ylab`.
 #'
-#' @param x A blended survival curve object obtain from [blendsurv()]
-#' @param alpha A vector specifying the opacity of ribbon for the blended curve and other curves
-#' @param ... Additional arguments
 #' @import ggplot2
 #' @importFrom stats quantile
 #'
-#' @return A \pkg{ggplot2} object
-#' @seealso [blendsurv()]
+#' @return A `ggplot` object representing the survival curves.
+#' @seealso [blendsurv()], [weightplot()]
 #' @method plot blended
 #' @export
 #'