Please select a category the issue is focused on?

Function Documentation

Let us know where something needs a refresh or put your idea here!

It could be advantageous for developers to have commented blocks of code for future developers making updates. These comment blocks could point out salient features of the code and/or give a more detailed explanation of how the code works/processes. This would be seen by developers or by users inspecting the code on github.

We would like to establish a common way to use these comment blocks in our code.

DoD:
Programming strategy has recommended best practice for using comments blocks in code.

@sgorm123 Does this capture our discussion yesterday?

Feature Idea

A function that helps to remind us when a function should be removed from the code-base.

Essentially a wrapper function around deprecate_stop, deprecate_warn but also causes the package to be unable to build once the function is no longer kept inside admiral.

Relevant Input

No response

Relevant Output

No response

Reproducible Example/Pseudo Code

No response

Background Information

Developers of any function that is a dev_utility should be listed in the Description file. As well as anyone working on this package.

Definition of Done

Description file updated

Background Information

There are no templates that need to be checked.

Definition of Done

This action should be removed from the repo.

Background Information

quo_is_desc_call is used within is_order_vars. Do we want to separate out this function so it can be used other places if needed, provide context on what it is, easily test it, etc.

Definition of Done

Decide if we want to split out this function.

If yes, set up documentation and test the function

Please select a category the issue is focused on?

Developer Guides

Let us know where something needs a refresh or put your idea here!

It has been observed that our roxygen headers are not standardized across the admiral code-base. For example, some function headers have @author or @return in different places from other function headers.

In order to standardized all of our headers, we first need to create a Standard Template that shows the order of the tags and what should go in each tag. This template will live in the Developer Guide-Programming Strategy . An existing example and guidance already exists and can be updated once agreed upon structure is met.

• Standardizing the headers also means a consistent structure across the Reference Tab on the packagedown site.
• This might be good as a check in the PR checklist that the roxygen headers follow the standard template?

