Gilead-BioStats · lauramaxwell · Mar 13, 2025 · Mar 11, 2025 · Mar 11, 2025 · Mar 11, 2025
diff --git a/.github/workflows/qualification-report.yaml b/.github/workflows/qualification-report.yaml
@@ -30,5 +30,6 @@ jobs:
           client-payload: '{
           "GH_TOKEN": "${{ secrets.GSM_QC_TOKEN }}",
           "repository": "${{ github.repository }}",
-          "release_tag": "${{ github.ref_name }}"
+          "release_tag": "${{ github.ref_name }}",
+          "head_ref": "${{ github.head_ref }}"
           }'
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -24,8 +24,9 @@ Authors@R: c(
     person("Devin", "Pastoor", , "devin@a2-ai.com", role = "aut"),
     person("Gilead Sciences", role = "cph")
   )
-Description: The Good Statistical Monitoring or 'gsm.core' R package provides a
-    framework for statistical data monitoring.
+Description: The Good Statistical Monitoring or 'gsm' suite of R packages provides a
+    framework for statistical data monitoring. 'gsm.core' provides the analytics framework for constructing
+    metrics, and the utility functions to run workflows.
 License: Apache License (>= 2)
 URL: https://github.com/Gilead-BioStats/gsm.core, https://gilead-biostats.github.io/gsm.core
 BugReports: https://github.com/Gilead-BioStats/gsm.core/issues

diff --git a/README.md b/README.md
@@ -4,22 +4,31 @@
 
 <!-- badges: end -->
 
-# Good Statistical Monitoring {gsm.core} R package
+# Good Statistical Monitoring `{gsm.core}` R package
 
-The {gsm.core} package provides a standardized Risk Based Quality Monitoring (RBQM) framework for clinical trials that pairs a flexible data pipeline with robust reports like the one shown below.  
+The `{gsm.core}` package provides the analytical foundation for a standardized Risk Based Quality Monitoring (RBQM) framework for clinical trials that pairs a flexible data pipeline with robust reports like the one shown below.  
 
 <center> 
 
 ![](man/figures/gsm_report_screenshot_1.png)
 
 </center>
 
