MRDviz

MRDviz is an R package that provides a powerful Shiny application for visualizing and simulating Minimal Residual Disease (MRD) data in clinical trials. This interactive tool enables researchers and clinicians to analyze longitudinal MRD measurements, perform survival analysis, and simulate MRD trajectories.

🚀 Features

MRDviz is composed of two primary, interconnected modules designed to support the full lifecycle of MRD research, from exploring existing data to designing future studies.

Interactive Visualization for Exploratory Data Analysis

This module provides an intuitive interface for the deep exploration of longitudinal MRD data and associated clinical outcomes. It is designed for rapid data quality control and hypothesis generation (Manual).

• Coordinated & Interactive Plots: All visualizations are linked. Selecting a patient subgroup in one plot will instantly update all other plots.
  • MRD Trajectories: Visualize how individual and group MRD levels change over time.
  • Dynamic Color-Coding: Instantly color-code trajectories by any covariate (e.g., treatment arm, mutation status) to discover patterns and outliers.
  • Heatmap of time-variant covariates: Get a clear overview of the state of time-variant covariates (such as response status or MRD negativity) over the course of the study.
  • Kaplan-Meier Survival Plots: Automatically generate and compare survival curves for any selected patient subgroup to immediately assess the impact of covariates on outcomes.
• Flexible Subgroup Analysis: Interactively filter and select complex patient subgroups based on any combination of clinical or genomic variables.
• Data Export: The detailed data table dynamically displays the currently selected patient cohort, which can be instantly downloaded as a CSV file for further downstream analysis or modeling.

Joint Simulation of MRD Trajectories and Survival Outcomes

This module provides a powerful and flexible engine to generate realistic, synthetic datasets where the ground truth is known. It is designed to support methodological research, clinical trial design, and power calculations (Manual).

• Sophisticated Joint Modeling: The simulator is built on a mathematical framework that jointly models the three phases of MRD kinetics (initial decay, plateau, relapse) and links the MRD trajectory to time-to-event outcomes using a Cox proportional-hazards model.
• Full Parameter Control: A comprehensive graphical interface allows you to define and control all parameters of the simulation, from baseline MRD levels and decay rates to the strength of the MRD-survival association.
• Real-Time Visual Feedback: As you adjust parameters, you can instantly visualize the resulting MRD trajectories and survival curves. This interactive feedback loop is a key feature that helps you tune the simulation to generate highly realistic data tailored to specific biological or clinical scenarios.
• "Gold Standard" Data Generation: The tool outputs both the raw simulated patient data and a "ground truth" table of the exact parameters used to generate the data for each patient. This is essential for creating benchmark datasets to validate and compare the performance of novel statistical models.

Installation

You can install MRDviz from GitHub using the remotes package:

# Install devtools if you haven't already
install.packages("remotes")

# Install MRDviz
remotes::install_github("abbvie-external/MRDviz")

Dependencies

MRDviz relies on several R packages that will be automatically installed:

• shiny
• shinyjs
• shinydashboard
• memoise
• highcharter
• data.table
• DT
• survival
• survminer
• tidyverse (especially ggplot2, dplyr, purrr)

Usage

Basic Usage

To launch the MRDviz application, simply run:

library(MRDviz)
run_mrdviz()

This will start the Shiny application in your default web browser, providing access to all visualization and simulation features.

Docker Usage

For a reproducible and isolated environment, MRDviz is available as a pre-built Docker container from the GitHub Container Registry (GHCR).

1. Pull the Docker Image:

   docker pull ghcr.io/abbvie-external/mrdviz:v0.3.1

2. Run the Container:

   docker run --rm -p 3838:3838 ghcr.io/abbvie-external/mrdviz:v0.3.1

   You can then access the application in your web browser at http://localhost:3838.

For advanced usage, including instructions on building the container from the Dockerfile, using Docker Compose, and important security considerations for running the container without root privileges, please see the detailed Docker Tutorial.

Quick Start with Example Data

To get started immediately with example data, you can launch the app with a pre-loaded dataset:

library(MRDviz)

# Launch with small example dataset (recommended for first-time users)
example_file <- system.file("testdata", "simulated_mrd.short.json", package = "MRDviz")
run_mrdviz(example_file)

# Or launch with the full example dataset
example_file <- system.file("testdata", "simulated_mrd.json", package = "MRDviz")
run_mrdviz(example_file)

Exploring Available Example Datasets

To see what example datasets are available:

# View all available example datasets
get_example_datasets()

# Load example data for programmatic analysis
example_data <- load_example_data("simulated_mrd.short.json")
str(example_data, max.level = 2)

Using Your Own Data

MRDviz is designed to work with your own clinical data. Since data in clinical research settings is often in tabular formats like Excel or CSV, MRDviz includes a helper function to make the conversion process as simple as possible.

1. Convert to JSON: Use the convert_to_json() helper function to convert your CSV or Excel files directly into the required JSON format.

   # Example of converting your own data from files
   convert_to_json(
     longitudinal_file = "path/to/longitudinal_data.csv",
     event_file = "path/to/event_data.csv",
     output_file = "my_mrd_data.json"
   )

2. Launch the App: Launch MRDviz with the path to your newly created JSON file.

   run_mrdviz("my_mrd_data.json")

For a complete guide on the required data structure, field descriptions, and the JSON schema, please see the detailed JSON Format Guide. This guide also includes important advice on data de-identification and privacy.

License

This package is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions to MRDviz! Whether you're interested in fixing bugs, adding new features, improving documentation, or helping with testing, your contributions are valued.

For detailed information on how to contribute, including:

• Development setup and workflow
• Coding standards and best practices
• Testing guidelines
• Pull request process
• Issue reporting

Please see our comprehensive Contributing Guide.

For quick contributions, feel free to submit a Pull Request, but we encourage reviewing the contributing guidelines first to ensure a smooth process.

Citation

If you use MRDviz in your research, please cite:

@article{Choi2025,
author    = {K. Choi and others},
title     = {MRDviz: An Integrated Platform for Interactive Visualization and Joint Simulation of Minimal Residual Disease Trajectories and Associated Survival Outcomes},
year      = {2025},
note      = {In Review at Bioinformatics Advances}
}