Proposed Structure (Updated based on Stefan's feedback)

#' Title
#'
#' Short Description (If the description consists of more than one paragraph, use the `@description` tag.)
#'
#' @param dataset Descriptive Text (order of @param tags should be order as they appear in function)
#'
.
.
#' @param an_input Descriptive Text
#'
#' @details (Deep dive of purpose, recommend workflow, documentation/links)
#'
#' @return (What is returned by this function)
#'
#' @author (original and updating authors)
#'
#' @family (This will create an additional See Also section that links to similar functions)
#'
#' @keywords (This is helpful for our packagedown site to organize the reference page)
#'  If possible, use keywords which are used in `_pgkdown.yml`.
#'  If a new keyword is required, a corresponding section needs to be added to `_pgkdown.yml`.
#'  All keywords must be lower case.
#'
#' @seealso [related_function()] (This tag is optional. It should be used to refer to related functions.)
#'
#' @export
#'
#' @examples (Use `library(pkg_name)` rather than `pgk_name::function()`)

Background Information

admiral has assert functions and asset_that functions in several files. These should be confirmed and brought over.

Definition of Done

All tests and functions related to the assert should be brought over to admiraldev

Background Information

Most of the admiral warning functions are within the warnings.R file. This should be confirmed. We want all warning functions used in development to be brought over.

Definition of Done

All warnings function and tests are brought over to admiraldev

Please select a category the issue is focused on?

Function Documentation

Let us know where something needs a refresh or put your idea here!

https://github.com/pharmaverse/admiral/blob/main/R/compat_friendly_type.R

• Why did we adopt this code?
• Where is this code used in admiral and admiraldev?
• Explore Alternatives that allow us to remove this code.

Once these are brought over, we need to make a note in the file of why we have them and when they can removed.

Definition of Done

• Create a Details section with @zdz2101 explanations [craft in a way that makes sense for a new user]
• Create a .Rd file
• Make sure entry on site is legible and falls in a category that makes sense.

Please select a category the issue is focused on?

I have a new documentation idea! Yay!

Let us know where something needs a refresh or put your idea here!

once the testthat addin is finalized we need to provide a little bit of documentation on how to use it and what to watch out for.

Please select a category the issue is focused on?

Function Documentation

Let us know where something needs a refresh or put your idea here!

Since we are splitting out these from admiral I feel that these can have proper documentation and read out to the pkgdown site.

Background Information

These look to be doing similar things. one is robustly documented and other is not. Do we need the undocumented function?

Is the undocumented function used in admiral? Yes, in derive_vars_duration.

Definition of Done

Keep or remove valid_time_units?

If we keep, then update roxygen documentation for this function.

Please select a category the issue is focused on?

User Guides

Let us know where something needs a refresh or put your idea here!

Background Information

Check that functions are being used within admiral or admiraldev. If not, please create an issue for discussion if that unused function should be removed from this package.

Definition of Done

All functions within admiraldev have been checked for use within either admiral or admiraldev. Separate Issue created for each function that could be potentially removed.

Please select a category the issue is focused on?

Developer Guides

Let us know where something needs a refresh or put your idea here!

In general, no default values should be set if the expected value is study specific. If in doubt do not set a default value.

@dinakar29 , I think the reusable workflows are great. I wonder if we should move the workflows to a separate repository and keep only common.yml in admiraltemplate. Otherwise, all the workflows will be copied if a new repository is created based on admiraltemplate.

Originally posted by @bundfussr in pharmaverse/admiraltemplate#27 (comment)

Please select a category the issue is focused on?

Developer Guides

Let us know where something needs a refresh or put your idea here!

Language is very specific to admiral-core, but admiraldev is intended for all packages. We should reflect this generalization in the language we use within the vignettes.

Okay...how did you make that diagram...I want that power.

GitHub now support mermaid.js: https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

This all makes sense to me. We just need to be able to have a process, and make it well known, on how deverlopers can request updates to the renv.lock file. I think a lot of people think this thing is set in stone for eternity, but that is not the case.

Agreed - this will need to be documented and well-described.

Originally posted by @cicdguy in pharmaverse/admiralci#2 (comment)

Please select a category the issue is focused on?

Developer Guides

Let us know where something needs a refresh or put your idea here!

Since we have more room, we should split out some the vignettes to make it easier to find things and keep things fresh

Starting with vignette for release process - the really nit and gritty

Background Information

Missing information in the joins.R file and why we suppress that information

Definition of Done

No response

Feature Idea

This will follow our stated pharmaverse/admiral# roxygen template. A user can use the Addin feature to load in a template of the roxygen structure need to create an admiral function.

Relevant Input

Header should create what is laid out in programming strategy - https://pharmaverse.github.io/admiraldev/devel/articles/programming_strategy.html#function-header-documentation

Relevant Output

No response

Reproducible Example/Pseudo Code

No response

Please select a category the issue is focused on?

No response

Let us know where something needs a refresh or put your idea here!

Background Information

We should be able to link this repo to the admiral board automatically, but I can not figure it out

https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/linking-a-repository-to-a-project-board

Definition of Done

Successfully link admiraldev and admiral.test to the admiral core board.

Background Information

We should have a file called get.R and is.R that have get_ and is_ functions in them to make finding them easier. These functions live in dev_utilities, but might live in other files.

Definition of Done

Releveant functions are moved to appropriate files

I think in principle such a message could be helpful. However, I would not implement it just for one function. If we want to implement something like that, we should have a general concept for:

• Which functions issue which messages?
• Where are the messages written to?
• How can the developer switch on and off the messages?

Originally posted by @bundfussr in pharmaverse/admiral#1110 (comment)

Please select a category the issue is focused on?

Other

Let us know where something needs a refresh or put your idea here!

Since these ariticles are only relevant to developers we should them to here. This clears up space for other user guides. A quick how to get involved in development should still remain.

Feature Idea

We need tests written for all the is.R functions. There are none available as far as I can tell.

Relevant Input

No response

Relevant Output

No response

Reproducible Example/Pseudo Code

No response

Feature Idea

Looking over the package manual. I see this idea of an unexported function for prompting us to remember certain release procedures, updates, etc. This might be better than a PR request template for releasing the package and could be used across the admiral family.

Relevant Input

No response

Relevant Output

No response

Reproducible Example/Pseudo Code

No response

Background Information

A lot of the is functions have a nested on_failure function within them. Do we want to split this out? I see most of them follow the same pattern, but a few differ.

Definition of Done

No response

Please select a category the issue is focused on?

Function Documentation

Let us know where something needs a refresh or put your idea here!

Background Information

Current global.R file has a lot of unused global variables copied over from admiral. As these are not necessary they should be removed.

• Create a list of the global variables in the global.R file
• Identify global variables that are not used in this package.
• Remove global variables.

Definition of Done

Unused global variables have been removed from admiraldev

Please select a category the issue is focused on?

Function Documentation

Let us know where something needs a refresh or put your idea here!

We need keywords and families that can help developers quickly find and understand the suite of developer functions that we have avaialble.

Background Information

The functions within admiraldev are used in core, onco and roche packages. We need to think on how to deploy this package and how to deal with potential issues that could arise.

For example, one issue is where the assert_data_frame will now appears in multiple packages and how to only use the one from admiraldev.

• When is this package deemed stable on Github
• When do we release this package to CRAN?

Definition of Done

Release Strategy developed

Background Information

As we develop our programming processes, we should keep these updated in the website for all core and extension packages to see. Rather than releasing updated website at every CRAN release, we should update it from devel so it stays current.

Definition of Done

pkgdown action is switched to devel

Please select a category the issue is focused on?

Function Documentation

Let us know where something needs a refresh or put your idea here!

These should have roxygen headers added to them

Background Information

admiraldev will be essential part of the admiral family. We need to be aware when this package should be released so others can plan accordingly. Please seee admiral issue for when the releases are scheduled.

pharmaverse/admiral#1220

Definition of Done

Readme updated with release schedule.

A function should be implemented which adds the function name and a test number to the title of the tests. Additionally it should add a comment before the test such that it is displayed in the TOC in RStudio.
For example

test_that("duration and unit variable are added", {
...
}

should be transformed to

#---- derive_vars_aage, test 1: duration and unit variable are added ----
test_that("derive_vars_aage, test 1: duration and unit variable are added", {
...
}

If the function name and test number are already in the title, it should be updated if necessary.

Please note this is quite a large task and good for someone familiar with the RStudio API.

Background Information

Current language in the Description File:

• A toolbox for developers working on pharmaverse admiral packages.

Current language in the README:

• Tools for developing functions and maintaining a healthy codebase within the family of admiral R packages.

But want to make sure we are all on the same page as these two phrases aren't exact and the overlap of admiral and admiraldev is a bit tricky.

I see this package as not only being for a place for specific functions that help our admiral packages functions, but also give us reports and tools to make our development life easier.

For example, the testing Addin that reformats the testthat files to adhere to our Unit Test Guidance. An addin that allows for easier setup of roxygen headers and reports on keywords and families being used. I see a lot more potential here, but don't want it to get too wild!

Definition of Done

The Scope of package is decided upon and written into the Readme.

See pharmaverse/admiralonco#100

Background Information

I needed to export a lot of the functions to get admiral working with admiraldev. While doing this I did not fill out the documentation for a lot of the newly exported functions.

Definition of Done

All something references removed and updated with appropriate documentation.

Please select a category the issue is focused on?

Developer Guides

Let us know where something needs a refresh or put your idea here!

• https://pharmaverse.github.io/admiral/articles/unit_test_guidance.html#writing-unit-tests-in-admiral-
• https://pharmaverse.github.io/admiral/articles/programming_strategy.html#function-header-documentation

See pharmaverse/admiral#1235 for additional discussion

Please select a category the issue is focused on?

Function Documentation

Let us know where something needs a refresh or put your idea here!

Do we need this? If so, we should document it.

It seems that assert_list_of_formulas() is never used. Should we remove it?

Originally posted by @bundfussr in #20 (comment)

Please select a category the issue is focused on?

Function Documentation

Let us know where something needs a refresh or put your idea here!

A good part of our function documentation have default and permitted values listed in the function arguments. However, this is not completely adopted across admiral.

To remedy this:

• Update the Programming Strategy to have best practices on when and how Default to be used.
• Update the Programming Strategy to have best practices on when and how Permitted Values are to be used.
• #166
• Update function documentation for Default per programming strategy
• Update function documentation for Permitted Values per programming strategy

Please select a category the issue is focused on?

Vignette

Let us know where something needs a refresh or put your idea here!

goal: vignette that explains how to create a new admiral function

explain how to build a function with these in mind - link to manifesto, other vignettes, programming strategy, style guide?
Part 1

• readability

• findability

• simplicity principles
  Part 2

• technical: quoting and unquoting - how to use tidy within functions (i.e. !! vs. !!!) - Thomas

• example: building blocks

Pick some existing functions to explain decisions why things were done this way and not other, e.g. generic functions vs specific functions. - is it needed?

Background Information

Create and move what functions to a filed called what.R. Relevant test file is needed.

Definition of Done

No response

Background Information

• .rlang_as_friendly_type
• .rlang_as_friendly_vector_type
• .rlang_stop_unexpected_typeof
• %notin% (keep in admiral)
• %or%
• anti_join
• arg_name
• as_name
• assert_character_scalar
• assert_character_vector
• assert_data_frame
• assert_db_requirements (keep in admiral)
• assert_expr
• assert_filter_cond
• assert_function
• assert_function_param
• assert_has_variables
• assert_integer_scalar
• assert_list_element
• assert_list_of
• assert_list_of_formulas (Removed from admiraldev and needs to be removed from admiral)
• assert_logical_scalar
• assert_named_exprs
• assert_numeric_vector
• assert_one_to_one
• assert_order_vars
• assert_param_does_not_exist
• assert_s3_class
• assert_symbol
• assert_terms (keep in admiral - rename?)
• assert_unit
• assert_valid_queries
• assert_vars
• assert_varval_list
• backquote
• contains_vars
• dataset_vignette
• dquote
• enumerate
• expect_dfs_equal
• extend_source_datasets (keep in admiral)
• extract_vars
• format.sdg_select (keep in admiral)
• format.smq_select (keep in admiral)
• format_arg
• friendly_type_of
• get_constant_vars
• get_duplicates
• get_source_vars
• grapes-notin-grapes (not sure what this is?)
• inner_join
• is_auto
• is_date
• is_named
• is_order_vars
• is_timeunit
• is_valid_date_entry
• is_valid_day
• is_valid_dtc
• is_valid_hour
• is_valid_month
• is_valid_sec_min
• is_valid_time_entry
• left_join
• print.duplicates (stay in admiral)
• quo_c
• quo_is_desc_call
• quo_not_missing
• replace_values_by_names
• squote
• stop_input_type
• suppress_warning
• valid_time_units
• validate_query (keep in admiral)
• validate_sdg_select (keep in admiral)
• validate_smq_select (keep in admiral)
• warn_if_incomplete_dtc
• warn_if_inconsistent_list
• warn_if_invalid_dtc
• warn_if_vars_exist
• what_is_it

Definition of Done

• Final list of functions created
• This list of functions and tests are removed from admiral

Background Information

Bring over join.R functions

Definition of Done

Functions, tests are brought over.

run devtools::check and fix any errors

Please select a category the issue is focused on?

Function Documentation

Let us know where something needs a refresh or put your idea here!

contain_vars within the dev_utils.R file is in need of roxygen documentation

Background Information

Updates badges for readme. There should only be 4 badges on admiraldev homepage

Definition of Done

4 badges appear on the readme

• pharmaverse admiraldev
• CRAN 0.1.0
• R-CMD-check
• Test Coverage