Closes #268: admiralmetabolic release announcment (#269)

* #268 admiralmetabolic release announcment first draft * #268 added description * #268 fix spelling * #268 fix spelling again * Apply suggestions from code review Co-authored-by: StefanThoma <[email protected]> Co-authored-by: Anders Askeland <[email protected]> * #268 update following review * #268 updates following review * #268 updates following review * #268 final updates following review * Update posts/zzz_DO_NOT_EDIT_hello_admiralmetabolic/hello_admiralmetabolic!.qmd Co-authored-by: StefanThoma <[email protected]> * #268 activate link package * #268 update filename --------- Co-authored-by: StefanThoma <[email protected]> Co-authored-by: Anders Askeland <[email protected]>
pharmaverse · Jan 21, 2025 · 1ee6549 · 1ee6549
1 parent ad63a87
commit 1ee6549
Show file tree

Hide file tree

Showing 5 changed files with 243 additions and 0 deletions.
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -41,6 +41,9 @@ jobs:
     steps:
       - name: Check out repository
         uses: actions/checkout@v4
+        with:
+          ref: main
+          token: ${{ secrets.PHARMAVERSE_BOT }}
 
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2
@@ -64,6 +67,7 @@ jobs:
             admiralophtha
             admiralpeds
             admiralvaccine
+            admiralmetabolic
             patchwork
             here
             reactable

diff --git a/inst/WORDLIST.txt b/inst/WORDLIST.txt
@@ -17,6 +17,8 @@ ADaMs
 AdaMTeamIndia
 ADBCVA
 adbds
+adcoeq
+ADCOEQ
 adex
 ADEX
 adlb
@@ -100,6 +102,7 @@ AMBUL
 amd
 amongst
 Amor
+Anders
 analysing
 analytics
 Analytics
@@ -124,6 +127,7 @@ arjun
 Arjun
 ARMCD
 asis
+Askeland
 aspx
 AST
 ASTDT
@@ -227,6 +231,8 @@ CMSTTPT
 CMTRT
 codebase
 codelist
+coeq
+COEQ
 COHORTC
 colcounts
 collapseExample
@@ -404,6 +410,7 @@ eWSIK
 examplesShinyLive
 EXDOSE
 EXDOSFRM
+expr
 exprs
 EXROUTE
 EXSEQ
@@ -474,6 +481,8 @@ hardcode
 hardcoded
 hc
 HICC
+hipcir
+HIPCIR
 Hk
 hm
 hms
@@ -558,6 +567,7 @@ LBSTRESN
 LBTESTCD
 LBTESTCDB
 learnings
+leeds
 leena
 Leena
 lefunctionsref
@@ -1006,6 +1016,7 @@ ubuntu
 ucla
 ug
 ui
+uk
 UI
 Ul
 un
@@ -1057,8 +1068,13 @@ VSTEST
 VSTESTCD
 VSTPT
 waddella
+waisthgt
+WAISTHGT
+waisthip
+WAISTHIP
 Walkowiak
 Walkthrough
+walkthrough
 wasm
 WAWA
 wayback
@@ -1080,6 +1096,8 @@ wlandau
 WnpvVgmyE
 writeLines
 writeup
+wstcir
+WSTCIR
 WTBL
 www
 XANO

