diff --git a/NEWS.md b/NEWS.md index 6f436f17..284042a6 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,11 @@ # cardx 0.2.1.9008 +* Implemented `summary(extend=TRUE)` in `ard_survival_survfit()` to return results for time points out of bounds. (#224) + +* Added a `data.frame` method to `ard_survival_survfit()`. + +* Added a warning for incorrect formula type to `ard_survival_survfit()`. (#223) + # cardx 0.2.1 ## New Features and Updates diff --git a/R/ard_survival_survfit.R b/R/ard_survival_survfit.R index 461e1773..02d2dd44 100644 --- a/R/ard_survival_survfit.R +++ b/R/ard_survival_survfit.R @@ -34,28 +34,23 @@ #' @inheritParams rlang::args_dots_empty #' #' @section Formula Specification: +#' When passing a [`survival::survfit()`] object to `ard_survival_survfit()`, +#' the `survfit()` call must use an evaluated formula and not a stored formula. +#' Including a proper formula in the call allows the function to accurately +#' identify all variables included in the estimation. See below for examples: #' -#' The `x` argument can accepts a [survival::survfit()] object, which must be created from a formula or previously -#' fitted model. In order to identify the underlying variable names when processing this formula, it must be supplied -#' directly to [survival::survfit()] rather and not taken from a variable. For example, `x` can be constructed and -#' supplied to `ard_survival_survfit()` as follows: -#' ```{r, eval = FALSE} -#' data <- mtcars -#' x <- survival::survfit(survival::Surv(mpg, am) ~ cyl, data = data) -#' -#' ard_survival_survfit(x, times = 25) -#' ``` +#' ```r +#' library(cardx) +#' library(survival) #' -#' Alternatively, a data frame can be passed as `x`, with the formula outcome supplied to `y` and stratification -#' variables passed to `variables`, and the formula will be constructed and passed to [survival::survfit()] within the -#' function. -#' ```{r, eval = FALSE} -#' x <- mtcars -#' y <- "survival::Surv(mpg, am)" -#' variables <- "cyl" +#' # include formula in `survfit()` call +#' survfit(Surv(time, status) ~ sex, lung) |> ard_survival_survfit(time = 500) #' -#' ard_survival_survfit(x, y, variables, times = 25) +#' # you can also pass a data frame to `ard_survival_survfit()` as well. +#' lung |> +#' ard_survival_survfit(y = Surv(time, status), variables = "sex", time = 500) #' ``` +#' You **cannot**, however, pass a stored formula, e.g. `survfit(my_formula, lung)` #' #' @return an ARD data frame of class 'card' #' @name ard_survival_survfit diff --git a/man/ard_survival_survfit.Rd b/man/ard_survival_survfit.Rd index 93e4988e..0d68a851 100644 --- a/man/ard_survival_survfit.Rd +++ b/man/ard_survival_survfit.Rd @@ -70,28 +70,23 @@ survival fit model. } \section{Formula Specification}{ +When passing a \code{\link[survival:survfit]{survival::survfit()}} object to \code{ard_survival_survfit()}, +the \code{survfit()} call must use an evaluated formula and not a stored formula. +Including a proper formula in the call allows the function to accurately +identify all variables included in the estimation. See below for examples: -The \code{x} argument can accepts a \code{\link[survival:survfit]{survival::survfit()}} object, which must be created from a formula or previously -fitted model. In order to identify the underlying variable names when processing this formula, it must be supplied -directly to \code{\link[survival:survfit]{survival::survfit()}} rather and not taken from a variable. For example, \code{x} can be constructed and -supplied to \code{ard_survival_survfit()} as follows: +\if{html}{\out{
}}\preformatted{library(cardx) +library(survival) -\if{html}{\out{
}}\preformatted{data <- mtcars -x <- survival::survfit(survival::Surv(mpg, am) ~ cyl, data = data) +# include formula in `survfit()` call +survfit(Surv(time, status) ~ sex, lung) |> ard_survival_survfit(time = 500) -ard_survival_survfit(x, times = 25) +# you can also pass a data frame to `ard_survival_survfit()` as well. +lung |> + ard_survival_survfit(y = Surv(time, status), variables = "sex", time = 500) }\if{html}{\out{
}} -Alternatively, a data frame can be passed as \code{x}, with the formula outcome supplied to \code{y} and stratification -variables passed to \code{variables}, and the formula will be constructed and passed to \code{\link[survival:survfit]{survival::survfit()}} within the -function. - -\if{html}{\out{
}}\preformatted{x <- mtcars -y <- "survival::Surv(mpg, am)" -variables <- "cyl" - -ard_survival_survfit(x, y, variables, times = 25) -}\if{html}{\out{
}} +You \strong{cannot}, however, pass a stored formula, e.g. \code{survfit(my_formula, lung)} } \examples{