chore: cran changes (#70)

* docs: provide a more detailed description of the package

* fix: formatting

* docs: editted description

* docs: added return value

* docs: re-written return text to be more accurate

* docs: rebuilt site

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: dsTidyverse
 Type: Package
-Title: DataSHIELD Tidyverse Serverside Package
+Title: 'DataSHIELD' Tidyverse Serverside Package
 Version: 1.0.0
 Authors@R:
     c(
@@ -22,7 +22,7 @@ Authors@R:
             role = c("aut"))
        )
 Maintainer: Tim Cadman <[email protected]>
-Description: DataSHIELD serverside implementation of Tidyverse packages.
+Description: This package implements selected <['Tidyverse']https://www.tidyverse.org/> functions within <['DataSHIELD']https://datashield.org/>, an open-source federated analysis solution in R. DataSHIELD currently provides limited tools for data manipulation. This package enhances the researcher experience by introducing essential functions for tasks such as subsetting, filtering, grouping, and renaming variables, improving data management capabilities within the DataSHIELD framework.
 License: LGPL (>= 2.1)
 Encoding: UTF-8
 LazyData: true

R/arrangeDS.R

@@ -5,8 +5,7 @@
 #' order.
 #' @param .by_group If TRUE, will sort first by grouping variable. Applies to grouped data frames
 #' only.
