Merge pull request #33 from Merck/prepcran

Remove documentation for non-exported functions

R/basics.R

@@ -35,6 +35,7 @@
 #' - Generalized Gamma requires the mu, sigma and Q parameters if using the standard parameterization (`gengamma`) or shape, scale and k parameters if using the original parameterization (`gengamma.orig`).
 #' @seealso [flexsurv::flexsurvreg]
 #' @return The value of the distribution function, a numeric value.
+#' @noRd
 # Examples
 # calc_pdist_par(10, "exp", 0.01)
 # calc_pdist_par(5, "lnorm", c(3, 1))
@@ -80,6 +81,7 @@ calc_pdist_par <- function(time, dist, pars) {
 #' - `scale` - Either "hazard", "odds", or "normal", as described in [flexsurv::flexsurvspline]. With the default of no knots in addition to the boundaries, this model reduces to the Weibull, log-logistic and log-normal respectively. The scale must be common to all times.
 #' @seealso [flexsurv::flexsurvspline] and [flexsurv::flexsurvreg]
 #' @return The value of the distribution function, a numeric value.
+#' @noRd
 # Examples
 # calc_pdist(time=1:5,
 #     type="spl",
@@ -114,6 +116,7 @@ calc_pdist <- function(time, type, spec){
 #' @inheritParams calc_pdist
 #' @return The value of the survival function, a numeric value.
 #' @inherit calc_pdist seealso
+#' @noRd
 # Examples
 # calc_surv(time=1:5,
 #     type="spl",
@@ -132,6 +135,7 @@ calc_surv <- function(time, type, spec) {
 #' @inheritParams calc_pdist_par
 #' @inherit calc_pdist_par seealso
 #' @return The value of a hazard function, a numeric value.
+#' @noRd
 # Examples
 # calc_haz_par(10, "exp", 0.01)
 # calc_haz_par(5, "lnorm", c(3, 1))
@@ -163,6 +167,7 @@ calc_haz_par <- function(time, dist, pars) {
 #' @description Calculate the value of the hazard function, given specification as either parametric or Royston-Parmar splines model
 #' @inheritParams calc_surv
 #' @inherit calc_haz_par return
+#' @noRd
 # Examples
 # calc_haz(time=1:5,
 #     type="spl",
@@ -195,6 +200,7 @@ calc_haz <- function(time, type, spec){
 #' @inheritParams calc_pdist_par
 #' @inherit calc_pdist_par seealso
 #' @return The value of a density function, a numeric value.
+#' @noRd
 # Examples
 # calc_dens_par(10, "exp", 0.01)
 # calc_dens_par(5, "lnorm", c(3, 1))
@@ -226,6 +232,7 @@ calc_dens_par <- function(time, dist, pars) {
 #' @description Calculate the value of the density function, given specification as either parametric or Royston-Parmar splines model
 #' @inheritParams calc_surv
 #' @inherit calc_haz_par return
+#' @noRd
 # Examples
 # calc_dens(time=1:5,
 #     type="spl",
@@ -266,6 +273,7 @@ calc_dens <- function(time, type, spec){
 #' @param Tw is the time period over which the restricted mean is calculated
 #' @inherit calc_pdist seealso
 #' @return the restricted mean duration, a numeric value.
+#' @noRd
 # Examples
 # calc_rmd_par(20, "exp", 0.2)
 # calc_rmd_par(10, "lnorm", c(3, 1))
@@ -310,8 +318,8 @@ calc_rmd_par <- function(Tw, dist, pars) {
 #' - `knots` - Vector of locations of knots on the axis of log time, supplied in increasing order. Unlike in [flexsurv::flexsurvspline], these include the two boundary knots.
 #' - `scale` - Either "hazard", "odds", or "normal", as described in [flexsurv::flexsurvspline]. With the default of no knots in addition to the boundaries, this model reduces to the Weibull, log-logistic and log-normal respectively. The scale must be common to all times.
 #' @param discrate Discounting rate (%) per year
-#' @inherit calc_haz_par seealso
-#' @inherit calc_haz_par return
+#' @returns Numeric
+#' @seealso [flexsurv::flexsurvspline] and [flexsurv::flexsurvreg]
 #' @export
 #' @examples
 #' calc_rmd(Tw=200,
@@ -347,6 +355,7 @@ calc_rmd <- function(Tw, type, spec, discrate=0){
 #' @param dist is the statistical distribution (named per [flexsurv::flexsurvreg])
 #' @return a numeric value
 #' @inherit calc_pdist seealso
+#' @noRd
 # Examples
 # give_noparams_par("llogis")
 give_noparams_par <- function(dist) {
@@ -365,6 +374,7 @@ give_noparams_par <- function(dist) {
 #' @inheritParams calc_surv
 #' @return a numeric value
 #' @inherit calc_pdist seealso
+#' @noRd
 # Examples
 # give_noparams(type="par", spec=list(dist="weibullPH"))
 # give_noparams(type="spl", spec=list(gamma=c(1.1,2.1,3.1)))
@@ -386,6 +396,7 @@ give_noparams <- function(type, spec) {
 #' @param weeks Number of weeks
 #' @return Number of years = weeks x 7 / 365.25
 #' @seealso [psm3mkv::convert_yrs2wks]
+#' @noRd
 convert_wks2yrs <- function(weeks) {
   weeks*7/365.25
 }
@@ -395,6 +406,7 @@ convert_wks2yrs <- function(weeks) {
 #' @param years Number of years
 #' @return Number of weeks = years / 7 * 365.25
 #' @seealso [psm3mkv::convert_wks2yrs]
+#' @noRd
 convert_yrs2wks <- function(years) {
   years*365.25/7
 }

R/datasets.R

@@ -46,6 +46,7 @@ create_dummydata <- function(dsname) {
 #' @return Tibble dataset, for use with [psm3mkv] functions
 #' @seealso [create_dummydata()]
 #' @importFrom rlang .data
+#' @noRd
 create_dummydata_survcan <- function() {
   # Declare local variables
   ptid <- os.durn <- os.flag <- NULL
@@ -64,6 +65,7 @@ create_dummydata_survcan <- function() {
 #' @return Tibble dataset, for use with [psm3mkv] functions
 #' @seealso [create_dummydata()]
 #' @importFrom rlang .data
+#' @noRd
 create_dummydata_flexbosms <- function() {
   # Declare local variables
   id <- pfs.durn <- pfs.flag <- NULL

R/discrmd.R

@@ -45,6 +45,7 @@
 #' - pd: RMD in PD state
 #' - os: RMD in either alive state
 #' @seealso [drmd_stm_cf()] [drmd_stm_cr()]
+#' @noRd
 # Examples
 # # Create dataset and fit survival models (splines)
 # bosonc <- create_dummydata("flexbosms")
@@ -93,6 +94,7 @@ drmd_psm <- function(ptdata, dpam, psmtype="simple", Ty=10, discrate=0, lifetabl
 #' Calculate restricted mean duration (RMD) in PF, PD and OS states under a State Transition Model Clock Forward structure.
 #' @inherit drmd_psm params return
 #' @seealso [drmd_psm()] [drmd_stm_cr()]
+#' @noRd
 # Examples
 # # Create dataset and fit survival models (splines)
 # bosonc <- create_dummydata("flexbosms")
@@ -149,6 +151,7 @@ drmd_stm_cf <- function(dpam, Ty=10, discrate=0, lifetable=NA, timestep=1) {
 #' Calculate restricted mean duration (RMD) in PF, PD and OS states under a State Transition Model Clock Reset structure.
 #' @inherit drmd_psm params return
 #' @seealso [drmd_stm_cf()] [drmd_psm()]
+#' @noRd
 # Examples
 # # Create dataset and fit survival models (splines)
 # bosonc <- create_dummydata("flexbosms")

R/fitting-spl.R

@@ -33,6 +33,7 @@
 #' - result: A list of class [flexsurv::flexsurvspline] containing information about the fitted model.
 #' - error: Any error message returned on fitting the regression (NULL indicates no error).
 #' @seealso [flexsurv::flexsurvspline] and [survival::Surv()]
+#' @noRd
 fit_mods_spl <- function(durn1, durn2=NA, evflag,
                          knot_set=1:3,
                          scale_set=c("hazard", "odds", "normal"),

R/fitting.R

@@ -25,6 +25,7 @@
 #' @description Checks whether the Hessian matrix returned in a list after fitting a survival regression with flexsurvreg is positive-definite.
 #' @param fitlist is a list returned after running [flexsurv::flexsurvreg()] describing a fitted survival model
 #' @return logical: TRUE if Hessian matrix is positive definite, FALSE if not.
+#' @noRd
 # Examples
 # bosonc <- create_dummydata("flexbosms")
 # fits <- fit_ends_mods_par(bosonc)
@@ -56,6 +57,7 @@ check_posdef <- function(fitlist) {
 #' @return A list by distribution, each containing two components:
 #' - result: A list of class [flexsurv::flexsurvreg] containing information about the fitted model.
 #' - error: Any error message returned on fitting the regression (NULL indicates no error).
+#' @noRd
 fit_mods_par <- function(durn1, durn2=NA, evflag, dists, expvar=NA) {
   # Return nothing if no distributions specified
   if (sum(is.na(dists))!=0) {return(NA)}
@@ -90,6 +92,7 @@ fit_mods_par <- function(durn1, durn2=NA, evflag, dists, expvar=NA) {
 #' @return A list by distribution, each containing two components:
 #' - result: A list containing information about the fitted model.
 #' - error: Any error message returned on fitting the regression (NULL indicates no error).
+#' @noRd
 fit_mods <- function(durn1, durn2=NA, evflag, type, spec) {
   if (type=="spl"){
     fit_mods_spl(durn1, durn2, evflag, knot_set=spec$k, scale_set=spec$scale)

R/lhoods.R

@@ -28,6 +28,7 @@
 #' - `spec` contains distribution (`dist`) and coefficients (`coefs`) if `type=="par"`
 #' - `spec` contains gamma values (`gamma`), knot locations (log scale, `knots`) and scale (`scale`) for Royston-Parmar splines model, if `type=="spl"`
 #' @seealso [flexsurv::flexsurvspline()]
+#' @noRd
 # Examples
 # bosonc <- create_dummydata("flexbosms")
 # fits <- fit_ends_mods_spl(bosonc)
@@ -53,13 +54,13 @@ convert_fit2spec <- function(fitsurv) {
 #' Calculate likelihood for a simple three-state partitioned survival model
 #' @description Calculate likelihood values and other summary output for a simple three-state partitioned survival model, given appropriately formatted patient-level data, a set of fitted survival regressions, and the time cut-off (if two-piece modeling is used). This function is called by [calc_likes].x three-state partitioned survival model, given appropriately formatted patient-level data, a set of fitted survival regressions, and the time cut-off (if two-piece modeling is used). This function is called by [calc_likes]. Unlike [calc_likes_psm_complex], this likelihood function assumes a progression hazard can be derived from the PFS hazard function and the ratio of progression to PFS events from PF patients.
 #' @param ptdata Dataset of patient level data. Must be a tibble with columns named:
-#' - ptid: patient identifier
-#' - pfs.durn: duration of PFS from baseline
-#' - pfs.flag: event flag for PFS (=1 if progression or death occurred, 0 for censoring)
-#' - os.durn: duration of OS from baseline
-#' - os.flag: event flag for OS (=1 if death occurred, 0 for censoring)
-#' - ttp.durn: duration of TTP from baseline (usually should be equal to pfs.durn)
-#' - ttp.flag: event flag for TTP (=1 if progression occurred, 0 for censoring).
+#' - `ptid`: patient identifier
+#' - `pfs.durn`: duration of PFS from baseline
+#' - `pfs.flag`: event flag for PFS (=1 if progression or death occurred, 0 for censoring)
+#' - `os.durn`: duration of OS from baseline
+#' - `os.flag`: event flag for OS (=1 if death occurred, 0 for censoring)
+#' - `ttp.durn`: duration of TTP from baseline (usually should be equal to pfs.durn)
+#' - `ttp.flag`: event flag for TTP (=1 if progression occurred, 0 for censoring).
 #'
 #' Survival data for all other endpoints (time to progression, pre-progression death, post-progression survival) are derived from PFS and OS.
 #' @param dpam List of survival regressions for each endpoint:
@@ -81,6 +82,7 @@ convert_fit2spec <- function(fitsurv) {
 #' - `BIC`: Bayesian Information Criterion value for this model
 #' @seealso [calc_likes()], [calc_likes_psm_complex()], [calc_likes_stm_cf()], [calc_likes_stm_cr()]
 #' @importFrom rlang .data
+#' @noRd
 # Examples
 # bosonc <- create_dummydata("flexbosms")
 # fits <- fit_ends_mods_spl(bosonc)
@@ -181,6 +183,7 @@ calc_likes_psm_simple <- function(ptdata, dpam, cuttime=0) {
 #' @inherit calc_likes_psm_simple return
 #' @seealso [calc_likes()], [calc_likes_psm_simple()], [calc_likes_psm_complex()], [calc_likes_stm_cr()]
 #' @importFrom rlang .data
+#' @noRd
 # Examples
 # bosonc <- create_dummydata("flexbosms")
 # fits <- fit_ends_mods_par(bosonc)
@@ -285,6 +288,7 @@ calc_likes_psm_complex <- function(ptdata, dpam, cuttime=0) {
 #' @inherit calc_likes_psm_simple return
 #' @seealso [calc_likes()], [calc_likes_psm_simple()], [calc_likes_psm_complex()], [calc_likes_stm_cr()]
 #' @importFrom rlang .data
+#' @noRd
 # Examples
 # bosonc <- create_dummydata("flexbosms")
 # fits <- fit_ends_mods_spl(bosonc)
@@ -377,6 +381,7 @@ calc_likes_stm_cf <- function(ptdata, dpam, cuttime=0) {
 #' @inherit calc_likes_psm_simple return
 #' @seealso [calc_likes()], [calc_likes_stm_cf()], [calc_likes_psm_simple()], [calc_likes_psm_complex()]
 #' @importFrom rlang .data
+#' @noRd
 # Examples
 # bosonc <- create_dummydata("flexbosms")
 # fits <- fit_ends_mods_spl(bosonc)
@@ -466,7 +471,24 @@ calc_likes_stm_cr <- function(ptdata, dpam, cuttime=0) {
 
 #' Calculate likelihoods for three three-state model structures
 #' @description Calculate likelihood values and other summary output for the following three state models structures: partitioned survival, clock forward state transition, and clock reset state transition. The function requires appropriately formatted patient-level data, a set of fitted survival regressions, and the time cut-off (if two-piece modeling is used).
-#' @inheritParams calc_likes_psm_simple
+#' @param ptdata Dataset of patient level data. Must be a tibble with columns named:
+#' - `ptid`: patient identifier
+#' - `pfs.durn`: duration of PFS from baseline
+#' - `pfs.flag`: event flag for PFS (=1 if progression or death occurred, 0 for censoring)
+#' - `os.durn`: duration of OS from baseline
+#' - `os.flag`: event flag for OS (=1 if death occurred, 0 for censoring)
+#' - `ttp.durn`: duration of TTP from baseline (usually should be equal to pfs.durn)
+#' - `ttp.flag`: event flag for TTP (=1 if progression occurred, 0 for censoring).
+#'
+#' Survival data for all other endpoints (time to progression, pre-progression death, post-progression survival) are derived from PFS and OS.
+#' @param dpam List of survival regressions for each endpoint:
+#' - pre-progression death (PPD)
+#' - time to progression (TTP)
+#' - progression-free survival (PFS)
+#' - overall survival (OS)
+#' - post-progression survival clock forward (PPS-CF) and
+#' - post-progression survival clock reset (PPS-CR).
+#' @param cuttime Time cutoff - this is nonzero for two-piece models.
 #' @return Two outputs are returned:
 #' 
 #' `results` is a tibble of values and data relating to the likelihood for this model:
@@ -487,7 +509,6 @@ calc_likes_stm_cr <- function(ptdata, dpam, cuttime=0) {
 #'
 #' The number of patients for each outcome are given for each model structure. You may confirm that these are identical across model structures.
 #' The contribution of each patient group to the calculation of log-likelihood for each model is given in fields beginning `ll_`. This is helpful for understanding differences in likelihoods between model structures, according to patient outcomes.
-#' @seealso This function calls [calc_likes_psm_simple()], [calc_likes_psm_complex()], [calc_likes_stm_cf()], and [calc_likes_stm_cr()].
 #' @export
 #' @examples
 #' \donttest{

R/ltablesurv.R

@@ -33,6 +33,7 @@
 #' - `arith`: Arithmetic mean, where interpolation is required between measured values
 #' - `geom`: Geometric mean, where interpolation is required between measured values
 #' @seealso [psm3mkv::vlookup]
+#' @noRd
 vonelookup <- function(oneindexval, indexvec, valvec, method="geom") {
   if (is.na(oneindexval)) return(NA) # Return NA rather than error if index value lookup is NA
   if (oneindexval<min(indexvec)) stop("Lookup value is below range of lookup table")
@@ -93,6 +94,7 @@ vlookup <- function(indexval, indexvec, valvec, method="geom") {
 #' @param lifetable The lifetable must be a dataframe with columns named `lttime` (years) and `lx`. The first entry of the time column must be zero. Data should be sorted in ascending order by time, and all times must be unique.
 #' @param method Method may be `floor`, `ceiling`, `arith` or `geom` (default).
 #' @return Numeric survival probability
+#' @noRd
 # Examples
 # ltable <- tibble::tibble(lttime=0:10, lx=10-(0:10))
 # calc_ltsurv(c(2, 2.5, 9.3), ltable)
@@ -108,6 +110,7 @@ calc_ltsurv <- function(looktime, lifetable=NA, method="geom"){
 #' @param lifetable The lifetable must be a dataframe with columns named `lttime` (years) and `lx`. The first entry of the time column must be zero. Data should be sorted in ascending order by time, and all times must be unique.
 #' @param method Method may be `floor`, `ceiling`, `arith` or `geom` (default). 
 #' @return Numeric survival probability
+#' @noRd
 # Examples
 # ltable <- tibble::tibble(lttime=0:10, lx=10-(0:10))
 # calc_ltdens(c(2, 2.5, 9.3), ltable)
@@ -134,11 +137,12 @@ calc_ltdens <- function(looktime, lifetable=NA, method="geom"){
 #' @param discrate Discount rate (%) per year
 #' @return List containing `ex_y` and `ex_w'`, the numeric (restricted) life expectancy in years and weeks respectively,
 #' and `calcs`, a dataframe of the calculations.
-#' @examples
-#' # Create a lifetable. Must end with lx=0.
-#' # ltable <- tibble::tibble(lttime=0:20, lx=1-lttime*0.05)
-#' # calc_ex(lifetable=ltable, discrate=0.03)
-#' # calc_ex(Ty=Inf, lifetable=ltable)
+#' @noRd
+# Examples
+# Create a lifetable. Must end with lx=0.
+# ltable <- tibble::tibble(lttime=0:20, lx=1-lttime*0.05)
+# calc_ex(lifetable=ltable, discrate=0.03)
+# calc_ex(Ty=Inf, lifetable=ltable)
 calc_ex <- function(Ty=10, lifetable, discrate=0) {
   lx <- lttime <- midtime <- vn <- beyond <- lxvn <- blxvn <- NULL
   # Lifetable must have minimum lx = 0