README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# amRshiny

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

**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](https://github.com/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.

```r
# 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

```r
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

```r
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](CONTRIBUTING.md) for details.

### Reporting Issues

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

## Related projects

- [amRdata](https://github.com/JRaviLab/amRdata): Data preparation for AMR prediction
- [amRml](https://github.com/JRaviLab/amRml): ML modeling framework
- [BV-BRC](https://www.bv-brc.org/): Bacterial and Viral Bioinformatics Resource Center

## Code of conduct

Please note that the amRshiny project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.

## License

BSD 3-Clause License. See [LICENSE](LICENSE) for details.

## Contact

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

**JRaviLab**: https://jravilab.github.io