gsm.timez

Overview

gsm.timez is a GSM extension for longitudinal site monitoring. It applies funnel plot scoring across sequential months to detect sites with unusual cumulative event trajectories.

The package includes the following main functions:

• Timeline(): Generates a site-level timeline of cumulative numerator events (e.g. adverse events) over sequential months.
• Analyze_TimeZFunnel(): Applies gsm.core::Analyze_NormalApprox() across sequential months, producing funnel plot scores for each site over time.
• Flag(): Extends gsm.core::Flag() with sparse-month awareness for time-series data.
• PredictBounds_TimeZFunnel(): Applies gsm.core::Analyze_NormalApprox_PredictBounds() across sequential months to produce funnel bounds for visualization.
• Visualize_Funnel(): funnel plot for a single selected month, showing site Metric values against their Denominator with Normal approximation control bounds.
• Visualize_Heatmap(): heatmap showing each site’s flag status over time.
• Visualize_Site(): line plot highlighting a single site’s cumulative metric trajectory against all other sites, marking flagged months.

Installation

You can install the development version of gsm.timez with:

install.packages("pak")
pak::pak("IMPALA-Consortium/gsm.timez")

Quick Start

library(gsm.timez)
library(dplyr)

# Prepare data
dfSubjects <- clindata::rawplus_dm
dfNumerator <- clindata::rawplus_ae
dfDenominator <- clindata::rawplus_visdt %>%
  dplyr::mutate(visit_dt = as.Date(visit_dt, "%Y-%m-%d"))

# Full pipeline: Timeline -> Funnel Score -> Flag -> Visualize
gsm.timez::Timeline(
  dfSubjects            = dfSubjects,
  dfNumerator           = dfNumerator,
  dfDenominator         = dfDenominator,
  strGroupCol           = "invid",
  strSubjectCol         = "subjid",
  strNumeratorDateCol   = "aest_dt",
  strDenominatorDateCol = "visit_dt"
) %>%
  gsm.timez::Analyze_TimeZFunnel() %>%
  gsm.timez::Flag(vThreshold = c(-1.5, -1, 2, 3)) %>%
  gsm.timez::Visualize_Heatmap(nSites = 30)

Quality Control

Since {gsm} is designed for use in a GCP framework, we have conducted extensive quality control as part of our development process. In particular, we do the following during early development:

• Unit Tests - Unit tests are written for all core functions, 100% coverage required.
• Workflow Tests - Additional unit tests confirm that core workflows behave as expected.
• Function Documentation - Detailed documentation for each exported function with examples is maintained with Roxygen.
• Package Checks - Standard package checks are run using GitHub Actions and must be passing before PRs are merged.
• Continuous Integration - Continuous integration is provided via GitHub Actions.
• Code Formatting - Code is formatted with {styler} before each release.
• Contributor Guidelines - Detailed contributor guidelines including step-by-step processes for code development and releases are provided as a vignette.
• Code Demonstration - Cookbook Vignette provides demos and explanations for code usage.