diff --git a/DESCRIPTION b/DESCRIPTION index 68c4e389..7a34def4 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: pammtools Title: Piece-Wise Exponential Additive Mixed Modeling Tools for Survival Analysis -Version: 0.5.93 -Date: 2024-02-24 +Version: 0.6.01 +Date: 2025-01-29 Authors@R: c( person("Andreas", "Bender", , "andreas.bender@stat.uni-muenchen.de", role = c("aut", "cre"), comment=c(ORCID = "0000-0001-5628-8611")), person("Fabian", "Scheipl", , "fabian.scheipl@stat.uni-muenchen.de", role = c("aut"), comment = c(ORCID = "0000-0001-8172-3603")), @@ -16,7 +16,7 @@ Description: The Piece-wise exponential (Additive Mixed) Model including data simulation, transformation and other functions for data preprocessing and model post-processing as well as visualization. Depends: - R (>= 3.5.0) + R (>= 4.1.0) Imports: mgcv, survival (>= 2.39-5), @@ -45,6 +45,6 @@ License: MIT + file LICENSE LazyData: true URL: https://adibender.github.io/pammtools/ BugReports: https://github.com/adibender/pammtools/issues -RoxygenNote: 7.1.2 +RoxygenNote: 7.3.2 Encoding: UTF-8 Roxygen: list(markdown = TRUE) diff --git a/R/add-functions.R b/R/add-functions.R index 94c8555e..d1ceb371 100644 --- a/R/add-functions.R +++ b/R/add-functions.R @@ -71,21 +71,31 @@ add_term <- function( } +#' Create design matrix from a suitable object +#' +#' @keywords internal +#' @param object A suitable object from which a design matrix can be generated. +#' Often a model object. make_X <- function(object, ...) { UseMethod("make_X", object) } +#' @rdname make_X +#' @inherit make_X +#' @param newdata A data frame from which design matrix will be constructed make_X.default <- function(object, newdata, ...) { - X <- model.matrix(object$formula[-2], data = newdata, ...) + model.matrix(object$formula[-2], data = newdata, ...) } +#' @inherit make_X.default +#' @rdname make_X make_X.gam <- function(object, newdata, ...) { - X <- predict.gam(object, newdata = newdata, type = "lpmatrix", ...) + predict.gam(object, newdata = newdata, type = "lpmatrix", ...) } diff --git a/R/get-cut-points.R b/R/get-cut-points.R index 168f5ab1..6f9b0c22 100644 --- a/R/get-cut-points.R +++ b/R/get-cut-points.R @@ -41,6 +41,8 @@ get_cut.default <- function( } +#' @rdname get_cut +#' @inherit get_cut get_cut.list <- function ( data, formula, diff --git a/R/ggplot-extensions.R b/R/ggplot-extensions.R index a3e7854a..ae89ee95 100644 --- a/R/ggplot-extensions.R +++ b/R/ggplot-extensions.R @@ -11,8 +11,6 @@ #' @seealso #' \code{\link[ggplot2]{geom_ribbon}} \code{geom_stepribbon} #' inherits from \code{geom_ribbon}. -#' @inheritParams ggplot2:::geom_ribbon -#' @inheritParams ggplot2:::geom_step #' @examples #' library(ggplot2) #' huron <- data.frame(year = 1875:1972, level = as.vector(LakeHuron)) @@ -23,6 +21,8 @@ #' geom_line(aes(y = level)) #' @rdname geom_stepribbon #' @importFrom ggplot2 layer GeomRibbon +#' @inheritParams ggplot2::geom_step +#' @inheritParams ggplot2::geom_ribbon #' @export geom_stepribbon <- function( mapping = NULL, diff --git a/R/interval-information.R b/R/interval-information.R index 3cf16665..121f7bea 100644 --- a/R/interval-information.R +++ b/R/interval-information.R @@ -39,21 +39,20 @@ int_info.default <- function( if (is.unsorted(x)) { x <- sort(x) } - if (min(x != 0)) { + if (min(x) != 0) { x <- c(0, x) } - intlen <- diff(x) tstart <- x[-length(x)] - tend <- tstart + intlen + tend <- x[-1] tdf <- data.frame( tstart = tstart, tend = tend, - intlen = intlen) %>% + intlen = tend - tstart) %>% mutate( - intmid = tstart + intlen / 2, - interval = paste0("(", tstart, ",", tend, "]"), + intmid = .data$tstart + .data$intlen / 2, + interval = paste0("(", .data$tstart, ",", .data$tend, "]"), interval = factor(.data$interval, levels = unique(.data$interval)) ) @@ -155,7 +154,7 @@ get_intervals.default <- function( int_df <- int_info(x) int <- findInterval( x = times, - vec = sort(union(int_df$tstart, int_df$tend)), + vec = c(int_df$tstart[1], int_df$tend), left.open = left.open, rightmost.closed = rightmost.closed) diff --git a/R/pammtools.R b/R/pammtools.R index 7c335d7d..8fe75a52 100644 --- a/R/pammtools.R +++ b/R/pammtools.R @@ -50,6 +50,6 @@ #' #' Bender, Andreas, and Fabian Scheipl. 2018. #' “pammtools: Piece-Wise Exponential Additive Mixed Modeling Tools.” -#' ArXiv:1806.01042 [Stat], June. https://arxiv.org/abs/1806.01042. -NULL +#' ArXiv:1806.01042 Stat, June. https://arxiv.org/abs/1806.01042. +"_PACKAGE" NULL diff --git a/R/warnings.R b/R/warnings.R index a3e30501..64261c41 100644 --- a/R/warnings.R +++ b/R/warnings.R @@ -7,23 +7,27 @@ warn_about_new_time_points <- function(object, newdata, ...) { } - +#' @inherit warn_about_new_time_points +#' @keywords internal warn_about_new_time_points.glm <- function(object, newdata, time_var, ...) { is_pam <- inherits(object, "gam") - if(is_pam & is.null(object$model)){ + if (is_pam && is.null(object$model)) { return(invisible()) } original_intervals <- if (is_pam) { unique(model.frame(object)[[time_var]]) - } else levels(model.frame(object)[[time_var]]) + } else { + levels(model.frame(object)[[time_var]]) + } prediction_intervals <- if (is_pam) { unique(newdata[[time_var]]) - } else levels(factor(newdata[[time_var]])) + } else { + levels(factor(newdata[[time_var]])) + } new_ints <- which(!(prediction_intervals %in% original_intervals)) - n_out <- pmin(10, length(new_ints)) if (length(new_ints)) { message <- paste0( "Time points/intervals in new data not equivalent to time points/intervals during model fit.", diff --git a/man/dplyr_verbs.Rd b/man/dplyr_verbs.Rd index 4d98021d..ca8e9d2b 100644 --- a/man/dplyr_verbs.Rd +++ b/man/dplyr_verbs.Rd @@ -97,10 +97,6 @@ the input. Weights are automatically standardised to sum to 1.} \item{.env}{DEPRECATED.} -\item{y}{A pair of data frames, data frame extensions (e.g. a tibble), or -lazy data frames (e.g. from dbplyr or dtplyr). See \emph{Methods}, below, for -more details.} - \item{by}{A join specification created with \code{\link[dplyr:join_by]{join_by()}}, or a character vector of variables to join by. diff --git a/man/geom_hazard.Rd b/man/geom_hazard.Rd index 0fc1f85b..00f1be7b 100644 --- a/man/geom_hazard.Rd +++ b/man/geom_hazard.Rd @@ -65,15 +65,31 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[ggplot2:layer_stats]{layer stat} documentation. +}} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[ggplot2:layer_positions]{layer position} documentation. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} @@ -89,10 +105,33 @@ rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[ggplot2:borders]{borders()}}.} -\item{...}{Other arguments passed on to \code{\link[ggplot2:layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[ggplot2:layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. Please note that while passing +unmapped aesthetics as vectors is technically possible, the order and +required length is not guaranteed to be parallel to the input data. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[ggplot2:layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[ggplot2:draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{direction}{direction of stairs: 'vh' for vertical then horizontal, 'hv' for horizontal then vertical, or 'mid' for step half-way between diff --git a/man/geom_stepribbon.Rd b/man/geom_stepribbon.Rd index f13322d7..4207c3f3 100644 --- a/man/geom_stepribbon.Rd +++ b/man/geom_stepribbon.Rd @@ -39,15 +39,31 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[ggplot2:layer_stats]{layer stat} documentation. +}} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[ggplot2:layer_positions]{layer position} documentation. +}} \item{direction}{direction of stairs: 'vh' for vertical then horizontal, 'hv' for horizontal then vertical, or 'mid' for step half-way between @@ -67,10 +83,33 @@ rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[ggplot2:borders]{borders()}}.} -\item{...}{Other arguments passed on to \code{\link[ggplot2:layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[ggplot2:layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. Please note that while passing +unmapped aesthetics as vectors is technically possible, the order and +required length is not guaranteed to be parallel to the input data. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[ggplot2:layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[ggplot2:draw_key]{key glyphs}, to change the display of the layer in the legend. +}} } \description{ \code{geom_stepribbon} is an extension of the \code{geom_ribbon}, and diff --git a/man/get_cut.Rd b/man/get_cut.Rd index 98df0edd..a3a2b5b2 100644 --- a/man/get_cut.Rd +++ b/man/get_cut.Rd @@ -3,11 +3,22 @@ \name{get_cut} \alias{get_cut} \alias{get_cut.default} +\alias{get_cut.list} \title{Obtain interval break points} \usage{ get_cut(data, formula, cut = NULL, ...) \method{get_cut}{default}(data, formula, cut = NULL, max_time = NULL, event = 1L, ...) + +\method{get_cut}{list}( + data, + formula, + cut = NULL, + max_time = NULL, + event = 1L, + timescale = "gap", + ... +) } \description{ Default method words for data frames. diff --git a/man/get_term.Rd b/man/get_term.Rd index 1eff8c94..f78f8d0a 100644 --- a/man/get_term.Rd +++ b/man/get_term.Rd @@ -14,13 +14,6 @@ first row will be used.} \item{term}{The (non-linear) model term of interest.} -\item{n}{Specify the output sequence either by supplying the -length of the sequence with \code{n}, or the spacing between value -with \code{by}. Specifying both is an error. - -I recommend that you name these arguments in order to make it clear to -the reader.} - \item{...}{Further arguments passed to \code{\link{seq_range}}.} } \description{ diff --git a/man/make_X.Rd b/man/make_X.Rd new file mode 100644 index 00000000..10c5291e --- /dev/null +++ b/man/make_X.Rd @@ -0,0 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/add-functions.R +\name{make_X} +\alias{make_X} +\alias{make_X.default} +\alias{make_X.gam} +\title{Create design matrix from a suitable object} +\usage{ +make_X(object, ...) + +\method{make_X}{default}(object, newdata, ...) + +\method{make_X}{gam}(object, newdata, ...) +} +\arguments{ +\item{object}{A suitable object from which a design matrix can be generated. +Often a model object.} + +\item{newdata}{A data frame from which design matrix will be constructed} +} +\description{ +Create design matrix from a suitable object +} +\keyword{internal} diff --git a/man/pammtools.Rd b/man/pammtools.Rd index 55f93320..fa0779ff 100644 --- a/man/pammtools.Rd +++ b/man/pammtools.Rd @@ -2,6 +2,7 @@ % Please edit documentation in R/pammtools.R \docType{package} \name{pammtools} +\alias{pammtools-package} \alias{pammtools} \title{pammtools: Piece-wise exponential Additive Mixed Modeling tools.} \description{ @@ -54,5 +55,28 @@ Biostatistics 20 (2): 315–31. https://doi.org/10.1093/biostatistics/kxy003. Bender, Andreas, and Fabian Scheipl. 2018. “pammtools: Piece-Wise Exponential Additive Mixed Modeling Tools.” -ArXiv:1806.01042 \link{Stat}, June. https://arxiv.org/abs/1806.01042. +ArXiv:1806.01042 Stat, June. https://arxiv.org/abs/1806.01042. +} +\seealso{ +Useful links: +\itemize{ + \item \url{https://adibender.github.io/pammtools/} + \item Report bugs at \url{https://github.com/adibender/pammtools/issues} +} + +} +\author{ +\strong{Maintainer}: Andreas Bender \email{andreas.bender@stat.uni-muenchen.de} (\href{https://orcid.org/0000-0001-5628-8611}{ORCID}) + +Authors: +\itemize{ + \item Fabian Scheipl \email{fabian.scheipl@stat.uni-muenchen.de} (\href{https://orcid.org/0000-0001-8172-3603}{ORCID}) + \item Philipp Kopper \email{philipp.kopper@stat.uni-muenchen.de} (\href{https://orcid.org/0000-0002-5037-7135}{ORCID}) +} + +Other contributors: +\itemize{ + \item Lukas Burk \email{burk@leibniz-bips.de} (\href{https://orcid.org/0000-0001-7528-3795}{ORCID}) [contributor] +} + } diff --git a/man/rpexp.Rd b/man/rpexp.Rd index a9b44df1..da1ef0ac 100644 --- a/man/rpexp.Rd +++ b/man/rpexp.Rd @@ -8,13 +8,12 @@ rpexp(n = 1, rate = 1, t = 0) } \arguments{ \item{n}{number of observations. If \code{length(n) > 1}, the length is - taken to be the number required.} +taken to be the number required.} \item{rate}{vector of rates.} -\item{t}{vector of the same length as \code{rate}, giving the times at - which the rate changes. The first element of \code{t} should be 0, - and \code{t} should be in increasing order.} +\item{t}{vector of the same length as \code{rate}, giving the times at which +the rate changes. The values of \code{t} should be in increasing order.} } \description{ This is a copy of the same function from \code{rpexp} from package diff --git a/man/warn_about_new_time_points.glm.Rd b/man/warn_about_new_time_points.glm.Rd new file mode 100644 index 00000000..75bb7c52 --- /dev/null +++ b/man/warn_about_new_time_points.glm.Rd @@ -0,0 +1,12 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/warnings.R +\name{warn_about_new_time_points.glm} +\alias{warn_about_new_time_points.glm} +\title{Warn if new t_j are used} +\usage{ +\method{warn_about_new_time_points}{glm}(object, newdata, time_var, ...) +} +\description{ +Warn if new t_j are used +} +\keyword{internal}