From de1220a2b66a0c398e12ae2f569f3fdc5524acf7 Mon Sep 17 00:00:00 2001 From: Quentin Marcou <18257721+qmarcou@users.noreply.github.com> Date: Fri, 31 May 2024 21:23:43 +0200 Subject: [PATCH] Add draft documentation --- man/apply_iddata_censoring.Rd | 22 ++++++ man/apply_iddata_death.Rd | 24 +++++++ man/compute_survprob_pch.Rd | 40 +++++++++++ man/dot-filter_times.Rd | 24 +++++++ man/generate_exponential_time_to_event.Rd | 21 ++++++ man/generate_poisson_time_to_event.Rd | 31 +++++++++ man/generate_uncensored_ind_exp_idm_data.Rd | 31 +++++++++ man/get_survival_at.Rd | 23 +++++++ man/indiv_survprob_pch.Rd | 25 +++++++ man/invalid_argument.Rd | 21 ++++++ man/mod.glm.fit.callingwrapper.Rd | 30 +++++++++ man/mod.glm.fit.errorwrapper.Rd | 30 +++++++++ man/multi_assert.Rd | 23 +++++++ man/netidmtpreg-package.Rd | 23 +++++++ man/offsetlogit.Rd | 29 ++++++++ man/rellogit.Rd | 29 ++++++++ man/renewnetTPreg.Rd | 75 +++++++++++++++++++++ 17 files changed, 501 insertions(+) create mode 100644 man/apply_iddata_censoring.Rd create mode 100644 man/apply_iddata_death.Rd create mode 100644 man/compute_survprob_pch.Rd create mode 100644 man/dot-filter_times.Rd create mode 100644 man/generate_exponential_time_to_event.Rd create mode 100644 man/generate_poisson_time_to_event.Rd create mode 100644 man/generate_uncensored_ind_exp_idm_data.Rd create mode 100644 man/get_survival_at.Rd create mode 100644 man/indiv_survprob_pch.Rd create mode 100644 man/invalid_argument.Rd create mode 100644 man/mod.glm.fit.callingwrapper.Rd create mode 100644 man/mod.glm.fit.errorwrapper.Rd create mode 100644 man/multi_assert.Rd create mode 100644 man/netidmtpreg-package.Rd create mode 100644 man/offsetlogit.Rd create mode 100644 man/rellogit.Rd create mode 100644 man/renewnetTPreg.Rd diff --git a/man/apply_iddata_censoring.Rd b/man/apply_iddata_censoring.Rd new file mode 100644 index 0000000..c81fea8 --- /dev/null +++ b/man/apply_iddata_censoring.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/idm_data_generation.R +\name{apply_iddata_censoring} +\alias{apply_iddata_censoring} +\title{Apply censoring times to an existing Illness-Death dataframe.} +\usage{ +apply_iddata_censoring(iddata_df, censoring_times) +} +\arguments{ +\item{iddata_df}{An Illness-Death dataframe in \code{iddata} format.} + +\item{censoring_times}{Censoring time(s), either a single value or a vector +length \code{nrow(iddata_df)}} +} +\value{ +An iddata tibble with updated censoring times +} +\description{ +Update event times (Zt and Tt) and censoring indicators according to the +prescribed censoring time(s). Note that previous censoring information will +be updated where newer censoring times are provided. +} diff --git a/man/apply_iddata_death.Rd b/man/apply_iddata_death.Rd new file mode 100644 index 0000000..182e319 --- /dev/null +++ b/man/apply_iddata_death.Rd @@ -0,0 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/idm_data_generation.R +\name{apply_iddata_death} +\alias{apply_iddata_death} +\title{Update death times in an existing Illness-Death dataframe.} +\usage{ +apply_iddata_death(iddata_df, death_times) +} +\arguments{ +\item{iddata_df}{An Illness-Death dataframe in \code{iddata} format.} + +\item{death_times}{Updated death time(s), either a single value or a vector +length \code{nrow(iddata_df)}} +} +\value{ +An iddata tibble with updated death times +} +\description{ +Update event times (Zt and Tt) according to the prescribed death time(s). +Death times are only updated when the new death time is earlier than the +previous one for a given individual. This function cannot postpone an +existing death time as the parameters provide no way to know whether illness +occurred between old and new death time. +} diff --git a/man/compute_survprob_pch.Rd b/man/compute_survprob_pch.Rd new file mode 100644 index 0000000..919ed0a --- /dev/null +++ b/man/compute_survprob_pch.Rd @@ -0,0 +1,40 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/survexp_wrappers.R +\name{compute_survprob_pch} +\alias{compute_survprob_pch} +\title{Apply individual surv prob computation to DF} +\usage{ +compute_survprob_pch(patientsDF, eval_times, ratetable, rmap) +} +\arguments{ +\item{patientsDF}{a DF/DT/tibble containing the data needed to compute +individual expected survival probability} + +\item{eval_times}{The times at which survival must be evaluated. Times must +be in days if using a ratetable with a Date component. Provided times can +be passed as single numeric value or vector of numeric values or as unamed +list of numeric values if common for all individuals. Otherwise the name of +the column containing the list,vector or single value evaluation point can +be passed as character string or as variable name.} + +\item{ratetable}{A ratetable object. See ?survival::ratetable for details.} + +\item{rmap}{An rmap argument as the one passed to survival::survexp. This +argument will only be evaluated inside survexp} +} +\value{ +Returns a tidy tibble with 3 columns: the row name of the individual +row (as given by the call of row.names() on the patientsDF), the evaluation +time and the corresponding survival probability. +} +\description{ +This function is a wrapper around \code{indiv_survprob_pch}. It calls +the latter function on every row of the DF in order to compute the expected +survival probability for each individual row at each provided \code{eval_times}. +The point of this is to call survexp only once per patient and compute the +survival probablity at all patime points for each patient, thus avoiding +redundant computation. +} +\examples{ +compute_survprob_pch(patients,eval_times = c(10,20,30),ratetable = slopop,rmap=list(year=date_chir, age=age_at_dg, sex=sexe)) +} diff --git a/man/dot-filter_times.Rd b/man/dot-filter_times.Rd new file mode 100644 index 0000000..95eb234 --- /dev/null +++ b/man/dot-filter_times.Rd @@ -0,0 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/survexp_wrappers.R +\name{.filter_times} +\alias{.filter_times} +\title{Map time steps to event times} +\usage{ +.filter_times(time_steps, event_times) +} +\arguments{ +\item{time_steps}{An array/vector of desired timesteps} + +\item{event_times}{An array/vector of actual event-times or breakpoints} +} +\value{ +An array of unique time points ordered in increasing order +} +\description{ +Filter and map a list/vector of time steps to a list/vector of event times. +This is useful for evaluating a piecewise constant function (e.g Kaplan-Meier survival, binomial regression) +but limit the number of redundant computation steps, by evaluating the function only at breakpoints. +} +\examples{ +.filter_times(c(1,2,4,5,6),c(1,3,5)) +} diff --git a/man/generate_exponential_time_to_event.Rd b/man/generate_exponential_time_to_event.Rd new file mode 100644 index 0000000..a52f404 --- /dev/null +++ b/man/generate_exponential_time_to_event.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/idm_data_generation.R +\name{generate_exponential_time_to_event} +\alias{generate_exponential_time_to_event} +\title{Generate time to events from an exponential distribution} +\usage{ +generate_exponential_time_to_event(n_individuals, lambda) +} +\arguments{ +\item{n_individuals}{integer, Number of individuals to simulate} + +\item{lambda}{float > 0, Rate of the underlying Poisson point process} +} +\value{ +Atomic vector of time to (first) event. +} +\description{ +This is a simple wrapper around the stats::rexp function, without added value +beyond consistent argument checking and format with other generating functions +from the package. +} diff --git a/man/generate_poisson_time_to_event.Rd b/man/generate_poisson_time_to_event.Rd new file mode 100644 index 0000000..60885e7 --- /dev/null +++ b/man/generate_poisson_time_to_event.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/idm_data_generation.R +\name{generate_poisson_time_to_event} +\alias{generate_poisson_time_to_event} +\title{Generate synthetic time to event data from a homogeneous Poisson process.} +\usage{ +generate_poisson_time_to_event( + n_individuals, + lambda, + n_timesteps, + recurring = FALSE +) +} +\arguments{ +\item{n_individuals}{integer, Number of individuals to simulate} + +\item{lambda}{float > 0, Rate of the Poisson point process} + +\item{n_timesteps}{integer, Number of evenly spaced timesteps} + +\item{recurring}{logical, whether event is recurring or fully absorbing.} +} +\value{ +If recurring=FALSE a vector of first time to event, if recurring=TRUE +a list of event times of length n_individuals. +} +\description{ +Note that this is not a efficient way to model time homogeneous non recurring +events that may be better captured by a continuous time exponential +distribution from \code{\link{generate_exponential_time_to_event}}. +} diff --git a/man/generate_uncensored_ind_exp_idm_data.Rd b/man/generate_uncensored_ind_exp_idm_data.Rd new file mode 100644 index 0000000..5c3297b --- /dev/null +++ b/man/generate_uncensored_ind_exp_idm_data.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/idm_data_generation.R +\name{generate_uncensored_ind_exp_idm_data} +\alias{generate_uncensored_ind_exp_idm_data} +\title{Generate uncensored independent exponential illness-death data.} +\usage{ +generate_uncensored_ind_exp_idm_data( + n_individuals, + lambda_illness, + lambda_death +) +} +\arguments{ +\item{n_individuals}{integer, Number of individuals to simulate} + +\item{lambda_illness}{float > 0, Rate of the underlying Poisson point process +to transition from healthy to illness} + +\item{lambda_death}{float > 0, Rate of death, either from healthy or illness +state.} +} +\value{ +a tibble of iddata +} +\description{ +Mostly for testing purposes. Illness and death times are assumed independent, +in particular the death rate is assumed equal in healthy and illness states. +This simplification creates data that are not really following an +Illness-Death model but a simpler semi competitive model, where death +prevents observation of illness times. +} diff --git a/man/get_survival_at.Rd b/man/get_survival_at.Rd new file mode 100644 index 0000000..d63667b --- /dev/null +++ b/man/get_survival_at.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/renewnetTPreg.R +\name{get_survival_at} +\alias{get_survival_at} +\title{Estimated survival at time t from a survfit like df.} +\usage{ +get_survival_at(t, survfit_data, safe = TRUE) +} +\arguments{ +\item{t}{Single or vector numeric value $\geq$ 0.} + +\item{survfit_data}{A survfit, summary.survfit or data.frame object. If +data.frame, it should contain at least columns \code{surv} and \code{time}.} + +\item{safe}{boolean, Indicate whether to enable input argument checking, +default to TRUE.} +} +\value{ +A survival probabilities of same length as \code{t}. +} +\description{ +Estimated survival at time t from a survfit like df. +} diff --git a/man/indiv_survprob_pch.Rd b/man/indiv_survprob_pch.Rd new file mode 100644 index 0000000..80767c3 --- /dev/null +++ b/man/indiv_survprob_pch.Rd @@ -0,0 +1,25 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/survexp_wrappers.R +\name{indiv_survprob_pch} +\alias{indiv_survprob_pch} +\title{Compute expected survival for one individual at several times} +\usage{ +indiv_survprob_pch(individual_df, eval_times, ratetable, rmap, fast = FALSE) +} +\arguments{ +\item{individual_df}{A DF or DT containing a single row with a single patient's covariates} + +\item{eval_times}{Times at which the expected survival should be evaluated. Times must be in days if using a ratetable with a Date component.} + +\item{ratetable}{A ratetable object} + +\item{rmap}{An rmap argument as the one passed to survival::survexp. This argument will only be evaluated inside survexp} + +\item{fast}{Binary, if TRUE the function will omit some validity checks on the arguments. Should be used with caution.} +} +\value{ +Returns a tibble with two columns: eval_times and surv the survival probability from the survexp object at those times. Upon failure of surv.exp because of missing data in the DF row, a vector of NA will be returned. +} +\description{ +A wrapper function calling survival::survexp to compute expected survival probablity of a single individual for one or several times, using a piecewise constant hazard (pch) defined in a ratetable object. +} diff --git a/man/invalid_argument.Rd b/man/invalid_argument.Rd new file mode 100644 index 0000000..73b205e --- /dev/null +++ b/man/invalid_argument.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/error.R +\name{invalid_argument} +\alias{invalid_argument} +\title{Custom exception for invalid arguments} +\usage{ +invalid_argument(arg, must, not = NULL) +} +\arguments{ +\item{arg}{string, faulty argument name} + +\item{must}{string, description of the expected nature of the argument} + +\item{not}{string, optional, description of the received argument} +} +\value{ +None +} +\description{ +Derived from https://adv-r.hadley.nz/conditions.html#custom-conditions +} diff --git a/man/mod.glm.fit.callingwrapper.Rd b/man/mod.glm.fit.callingwrapper.Rd new file mode 100644 index 0000000..8f9f5c2 --- /dev/null +++ b/man/mod.glm.fit.callingwrapper.Rd @@ -0,0 +1,30 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/renewnetTPreg.R +\name{mod.glm.fit.callingwrapper} +\alias{mod.glm.fit.callingwrapper} +\title{Check input and output of mod.glm.fit} +\usage{ +mod.glm.fit.callingwrapper( + X, + response, + family, + weights, + maxit = stats::glm.control()$maxit, + maxmaxit = 1000, + warning_str = "", + ... +) +} +\arguments{ +\item{X}{array, must have at least 2 dimensions} + +\item{...}{} +} +\value{ +A set of glm coefficients +} +\description{ +Avoids calling the glm fitting function when there are no contrasted response +values (all 0 or all 1). Ensures return of NA coefficient when the algorithm +did not converge. +} diff --git a/man/mod.glm.fit.errorwrapper.Rd b/man/mod.glm.fit.errorwrapper.Rd new file mode 100644 index 0000000..874ee21 --- /dev/null +++ b/man/mod.glm.fit.errorwrapper.Rd @@ -0,0 +1,30 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/renewnetTPreg.R +\name{mod.glm.fit.errorwrapper} +\alias{mod.glm.fit.errorwrapper} +\title{Wraps the call to mod.glm.fit to handle convergence errors} +\usage{ +mod.glm.fit.errorwrapper( + X, + response, + family, + weights, + maxit = stats::glm.control()$maxit, + maxmaxit = 1000, + warning_str = "", + ... +) +} +\arguments{ +\item{...}{} +} +\value{ +A glm object +} +\description{ +Tries to handle convergence and other issues upon calling the mod.glm.fit +function. Some errors returned by mod.glm.fit are cast to warnings. In order +to reduce crashes several values of \code{maxit} are tested if convergence issues +are detected. NAs will be returned in case of crash/divergence or lack of +informative observations. +} diff --git a/man/multi_assert.Rd b/man/multi_assert.Rd new file mode 100644 index 0000000..72d63f9 --- /dev/null +++ b/man/multi_assert.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/error.R +\name{multi_assert} +\alias{multi_assert} +\title{Perform multiple assertions raising a common aborting class.} +\usage{ +multi_assert(x, x_name, abort_class, assert_list) +} +\arguments{ +\item{x}{any, object to be tested} + +\item{x_name}{string, name of the object to be tested} + +\item{abort_class}{callable, the custom abort class} + +\item{assert_list}{a vector or list of asserting functions} +} +\value{ +None +} +\description{ +Perform multiple assertions raising a common aborting class. +} diff --git a/man/netidmtpreg-package.Rd b/man/netidmtpreg-package.Rd new file mode 100644 index 0000000..731cb00 --- /dev/null +++ b/man/netidmtpreg-package.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/netidmtpreg-package.R +\docType{package} +\name{netidmtpreg-package} +\alias{netidmtpreg} +\alias{netidmtpreg-package} +\title{netidmtpreg: Net Survival Binomial Regression for Progressive Illness Death Models} +\description{ +This package implements utilities to infer and inspect transition probabilities in a progressive illness-death model in a net survival context through binomial regression. As such it also provides routines to analyze illness-death transition probabilities without correcting for background mortality. Ref: Azarang L & Giorgi R. (2021) \doi{10.1177/09622802211003608} +} +\seealso{ +Useful links: +\itemize{ + \item \url{https://github.com/qmarcou/netidmtpreg} + \item Report bugs at \url{https://github.com/qmarcou/netidmtpreg/issues} +} + +} +\author{ +\strong{Maintainer}: Quentin Marcou \email{quentin.marcou@univ-amu.fr} (\href{https://orcid.org/0000-0001-7074-2761}{ORCID}) + +} +\keyword{internal} diff --git a/man/offsetlogit.Rd b/man/offsetlogit.Rd new file mode 100644 index 0000000..db03451 --- /dev/null +++ b/man/offsetlogit.Rd @@ -0,0 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/renewnetTPreg.R +\name{offsetlogit} +\alias{offsetlogit} +\title{An offset survival logit link function closure for 13 and 23 transitions.} +\usage{ +offsetlogit(s, t, data_df, ratetable, rmap) +} +\arguments{ +\item{s}{positive scalar.} + +\item{t}{positive scalar.} + +\item{data_df}{A \code{data.frame} containing population characteristics.} + +\item{ratetable}{a \code{ratetable} object.} + +\item{rmap}{see survival::survexp.fit.} +} +\value{ +a \code{link-glm} object +} +\description{ +Returns a offset logit \code{link-glm} object taking into account population +mortality a the considered times s and t. +} +\examples{ +# ADD_EXAMPLES_HERE +} diff --git a/man/rellogit.Rd b/man/rellogit.Rd new file mode 100644 index 0000000..87a3df4 --- /dev/null +++ b/man/rellogit.Rd @@ -0,0 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/renewnetTPreg.R +\name{rellogit} +\alias{rellogit} +\title{An relative survival logit link function closure.} +\usage{ +rellogit(s, t, data_df, ratetable, rmap) +} +\arguments{ +\item{s}{positive scalar.} + +\item{t}{positive scalar.} + +\item{data_df}{A \code{data.frame} containing population characteristics.} + +\item{ratetable}{a \code{ratetable} object.} + +\item{rmap}{see survival::survexp.fit.} +} +\value{ +a \code{link-glm} object +} +\description{ +Returns a offset logit \code{link-glm} object taking into account population +mortality a the considered times s and t. This relative logit function +arises when decomposing observed transition probabilities into net +transitions and population survival for all transitions where death (3) is +not the target state. +} diff --git a/man/renewnetTPreg.Rd b/man/renewnetTPreg.Rd new file mode 100644 index 0000000..0170ec2 --- /dev/null +++ b/man/renewnetTPreg.Rd @@ -0,0 +1,75 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/renewnetTPreg.R +\name{renewnetTPreg} +\alias{renewnetTPreg} +\title{Fit (net) survival Illness-Death transition probabilities} +\usage{ +renewnetTPreg( + s = 0, + t = NULL, + trans, + formula, + ratetable, + time_dep_popvars = NULL, + rmap = NULL, + data, + link = "logit", + R = 199, + by = NULL, + readjust_t = TRUE +) +} +\arguments{ +\item{s}{DESCRIPTION.} + +\item{t}{Times at which survival should be estimated, either \code{NULL}, scalar +or vector of numerics. Default to NULL. If a scalar value is given, it will +be interpreted as the maximum time at which survival shall be estimated +using a non-parametric approach. If a vector or list-like object, the values +will be interpreted as the list of times at which one whishes to get point +estimations of survivals. By default estimation will be made at the time of +last events before the requested times. This behavior can be altered by +setting \code{readjust_t} to \code{FALSE}, mostly for testing purposes. If set to +\code{NULL} (default) \code{t} is set as a scalar value to the last observed +transition time.} + +\item{trans}{DESCRIPTION.} + +\item{formula}{DESCRIPTION.} + +\item{ratetable}{DESCRIPTION.} + +\item{time_dep_popvars}{DESCRIPTION.} + +\item{rmap}{DESCRIPTION.} + +\item{data}{DESCRIPTION.} + +\item{link}{DESCRIPTION.} + +\item{R}{DESCRIPTION.} + +\item{by}{DESCRIPTION.} + +\item{readjust_t}{boolean, default \code{TRUE}. Whether to use exact \code{t} values +(\code{FALSE}) or adjust t values to observed transition times (\code{TRUE}).} +} +\value{ +RETURN_DESCRIPTION +} +\description{ +Core function of the package, implementing a +} +\examples{ +# ADD_EXAMPLES_HERE +} +\references{ +Azarang, L., Scheike, T., & de Uña‐Álvarez, J. (2017). Direct modeling of +regression effects for transition probabilities in the progressive +illness–death model. \strong{Statistics in Medicine}, 36(12), 1964-1976. + +Azarang L, Giorgi R. (2021). Estimation of covariate effects on net +survivals in the relative survival progressive illness-death model. +\strong{Statistical Methods in Medical Research}, 30(6), 1538-1553. +doi:10.1177/09622802211003608 +}