Skip to content

Commit

Permalink
#1941: chore: fix space after commas. move some acknowledgees to cont…
Browse files Browse the repository at this point in the history
…ributors. link README in authors page.
  • Loading branch information
manciniedoardo committed Jun 26, 2023
1 parent e409d26 commit cdee185
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 55 deletions.
3 changes: 3 additions & 0 deletions DESCRIPTION
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,11 @@ Authors@R: c(
person("Kangjie", "Zhang", role = "aut"),
person("Zelos", "Zhu", role = "aut"),
person("Kamila", "Duniec", role = "ctb"),
person("G", "Gayatri", role = "ctb"),
person("Declan", "Hodges", role = "ctb"),
person("Robin", "Koeger", role = "ctb"),
person("Pooja", "Kumari", role = "ctb"),
person("Shan", "Lee", role = "ctb"),
person("Thomas", "Neitmann", role = "ctb"),
person("F. Hoffmann-La Roche AG", role = c("cph", "fnd")),
person("GlaxoSmithKline LLC", role = c("cph", "fnd"))
Expand Down
90 changes: 36 additions & 54 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ ADaM in R Asset Library

## Purpose

To provide an open source, modularized toolbox that enables the pharmaceutical programming community
To provide an open source, modularized toolbox that enables the pharmaceutical programming community
to develop ADaM datasets in R.

## Installation
Expand All @@ -22,13 +22,13 @@ The package is available from CRAN and can be installed by running `install.pack
To install the latest development version of the package directly from GitHub use the following code:

```r
if (!requireNamespace("remotesquietly = TRUE)) {
if (!requireNamespace("remotes", quietly = TRUE)) {
install.packages("remotes")
}

remotes::install_github("pharmaverse/admiral.testref = "devel") # This is a required dependency of {admiral}
remotes::install_github("pharmaverse/admiraldevref = "devel") # This is a required dependency of {admiral}
remotes::install_github("pharmaverse/admiralref = "devel")
remotes::install_github("pharmaverse/admiral.test") # This is a required dependency of {admiral}
remotes::install_github("pharmaverse/admiraldev") # This is a required dependency of {admiral}
remotes::install_github("pharmaverse/admiral")
```

## Release Schedule
Expand All @@ -37,8 +37,8 @@ remotes::install_github("pharmaverse/admiralref = "devel")
The `admiral` family has several downstream and upstream dependencies and so this release shall be done in three
Phases:

* Phase 1 release is for `{admiraldev}`, `{admiral.test}`, and `{admiral}` core
* Phase 2 release is extension packages, e.g. `{admiralonco}`, `admiralophtha`
* Phase 1 release is for `{admiraldev}`, `{admiral.test}`, and `{admiral}` core
* Phase 2 release is extension packages, e.g. `{admiralonco}`, `admiralophtha`

|Release Schedule | Phase 1- Date and Packages | Phase 2- Date and Packages |
|---------------- | -------------------------- | -------------------------- |
Expand All @@ -51,19 +51,19 @@ Phases:

## Main Goal

Provide users with an open source, modularized toolbox with which to create ADaM datasets
Provide users with an open source, modularized toolbox with which to create ADaM datasets
in R. _As opposed to a “run 1 line and an ADaM appears” black-box solution or an attempt to
automate ADaM._

One of the key aspects of `{admiral}` is its development by the users for the users.
It gives an entry point for all to collaborate, co-create and contribute to a
It gives an entry point for all to collaborate, co-create and contribute to a
harmonized approach of developing ADaMs in R across the pharmaceutical industry.

## Scope

To set expectations: It is not our target that `{admiral}` will ever provide all possible solutions
for all ADaM datasets outside of study specific needs. It depends on the user's collaboration
and contribution to help grow over time to an asset library that is robust, easy to use and
and contribution to help grow over time to an asset library that is robust, easy to use and
has an across-industry focus. We do not see a coverage of 100% of all ADaM derivations as ever
achievable---ADaM is endless.

Expand All @@ -73,29 +73,27 @@ We will provide:
modular manner (an "opinionated" design strategy)
* Pharmaceutical communities and companies are encouraged to contribute to `{admiral}` following
the provided programming strategy and modular approach
* Functions that are comprehensively documented and tested, including example calls---these are
* Functions that are comprehensively documented and tested, including example calls---these are
all listed in the [Reference section](https://pharmaverse.github.io/admiral/cran-release/reference/index.html)
* Vignettes on how to create ADSL, BDS and OCCDS datasets, including example scripts
* Vignettes for ADaM dataset specific functionality (i.e. dictionary coding, date imputation,
SMQs ...)
* Vignettes on how to create ADSL, BDS and OCCDS datasets, including example scripts
* Vignettes for ADaM dataset specific functionality (i.e. dictionary coding, date imputation, SMQs ...)

## Types of Packages

There will be 3 foreseeable types of `{admiral}` packages:

* Core package---one package containing all core functions required to create ADaMs,
usable by any company (i.e. general derivations, utility functions and checks for ADSL, OCCDS and BDS)
* Core package---one package containing all core functions required to create ADaMs, usable by any company (i.e. general derivations, utility functions and checks for ADSL, OCCDS and BDS)
* TA (Therapeutic Area) package extensions---one package per TA with functions that are
specific to algorithms and requirements for that particular TA (e.g. [`{admiralonco}`](https://pharmaverse.github.io/admiralonco/))
* Company package extensions---specific needs and plug-ins for the company, such as access to metadata
* Company package extensions---specific needs and plug-ins for the company, such as access to metadata
(e.g. `{admiralroche}` or `{admiralgsk}`)

## Admiral Manifesto

For `{admiral}` and all extension packages, we prioritize providing our users with a __simple to adopt__ toolkit
For `{admiral}` and all extension packages, we prioritize providing our users with a __simple to adopt__ toolkit
that enables them to produce __readable__ and __easily constructible__ ADaM programs. The following explains
our philosophy, which we try to adhere to across the `{admiral}` family of packages.
There isn’t always a clear single, straightforward rule, but there are guiding principles we adhere to for `{admiral}`.
our philosophy, which we try to adhere to across the `{admiral}` family of packages.
There isn’t always a clear single, straightforward rule, but there are guiding principles we adhere to for `{admiral}`.
This manifesto helps show the considerations of our developers when making decisions.

We have four design principles to achieve the main goal:
Expand All @@ -104,58 +102,43 @@ We have four design principles to achieve the main goal:

All `{admiral}` functions should be easy to use.

* Documentation is an absolute priority. Each function reference page should cover the purpose,
descriptions of each argument with permitted values, the expected input and output, with clear real-life
examples---so that users don’t need to dig through code to find answers.
* Vignettes that complement the functional documentation to help users see how best the functions can be
applied to achieve ADaM requirements.
* Functions should be written and structured in a way that users are able to read, re-use or extend them
for study specific purposes if needed (see Readability below).
* Documentation is an absolute priority. Each function reference page should cover the purpose, descriptions of each argument with permitted values, the expected input and output, with clear real-life examples---so that users don’t need to dig through code to find answers.
* Vignettes that complement the functional documentation to help users see how best the functions can be applied to achieve ADaM requirements.
* Functions should be written and structured in a way that users are able to read, re-use or extend them for study specific purposes if needed (see Readability below).

### Simplicity

All `{admiral}` functions have a clear purpose.

* We try not to ever design single functions that could achieve numerous very different derivations. For
example if you as a user pick up a function with >10 different arguments then chances are it is going to be
difficult to understand if this function could be applied for your specific need. The intention is that
arguments/parameters can influence how the output of a function is calculated, but not change the purpose of
the function.
* We try not to ever design single functions that could achieve numerous very different derivations. For example if you as a user pick up a function with >10 different arguments then chances are it is going to be difficult to understand if this function could be applied for your specific need. The intention is that arguments/parameters can influence how the output of a function is calculated, but not change the purpose of the function.

* We try to combine similar tasks and algorithms into one function where applicable to reduce the amount of repetitive functions with similar algorithms and to group together similar functionality to increase usability (e.g. one study day calculation rather than a function per variable).

* We strive to design functions that are not too general and trying to fulfill multiple, complex purposes.
* We strive to design functions that are not too general and trying to fulfill multiple, complex purposes.

* Functions should not allow expressions as arguments that are used as code snippets in function calls.

* We recommend to avoid copy and paste of complex computational algorithms or repetitive code like checks
and advise to wrap them into a function. However we would also like to avoid multi-layered functional nesting,
so this needs to be considered carefully to keep the nesting of 3-4 functions an exception rather than the rule.
* We recommend to avoid copy and paste of complex computational algorithms or repetitive code like checks and advise to wrap them into a function. However we would also like to avoid multi-layered functional nesting, so this needs to be considered carefully to keep the nesting of 3-4 functions an exception rather than the rule.

### Findability

All `{admiral}` functions are easily findable.

* In a growing code base, across a family of packages, we make every effort to make our functions easily findable.
* We use consistent naming conventions across all our functions, and provide vignettes and ADaM templates that
help users to get started and build familiarity. Each `{admiral}` family package website is searchable.
* In a growing code base, across a family of packages, we make every effort to make our functions easily findable.
* We use consistent naming conventions across all our functions, and provide vignettes and ADaM templates that help users to get started and build familiarity. Each `{admiral}` family package website is searchable.
* We avoid repetitive functions that will do similar tasks (as explained above with study day example).
* Each package extension is kept focused on the specific scope, e.g. features that are relevant across multiple
extension packages will be moved to the core `{admiral}` package.
* Each package extension is kept focused on the specific scope, e.g. features that are relevant across multiple extension packages will be moved to the core `{admiral}` package.

### Readability

All `{admiral}` functions follow the [Programming Strategy](https://pharmaverse.github.io/admiraldev/main/articles/programming_strategy.html)
that all our developers and contributors must follow, so that all our code has a high degree of consistency and readability.
that all our developers and contributors must follow, so that all our code has a high degree of consistency and readability.

* We mandate use of tidyverse (e.g. dplyr) over similar functionality existing in base R.
* For sections of code that perform the actual derivations (e.g. besides assertions or basic utilities),
we try to limit nesting of too many dependencies or functions.
* For sections of code that perform the actual derivations (e.g. besides assertions or basic utilities), we try to limit nesting of too many dependencies or functions.
* Modularity is a focus---we don’t try to achieve too many steps in one.
* All code has to be well commented.
* We recognize that a user or a Health Authority reviewer may have the wish to delve into the code base (especially
given this open source setting), or users may need to extend/adapt the code for their study specific needs. We
therefore want any module to be understandable to all, not only the `{admiral}` developers.
* We recognize that a user or a Health Authority reviewer may have the wish to delve into the code base (especially given this open source setting), or users may need to extend/adapt the code for their study specific needs. We therefore want any module to be understandable to all, not only the `{admiral}` developers.

## References and Documentation

Expand All @@ -169,22 +152,21 @@ that all our developers and contributors must follow, so that all our code has
## Conference Presentations

* [Paving the way for clinical submissions in R](https://phuse.s3.eu-central-1.amazonaws.com/Archive/2023/SDE/EU/London/PRE_London09.pdf) (slides from PHUSE SDE in London)
* [An Overview of {admiral}](https://phuse.s3.eu-central-1.amazonaws.com/Archive/2023/SDE/US/Summit/PRE_Summit03.pdf) (slides from PHUSE SDE in Summit, NJ)
* [{admiralonco}](https://phuse.s3.eu-central-1.amazonaws.com/Archive/2023/Connect/US/Florida/REC_OS12.mp4) (recording for talk at PHUSE US Connect 2023, slides also available [here](https://phuse.s3.eu-central-1.amazonaws.com/Archive/2023/Connect/US/Florida/PRE_OS12.pdf))
* [An Overview of {admiral}](https://phuse.s3.eu-central-1.amazonaws.com/Archive/2023/SDE/US/Summit/PRE_Summit03.pdf) (slides from PHUSE SDE in Summit, NJ)
* [{admiralonco}](https://phuse.s3.eu-central-1.amazonaws.com/Archive/2023/Connect/US/Florida/REC_OS12.mp4) (recording for talk at PHUSE US Connect 2023, slides also available [here](https://phuse.s3.eu-central-1.amazonaws.com/Archive/2023/Connect/US/Florida/PRE_OS12.pdf))
* [Programming ADNCA using R and {admiral}](https://phuse.s3.eu-central-1.amazonaws.com/Archive/2023/Connect/US/Florida/REC_OS09.mp4) (recording of presentation from PHUSE US Connect 2023)
* [Clinical Reporting in R](https://www.youtube.com/watch?v=9eod8MLF5ys&list=PLMtxz1fUYA5AWYQHB5mZAs-yamNJ5Tm_8&index=2) (recording of workshop at R in Pharma 2022)
* [Introducing {admiral}](https://www.youtube.com/watch?v=N7Bw8c3D5fU) (recording of talk for R in Pharma 2021)
* [Pharmaverse workshop](https://github.com/pharmaverse/pharmaverse.workshop.phuseUS2022) (slides and materials from PHUSE US Connect 2022---including `{admiral}`
workshop slides from PHUSE EU Connect 2021)
* [Pharmaverse workshop](https://github.com/pharmaverse/pharmaverse.workshop.phuseUS2022) (slides and materials from PHUSE US Connect 2022---including `{admiral}` workshop slides from PHUSE EU Connect 2021)

## Contact

We use the following for support and communications between user and developer community:

* [Slack](https://app.slack.com/client/T028PB489D3/C02M8KN8269)---for informal discussions, Q\&A and building our user community. If you don't have access, use this [link](https://join.slack.com/t/pharmaverse/shared_invite/zt-yv5atkr4-Np2ytJ6W_QKz_4Olo7Jo9A) to join the pharmaverse Slack workspace
* [GitHub Issues](https://github.com/pharmaverse/admiral/issues)---for direct feedback, enhancement requests or raising bugs
* [Slack](https://app.slack.com/client/T028PB489D3/C02M8KN8269)---for informal discussions, Q\&A and building our user community. If you don't have access, use this [link](https://join.slack.com/t/pharmaverse/shared_invite/zt-yv5atkr4-Np2ytJ6W_QKz_4Olo7Jo9A) to join the pharmaverse Slack workspace
* [GitHub Issues](https://github.com/pharmaverse/admiral/issues)---for direct feedback, enhancement requests or raising bugs

## Acknowledgments

Along with the authors and contributors, thanks to the following people for their work on the package:
Jaxon Abercrombie, Mahdi About, Teckla Akinyi, James Black, Claudia Carlucci, Bill Denney, Alice Ehmann, Gayatri G, Ania Golab, Alana Harris, Anthony Howard, Shimeng Huang, Samia Kabi, James Kim, John Kirkpatrick, Leena Khatri, Konstantina Koukourikou, Pavan Kumar, Pooja Kumari, Shan Lee, Wenyi Liu, Jack McGavigan, Jordanna Morrish, Syed Mubasheer, Yohann Omnes, Barbara O'Reilly, Hamza Rahal, Nick Ramirez, Tom Ratford, Tamara Senior, Sophie Shapcott, Ondrej Slama, Andrew Smith, Daniil Stefonishin, Vignesh Thanikachalam, Michael Thorpe, Annie Yang, Ojesh Upadhyay and Franciszek Walkowiak.
Jaxon Abercrombie, Mahdi About, Teckla Akinyi, James Black, Claudia Carlucci, Bill Denney, Alice Ehmann, Ania Golab, Alana Harris, Anthony Howard, Shimeng Huang, Samia Kabi, James Kim, John Kirkpatrick, Leena Khatri, Konstantina Koukourikou, Pavan Kumar, Wenyi Liu, Jack McGavigan, Jordanna Morrish, Syed Mubasheer, Yohann Omnes, Barbara O'Reilly, Hamza Rahal, Nick Ramirez, Tom Ratford, Tamara Senior, Sophie Shapcott, Ondrej Slama, Andrew Smith, Daniil Stefonishin, Vignesh Thanikachalam, Michael Thorpe, Annie Yang, Ojesh Upadhyay and Franciszek Walkowiak.
2 changes: 1 addition & 1 deletion _pkgdown.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ news:
cran_dates: true

authors:
before: "We define *authors* as those who are actively maintaining the code base, and *contributors* as those who made a significant contribution in the past. For all acknowledgements, see the README section."
before: "We define *authors* as those who are actively maintaining the code base, and *contributors* as those who made a significant contribution in the past. For all acknowledgements, see the eponymous section in the [Home Page](https://pharmaverse.github.io/admiral/cran-release/)."
footer:
roles: [aut, ctb, cre, fnd]
text: "Developed by"
Expand Down

0 comments on commit cdee185

Please sign in to comment.