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

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 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 (janani.ravi@cuanschutz.edu)

JRaviLab: https://jravilab.github.io