From 7228d3280cef90b894ca5261337c579831be5689 Mon Sep 17 00:00:00 2001 From: bms63 Date: Thu, 11 Aug 2022 01:32:18 +0000 Subject: [PATCH] Scenarios added of when to add in functions to certain packages. Cleaned up functions language. Removed dev_util prefix --- R/dev_utilities.R | 17 ++++------ R/quote.R | 19 +++++------ R/remove_these.R | 6 ++-- README.Rmd | 4 +-- _pkgdown.yml | 29 ++++++++++------- man/{dev_util_arg_name.Rd => arg_name.Rd} | 9 ++++++ man/as_name.Rd | 25 +++++++++++++++ man/{dev_util_backquote.Rd => backquote.Rd} | 7 ++-- ...rt_dtm_to_dtc.Rd => convert_dtm_to_dtc.Rd} | 9 ++++++ man/dev_util_quo_c.Rd | 7 ---- man/dquote.Rd | 7 ++-- man/{dev_util_enumerate.Rd => enumerate.Rd} | 7 ++-- ...v_util_extract_vars.Rd => extract_vars.Rd} | 9 ++++++ man/filter_if.Rd | 2 +- ...v_util_notin.Rd => grapes-notin-grapes.Rd} | 9 ++++++ man/negate_vars.Rd | 2 +- ...by_names.Rd => replace_values_by_names.Rd} | 9 ++++++ man/roxygen/meta.R | 3 +- man/{dev_util_squote.Rd => squote.Rd} | 9 +++--- man/vars2chr.Rd | 2 +- tests/testthat/test-quo.R | 4 +++ vignettes/admiraldev.Rmd | 32 ++++++++++++++++--- 22 files changed, 158 insertions(+), 69 deletions(-) rename man/{dev_util_arg_name.Rd => arg_name.Rd} (65%) create mode 100644 man/as_name.Rd rename man/{dev_util_backquote.Rd => backquote.Rd} (79%) rename man/{dev_util_convert_dtm_to_dtc.Rd => convert_dtm_to_dtc.Rd} (71%) rename man/{dev_util_enumerate.Rd => enumerate.Rd} (85%) rename man/{dev_util_extract_vars.Rd => extract_vars.Rd} (68%) rename man/{dev_util_notin.Rd => grapes-notin-grapes.Rd} (67%) rename man/{dev_util_replace_values_by_names.Rd => replace_values_by_names.Rd} (66%) rename man/{dev_util_squote.Rd => squote.Rd} (74%) diff --git a/R/dev_utilities.R b/R/dev_utilities.R index 3c9ff103..10d76242 100644 --- a/R/dev_utilities.R +++ b/R/dev_utilities.R @@ -9,8 +9,7 @@ #' @author Thomas Neitmann #' #' @keywords dev_utility -#' -#' @rdname dev_util_notin +#' @family dev_utility #' @export `%notin%` <- function(x, table) { # nolint !(x %in% table) @@ -26,8 +25,7 @@ #' @author Ondrej Slama #' #' @keywords dev_utility -#' -#' @rdname dev_util_convert_dtm_to_dtc +#' @family dev_utility #' @export convert_dtm_to_dtc <- function(dtm) { stopifnot(lubridate::is.instant(dtm)) @@ -41,8 +39,7 @@ convert_dtm_to_dtc <- function(dtm) { #' @author Thomas Neitmann, Ondrej Slama #' #' @keywords dev_utility -#' -#' @rdname dev_util_arg_name +#' @family dev_utility #' @export arg_name <- function(expr) { # nolint if (length(expr) == 1L && is.symbol(expr)) { @@ -70,8 +67,7 @@ arg_name <- function(expr) { # nolint #' @author Thomas Neitmann #' #' @keywords dev_utility -#' -#' @rdname dev_util_extract_vars +#' @family dev_utility #' @export extract_vars <- function(x, side = "lhs") { if (is.null(x)) { @@ -106,8 +102,8 @@ extract_vars <- function(x, side = "lhs") { #' @author Thomas Neitmann #' #' @keywords dev_utility +#' @family dev_utility #' -#' @rdname dev_util_replace_values_by_names #' #' @return A list of quosures #' @export @@ -131,7 +127,8 @@ replace_values_by_names <- function(quosures) { #' This function is missing in earlier version of {rlang} which is why we re- #' implment it here. #' -#' @noRd +#' @keywords dev_utility +#' @family dev_utility #' @export as_name <- function(x) { if (is_quosure(x)) { diff --git a/R/quote.R b/R/quote.R index 32ce32da..481b295e 100644 --- a/R/quote.R +++ b/R/quote.R @@ -6,10 +6,9 @@ #' #' @author Thomas Neitmann #' -#' @keywords quo -#' @family quo +#' @keywords quote +#' @family quote #' -#' @rdname dev_util_enumerate #' @export enumerate <- function(x, quote_fun = backquote, conjunction = "and") { if (length(x) == 1L) { @@ -29,10 +28,9 @@ enumerate <- function(x, quote_fun = backquote, conjunction = "and") { #' #' @author Thomas Neitmann #' -#' @keywords quo -#' @family quo +#' @keywords quote +#' @family quote #' -#' @rdname dev_util_backquote #' @export backquote <- function(x) { paste0("`", x, "`") @@ -44,10 +42,9 @@ backquote <- function(x) { #' #' @author Thomas Neitmann #' -#' @keywords quo -#' @family quo +#' @keywords quote +#' @family quote #' -#' @rdname dev_util_squote #' @export squote <- function(x) { paste0("'", x, "'") @@ -65,8 +62,8 @@ squote <- function(x) { #' #' @author Stefan Bundfuss #' -#' @keywords quo -#' @family quo +#' @keywords quote +#' @family quote #' @export dquote <- function(x) { if (is.null(x)) { diff --git a/R/remove_these.R b/R/remove_these.R index 7239d252..c2ca9c6b 100644 --- a/R/remove_these.R +++ b/R/remove_these.R @@ -8,7 +8,7 @@ #' #' @export #' -#' @keywords user_utility +#' @keywords remove_utility #' #' @examples #' vars2chr(vars(USUBJID, AVAL)) @@ -34,7 +34,7 @@ vars2chr <- function(quosures) { #' #' @export #' -#' @keywords user_utility +#' @keywords remove_utility #' #' @examples #' negate_vars(vars(USUBJID, STUDYID)) @@ -61,7 +61,7 @@ negate_vars <- function(vars = NULL) { #' #' @export #' -#' @keywords user_utility +#' @keywords remove_utility #' filter_if <- function(dataset, filter) { assert_data_frame(dataset) diff --git a/README.Rmd b/README.Rmd index 0564007d..42559d0b 100644 --- a/README.Rmd +++ b/README.Rmd @@ -43,7 +43,7 @@ ADaM in R Asset Library Development Utilities Tools for developing functions and maintaining a healthy code base within the family of admiral R packages. `{admiraldev}` is intended to be used when developing `{admiral}` or `{admiral}` extension packages. -**NOTE:** Use of this package as a standalone package is currently not recommended. +**NOTE:** This package is not intended for standalone use but rather as a central dependency for all developer utilities of `{admiral}` and its extension packages ## Installation @@ -61,7 +61,7 @@ remotes::install_github("pharmaverse/admiraldev", ref = "devel") ## Release Schedule -`{admiraldev}` is to be official released to CRAN one week before the release of `{admiral}`. You can find the release schedule for `{admiral}` packages [here](https://github.com/pharmaverse/admiral/tree/devel#release-schedule). +`{admiraldev}` is to be officially released to CRAN one week before an official release of `{admiral}`. You can find the release schedule for `{admiral}` packages [here](https://github.com/pharmaverse/admiral/tree/devel#release-schedule). diff --git a/_pkgdown.yml b/_pkgdown.yml index 5465fc11..a846ef3a 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -46,16 +46,26 @@ reference: contents: - has_keyword('test_helper') -- title: Quosure and Quoting Helper Functions - desc: Helping your quoting and quosure needs +- title: Quosure Helper Functions + desc: Helping yourquosure needs contents: - has_keyword('quo') -- title: Developer Utility Functions - desc: General Utilities +- title: Quoting Helper Functions + desc: Helping your quoting needs + contents: + - has_keyword('quote') + +- title: Miscellaneous + desc: Utilities without a theme contents: - has_keyword('dev_utility') +- title: Unsure where these functions should live? + desc: Used with dataset_vignette and a few assert, is and get functions... + contents: + - has_keyword('remove_utility') + navbar: components: reference: @@ -64,18 +74,15 @@ navbar: articles: text: Developer Guides menu: - - text: Overview - text: Development Process href: articles/development_process.html - - text: ------- - - text: "{admiral} development processes" - text: Programming Strategy href: articles/programming_strategy.html - - text: Guidance for git and GitHub Usage - href: articles/git_usage.html - text: Writing Vignettes href: articles/writing_vignettes.html - - text: Pull Request Review Guidance - href: articles/pr_review_guidance.html - text: Unit Test Guidance href: articles/unit_test_guidance.html + - text: Guidance for git and GitHub Usage + href: articles/git_usage.html + - text: Pull Request Review Guidance + href: articles/pr_review_guidance.html diff --git a/man/dev_util_arg_name.Rd b/man/arg_name.Rd similarity index 65% rename from man/dev_util_arg_name.Rd rename to man/arg_name.Rd index f7d2c958..06ffd8e9 100644 --- a/man/dev_util_arg_name.Rd +++ b/man/arg_name.Rd @@ -12,7 +12,16 @@ arg_name(expr) \description{ Extract Argument Name from an Expression } +\seealso{ +Developer Utility Functions: +\code{\link{\%notin\%}()}, +\code{\link{as_name}()}, +\code{\link{convert_dtm_to_dtc}()}, +\code{\link{extract_vars}()}, +\code{\link{replace_values_by_names}()} +} \author{ Thomas Neitmann, Ondrej Slama } +\concept{dev_utility} \keyword{dev_utility} diff --git a/man/as_name.Rd b/man/as_name.Rd new file mode 100644 index 00000000..dd5d9e70 --- /dev/null +++ b/man/as_name.Rd @@ -0,0 +1,25 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/dev_utilities.R +\name{as_name} +\alias{as_name} +\title{Turn a Quosure into a String} +\usage{ +as_name(x) +} +\description{ +Turn a Quosure into a String +} +\details{ +This function is missing in earlier version of {rlang} which is why we re- +implment it here. +} +\seealso{ +Developer Utility Functions: +\code{\link{\%notin\%}()}, +\code{\link{arg_name}()}, +\code{\link{convert_dtm_to_dtc}()}, +\code{\link{extract_vars}()}, +\code{\link{replace_values_by_names}()} +} +\concept{dev_utility} +\keyword{dev_utility} diff --git a/man/dev_util_backquote.Rd b/man/backquote.Rd similarity index 79% rename from man/dev_util_backquote.Rd rename to man/backquote.Rd index c05dc131..508c86d6 100644 --- a/man/dev_util_backquote.Rd +++ b/man/backquote.Rd @@ -13,14 +13,13 @@ backquote(x) Wrap a String in Backquotes } \seealso{ -Helpers for working with Quosures and Quoting: +Helpers for working with Quotes and Quoting: \code{\link{dquote}()}, \code{\link{enumerate}()}, -\code{\link{quo_c}()}, \code{\link{squote}()} } \author{ Thomas Neitmann } -\concept{quo} -\keyword{quo} +\concept{quote} +\keyword{quote} diff --git a/man/dev_util_convert_dtm_to_dtc.Rd b/man/convert_dtm_to_dtc.Rd similarity index 71% rename from man/dev_util_convert_dtm_to_dtc.Rd rename to man/convert_dtm_to_dtc.Rd index 8c1a3c20..2d1a768f 100644 --- a/man/dev_util_convert_dtm_to_dtc.Rd +++ b/man/convert_dtm_to_dtc.Rd @@ -17,7 +17,16 @@ character Helper Function to Convert Date (or Date-time) Objects to Characters of dtc Format (-DTC type of variable) } +\seealso{ +Developer Utility Functions: +\code{\link{\%notin\%}()}, +\code{\link{arg_name}()}, +\code{\link{as_name}()}, +\code{\link{extract_vars}()}, +\code{\link{replace_values_by_names}()} +} \author{ Ondrej Slama } +\concept{dev_utility} \keyword{dev_utility} diff --git a/man/dev_util_quo_c.Rd b/man/dev_util_quo_c.Rd index 4aa3fc1c..4c5bc73c 100644 --- a/man/dev_util_quo_c.Rd +++ b/man/dev_util_quo_c.Rd @@ -15,13 +15,6 @@ An object of class \code{quosures} \description{ Concatenate One or More Quosure(s) } -\seealso{ -Helpers for working with Quosures and Quoting: -\code{\link{backquote}()}, -\code{\link{dquote}()}, -\code{\link{enumerate}()}, -\code{\link{squote}()} -} \author{ Thomas Neitmann } diff --git a/man/dquote.Rd b/man/dquote.Rd index 5f9b0f04..041b3ace 100644 --- a/man/dquote.Rd +++ b/man/dquote.Rd @@ -18,14 +18,13 @@ Wrap a string in double quotes, e.g., for displaying character values in messages. } \seealso{ -Helpers for working with Quosures and Quoting: +Helpers for working with Quotes and Quoting: \code{\link{backquote}()}, \code{\link{enumerate}()}, -\code{\link{quo_c}()}, \code{\link{squote}()} } \author{ Stefan Bundfuss } -\concept{quo} -\keyword{quo} +\concept{quote} +\keyword{quote} diff --git a/man/dev_util_enumerate.Rd b/man/enumerate.Rd similarity index 85% rename from man/dev_util_enumerate.Rd rename to man/enumerate.Rd index f60c711d..8ec80bbd 100644 --- a/man/dev_util_enumerate.Rd +++ b/man/enumerate.Rd @@ -17,14 +17,13 @@ enumerate(x, quote_fun = backquote, conjunction = "and") Enumerate Multiple Strings } \seealso{ -Helpers for working with Quosures and Quoting: +Helpers for working with Quotes and Quoting: \code{\link{backquote}()}, \code{\link{dquote}()}, -\code{\link{quo_c}()}, \code{\link{squote}()} } \author{ Thomas Neitmann } -\concept{quo} -\keyword{quo} +\concept{quote} +\keyword{quote} diff --git a/man/dev_util_extract_vars.Rd b/man/extract_vars.Rd similarity index 68% rename from man/dev_util_extract_vars.Rd rename to man/extract_vars.Rd index 1799ca91..7dd2ee14 100644 --- a/man/dev_util_extract_vars.Rd +++ b/man/extract_vars.Rd @@ -17,7 +17,16 @@ A list of \code{quosures} \description{ Extract All Symbols from a List of Quosures } +\seealso{ +Developer Utility Functions: +\code{\link{\%notin\%}()}, +\code{\link{arg_name}()}, +\code{\link{as_name}()}, +\code{\link{convert_dtm_to_dtc}()}, +\code{\link{replace_values_by_names}()} +} \author{ Thomas Neitmann } +\concept{dev_utility} \keyword{dev_utility} diff --git a/man/filter_if.Rd b/man/filter_if.Rd index 7dfdf243..6903a17a 100644 --- a/man/filter_if.Rd +++ b/man/filter_if.Rd @@ -21,4 +21,4 @@ Filters the input dataset if the provided expression is not \code{NULL} \author{ Thomas Neitmann } -\keyword{user_utility} +\keyword{remove_utility} diff --git a/man/dev_util_notin.Rd b/man/grapes-notin-grapes.Rd similarity index 67% rename from man/dev_util_notin.Rd rename to man/grapes-notin-grapes.Rd index 9cea8b67..959f20a0 100644 --- a/man/dev_util_notin.Rd +++ b/man/grapes-notin-grapes.Rd @@ -15,7 +15,16 @@ x \%notin\% table Returns a \code{logical} vector indicating if there is \emph{no} match of the left operand in the right operand. } +\seealso{ +Developer Utility Functions: +\code{\link{arg_name}()}, +\code{\link{as_name}()}, +\code{\link{convert_dtm_to_dtc}()}, +\code{\link{extract_vars}()}, +\code{\link{replace_values_by_names}()} +} \author{ Thomas Neitmann } +\concept{dev_utility} \keyword{dev_utility} diff --git a/man/negate_vars.Rd b/man/negate_vars.Rd index b9abc5e7..01f52fab 100644 --- a/man/negate_vars.Rd +++ b/man/negate_vars.Rd @@ -25,4 +25,4 @@ negate_vars(vars(USUBJID, STUDYID)) \author{ Stefan Bundfuss } -\keyword{user_utility} +\keyword{remove_utility} diff --git a/man/dev_util_replace_values_by_names.Rd b/man/replace_values_by_names.Rd similarity index 66% rename from man/dev_util_replace_values_by_names.Rd rename to man/replace_values_by_names.Rd index 28e8968d..db8caa00 100644 --- a/man/dev_util_replace_values_by_names.Rd +++ b/man/replace_values_by_names.Rd @@ -15,7 +15,16 @@ A list of quosures \description{ Replace Quosure Value with Name } +\seealso{ +Developer Utility Functions: +\code{\link{\%notin\%}()}, +\code{\link{arg_name}()}, +\code{\link{as_name}()}, +\code{\link{convert_dtm_to_dtc}()}, +\code{\link{extract_vars}()} +} \author{ Thomas Neitmann } +\concept{dev_utility} \keyword{dev_utility} diff --git a/man/roxygen/meta.R b/man/roxygen/meta.R index 63c9bea5..6a7e59de 100644 --- a/man/roxygen/meta.R +++ b/man/roxygen/meta.R @@ -3,7 +3,8 @@ list( is = "Identifies type of Object with return of TRUE/FALSE: ", assertion = "Checks for valid input and returns warning or errors messages: ", what = "Identifies type of object and returns type: ", - quo = "Helpers for working with Quosures and Quoting: ", + quo = "Helpers for working with Quosures: ", + quote = "Helpers for working with Quotes and Quoting: ", get = "Brings something to you!?!: ", test_helper = "Helps with Testing: ", dev_utility = "Developer Utility Functions: ", diff --git a/man/dev_util_squote.Rd b/man/squote.Rd similarity index 74% rename from man/dev_util_squote.Rd rename to man/squote.Rd index 0341361c..eae8c056 100644 --- a/man/dev_util_squote.Rd +++ b/man/squote.Rd @@ -13,14 +13,13 @@ squote(x) Wrap a String in Single Quotes } \seealso{ -Helpers for working with Quosures and Quoting: +Helpers for working with Quotes and Quoting: \code{\link{backquote}()}, \code{\link{dquote}()}, -\code{\link{enumerate}()}, -\code{\link{quo_c}()} +\code{\link{enumerate}()} } \author{ Thomas Neitmann } -\concept{quo} -\keyword{quo} +\concept{quote} +\keyword{quote} diff --git a/man/vars2chr.Rd b/man/vars2chr.Rd index baafae6a..58702c3e 100644 --- a/man/vars2chr.Rd +++ b/man/vars2chr.Rd @@ -21,4 +21,4 @@ vars2chr(vars(USUBJID, AVAL)) \author{ Thomas Neitmann } -\keyword{user_utility} +\keyword{remove_utility} diff --git a/tests/testthat/test-quo.R b/tests/testthat/test-quo.R index 88171777..3f56ba7f 100644 --- a/tests/testthat/test-quo.R +++ b/tests/testthat/test-quo.R @@ -13,3 +13,7 @@ test_that("Test 11 : `quo_not_missing` throws and Error if missing argument", { } expect_error(test_fun()) # missing argument -> throws error }) + +test_that("Test 11 : `quo_not_missing` throws and Error if missing argument", { + # quo_c test here +}) diff --git a/vignettes/admiraldev.Rmd b/vignettes/admiraldev.Rmd index 280429d2..f6a24000 100644 --- a/vignettes/admiraldev.Rmd +++ b/vignettes/admiraldev.Rmd @@ -28,15 +28,39 @@ Tools are loosely defined as follows: * Vignettes on working on `{admiral}` functions, developing unit testing, releases process, vignette writing and other documentation needs. These vignettes are intended for use across all admiral packages. -# Adding new tools +# Why have a separate development package? + +As the `{admiral}` package function base has grown it was decided to create extension packages for use within companies and specific TAs to help with specific problems. We intended these extension packages to follow the same processes as `{admiral}` core, e.g. Unit Testing, Roxygen Documentation, Function Design. A standalone development package allows us to keep an up to date development process for all developers across the family. We also feel that a lot of the developer functions are not user-specific and gives us more freedom to create and release utility tools specific to our family of packages and reduces non-user facing functions within the admiral family of packages. -* Just like in `{admiral}`, we follow the same procedures of adding issues, developing those issues in branches and doing a Pull Request. +# How to add new tools to `{admiraldev}`? + +* Just like in `{admiral}`, we follow the same procedures of adding issues to discuss feature requests, bugs and documentation updates. We then develop those issues in branches and do a Pull Request with a Code Review. * Experimental tools are highly encouraged to help reduce repetitive patterns and automating the boring stuff. -# Why have a separate development package? +# When to add a function to `{admiraldev}`? + +## **Scenario One: {admiral} core** + +A developer working on `{admiral}` core implements a new type of derivation function for a BDS-Findings ADaM dataset. The new derivation function has two new `assert` custom checking functions for inputs as well as a helper function. + +Loose guidelines: + +1. The derivation function should always live in `{admiral}` core. +1. The helper function should be looked at to see it should be made available within `{admiraldev}` for other extension packages needs and so reduce repetitive coding across the family of `{admiral}`. If it cannot be generalized, then it should remain in `{admiral}`. +1. The `assert` custom checking functions should always live within `{admiraldev}` to stay with the family of `assertion` functions. + +## **Scenario Two: {admiral} extension** + +A developer working on `{admiralonco}` implements a new type of derivation function for adding certain parameters to an oncology specific ADaM dataset. The new derivation function has one new `assert` custom checking function. + +Loose guidelines: + +1. The derivation function should be closely looked at to see if it can be generalized to other ADaM datsets. If that is the case, then it should be moved to `{admiral}` core. If the function is very specific to onoclogy needs, then it should remain in `{admiralonco}`. +1. The `assert` custom checking functions should always live within `{admiraldev}` to stay with the family of `assertion` functions. + + -As the `{admiral}` package function base has grown it was decided to create extension packages for use within companies and specific TAs to help with specific problems. We intended these extension packages to follow the same processes as `{admiral}` core, e.g. Unit Testing, Roxygen Documentation, Function Design. A standalone development package allows us to keep an up to date development process for all developers across the family. We also feel that a lot of the developer functions are not user-specific and gives us more freedom to create and release utility tools specific to our family of packages.