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)
- 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 sonnei data; swap in your own amRml output with one argument
- Headless figure export: Render every visualization to PNG/PDF/JPG
files without launching the dashboard, with one call to
exportAMRVisualizations()
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")library(amRviz)
# Launch with built-in Shigella sonnei demo data
launchAMRDashboard()
# Launch with your own amRml output
launchAMRDashboard(results_root = "/path/to/your/orb")The dashboard will open in your default web browser. Species dropdowns will populate automatically from whichever data is loaded.
If you’d rather not run the interactive dashboard,
exportAMRVisualizations() renders every visualization to static image
files in a single call — handy for reports, batch pipelines, or a quick
look at all the figures at once.
library(amRviz)
# Export the bundled demo figures as PNG + PDF into ./amRviz_exports/
exportAMRVisualizations()
# Your own results, PNG + JPG, a single species
exportAMRVisualizations(
output_dir = "figures",
formats = c("png", "jpg"),
results_root = "/path/to/your/orb",
species = "Shigella_sonnei"
)One figure set is produced per species using the same default selections
the dashboard opens with, organized as
output_dir/<species>/<panel>.<ext>. Cross-species overviews (the
performance heatmaps and the across-species feature-importance panel)
are written once under _overview/ and _across_species/.
You can adjust how many features appear with top_n_features
(feature-importance panels) and network_top_n (the drug-feature
network), and control raster resolution with scale:
exportAMRVisualizations(top_n_features = 25, network_top_n = 10, scale = 3)- Formats: all four (
png,jpg,pdf,svg) are supported.pngis a headless-Chrome screenshot;jpgandpdfare re-encodes of that PNG, so every raster format shares the same crop and dimensions.svgis extracted from the rendered DOM (with all text inlined), giving a scalable, vector figure — the best choice for publication. - Requirements: every plot is an interactive htmlwidget, so export
drives each one with a headless Chrome via the
webshot2andchromotepackages, then reformats withmagick. Install Google Chrome or Chromium if you don’t already have one; the function stops early with a clear message if no browser is found.
The dashboard is organized into tabs:
- Home: Overview, suite workflow, and project information
- 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
- 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)
- Bug/Drug feature comparison: Analyze predictive features
- Top features across species or across drugs
- Annotated feature tables (COG/ARG), category barplots, and ego networks
- Model holdouts: Compare models across stratifications
- Country-holdout and year-interval models
- Accuracy distributions, performance heatmaps, and feature consistency
- Network: Interactive force-directed drug → feature graph, with optional cluster/COG nodes
- Query data: Browse and export the raw performance-metric and top-feature tables as CSV
amRviz reads an amRdata ORB and the amRml runs saved inside it:
Shigella_sonnei/orb/
├── manifest_run_*.json # the amRdata record: species, files
├── metadata.parquet
├── ... # feature and annotation tables
└── amRml/
└── test-full/ # one amRml run (any folder name)
├── manifest.json # the amRml record: lists the run's tables
├── metadata/
│ └── matrices.parquet # each model's data: type, drug, features
└── results/
├── tasks.parquet # each model: labels, seed, status
├── performance.parquet
└── importance.parquet
- Nothing is read from file or folder names. The species and the
metadata file come from the ORB manifest; each model’s type,
drug or drug class, feature type, encoding, labels and seed come
from the run’s tasks and matrices tables, found through its
manifest.json. - Runs are read only from inside an ORB, at
{orb}/amRml/{run}/. Passresults_rootan ORB or a folder of ORBs (such as the amRdata data folder) tolaunchAMRDashboard()to load your own data. Without this argument the dashboard loads the bundled demo data. - The bundled demo data is a small copy of a Shigella sonnei ORB
with one amRml run, made by
data-raw/demo_orb.R.
The tabs read the run’s results joined to its tasks and matrices, under these column names.
| 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, cogs, args, struct, DefenseCas |
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) |
mcc, bal_acc, f1, sens, spec |
Performance metrics |
| 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 |
| Column | Description |
|---|---|
genome.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 |
amRviz/
├── R/
│ ├── app.R # Main Shiny app (ui + server)
│ ├── app_shared.R # Results-folder picker and data shared by the tabs
│ ├── export.R # Figure export
│ ├── globals.R # Global variable declarations
│ ├── utils_*.R # Data loading, ORB discovery, colors, helpers
│ ├── metadata_ui.R # Each tab has a layout file (_ui), a logic
│ ├── metadata_server.R # file (_server) and a plots file (_plots)
│ ├── metadata_plots.R
│ ├── modelperf_{ui,server,plots}.R # Model Performance tab
│ ├── features_{ui,server,plots}.R # Feature Importance tab
│ ├── holdouts_{ui,server,plots}.R # Model Holdouts tab
│ ├── network_{ui,server,plots}.R # Drug-Feature Network tab
│ └── query_{ui,server}.R # Query Data tab
├── inst/
│ ├── app/www/ # Static assets (CSS, images)
│ └── extdata/
│ └── Shigella_sonnei/ # Demo ORB with one amRml run
├── man/ # Documentation
├── vignettes/ # Usage vignette and figures
└── DESCRIPTION
If you use amRviz in your research, please cite:
Ghosh A^, Brenner EP^, Boyer EA, McKim AP, Vang CK, Wolfe EP, Mayer D, Lesiyon RL, Ravi J.
amR: an R package suite to predict antimicrobial resistance in bacterial pathogens.
bioRxiv. 2026. DOI: 10.64898/2026.07.10.734579.
^ Co-first authors
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 sonnei
included in
inst/extdata/
We welcome contributions! Please see our Contributing Guidelines for details.
Report bugs and request features at: https://github.com/JRaviLab/amRviz/issues
- amRdata: Data preparation for AMR prediction
- amRml: ML modeling framework
- BV-BRC: Bacterial and Viral Bioinformatics Resource Center
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.
BSD 3-Clause License. See LICENSE for details.
Corresponding author: Janani Ravi (janani.ravi@cuanschutz.edu)
JRaviLab: https://jravilab.github.io