-#' @return the object specified by the \code{newobj} argument of \code{ds.arrange} which is written
-#' to the serverside.
+#' @return An object of the same type as \code{df.name}, typically a data frame or tibble.
 #' @export
 arrangeDS <- function(tidy_expr, df.name, .by_group) {
   checkPermissivePrivacyControlLevel(c('permissive', 'banana'))

R/asTibbleDS.R

@@ -19,8 +19,7 @@
 #'     into this column and the \code{row.names} attribute is deleted. No name repair is applied
 #'     to the new column name, even if \code{x} already contains a column of that name.
 #'   }
-#' @return the object specified by the \code{newobj} argument of \code{ds.as_tibble} which is
-#' written to the serverside.
+#' @return A tibble.
 #' @export
 asTibbleDS <- function(tidy_expr, x, .rows, .name_repair, rownames) {
   other_args <- .paste_character_args(.rows, .name_repair, rownames)

R/bindColsDS.R

@@ -5,8 +5,7 @@
 #' columns will be filled with NA.
 #' @param .name_repair One of "unique", "universal", or "check_unique". See
 #' \code{vctrs::vec_as_names()} for the meaning of these options.
-#' @return A serverside data frame with name specified in \code{newobj} and the same type as the
-#' first element of \code{to_combine}.
+#' @return A data frame the same type as the first element of \code{to_combine}
 #' @export
 bindColsDS <- function(to_combine = NULL, .name_repair = NULL) {
   checkPermissivePrivacyControlLevel(c('permissive', 'banana'))

R/bindRowsDS.R

@@ -6,8 +6,7 @@
 #' @param .id he name of an optional identifier column. Provide a string to create an output column
 #' that identifies each input. The column will use names if available, otherwise it will use
 #' positions.
-#' @return A serverside data frame with name specified in \code{newobj} and the same type as the
-#' first element of \code{to_combine}.
+#' @return A data frame the same type as the first element of \code{to_combine}
 #' @export
 bindRowsDS <- function(to_combine = NULL, .id = NULL) {
   checkPermissivePrivacyControlLevel(c('permissive', 'banana'))

R/caseWhenDS.R

@@ -11,8 +11,7 @@
 #' @param .default The value used when all of the LHS inputs return either FALSE or NA.
 #' @param .ptype An optional prototype declaring the desired output type. If supplied, this overrides the common type of true, false, and missing.
 #' @param .size An optional size declaring the desired output size. If supplied, this overrides the size of condition.
-#' @return the object specified by the \code{newobj} argument of \code{ds.case_when} which is
-#' written to the serverside.
+#' @return A vector with the same size as the common size computed from the inputs in \code{tidy_expr} and the same type as the common type of the RHS inputs in \code{tidy_expr}.
 #' @export
 caseWhenDS <- function(tidy_expr = NULL, .default = NULL, .ptype = NULL, .size = NULL) {
   checkPermissivePrivacyControlLevel(c('permissive', 'banana', 'avacado'))

R/distinctDS.R

@@ -3,17 +3,18 @@
 #' @param tidy_expr Optional variables to use when determining uniqueness. If there are multiple rows for
 #' a given combination of inputs, only the first row will be preserved. If omitted, will use all
 #' variables in the data frame.
-#' @param .data A data frame, data frame extension (e.g. a tibble), or a lazy data frame
+#' @param df.name A data frame, data frame extension (e.g. a tibble), or a lazy data frame
 #' (e.g. from dbplyr or dtplyr).
-#' @param .keep_all If TRUE, keep all variables in .data. If a combination of expr is not distinct,
+#' @param .keep_all If TRUE, keep all variables in df.name If a combination of expr is not distinct,
 #' this keeps the first row of values.
+#' @return An object of the same type as \code{df.name}, typically a data frame or tibble.
 #' @export
-distinctDS <- function(tidy_expr, .data, .keep_all) {
+distinctDS <- function(tidy_expr, df.name, .keep_all) {
   checkPermissivePrivacyControlLevel(c('permissive', 'banana'))
   tidy_expr <- .decode_tidy_eval(tidy_expr, .get_encode_dictionary())
   other_args <- .paste_character_args(.keep_all)
-  call <- .make_tidyverse_call(.data, "distinct", tidy_expr, other_args)
+  call <- .make_tidyverse_call(df.name, "distinct", tidy_expr, other_args)
   out <- .execute_with_error_handling("distinct", call)
-  .check_subset_disclosure_risk(eval(parse(text = .data)), out)
+  .check_subset_disclosure_risk(eval(parse(text = df.name)), out)
   return(out)
 }

R/filterDS.R

@@ -8,8 +8,7 @@
 #' an alternative to \code{group_by}.
 #' @param .preserve Relevant when the df.name input is grouped. If .preserve = FALSE (the default),
 #' the grouping structure is recalculated based on the resulting data, otherwise the grouping is kept as is.
-#' @return the object specified by the \code{newobj} argument of \code{ds.filter} which is written
-#' to the serverside.
+#' @return An object of the same type as \code{df.name}, typically a data frame or tibble.
 #' @export
 filterDS <- function(tidy_expr, df.name, .by, .preserve) {
   checkPermissivePrivacyControlLevel(c('permissive', 'banana'))

R/groupByDS.R

@@ -7,8 +7,8 @@
 #' the existing groups, use .add = TRUE.
 #' @param .drop Drop groups formed by factor levels that don't appear in the data? The default is
 #' TRUE except when df.name has been previously grouped with .drop = FALSE.
-#' @return the object specified by the \code{newobj} argument of \code{ds.group_by} which is written
-#' to the serverside.
+#' @return A grouped data frame with class grouped_df, unless the combination of \code{tidy_expr}
+#' and \code{.add} yields a empty set of grouping columns, in which case a tibble will be returned.
 #' @export
 groupByDS <- function(tidy_expr, df.name, .add, .drop) {
   checkPermissivePrivacyControlLevel(c('permissive', 'banana'))
@@ -24,8 +24,7 @@ groupByDS <- function(tidy_expr, df.name, .add, .drop) {
 #' @description DataSHIELD implentation of \code{dplyr::ungroup}.
 #' @param tidy_expr Unused in this function.
 #' @param x A tibble.
-#' @return the object specified by the \code{newobj} argument of \code{ds.ungroup} which is written
-#' to the serverside.
+#' @return An ungrouped data frame or tibble.
 #' @export
 ungroupDS <- function(tidy_expr, x) {
   .check_data_name_length(x, listDisclosureSettingsDS())

R/groupKeysDS.R

@@ -2,7 +2,7 @@
 #' @description DataSHIELD implentation of \code{dplyr::group_keys}
 #' @param tidy_select Unused in this function.
 #' @param x a grouped tibble.
-#' @return A tibble describing the groups is returned to the client.
+#' @return A data frame describing the groups.
 #' @export
 groupKeysDS <- function(tidy_select, x) {
   dsBase::checkPermissivePrivacyControlLevel(c('permissive', 'banana'))

R/ifElseDS.R

@@ -6,7 +6,7 @@
 #' @param missing If not NULL, will be used as the value for NA values of condition. Follows the same size and type rules as true and false.
 #' @param ptype An optional prototype declaring the desired output type. If supplied, this overrides the common type of true, false, and missing.
 #' @param size An optional size declaring the desired output size. If supplied, this overrides the size of condition.
-#' @return the object specified by the \code{newobj} argument of \code{ds.if_else} which is written to the serverside.
+#' @return A vector with the same size as \code{condition} and the same type as the common type of \code{true}, \code{false}, and \code{missing}.
 #' @export
 ifElseDS <- function(condition = NULL, true = NULL, false = NULL, missing = NULL,
                      ptype = NULL, size = NULL) {

R/mutateDS.R

@@ -15,8 +15,7 @@
 #' to add to the right hand side). See \code{relocate} for more details.
 #' @param .after <tidy-select> Optionally, control where new columns should appear (the default is
 #' to add to the right hand side). See \code{relocate} for more details.
-#' @return the object specified by the \code{newobj} argument of \code{ds.mutate} which is written
-#' to the serverside.
+#' @return An object of the same type as \code{df.name}, typically a data frame or tibble.
 #' @export
 mutateDS <- function(tidy_expr, df.name, .keep = NULL, .before = NULL, .after = NULL) {
   checkPermissivePrivacyControlLevel(c('permissive', 'banana', 'avacado'))

R/renameDS.R

@@ -2,10 +2,8 @@
 #' @description DataSHIELD implentation of\code{dplyr::rename}.
 #' @param df.name A data frame or tibble.
 #' @param tidy_expr list containing diffused expression.
-#' @return the object specified by the \code{newobj} argument of \code{ds.rename} which is written
-#' to the serverside.
+#' @return An object of the same type as \code{df.name}, typically a data frame or tibble.
 #' @export
-#'
 renameDS <- function(tidy_expr, df.name) {
   tidy_expr <- .decode_tidy_eval(tidy_expr, .get_encode_dictionary())
   .check_tidy_disclosure(df.name, tidy_expr)

R/selectDS.R

@@ -3,8 +3,7 @@
 #' @details Performs dplyr select
 #' @param df.name A data frame or tibble.
 #' @param tidy_expr One or more unquoted expressions separated by commas.
-#' @return the object specified by the \code{newobj} argument of \code{ds.select} which is written
-#' to the serverside.
+#' @return An object of the same type as \code{df.name}, typically a data frame or tibble.
 #' @export
 selectDS <- function(tidy_expr, df.name) {
   tidy_expr <- .decode_tidy_eval(tidy_expr, .get_encode_dictionary())

R/sliceDS.R

@@ -10,8 +10,7 @@
 #' @param .preserve Relevant when the df.name input is grouped. If .preserve = FALSE (the default),
 #' the grouping structure is recalculated based on the resulting data, otherwise the grouping is
 #' kept as is.
-#' @return the object specified by the \code{newobj} argument of \code{ds.slice} which is written
-#' to the serverside.
+#' @return An object of the same type as \code{df.name}, typically a data frame or tibble.
 #' @export
 sliceDS <- function(tidy_expr, df.name, .by, .preserve) {
   checkPermissivePrivacyControlLevel(c('permissive', 'banana'))

R/utils.R

@@ -450,10 +450,9 @@ listPermittedTidyverseFunctionsDS <- function() {
 #' @param privacyControlLevels is a vector of strings which contains the privacy control level names which are permitted by the calling method.
 #' @importFrom cli cli_abort
 #' @author Wheater, Dr SM., DataSHIELD Team.
+#' @return Returns an error if the method is not permitted; otherwise, no value is returned.
 #' @export
-#'
 checkPermissivePrivacyControlLevel <- function(privacyControlLevels){
-
   disclosureSettings <- listDisclosureSettingsDS()
   if (is.null(disclosureSettings) || is.null(disclosureSettings$datashield.privacyControlLevel) ||
       (! any(disclosureSettings$datashield.privacyControlLevel %in% privacyControlLevels))) {