diff --git a/posts/zzz_DO_NOT_EDIT_hello_admiralmetabolic/admiralmetabolic.png b/posts/zzz_DO_NOT_EDIT_hello_admiralmetabolic/admiralmetabolic.png
diff --git a/posts/zzz_DO_NOT_EDIT_hello_admiralmetabolic/appendix.R b/posts/zzz_DO_NOT_EDIT_hello_admiralmetabolic/appendix.R
@@ -0,0 +1,73 @@
+suppressMessages(library(dplyr))
+# markdown helpers --------------------------------------------------------
+
+markdown_appendix <- function(name, content) {
+  paste(paste("##", name, "{.appendix}"), " ", content, sep = "\n")
+}
+markdown_link <- function(text, path) {
+  paste0("[", text, "](", path, ")")
+}
+
+
+
+# worker functions --------------------------------------------------------
+
+insert_source <- function(repo_spec, name,
+                          collection = "posts",
+                          branch = "main",
+                          host = "https://github.com",
+                          text = "Source",
+                          file_name) {
+  path <- paste(
+    host,
+    repo_spec,
+    "tree",
+    branch,
+    collection,
+    name,
+    file_name,
+    sep = "/"
+  )
+  return(markdown_link(text, path))
+}
+
+insert_timestamp <- function(tzone = Sys.timezone()) {
+  time <- lubridate::now(tzone = tzone)
+  stamp <- as.character(time, tz = tzone, usetz = TRUE)
+  return(stamp)
+}
+
+insert_lockfile <- function(repo_spec, name,
+                            collection = "posts",
+                            branch = "main",
+                            host = "https://github.com",
+                            text = "Session info") {
+  path <- path <- "https://pharmaverse.github.io/blog/session_info.html"
+
+  return(markdown_link(text, path))
+}
+
+
+
+# top level function ------------------------------------------------------
+
+insert_appendix <- function(repo_spec, name, collection = "posts", file_name) {
+  appendices <- paste(
+    markdown_appendix(
+      name = "Last updated",
+      content = insert_timestamp()
+    ),
+    " ",
+    markdown_appendix(
+      name = "Details",
+      content = paste(
+        insert_source(repo_spec, name, collection, file_name = file_name),
+        # get renv information,
+        insert_lockfile(repo_spec, name, collection),
+        sep = ", "
+      )
+    ),
+    sep = "\n"
+  )
+  knitr::asis_output(appendices)
+}
diff --git a/posts/zzz_DO_NOT_EDIT_hello_admiralmetabolic/hello_admiralmetabolic.qmd b/posts/zzz_DO_NOT_EDIT_hello_admiralmetabolic/hello_admiralmetabolic.qmd
@@ -0,0 +1,148 @@
+---
+title: "Hello {admiralmetabolic}!"
+author:
+  - name: Anders Askeland
+  - name: Edoardo Mancini
+description: "We are happy to announce the release of the newest member of the {admiral} family - {admiralmetabolic}!"
+# Note that the date below will be auto-updated when the post is merged.
+date: "2024-12-01"
+# Please do not use any non-default categories.
+# You can find the default categories in the repository README.md
+categories: [ADaM, Community, Technical]
+# Feel free to change the image
+image: "admiralmetabolic.png"
+---
+
+<!--------------- typical setup ----------------->
+
+```{r setup, include=FALSE}
+long_slug <- "zzz_DO_NOT_EDIT_hello_admiralmetabolic"
+library(link)
+link::auto()
+```
+
+<!--------------- post begins here ----------------->
+
+[![](admiralmetabolic.png){fig-align="center" width="220"}](https://pharmaverse.github.io/admiralmetabolic/index.html)
+
+# Introduction
+
+The {admiral} team is celebrating the newest addition to the extension package family with the release of {admiralmetabolic} 0.1! This new package focuses on the therapeutic areas of obesity and cardiovascular metabolism, and was born out of a collaboration between Novo Nordisk and Roche, as well as a number of independent contributors. {admiralmetabolic} addresses a key unmet need in this area given the ever-increasing interest in obesity, diabetes and cardiovascular metabolism across the industry.
+
+# Package Contents
+
+For this first 0.1 release, {admiralmetabolic} focuses primarily on the obesity indication. The package offers:
+
+* Obesity-specific SDTM test data (to be moved to {pharmaversesdtm} at the next release of the package);
+* Two brand-new functions: admiralmetabolic::derive_param_waisthgt() and admiralmetabolic::derive_param_waisthip();
+* Two vignettes for an [obesity vital signs ADaM ADVS](https://pharmaverse.github.io/admiralmetabolic/articles/advs.html) and a [Control of Eating Questionnaire ADaM ADCOEQ](https://pharmaverse.github.io/admiralmetabolic/articles/adcoeq.html);
+* Two template programs for [ADVS](https://github.com/pharmaverse/admiralmetabolic/blob/main/inst/templates/ad_advs.R) and [ADCOEQ](https://github.com/pharmaverse/admiralmetabolic/blob/main/inst/templates/ad_adcoeq.R) matching the corresponding vignettes.
+
+## New Functions
+
+The first function, admiralmetabolic::derive_param_waisthgt(), is a wrapper to admiral::derive_param_computed() and enables users to add derived waist to height ratio parameters to a vital signs ADVS ADaM using waist circumference and height records. Here is an example of the function in action:
+
+```{r, eval = TRUE}
+library(tibble)
+library(admiral)
+library(admiralmetabolic)
+
+# Derive Waist to Height Ratio. In this example height is measured only once per subject.
+
+advs <- tribble(
+  ~USUBJID,      ~PARAMCD, ~PARAM,                     ~AVAL, ~AVALU, ~VISIT,
+  "01-101-1001", "HEIGHT", "Height (cm)",              147,   "cm",   "SCREENING",
+  "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110,   "cm",   "SCREENING",
+  "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108,   "cm",   "WEEK 2",
+  "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107,   "cm",   "WEEK 3",
+  "01-101-1002", "HEIGHT", "Height (cm)",              163,   "cm",   "SCREENING",
+  "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120,   "cm",   "SCREENING",
+  "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118,   "cm",   "WEEK 2",
+  "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117,   "cm",   "WEEK 3",
+)
+
+derive_param_waisthgt(
+  advs,
+  by_vars = exprs(USUBJID, VISIT),
+  wstcir_code = "WSTCIR",
+  height_code = "HEIGHT",
+  set_values_to = exprs(
+    PARAMCD = "WAISTHGT",
+    PARAM = "Waist to Height Ratio"
+  ),
+  constant_by_vars = exprs(USUBJID),
+  get_unit_expr = admiral::extract_unit(PARAM)
+)
+```
+
+Note that this function has built-in support for:
+
+* Unit conversion in cases where units differ across the numerator and denominator (allowed units: m, mm, ft, in);
+* Single or multiple height measurement by modifying the argument `constant_by_vars`. 
+Please visit the function's reference page for more details.
+
+`admiralmetabolic::derive_param_waisthip()` is very similar: it is also a wrapper to `admiral::derive_param_computed()`, but this time enables users to add derived waist to hip ratio parameters using waist- and hip circumference. It boasts the same unit-flexibility as `admiralmetabolic::derive_param_waisthgt()` - let's look at that in action:
+
+```{r, eval = TRUE}
+advs2 <- tribble(
+  ~USUBJID,      ~PARAMCD, ~PARAM,                     ~AVAL, ~AVALU, ~VISIT,
+  "01-101-1001", "HIPCIR", "Hip Circumference (cm)",   125,   "cm",   "SCREENING",
+  "01-101-1001", "HIPCIR", "Hip Circumference (cm)",   124,   "cm",   "WEEK 2",
+  "01-101-1001", "WSTCIR", "Waist Circumference (in)", 43.31, "in",   "SCREENING",
+  "01-101-1001", "WSTCIR", "Waist Circumference (in)", 42.52, "in",   "WEEK 2",
+  "01-101-1002", "HIPCIR", "Hip Circumference (cm)",   135,   "cm",   "SCREENING",
+  "01-101-1002", "HIPCIR", "Hip Circumference (cm)",   133,   "cm",   "WEEK 2",
+  "01-101-1002", "WSTCIR", "Waist Circumference (in)", 47.24, "in",   "SCREENING",
+  "01-101-1002", "WSTCIR", "Waist Circumference (in)", 46.46, "in",   "WEEK 2"
+)
+
+derive_param_waisthip(
+  advs2,
+  by_vars = exprs(USUBJID, VISIT),
+  wstcir_code = "WSTCIR",
+  hipcir_code = "HIPCIR",
+  set_values_to = exprs(
+    PARAMCD = "WAISTHIP",
+    PARAM = "Waist to Hip Ratio"
+  ),
+  get_unit_expr = admiral::extract_unit(PARAM)
+)
+```
+
+## Vignettes and Template
+
+On the {admiralmetabolic} package website, users will find the [obesity ADVS vignette](https://pharmaverse.github.io/admiralmetabolic/articles/advs.html). This documentation page will guide users towards creating an obesity ADVS ADaM, touching upon how to use our two new functions admiralmetabolic::derive_param_waisthgt() and admiralmetabolic::derive_param_waisthip() as well as how to apply existing {admiral} tools such as the brand-new (as of [admiral 1.2](https://pharmaverse.github.io/blog/posts/2025-01-17_1.2_admiral.../1.2_admiral_release.html)) admiral::derive_vars_cat() to create weight classes within the AVALCAT variable and admiral::derive_vars_crit_flag() to create criterion flag/variable pairs for endpoints such as a 5% reduction in weight at a certain visit.
+
+Of course, this vignette is coupled with the [obesity ADVS template program](https://github.com/pharmaverse/admiralmetabolic/blob/main/inst/templates/ad_advs.R), which users can use as a starting point for their ADaM scripts. The template can also be loaded and saved directly from the R console by running:
+
+```{r, eval = FALSE}
+admiral::use_ad_template("ADVS", package = "admiralmetabolic")
+```
+
+The [Control of Eating Questionnaire](https://licensing.leeds.ac.uk/product/control-of-eating-questionnaire-coeq) (COEQ) is used in many obesity trials as an endpoint. As such, {admiralmetabolic} also contains a vignette geared towards the creation of an ADaM dataset ADCOEQ for the COEQ. 
+Due to the flexibility of the parent {admiral} package, functions such as admiral::derive_summary_records() can be employed to create ADCOEQ. Users are invited to visit the [vignette](https://pharmaverse.github.io/admiralmetabolic/articles/adcoeq.html) for more details and a full walkthrough. 
+
+Once again, this vignette comes hand-in-hand with the [ADCOEQ program](https://github.com/pharmaverse/admiralmetabolic/blob/main/inst/templates/ad_advs.R), which can be accessed through the link above or directly from the R console by running:
+
+```{r, eval = FALSE}
+admiral::use_ad_template("ADCOEQ", package = "admiralmetabolic")
+```
+
+# Conclusion
+
+We love growing the {admiral} family, and hope you are just as excited about {admiralmetabolic} as we are.
+We welcome community feedback about the package, its content and development directions for future releases. Please raise your feedback as issues or discussions in our [GitHub repository](https://github.com/pharmaverse/admiralmetabolic) or the [pharmaverse slack](https://join.slack.com/t/pharmaverse/shared_invite/zt-yv5atkr4-Np2ytJ6W_QKz_4Olo7Jo9A). The development team will be meeting next month for a retrospective and a plan for the next release, so please reach out! 
+
+Finally, if you have any suggestions for new extension packages, or would like to drive one yourself, please reach out to the {admiral} Business Lead, Edoardo Mancini and/or the Technical Lead, Ben Straub through the [pharmaverse slack](https://join.slack.com/t/pharmaverse/shared_invite/zt-yv5atkr4-Np2ytJ6W_QKz_4Olo7Jo9A) and we'd be happy to discuss next steps with you.
+
+<!--------------- appendices go here ----------------->
+
+```{r, echo=FALSE}
+source("appendix.R")
+insert_appendix(
+  repo_spec = "pharmaverse/blog",
+  name = long_slug,
+  # file_name should be the name of your file
+  file_name = list.files() %>% stringr::str_subset(".qmd") %>% first()
+)
+```