Skip to contents

Cookbook

Cookbook.Rmd

Introduction

This vignette contains sample code showing how to use the gsm extension gsm.simaerep using sample data from clindata.

In order to familiarize yourself with the gsm package, please refer to the gsm cookbook.

Installation 

install.packages("pak")
pak::pak("Gilead-BioStats/clindata")
pak::pak("Gilead-BioStats/gsm")
pak::pak("IMPALA-Consortium/gsm.simaerep")

Load

{gsm.simaerep} Functions

simaerep expects the cumulative count of numerator events per denominator event per subject as input.

In this example we we are calculating the cumulative AE count per visit per patient per site.

dfInput <- Input_CumCount(
  dfSubjects = clindata::rawplus_dm,
  dfNumerator = clindata::rawplus_ae,
  dfDenominator = clindata::rawplus_visdt %>% dplyr::mutate(visit_dt = lubridate::ymd(visit_dt)),
  strSubjectCol = "subjid",
  strGroupCol = "siteid",
  strGroupLevel = "Site",
  strNumeratorDateCol = "aest_dt",
  strDenominatorDateCol = "visit_dt"
)

dfInput %>%
  dplyr::filter(max(Numerator) > 1, .by = "SubjectID") %>%
  head(25) %>%
  knitr::kable()
SubjectID GroupID GroupLevel Numerator Denominator
0486 10 Site 0 1
0486 10 Site 0 2
0486 10 Site 0 3
0486 10 Site 0 4
0486 10 Site 0 5
0486 10 Site 0 6
0486 10 Site 0 7
0486 10 Site 0 8
0486 10 Site 2 9
0486 10 Site 2 10
0486 10 Site 2 11
0486 10 Site 2 12
0486 10 Site 2 13
0486 10 Site 2 14
0486 10 Site 2 15
0486 10 Site 2 16
0486 10 Site 2 17
0486 10 Site 2 18
0486 10 Site 2 19
0486 10 Site 2 20
0486 10 Site 2 21
0489 10 Site 0 1
0489 10 Site 0 2
0489 10 Site 2 3
0489 10 Site 2 4

Now we can analyze the data using Analyze_Simaerep() and add flags with Flag_Simaerep() which adds a Score between -1 and 1. Positive values indicate the over-reporting probability and negative values indicate the under-reporting probability.

MetricExpected is the average simulated metric value for a site that has the same number of patients with identical number of visits. Sites with identical metric ratios can have different expected metrics as the total number of patients and their individual visit count varies.

dfAnalyzed <- Analyze_Simaerep(dfInput)
dfFlagged <- Flag_Simaerep(dfAnalyzed, vThreshold = c(-0.99, -0.95, 0.95, 0.99))
#> ℹ Sorted dfFlagged using custom Flag order: 2.Sorted dfFlagged using custom Flag order: -2.Sorted dfFlagged using custom Flag order: 1.Sorted dfFlagged using custom Flag order: -1.Sorted dfFlagged using custom Flag order: 0.


dfFlagged %>%
  arrange(Score) %>%
  head(5) %>%
  knitr::kable()
GroupID GroupLevel Numerator Denominator MetricExpected Metric OverReportingProbability UnderReportingProbability Score Flag
10 Site 8 390 0.1624462 0.0205128 0 1 -1 -2
140 Site 143 1442 0.1664237 0.0991678 0 1 -1 -2
141 Site 12 261 0.1701188 0.0459770 0 1 -1 -2
143 Site 25 597 0.1666382 0.0418760 0 1 -1 -2
167 Site 14 312 0.1727051 0.0448718 0 1 -1 -2 
dfFlagged %>%
  arrange(Score) %>%
  tail(5) %>%
  knitr::kable()
GroupID GroupLevel Numerator Denominator MetricExpected Metric OverReportingProbability UnderReportingProbability Score Flag
132 Site 16 35 0.2625714 0.4571429 1 0 1 2
43 Site 397 695 0.1712835 0.5712230 1 0 1 2
75 Site 93 210 0.1625667 0.4428571 1 0 1 2
83 Site 74 140 0.1632714 0.5285714 1 0 1 2
91 Site 129 366 0.1709891 0.3524590 1 0 1 2

These results are compatible with the gsm package for visualization.

