amRviz

amRviz is an interactive Shiny dashboard for exploring antimicrobial resistance (AMR) data and machine learning model results generated by amRml.

This is the final package in the AMR package suite, JRaviLab/amR:

• amRdata: Data (and metadata) preparation from BV-BRC
• amRml: ML modeling and analysis
• amRviz: Interactive visualization (this package)

Features

• Metadata exploration: Geographic distribution, temporal trends, host and isolation-source analysis
• Model performance: Compare ML models across species, drugs, and molecular scales (genes, proteins, domains, structures)
• Feature importance: Identify key predictive features with interactive plots, annotation tables, and networks
• Cross-model analysis: Compare models trained on different stratifications (country, year)
• Dynamic species selection: Dropdowns automatically populate from loaded data — no hardcoded species lists
• Demo mode: Ships with example Shigella flexneri data; swap in your own amRml output with one argument

Installation

The package is currently available via GitHub and will be submitted to Bioconductor.

# Install BiocManager if needed
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

# Install amRviz from GitHub
if (!requireNamespace("devtools", quietly = TRUE))
    install.packages("devtools")

devtools::install_github("JRaviLab/amRviz")

Quick start

library(amRviz)

# Launch with built-in Shigella flexneri demo data
launchAMRDashboard()

# Launch with your own amRml output
launchAMRDashboard(results_root = "/path/to/your/amRml/results")

The dashboard will open in your default web browser. Species dropdowns will populate automatically from whichever data is loaded.

Usage

Dashboard navigation

The dashboard is organized into tabs:

1. Home: Overview, suite workflow, and project information
2. Metadata: Explore geographic, temporal, host, and isolation-source metadata
   • Summary statistics (genomes, drugs, drug classes, resistant/susceptible tests)
   • Phenotype distribution by drug, geographic map, and temporal trends
   • Host and isolation-source breakdown, plus a phenotype → drug → country → source Sankey
3. Model performance: Compare ML model metrics
   • Filter by species, drug/drug class, molecular scale, and data encoding
   • Per-model metric distributions, plus a Performance overview (nMCC strip plot and drug-class heatmaps)
4. Bug/Drug feature comparison: Analyze predictive features
   • Top features across species or across drugs
   • Annotated feature tables (COG/ARG), category barplots, and ego networks
5. Model holdouts: Compare models across stratifications
   • Country-holdout and year-interval models
   • Accuracy distributions, performance heatmaps, and feature consistency
6. Network: Interactive force-directed drug → feature graph, with optional cluster/COG nodes
7. Query data: Browse and export the raw performance-metric and top-feature tables as CSV

Data requirements

amRviz reads the parquet files produced by amRml. Files must be organized into per-species subdirectories:

results/
├── Shigella_flexneri/
│   ├── Sfl_ML_perf.parquet
│   ├── Sfl_country_ML_perf.parquet
│   ├── Sfl_year_ML_perf.parquet
│   ├── Sfl_cross_ML_perf.parquet
│   ├── Sfl_ML_top_features.parquet
│   ├── Sfl_country_ML_top_features.parquet
│   ├── Sfl_year_ML_top_features.parquet
│   └── Sfl_metadata.parquet
├── Klebsiella_pneumoniae/
│   ├── Kpn_ML_perf.parquet
│   └── ...
└── ...

• The subdirectory name (e.g. Shigella_flexneri) is used as the display label throughout the dashboard.
• The species code (e.g. Sfl) inside each parquet is used for internal filtering.
• Pass results_root = "/path/to/results" to launchAMRDashboard() to load your own data. Without this argument the dashboard loads the bundled demo data.

Data schema

Performance metrics (*_ML_perf.parquet)

Column	Description
species	Species code (e.g. "Sfl")
drug_or_class	Drug or drug class abbreviation
drug_label	"drug" or "drug_class"
feature_type	Molecular scale: genes, proteins, domains, struct
feature_subtype	Data encoding: binary, counts
strat_label	Stratification: blank (baseline), "country", or "year"
strat_value / strat_value_test	Trained-on / tested-on country or year (stratified/cross models)
nmcc, bal_acc, f1, sens, spec	Performance metrics

Top features (*_ML_top_features.parquet)

Column	Description
species	Species code
drug_or_class	Drug or drug class abbreviation
feature_type	Molecular scale
feature_subtype	Data encoding
strat_label	Stratification (blank for baseline)
Variable	Feature identifier (gene/protein/domain ID)
Importance	Feature importance score
Sign	Direction of effect

Metadata (*_metadata.parquet)

Column	Description
genome_drug.genome_id	Unique genome identifier
genome_drug.antibiotic	Antibiotic tested
genome_drug.resistant_phenotype	"Resistant" or "Susceptible"
genome.isolation_country	Country of isolation
genome.collection_year	Collection year
genome.host_common_name	Host organism
genome.isolation_source	Isolation source
drug_class	Drug class
resistant_classes	All resistant drug classes for this isolate

Development

Package structure

amRviz/
├── R/
│   ├── app.R                      # Main Shiny app (ui + server)
│   ├── utils.R                    # File loading and plot functions
│   ├── globals.R                  # Global variable declarations
│   ├── metadataUI.R               # Metadata tab UI
│   ├── modelPerfUI.R              # Model performance tab UI
│   ├── featureImportanceUI.R      # Bug/Drug feature comparison tab UI
│   ├── crossModelComparisonUI.R   # Model holdouts tab UI
│   ├── networkUI.R                # Network tab UI
│   └── queryDataUI.R              # Query data tab UI
├── inst/
│   ├── app/www/                   # Static assets (CSS, images)
│   └── extdata/
│       └── Shigella_flexneri/     # Demo data (amRml output)
├── man/                           # Documentation
├── vignettes/                     # Usage vignette and figures
└── DESCRIPTION

Citation

If you use amRviz in your research, please cite:

Brenner E, Ghosh A, Boyer E, Vang C, Wolfe E, McKim A, Lesiyon R, Mayer D, Ravi J. (2026).
amR: an R package suite to predict antimicrobial resistance in bacterial pathogens.
R package version 0.99.0.
https://github.com/JRaviLab/amR

For Bioconductor submission

This package is being prepared for Bioconductor submission. It includes:

• biocViews: AMR, GUI, MicrobialGenomics, Pathogen, Visualization
• R version requirement: R >= 4.5.0
• Documentation: Function documentation with examples, plus a usage vignette
• Data: Pre-computed amRml results for Shigella flexneri included in inst/extdata/

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Reporting issues

Report bugs and request features at: https://github.com/JRaviLab/amRviz/issues

Related projects

• amRdata: Data preparation for AMR prediction
• amRml: ML modeling framework
• BV-BRC: Bacterial and Viral Bioinformatics Resource Center

Code of conduct

Please note that the amRviz project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

BSD 3-Clause License. See LICENSE for details.

Contact

Corresponding author: Janani Ravi (janani.ravi@cuanschutz.edu)

JRaviLab: https://jravilab.github.io