amRshiny

amRshiny is an interactive Shiny dashboard for exploring antimicrobial resistance (AMR) data and machine learning model results.

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)
  • Publication-quality exports: Download plots and tables
  • Modular design: Extensible UI components

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 the dashboard
launch_dashboard()

The dashboard will open in your default web browser.

Usage

Dashboard navigation

The dashboard includes several tabs:

  1. Home: Overview and project information
  2. Metadata: Explore geographic, temporal, and host metadata
    • Interactive maps and treemaps
    • Temporal trends
    • Host distribution
  3. Model performance: Compare ML model metrics
    • Filter by species, drug, molecular scale
    • View confusion matrices
    • Compare performance across models
  4. Feature importance: Analyze predictive features
    • Top features by importance
    • Cross-species/drug comparisons
    • Heatmaps and bar plots
  5. Cross-model comparison: Compare models across stratifications
    • Country-based models
    • Year-based models
    • Performance and feature consistency
  6. Query data: Custom data queries
    • Filter by multiple criteria
    • Export filtered results

Example: Exploring model performance 

launchAMRDashboard()

# In the dashboard:
# 1. Navigate to "Model Performance" tab
# 2. Select species: "Shigella flexneri"
# 3. Select drug: "ampicillin"
# 4. Select molecular scale: "genes"
# 5. View performance metrics and confusion matrix

Data requirements

The dashboard works with pre-computed data files located in inst/app/data/:

  • amr_filtered_tbls.db: DuckDB database with AMR data
  • all_performances.tsv: Model performance metrics
  • drug_class_map.tsv: Drug classification mapping
  • metadata/: Species-specific metadata files

To use your own data, structure files following the same schema.

Data Schema

Performance metrics

Required columns: - bug: Species code - antibiotic: Drug name - scale: Molecular scale (gene, protein, domain, struct) - type: Count or binary features - bal_acc: Balanced accuracy - f1: F1 score - nmcc: Normalized Matthews correlation coefficient - Additional columns for other metrics

Metadata files

Location: inst/app/data/metadata/{species}.parquet

Required columns: - genome_id: Unique genome identifier - genome.isolation_country: Country of isolation - genome.collection_year: Collection year - genome.host_name: Host organism - Additional metadata columns as needed

Development

Package structure 

amRshiny/
├── R/
│   └── launch_dashboard.R    # Main launch function
├── inst/
│   └── app/
│       ├── app.R             # Main Shiny app
│       ├── utils.R           # Utility functions
│       ├── modules/          # UI modules
│       ├── data/             # Dashboard data files
│       └── www/              # Static assets (CSS, images)
├── 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 AMR model results included in inst/app/data/

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