`simaerep scores represent are related to the metric ratio do not use a metric based threshold for flagging. Therefore we do not need to calculate boundaries to pass to the plotting function.

gsm.kri::Visualize_Scatter(
  dfFlagged,
  dfBounds = NULL,
  strGroupLabel = "GroupLevel",
  strUnit = "Visits"
)

gsm.kri::Widget_ScatterPlot(
  dfFlagged,
  dfBounds = NULL
)
gsm.kri::Widget_BarChart(
  dfFlagged
)

Report Building

We can create a workflow to create the gsm KRI report.

Mapping 

lRaw <- list(
  Raw_SUBJ = clindata::rawplus_dm,
  Raw_AE = clindata::rawplus_ae,
  Raw_VISIT = clindata::rawplus_visdt,
  Raw_PD = clindata::ctms_protdev,
  Raw_ENROLL = clindata::rawplus_enroll,
  Raw_SITE = clindata::ctms_site %>%
    rename(studyid = protocol) %>%
    rename(invid = pi_number) %>%
    rename(InvestigatorFirstName = pi_first_name) %>%
    rename(InvestigatorLastName = pi_last_name) %>%
    rename(City = city) %>%
    rename(State = state) %>%
    rename(Country = country) %>%
    rename(Status = site_status),
  Raw_STUDY = clindata::ctms_study %>%
    rename(studyid = protocol_number) %>%
    rename(Status = status)
)

mapping_wf <- gsm.core::MakeWorkflowList(
  strNames = NULL,
  strPath = system.file("workflow/1_mappings", package = "gsm.simaerep"),
  strPackage = NULL
)

lMapped <- gsm.core::RunWorkflows(lWorkflows = mapping_wf, lData = lRaw)

Metrics 

metrics_wf <- gsm.core::MakeWorkflowList(
  strNames = NULL,
  strPath = system.file("workflow/2_metrics", package = "gsm.simaerep"),
  strPackage = NULL
)

lAnalyzed <- gsm.core::RunWorkflows(lWorkflows = metrics_wf, lData = lMapped)

Report Generation - Workflow

This part is identical with gsm.

reporting_wf <- gsm.core::MakeWorkflowList(strPath = "workflow/3_reporting", strPackage = "gsm.reporting")

lReport <- gsm.core::RunWorkflows(reporting_wf, c(lMapped, list(
  lAnalyzed = lAnalyzed,
  lWorkflows = metrics_wf
)))

module_wf_gsm <- gsm.core::MakeWorkflowList(strPath = "workflow/4_modules", strPackage = "gsm.kri", strNames = "report_kri_site.yaml")

lModule <- gsm.core::RunWorkflows(module_wf_gsm, lReport)
#> /opt/hostedtoolcache/pandoc/3.1.11/x64/pandoc +RTS -K512m -RTS /tmp/RtmpjtG2WG/Report_KRI.knit.md --to html4 --from markdown+autolink_bare_uris+tex_math_single_backslash --output /home/runner/work/gsm.simaerep/gsm.simaerep/vignettes/kri_report_AAAA0000000_Site_20250321.html --lua-filter /home/runner/work/_temp/Library/rmarkdown/rmarkdown/lua/pagebreak.lua --lua-filter /home/runner/work/_temp/Library/rmarkdown/rmarkdown/lua/latex-div.lua --embed-resources --standalone --variable bs3=TRUE --section-divs --table-of-contents --toc-depth 3 --variable toc_float=1 --variable toc_selectors=h1,h2,h3 --variable toc_smooth_scroll=1 --variable toc_print=1 --template /home/runner/work/_temp/Library/rmarkdown/rmd/h/default.html --no-highlight --variable highlightjs=1 --variable theme=bootstrap --css styles.css --include-in-header /tmp/RtmpjtG2WG/rmarkdown-str1e7a1f16dab2.html

Report Generation - Script 

dfMetrics <- gsm.reporting::MakeMetric(lWorkflows = metrics_wf)

dfResults <- gsm.reporting::BindResults(
  lAnalysis = lAnalyzed,
  strName = "Analysis_Summary",
  dSnapshotDate = Sys.Date(),
  strStudyID = "ABC-123"
)

dfGroups <- dplyr::bind_rows(
  lMapped$Mapped_STUDY,
  lMapped$Mapped_SITE,
  lMapped$Country
)

dfBounds <- gsm.reporting::MakeBounds(
  dfResults = dfResults,
  dfMetrics = dfMetrics
)

lCharts <- gsm.kri::MakeCharts(
  dfResults = dfResults %>%
    filter(GroupLevel == "Site"),
  dfMetrics = dfMetrics %>%
    filter(GroupLevel == "Site"),
  dfGroups = dfGroups,
  dfBounds = dfBounds
)

gsm.kri::Report_KRI(
  lCharts = lCharts,
  dfResults = dfResults,
  dfGroups = dfGroups,
  dfMetrics = dfMetrics,
  strOutputFile = "report_kri_site.html"
)
#> /opt/hostedtoolcache/pandoc/3.1.11/x64/pandoc +RTS -K512m -RTS /tmp/RtmpjtG2WG/Report_KRI.knit.md --to html4 --from markdown+autolink_bare_uris+tex_math_single_backslash --output /home/runner/work/gsm.simaerep/gsm.simaerep/vignettes/report_kri_site.html --lua-filter /home/runner/work/_temp/Library/rmarkdown/rmarkdown/lua/pagebreak.lua --lua-filter /home/runner/work/_temp/Library/rmarkdown/rmarkdown/lua/latex-div.lua --embed-resources --standalone --variable bs3=TRUE --section-divs --table-of-contents --toc-depth 3 --variable toc_float=1 --variable toc_selectors=h1,h2,h3 --variable toc_smooth_scroll=1 --variable toc_print=1 --template /home/runner/work/_temp/Library/rmarkdown/rmd/h/default.html --no-highlight --variable highlightjs=1 --variable theme=bootstrap --css styles.css --include-in-header /tmp/RtmpjtG2WG/rmarkdown-str1e7a4e7bd23e.html