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%"
)
```

# amRviz

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

**amRviz** is an interactive Shiny dashboard for exploring antimicrobial resistance (AMR) data and machine learning model results generated by [amRml](https://github.com/JRaviLab/amRml).

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
- **amRviz**: Interactive visualization (this package)

## Features

- **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 flexneri* 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()`

## Installation

The package is currently available via GitHub and will be submitted to Bioconductor.

```{r, eval = FALSE}
# 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")
```

## Quick start

```{r, eval = FALSE}
library(amRviz)

# 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.

## Export figures without the dashboard

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.

```{r, eval = FALSE}
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/amRml/results",
  species      = "Shigella_flexneri"
)
```

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

```{r, eval = FALSE}
exportAMRVisualizations(top_n_features = 25, network_top_n = 10, scale = 3)
```

- **Formats**: all four (`png`, `jpg`, `pdf`, `svg`) are supported. `png` is a headless-Chrome screenshot; `jpg` and `pdf` are re-encodes of that PNG, so every raster format shares the same crop and dimensions. `svg` is 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 `webshot2` and `chromote` packages, then reformats with `magick`. 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.

## Usage

### Dashboard navigation

The dashboard is organized into tabs:

1. **Home**: Overview, suite workflow, and project information
2. **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
3. **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 (MCC strip plot and drug-class heatmaps)
4. **Bug/Drug feature comparison**: Analyze predictive features
   - Top features (genes, proteins, domains, cogs, args) across species or across drugs
   - Annotated feature tables (clusters), category barplots, and ego networks
5. **Model holdouts**: Compare models across stratifications
   - Country-holdout and year-interval models
   - Accuracy distributions, performance heatmaps, and feature consistency
6. **Network**: Interactive force-directed drug → feature graph, with optional cluster nodes
7. **Query data**: Browse and export the raw performance-metric and top-feature tables as CSV

### Data requirements

amRviz reads the parquet files produced by **amRml**. Files must be organized into per-species subdirectories:

```
results/
├── Shigella_flexneri/
│   ├── all_perf.parquet
│   ├── country_perf.parquet
│   ├── year_perf.parquet
│   ├── cross_perf.parquet
│   ├── all_top_features.parquet
│   ├── country_top_features.parquet
│   ├── year_top_features.parquet
│   └── metadata.parquet
├── Klebsiella_pneumoniae/
│   ├── all_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 (`*_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`, `struct` |
| `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 |

### Top features (`*_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 (blank for baseline) |
| `Variable` | Feature identifier (gene/protein/domain ID) |
| `Importance` | Feature importance score |
| `Sign` | Direction of effect |

### Metadata (`*_metadata.parquet`)

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

## Development

### Package structure

```
amRviz/
├── R/
│   ├── app.R                      # Main Shiny app (ui + server)
│   ├── utils.R                    # File loading and plot functions
│   ├── globals.R                  # Global variable declarations
│   ├── metadataUI.R               # Metadata tab UI
│   ├── modelPerfUI.R              # Model performance tab UI
│   ├── featureImportanceUI.R      # Bug/Drug feature comparison tab UI
│   ├── crossModelComparisonUI.R   # Model holdouts tab UI
│   ├── networkUI.R                # Network tab UI
│   └── queryDataUI.R              # Query data tab UI
├── inst/
│   ├── app/www/                   # Static assets (CSS, images)
│   └── extdata/
│       └── Shigella_flexneri/     # Demo data (amRml output)
├── man/                           # Documentation
├── vignettes/                     # Usage vignette and figures
└── DESCRIPTION
```

## Citation

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](https://doi.org/10.64898/2026.07.10.734579).

^ Co-first authors

## For Bioconductor submission

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 flexneri* included in `inst/extdata/`

## 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/amRviz/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 amRviz 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>