Merge pull request #142 from timcadman/feat/deprecate

deprecate functions

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: dsHelper
 Type: Package
 Title: Helper Functions for Use with 'DataSHIELD'
-Version: 1.5.2
+Version: 1.6.0
 Description: Often we need to automate things with 'DataSHIELD'. These functions help to do that.
 Authors@R: 
   c(person(given= "Tim", 
@@ -35,7 +35,8 @@ Imports:
   checkmate,
   lme4, 
   tidyselect, 
-  arrow (>= 16.1.0)
+  arrow (>= 16.1.0), 
+  lifecycle
 Suggests:
   knitr,
   rmarkdown,
@@ -50,4 +51,5 @@ BugReports: https://github.com/lifecycle-project/ds-helper/issues/
 VignetteBuilder: knitr
 License: GPL-3
 Encoding: UTF-8
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
+Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -125,6 +125,7 @@ importFrom(dsBaseClient,ds.summary)
 importFrom(dsBaseClient,ds.table)
 importFrom(dsBaseClient,ds.tapply)
 importFrom(dsBaseClient,ds.tapply.assign)
+importFrom(lifecycle,deprecated)
 importFrom(magrittr,"%<>%")
 importFrom(metafor,rma)
 importFrom(metafor,rma.uni)

R/cast-cols.R

@@ -1,9 +1,11 @@
 #' Casts column classes of a table
 #'
-#' This function allows you to specify the desired classes for a some variables
-#' of a dataframe. The resulting dataframe will have the same column order as
-#' the input one. If multiple columns are to be casted but only one objective class
-#' is provided, it will be reused for all the selected columns.
+#' @description 
+#' `r lifecycle::badge("deprecated")`
+#' 
+#' This function allowed you to change the class of variables within a data frame. It was depricated
+#' because you can now use \code{dsTidyverseClient::ds.mutate()} which is much quicker and has greater
+#' flexibility.
 #'
 #' @template df
 #' @param target_vars Character vector specifying which columns are to be casted to new classes.
@@ -14,10 +16,11 @@
 #' @importFrom dsBaseClient ds.asFactor ds.asCharacter ds.asNumeric ds.asInteger ds.colnames ds.dim ds.rep ds.dataFrameSubset ds.cbind
 #' @importFrom DSI datashield.connections_find
 #' @importFrom utils tail
-#'
 #' @return Tibble with a summary of the successful and failed casts
+#' @keywords internal
 #' @export
 dh.columnCast <- function(df = NULL, target_vars = NULL, target_class = NULL, conns = NULL, checks = TRUE) {
+  lifecycle::deprecate_warn("1.6.0", "dh.columnCast()", "dsTidyverseClient::ds.mutate()")
   if (is.null(df)) {
     stop("`df` must not be NULL.", call. = FALSE)
   }

R/define-cases.R

@@ -1,12 +1,12 @@
 #' Indicates whether each subject has any or all of the variables contained
 #' within a set
 #'
-#' In an analysis you may want to subset your dataset to contain only subjects
-#' meeting a specific criteria, e.g. data on at least one outcome or data on all
-#' exposures. This function automates this operation by describing whether a
-#' subject has non-missing values for any or all of a set of given variables.
-#'
-#' This function replaces the deprecated dh.subjHasData.
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#' 
+#' This function allowed you to describe whether a had non-missing values for a set of variables. It 
+#' was depricated because you can now use \code{dsTidyverseClient::ds.filter()} to create a subset
+#' of a data frame matching multiple conditions.
 #'
 #' @template conns
 #' @template df
@@ -22,17 +22,16 @@
 #' `vars` and `type`. 1 indicates that criteria were met, 0 indicates that
 #' criteria weren't met.
 #'
-#' @family descriptive functions
-#'
 #' @importFrom dsBaseClient ds.Boole ds.make ds.asNumeric ds.replaceNA
 #' @importFrom DSI datashield.connections_find
 #' @importFrom purrr map
 #' @importFrom dplyr %>%
 #' @importFrom rlang arg_match
-#'
+#' @keywords internal
 #' @export
 dh.defineCases <- function(df = NULL, vars = NULL, type = NULL, new_obj = NULL,
                            conns = NULL, checks = FALSE, newobj = NULL) {
+  lifecycle::deprecate_warn("1.6.0", "dh.defineCases()", "dsTidyverseClient::ds.filter()")
   if (is.null(df)) {
     stop("`df` must not be NULL.", call. = FALSE)
   }

R/drop-cols.R

@@ -1,8 +1,11 @@
 #' Removes columns from a serverside data frame
 #'
-#' Often we want to remove variables from a dataframe. This function
-#' allows you to specify the variables you either want to remove or keep and
-#' and creates a new dataframe with only the required variables.
+#' @description 
+#' `r lifecycle::badge("deprecated")`
+#' 
+#' This function allowed you to subset a data frame by column names. It was deprecated
+#' because you can now use \code{dsTidyverseClient::ds.select()} which is much quicker and has greater
+#' flexibility.
 #'
 #' @template conns
 #' @template df
@@ -15,11 +18,8 @@
 #' kept in the data frame and all others are removed.
 #' @template checks
 #' @param new_df_name Retired argument name. Please use `new_obj' instead.
-#'
+#' @keywords internal
 #' @return Server-side data frame the specified subset of columns.
-#'
-#' @family data manipulation functions
-#'
 #' @importFrom dsBaseClient ds.asNumeric ds.colnames ds.dataFrameSubset ds.make
 #' @importFrom purrr imap map
 #' @importFrom dplyr %>%
@@ -29,6 +29,7 @@
 #' @export
 dh.dropCols <- function(df = NULL, vars = NULL, new_obj = NULL, type = NULL,
                         conns = NULL, checks = TRUE, new_df_name = NULL) {
+  lifecycle::deprecate_warn("1.6.0", "dh.dropCols()", "dsTidyverseClient::ds.select()")
   . <- NULL
 
   if (is.null(conns)) {

R/dsHelper-defunct.R

@@ -2,7 +2,7 @@
 #' @description The functions listed below are defunct and no longer available.
 #' When possible, alternative functions with similar functionality are
 #' mentioned. Help pages for deprecated functions are available at
-#' \code{help("<function>-defunct")}.
+#' `help("<function>-defunct")`.
 #' @name dsHelper-defunct
 #' @keywords internal
 NULL

R/dsHelper-package.R

@@ -0,0 +1,7 @@
+#' @keywords internal
+"_PACKAGE"
+
+## usethis namespace: start
+#' @importFrom lifecycle deprecated
+## usethis namespace: end
+NULL

R/make-age-polys.R

@@ -1,9 +1,14 @@
 #' Produces multiple transformations of the age term for fractional polynomial
 #' analyses
 #'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#' 
 #' When we do trajectory analyses using fractional polynomials we often want
 #' to try models with different combinations of age polynomials. This function
-#' creates multiple transformations of an age variable to different powers.
+#' creates multiple transformations of an age variable to different powers. We recommend moving to 
+#' \code{dsTidyverseClient::ds.mutate()} which is quicker, although would require a few more lines 
+#' of code.
 #'
 #' @template conns
 #' @template df
@@ -31,6 +36,7 @@ dh.makeAgePolys <- function(df = NULL, age_var = NULL,
                             poly_form = c("^-2", "^-1", "^-0.5", "log", "^0.5", "^2", "^3"),
                             poly_names = c("_m_2", "_m_1", "_m_0_5", "log", "_0_5", "_2", "_3"),
                             conns = NULL, checks = TRUE, agevars = NULL) {
+  lifecycle::signal_stage("superseded", "dh.makeAgePolys()")
   df <- df
   if (is.null(df)) {
     stop("`df` must not be NULL.", call. = FALSE)

R/make-excluded-df.R

@@ -1,8 +1,12 @@
 #' Given df-A & df-B, creates a new df which is the rows in A but not in B
 #'
-#' When writing a paper often we need to exclude various participants for
-#' various reasons. Then we will need a df with all of these excluded
-#' participants. This is one way to do it.
+#' @description 
+#' `r lifecycle::badge("deprecated")`
+#' 
+#' Often we need to exclude participants in an analysis. This function created a 
+#' dataframe containing participants in \code{original_df} but not in \code{final_df}. It was 
+#' deprecated because you can now use \code{dsTidyverseClient::ds.filter}, which is much quicker
+#' and more flexible.
 #'
 #' @param original_df Dataframe containing the full sample
 #' @param final_df Dataframe containing the included sample
@@ -11,15 +15,14 @@
 #' @template id_var
 #' @template new_obj
 #' @template conns
-#'
 #' @return Creates a serverside dataframe containing the rows from `original_df`
 #' that are not contained in `final_df`
-#'
 #' @importFrom utils head
-#'
+#' @keywords internal
 #' @export
 dh.makeExcludedDf <- function(original_df, final_df, id_var = "child_id", new_obj,
                               type = "wide", conns = NULL) {
+  lifecycle::deprecate_warn("1.6.0", "dh.makeExcludedDf()", "dsTidyverseClient::ds.filter()")
   if (is.null(conns)) {
     conns <- datashield.connections_find()
   }

R/make-iqr.R

@@ -2,7 +2,7 @@
 #'
 #' This function scales variables by their interquartile range. IQR is
 #' calulcated either within cohort or using the combined IQR across cohorts.
-#' The formula used is: value[subject] / (75th percentile - 25th percentile).
+#' The formula used is: value_subject / (75th percentile - 25th percentile).
 #'
 #' @template df
 #' @param vars Character vector of columns within `df` to transform.

R/make-outcome.R

@@ -1,33 +1,13 @@
-#' This was the original version of dh.makeStrata. It has now been deprecated.
-#'
-#' dh.makeStrata contains a number of improvements: it is computationally more
-#' efficient, it is more clearly coded, and it has been more thoroughly tested.
-#'
-#' @param df See argument `df` in `dh.makeStrata`.
-#' @param outcome Renamed to `var_to_subset` in `dh.makeStrata`
-#' @param age_var See argument `age_var` in `dh.makeStrata`.
-#' @param bands See argument `df` in `dh.makeStrata`
-#' @param mult_action See argument `mult_action` in `dh.makeStrata`
-#' @param mult_vals See argument `mult_vals` in `dh.makeStrata`
-#' @param keep_original Argument no longer in use in `dh.makeStrata`
-#' @param df_name Renamed to `new_obj` in `dh.makeStrata`
-#' @param conns See argument `conns` in `dh.makeStrata`
-#' @param id_var See argument `id_var` in `dh.makeStrata`
-#' @param band_action See argument `band_action` in `dh.makeStrata`
-#'
-#' @name dh.makeOutcome-defunct
-#' @usage dh.meanByAge(df, outcome, age_var, bands, mult_action, mult_vals,
-#' keep_original, df_name, conns, id_var, band_action)
+#' Group and subset a data frame 
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#' 
+#' This was an early version of dh.makeStrata, which has in turn been deprecated in favour of 
+#'  \code{dsTidyverseClient::ds.arrange() |> dsTidyverseClient::ds.group_by() |> 
+#' dsTidyverseClient::ds.slice()}.
 #' @keywords internal
-#' @noRd
-NULL
-
-#' @rdname dsHelper-defunct
-#' @section \code{dh.makeOutcome}:
-#' For \code{dh.makeOutcome}, use \code{\link{dh.makeStrata}}.
-#'
 #' @export
 dh.makeOutcome <- function(...) {
-  .Defunct(msg = "`dh.makeOutcome` has been removed from this package.
-    Use `dh.makeStrata` instead. See help('Defunct')")
+  lifecycle::deprecate_stop("1.6.0", "dh.makeOutcome()", details = "Please use the following functions 
+                            from dsTidyverseClient: ds.arrange(), ds.group_by() and ds.slice()")
 }

R/make-strata.R

@@ -1,26 +1,13 @@
 #' Creates strata of a repeated measures variable within specified age or time
 #' bands
 #'
-#' For many analyses you may want to create strata of repeated measures data
-#' within specified bands. For example, you may have BMI measures between ages
-#' 0-18, but want to create a variable for each subject which is their BMI
-#' between ages 9-11. This function automates this process.
-#'
-#' The steps here are equivalent to the following dplyr chain:
-#'
-#' df %>%
-#' group_by(band, id) %>%
-#' arrange() %<%
-#' slice(1)
-#'
-#' One of the complexities of this operation is how to deal with cases where
-#' subjects have multiple observations within a specified band. This is handled
-#' by first sorting the group so that the required value is first. When the
-#' data is reshaped to wide format all but the first value for subjects with
-#' multiple observations within a band are dropped.
-#'
-#' Note that for big datasets this will take a long time to run.
-#'
+#' @description 
+#' `r lifecycle::badge("deprecated")`
+#' 
+#' This function attempted to replicate the process of \code{dplyr::arrange() |> dplyr::group_by() |> 
+#' dplyr::sort()}. It was deprecated because the same operation can be done much more quickly and flexibly
+#' using \code{dsTidyverseClient::ds.arrange() |> dsTidyverseClient::ds.group_by() |> 
+#' dsTidyverseClient::ds.slice()}.
 #' @template df
 #' @template id_var
 #' @param var_to_subset Character specifying variable in `df` to stratify
@@ -64,8 +51,6 @@
 #' added to the data frame representing these variables within the strata
 #' created.
 #'
-#' @family data manipulation functions
-#'
 #' @importFrom dsBaseClient ds.colnames ds.asNumeric ds.assign ds.Boole
 #'             ds.dataFrame ds.ls ds.make ds.dataFrameSort ds.dataFrameSubset
 #'             ds.listDisclosureSettings ds.mean ds.merge ds.reShape ds.isNA
@@ -77,13 +62,14 @@
 #' @importFrom magrittr %<>%
 #' @importFrom DSI datashield.connections_find
 #' @importFrom rlang :=
-#'
+#' @keywords internal
 #' @md
-#'
 #' @export
 dh.makeStrata <- function(df = NULL, id_var = NULL, age_var = NULL, var_to_subset = NULL, bands = NULL, # nolint
                           mult_action = NULL, mult_vals = NULL, keep_vars = NULL, new_obj = NULL,
                           band_action = NULL, conns = NULL, checks = TRUE, df_name = NULL) {
+  lifecycle::deprecate_warn("1.6.0", "dh.dropCols()", details = "Please use the following functions 
+                            from dsTidyverseClient: ds.arrange(), ds.group_by() and ds.slice()")
   op <- tmp <- dfs <- new_subset_name <- value <- cohort <- varname <- new_df_name <-
     available <- bmi_to_subset <- ref_val <- enough_obs <- boole_name <- subset_name <- wide_name <-
     end_objs <- . <- nearest_value <- age <- subset_short <- suffix <- value_1 <- value_2 <- Var1 <-

R/mean-by-age.R

@@ -17,8 +17,8 @@
 NULL
 
 #' @rdname dsHelper-defunct
-#' @section \code{dh.meanByAge}:
-#' For \code{dh.meanByAge}, use \code{\link{dh.meanByGroup}}.
+#' @section `dh.meanByAge`:
+#' For `dh.meanByAge`, use [dh.meanByGroup()].
 #'
 #' @export
 dh.meanByAge <- function(...) {

R/rename-vars.R

@@ -1,7 +1,10 @@
 #' Rename one or more columns within a serverside data frame
 #'
-#' This function is an analogue of `dplyr::rename` which allows you to rename
-#' columns of a serverside data frame.
+#' @description 
+#' `r lifecycle::badge("deprecated")`
+#' 
+#' This function was an analogue of \code{dplyr::rename()}. It was deprecated because you can now use
+#' \code{dsTidyverseClient::ds.rename()} which is much quicker and more flexible.
 #'
 #' @template conns
 #' @template df
@@ -11,16 +14,14 @@
 #' @template checks
 #' @return Data frame specified in `df` is returned server-side with variables
 #' renamed.
-#'
 #' @importFrom dsBaseClient ds.assign ds.dataFrame
 #' @importFrom purrr map pmap
 #' @importFrom DSI datashield.connections_find
-#'
-#' @family data manipulation functions
-#'
+#' @keywords internal
 #' @export
 dh.renameVars <- function(df = NULL, current_names = NULL, new_names,
                           conns = NULL, checks = TRUE) {
+  lifecycle::deprecate_warn("1.6.0", "dh.renameVars()", "dsTidyverseClient::ds.rename()")
   if (is.null(df)) {
     stop("`df` must not be NULL.", call. = FALSE)
   }

R/subj-has-data.R

@@ -1,6 +1,11 @@
-#' This was an old version of dh.defineCases which is now defunct
-#'
+#' Identify subjects with available data
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#' 
+#' This was an early version of \code{dh.defineCases()} which has in turn been deprecated. Please 
+#' use \code{dsTidyverseClient::ds.filter()}
+#' @keywords internal
 #' @export
 dh.subjHasData <- function() {
-  .Defunct("dh.defineCases")
+  lifecycle::deprecate_stop("1.6.0", "dh.subjHasData()", "dsTidyverseClient::ds.filter()")
 }