amRshiny

amRshiny 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
  • amRshiny: Interactive visualization (this package)

Features

  • Metadata exploration: Geographic distribution, temporal trends, host analysis
  • Model performance: Compare ML models across species, drugs, and molecular scales (genes, proteins, domains, structures)
  • Feature importance: Identify key predictive features with interactive heatmaps
  • 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

Current (development version)

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 Bioconductor dependencies
BiocManager::install("ComplexHeatmap")

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

devtools::install_github("JRaviLab/amRshiny")

Quick start 

library(amRshiny)

# 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 includes several tabs:

  1. Home: Overview and project information
  2. Metadata: Explore geographic, temporal, and host metadata
    • Summary statistics (genomes, drugs, drug classes, countries)
    • Data availability by drug
    • Geographic distribution map
    • Temporal resistance trends
    • Host and isolation source breakdown
  3. Model performance: Compare ML model metrics
    • Filter by species, drug/drug class, molecular scale, and data encoding
    • Boxplots of balanced accuracy, F1, and nMCC across drugs and scales
  4. Feature importance: Analyze predictive features
    • Top features across species or across drugs
    • Interactive heatmaps with optional COG/ARG annotation
  5. Cross-model comparison: Compare models across stratifications
    • Country-based holdout models
    • Year-based holdout models
    • Balanced accuracy heatmaps and feature consistency
  6. Query data: Custom data queries
    • Filter by species, drug, scale, and encoding
    • Export filtered results

Data requirements

amRshiny 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
feature_subtype Data encoding: binary, counts
strat_label Stratification: NA (baseline), "country", or "year"
strat_value Trained-on country or year (stratified models only)
strat_value_test Tested-on country or year (cross models only)
bal_acc Balanced accuracy
f1 F1 score
nmcc Normalized Matthews correlation coefficient

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 (NA for baseline)
Variable Feature identifier (gene/protein/domain ID)
Importance Feature importance score

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 

amRshiny/
├── R/
│   ├── app.R                      # Main Shiny app (ui + server)
│   ├── utils.R                    # File loading and plot functions
│   ├── metadataUI.R               # Metadata tab UI
│   ├── modelPerfUI.R              # Model performance tab UI
│   ├── featureImportanceUI.R      # Feature importance tab UI
│   ├── crossModelComparisonUI.R   # Cross-model comparison tab UI
│   └── queryDataUI.R              # Query data tab UI
├── inst/
│   └── extdata/
│       └── Shigella_flexneri/     # Demo data (amRml output)
├── man/                           # Documentation
└── DESCRIPTION

Citation

If you use amRshiny in your research, please cite:

Brenner E, Ghosh A, Wolfe E, Boyer E, Vang C, 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: GUI, MicrobialGenomics, Pathogen, Visualization
  • Bioconductor dependencies: ComplexHeatmap
  • R version requirement: R >= 4.1.0
  • Documentation: Comprehensive function documentation with examples
  • 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/amRshiny/issues

  • 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 amRshiny 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 ()

JRaviLab: https://jravilab.github.io