-This README provides a high-level overview of {gsm.core}; see the [package website](https://gilead-biostats.github.io/gsm.core/) for additional details.
+This README provides a high-level overview of `{gsm.core}`; see the [package website](https://gilead-biostats.github.io/gsm.core/) for additional details.
 
+The `{gsm.core}` package is a successor package to [`{gsm}`](https://github.com/Gilead-BioStats/gsm), which has been deprecated as of March 2025.
+The contents of `{gsm}` have been split out among 4 packages as follows:
+
+1. **`{gsm.core}`**: A package containing the analytics functionality and utility functions to run workflows.
+2. [**`{gsm.mapping}`**](https://github.com/Gilead-BioStats/gsm.mapping): A package that provides workflows to apply the necessary data transformation from raw/source datasets to appropriate domains.
+3. [**`{gsm.kri}`**](https://github.com/Gilead-BioStats/gsm.kri): A package that provides workflows
+    to generate metrics and functionality to visualize and report on these metrics.
+4. [**`{gsm.reporting}`**](https://github.com/Gilead-BioStats/gsm.reporting): A package that provides workflows
+    to generate the reporting data model needed to generate reports.
 
 # Background 
 
-The {gsm.core} package performs risk assessments primarily focused on detecting differences in quality at the site-level. "High quality" is defined as the absence of errors that matter. We interpret this as focusing on detecting potential issues related to critical data or process across the major risk categories of safety, efficacy, disposition, treatment, and general quality, where each category consists of one or more risk assessment(s). Each risk assessment will analyze the data to flag sites with potential issues and provide a visualization to help the user understand the issue. Some relevant references are provided below. 
+The `{gsm.core}` package lays the framework to perform risk assessments primarily focused on detecting differences in quality at the site-level. "High quality" is defined as the absence of errors that matter. We interpret this as focusing on detecting potential issues related to critical data or process across the major risk categories of safety, efficacy, disposition, treatment, and general quality, where each category consists of one or more risk assessment(s). Each risk assessment will analyze the data to flag sites with potential issues and provide a visualization to help the user understand the issue. Some relevant references are provided below. 
 
 - Centralized Statistical Monitoring: [1](https://documents.pub/reader/full/centralized-statistical-monitoring-to-detect-data-integrity-issues-statisticalcentralized), [2](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7308734/), [3](https://www.magiworld.org/Journal/2014/1411_Centralized.pdf).
 [4](https://pubmed.ncbi.nlm.nih.gov/38796099/)
@@ -30,7 +39,7 @@ The {gsm.core} package performs risk assessments primarily focused on detecting
 
 # Process Overview
 
-The {gsm.core} package establishes a data pipeline for RBM using R. The package provides a framework that allows users to **assess** and **visualize** site-level risk in clinical trial data. The package currently provides assessments for the following domains:
+The `{gsm.core}` package is the foundation of a data pipeline for RBM using R. The package, along with `{gsm.mapping}`, `{gsm.kri}` and `{gsm.reporting}` provides a framework that allows users to **assess** and **visualize** site-level risk in clinical trial data. The packages currently provide assessments for the following domains:
 
 1.  Adverse Event Reporting Rate
 2.  Serious Adverse Event Reporting Rate
@@ -45,7 +54,7 @@ The {gsm.core} package establishes a data pipeline for RBM using R. The package
 11. Data Change Rate
 12. Screen Failure Rate
 
-All {gsm.core} assessments use a standardized 6 step data pipeline: 
+All `{gsm.core}` assessments use a standardized 6 step data pipeline: 
 
 1.  **Input_Rate** - Converts `raw` data to `input` data.
 2.  **Transform** - Converts `input` data to `transformed` data.
@@ -54,7 +63,7 @@ All {gsm.core} assessments use a standardized 6 step data pipeline:
 5.  **Flag** - Uses `analyzed` data and numeric `thresholds` to create `flagged` data.
 6.  **Summarize** - Selects key columns from `flagged` data to create `summary` data.
 
-To learn more about {gsm.core}'s data pipeline, visit the [Data Pipeline Vignette](https://gilead-biostats.github.io/gsm.core/articles/DataModel.html).
+To learn more about `{gsm.core}`'s data pipeline, visit the [Data Pipeline Vignette](https://gilead-biostats.github.io/gsm.core/articles/DataModel.html).
 
 # Reporting
 

diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -14,9 +14,12 @@ navbar:
 articles:
   - title: Articles
     contents:
+      - Cookbook
       - DataAnalysis
-      - articles/KRIMethod
-      - articles/ContributorGuidelines
+      - DataModel
+      - gsmExtensions
+      - KRIMethod
+      - ContributorGuidelines
 reference:
   - title: Analyze
     desc: Conduct statistical analysis based on input data

diff --git a/inst/examples/3_ReportingWorkflow.R b/inst/examples/3_ReportingWorkflow.R
@@ -1,3 +1,8 @@
+library(gsm.core)
+library(gsm.mapping)
+library(gsm.kri)
+library(gsm.reporting)
+
 #### 3.1 - Create a KRI Report using 12 standard metrics in a step-by-step workflow
 
 core_mappings <- c("AE", "COUNTRY", "DATACHG", "DATAENT", "ENROLL", "LB",
@@ -61,16 +66,16 @@ lRaw <- Ingest(gsm.core::lSource, mappings_spec)
 mapped <- RunWorkflows(mappings_wf, lRaw)
 
 # Step 2 - Create Metrics - calculate metrics using mapped data
-metrics_wf <- MakeWorkflowList(strPath = "workflow/2_metrics")
+metrics_wf <- MakeWorkflowList(strPath = "workflow/2_metrics", strPackage = "gsm.kri")
 analyzed <- RunWorkflows(metrics_wf, mapped)
 
 # Step 3 - Create Reporting Layer - create reports using metrics data
-reporting_wf <- MakeWorkflowList(strPath = "workflow/3_reporting")
+reporting_wf <- MakeWorkflowList(strPath = "workflow/3_reporting", strPackage = "gsm.reporting")
 reporting <- RunWorkflows(reporting_wf, c(mapped, list(lAnalyzed = analyzed,
                                                        lWorkflows = metrics_wf)))
 
 # Step 4 - Create KRI Report - create KRI report using reporting data
-module_wf <- MakeWorkflowList(strPath = "workflow/4_modules")
+module_wf <- MakeWorkflowList(strPath = "workflow/4_modules", strPackage = "gsm.kri")
 lReports <- RunWorkflows(module_wf, reporting)
 
 #### 3.4 - Combine steps in to a single workflow

diff --git a/inst/examples/_setup.R b/inst/examples/_setup.R
@@ -1,3 +1,2 @@
-devtools::install_github('gilead-biostats/clindata')
-devtools::install_github('gilead-biostats/gsm@dev')
-# or gsm git checkout branch and devtools::load_all()
+devtools::install_github('gilead-biostats/gsm.core@dev')
+# or gsm.core git checkout branch and devtools::load_all()
diff --git a/man/gsm.core-package.Rd b/man/gsm.core-package.Rd
diff --git a/vignettes/articles/ContributorGuidelines.Rmd → vignettes/ContributorGuidelines.Rmd b/vignettes/articles/ContributorGuidelines.Rmd → vignettes/ContributorGuidelines.Rmd
@@ -1,6 +1,6 @@
 ---
 title: "Contributor Guidelines"
-description: "This page outlines the development process for `{gsm.core}` packages, including how to contribute by filing issues, bug reports, and submitting code via a Pull Request."
+description: "This page outlines the development process for `{gsm}` packages, including how to contribute by filing issues, bug reports, and submitting code via a Pull Request."
 output: rmarkdown::html_vignette
 vignette: >
   %\VignetteIndexEntry{Contributor Guidelines}
@@ -18,7 +18,7 @@ knitr::opts_chunk$set(
 
 # Introduction
 
-This page outlines the development process for `{gsm.core}` packages, including how to contribute by filing issues, bug reports, and submitting code via a Pull Request.
+This page outlines the development process for `{gsm}` packages, including how to contribute by filing issues, bug reports, and submitting code via a Pull Request.
 
 ## Prerequisites
 
@@ -65,7 +65,7 @@ Code release follows a process using `release` branches. A release is initiated
 
 # Style Guide {#style-guide}
 
-Code developers for `{gsm.core}` use the [tidyverse style guide](https://style.tidyverse.org/) with minimal modifications. The code below is run to standardize styling before each release:
+Code developers for `{gsm}` use the [tidyverse style guide](https://style.tidyverse.org/) with minimal modifications. The code below is run to standardize styling before each release:
 
     double_indent_style <- styler::tidyverse_style()
     double_indent_style$indention$unindent_fun_dec <- NULL
@@ -99,12 +99,10 @@ Code developers for `{gsm.core}` use the [tidyverse style guide](https://style.t
 ## `release` Branch Workflow {#release-branch-workflow}
 
 1.  Release Owner creates `release` branch from `dev` branch.
-    -   The `release` branch should be named according to the version of `{gsm.core}` being released (e.g., `release-v1.2.0`) using [semantic versioning](https://semver.org/).
+    -   The `release` branch should be named according to the version of the package being released (e.g., `release-v1.2.0`) using [semantic versioning](https://semver.org/).
     -   If a release branch is already created, make sure that it is synced with the current `dev` branch.
 2.  Release Owner prepares the release for QC by performing the following steps and pushing updates to the `release` branch:
     -   Confirm that the version in the `DESCRIPTION` file is up to date.
-        -   **After** the version in the `DESCRIPTION` file is updated, run `gsm.core::UpdateGSMVersion()` to update metadata that includes the `{gsm.core}` version number.
-
     -   Run `styler` using the script from the [style guide](#style-guide) above (or by running `gutil::style_code()`) and commit any updates.
     -   Update `NEWS.md` with a summary of the revisions/additions in the release. Keep any information from previous releases to maintain traceability through versions.
     -   Ensure that the qualification specifications spreadsheet is up-to-date and accurate. If there have been any changes/updates to qualification tests, reach out to the qualification developer to update any necessary files.
@@ -201,7 +199,7 @@ This QC checklist is to be used as part of the Development and Release Workflows
 
 # Appendix 3 - Continuous Integration with GitHub Actions <!--# Do we need to add missing actions, i.e., Style, check-dev, pages-build-deployment? --> {#github-action-workflow}
 
-GitHub Actions are used in `{gsm.core}` to automate processes and ensure all code and documentation is created consistently and documented thoroughly.
+GitHub Actions are used in all `{gsm}` packages to automate processes and ensure all code and documentation is created consistently and documented thoroughly.
 
 ## Merges to `dev` Branch
 
@@ -212,7 +210,7 @@ GitHub Actions are used in `{gsm.core}` to automate processes and ensure all cod
     -   Builds Assessment Specification tables from function documentation
     -   Outputs are added to `man`/`.md` and any changes are committed to the compare branch or the triggering Pull Request.
 -   Test Coverage (`test-coverage`):
-    -   Uses `{covr}` to check the package coverage of `{gsm.core}`.
+    -   Uses `{covr}` to check the package coverage.
 -   Qualification Check (`qualification-check-dev`):
     -   Runs the qualification tests but will not fail if any of the tests do not pass. Developers should review this check when changes that might need updates to qualification are done. <!--# Unsure what this sentence means -->
 
@@ -222,6 +220,6 @@ GitHub Actions are used in `{gsm.core}` to automate processes and ensure all cod
     -   Basic R CMD check which can be run using `rcmdcheck::rcmdcheck()`
     -   Provides an additional check for the ability to build the `pkgdown` reference index and ensure that all functions are documented correctly. The check will also run all qualification tests to ensure that the release is fully qualified. This check will run on `ubuntu-latest` and on R version 4.1.3. Additionally, it will be run on the latest R release version on `windows-latest`, `macOS-latest`, and `ubuntu-latest`.
 -   `pkgdown`:
-    -   Builds the [pkgdown site](https://gilead-biostats.github.io/gsm.core/) for `{gsm.core}`.
+    -   Builds the [pkgdown site](https://gilead-biostats.github.io/gsm.core/) for the relevant package (`{gsm.core}` in this case).
 -   Qualification Report (`qualification-report`):
     -   Builds the qualification vignette as an attached artifact to the Pull Request. This should be reviewed by the Pull Request Owner for completeness and correctness to ensure that the artifact added to the release is correct.
diff --git a/vignettes/Cookbook.Rmd b/vignettes/Cookbook.Rmd
@@ -0,0 +1,83 @@
+---
+title: "Cookbook"
+description: "Sample code showing how to use the Good Statistical Monitoring {gsm} suite of  packages using sample data from {gsm.core}."
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Cookbook}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include = FALSE}
+library(gsm.core)
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+# Introduction
+
+This vignette contains sample code showing how to use the Good Statistical Monitoring `{gsm}` suite of  packages using sample data from `{gsm.core}`. For more information on the `{gsm}` suite of packages see the [package homepage](https://gilead-biostats.github.io/gsm.core/).
+
+# Setup and Installation
+
+Run the following:
+
+```{r eval = FALSE, include = TRUE}
+## Install devtools
+install.packages('devtools')
+
+## Install and load gsm
+devtools::install_github("Gilead-BioStats/gsm.core", ref = "main")
+library(gsm.core)
+
+## Install and load gsm.mapping
+devtools::install_github("Gilead-BioStats/gsm.mapping", ref = "main")
+library(gsm.mapping)
+
+## Install and load gsm.kri
+devtools::install_github("Gilead-BioStats/gsm.kri", ref = "main")
+library(gsm.kri)
+
+## Install and load gsm.reporting
+devtools::install_github("Gilead-BioStats/gsm.reporting", ref = "main")
+library(gsm.kri)
+```
+
+# Example 1 - Adverse Events Metric - Scripted
+
+This example uses the standard {gsm} analysis workflows to creates site-level Adverse Event scripts. See the [Data Analysis Vignette](https://gilead-biostats.github.io/gsm.core/articles/DataAnalysis.html) for more detail.
+
+- **Example 1.1** calculates the Site-level AE rates.
+- **Example 1.2** adds a filter to include only Serious Adverse Events (SAEs) and implements pipes to run through the workflow.
+- **Example 1.3** generates bar charts showing SAE rates and z-scores by study.
+- **Example 1.4** generates a scatter plot with confidence bound for SAE rates.
+
+```{r file = system.file("examples", "1_AdverseEventKRI.R", package = "gsm.core"), eval = FALSE, include = TRUE}
+
+```
+
+# Example 2 - Adverse Events Metrics - Workflow
+
+This examples introduces YAML workflows to re-generate the same results as in **Example 1** via a reusable pipeline. See the [Data Model Vignette](https://gilead-biostats.github.io/gsm.core/articles/DataModel.html) for more detail.
+
+- **Example 2.1** runs the AE KRI workflow.
+- **Example 2.2** updates the metadata to run country-level metrics.
+- **Example 2.3** adds a filtering step to the workflow to generate the SAE metric.
+
+```{r file = system.file("examples", "2_AdverseEventWorkflow.R", package = "gsm.core"), eval = FALSE, include = TRUE}
+
+```
+
+# Example 3 - Study-Level Reporting Workflows 
+
+This example extends the previous examples to generate charts and reports for multiple KRIs. See the [Data Reporting Vignette](https://gilead-biostats.github.io/gsm.reporting/articles/DataReporting.html) for more detail.
+
+- **Example 3.1** steps through several workflows to generate a report for all 12 standard site-level KRIs.
+- **Example 3.2** automates data ingestion using `Ingest()` and `CombineSpecs()`.
+- **Example 3.3** generates a report incorporating multiple timepoints using the sample `reporting` data saved as part of {gsm}.  
+
+```{r file = system.file("examples", "3_ReportingWorkflow.R", package = "gsm.core"), eval = FALSE, include = TRUE}
+
+```