Vignette Rewrite

Author: eboyer221

README.Rmd

@@ -19,7 +19,7 @@ knitr::opts_chunk$set(
 [![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.
+**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):
 
@@ -29,27 +29,22 @@ This is the final package in the **AMR package suite**, [JRaviLab/amR](https://g
 
 ## Features
 
-- **Metadata exploration**: Geographic distribution, temporal trends, host analysis
+- **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 heatmaps
+- **Feature importance**: Identify key predictive features with interactive plots, annotation tables, and networks
 - **Cross-model analysis**: Compare models trained on different stratifications (country, year)
-- **Publication-quality exports**: Download plots and tables
-- **Modular design**: Extensible UI components
+- **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.
 
-```r
+```{r, eval = FALSE}
 # Install BiocManager if needed
 if (!requireNamespace("BiocManager", quietly = TRUE))
     install.packages("BiocManager")
 
-# Install Bioconductor dependencies
-BiocManager::install("ComplexHeatmap")
-
 # Install amRviz from GitHub
 if (!requireNamespace("devtools", quietly = TRUE))
     install.packages("devtools")
@@ -59,88 +54,107 @@ devtools::install_github("JRaviLab/amRviz")
 
 ## Quick start
 
-```r
+```{r, eval = FALSE}
 library(amRviz)
 
-# Launch the dashboard
-launch_dashboard()
+# 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.
+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:
+The dashboard is organized into tabs:
 
-1. **Home**: Overview and project information
-2. **Metadata**: Explore geographic, temporal, and host metadata
-   - Interactive maps and treemaps
-   - Temporal trends
-   - Host distribution
+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, 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
-```
+   - Filter by species, drug/drug class, molecular scale, and data encoding
+   - Per-model metric distributions, plus a Performance overview (nMCC strip plot and drug-class heatmaps)
+4. **Bug/Drug feature comparison**: Analyze predictive features
+   - Top features across species or across drugs
+   - Annotated feature tables (COG/ARG), 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/COG nodes
+7. **Query data**: Browse and export the raw performance-metric and top-feature tables as CSV
 
 ### Data requirements
 
-The dashboard works with pre-computed data files located in `inst/app/data/`:
+amRviz reads the parquet files produced by **amRml**. Files must be organized into per-species subdirectories:
 
-- `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
-- `mcc`: Matthews correlation coefficient
-- `nmcc`: Normalized Matthews correlation coefficient
-- Additional columns for other metrics
-
-### Metadata files
-Location: `inst/app/data/metadata/{species}.parquet`
+```
+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
+│   └── ...
+└── ...
+```
 
-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
+- 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`, `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) |
+| `nmcc`, `bal_acc`, `f1`, `sens`, `spec` | Performance metrics |
+
+### 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 (blank for baseline) |
+| `Variable` | Feature identifier (gene/protein/domain ID) |
+| `Importance` | Feature importance score |
+| `Sign` | Direction of effect |
+
+### 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
 
@@ -149,15 +163,21 @@ Required columns:
 ```
 amRviz/
 ├── R/
-│   └── launch_dashboard.R    # Main launch function
+│   ├── 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/
-│       ├── app.R             # Main Shiny app
-│       ├── utils.R           # Utility functions
-│       ├── modules/          # UI modules
-│       ├── data/             # Dashboard data files
-│       └── www/              # Static assets (CSS, images)
-├── man/                      # Documentation
+│   ├── app/www/                   # Static assets (CSS, images)
+│   └── extdata/
+│       └── Shigella_flexneri/     # Demo data (amRml output)
+├── man/                           # Documentation
+├── vignettes/                     # Usage vignette and figures
 └── DESCRIPTION
 ```
 
@@ -176,19 +196,18 @@ https://github.com/JRaviLab/amR
 
 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/`
+- **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
+### Reporting issues
 
-Report bugs and request features at: https://github.com/JRaviLab/amRviz/issues
+Report bugs and request features at: <https://github.com/JRaviLab/amRviz/issues>
 
 ## Related projects
 
@@ -206,6 +225,6 @@ BSD 3-Clause License. See [LICENSE](LICENSE) for details.
 
 ## Contact
 
-**Corresponding author**: Janani Ravi (janani.ravi@cuanschutz.edu)
+**Corresponding author**: Janani Ravi (<janani.ravi@cuanschutz.edu>)
 
-**JRaviLab**: https://jravilab.github.io
+**JRaviLab**: <https://jravilab.github.io>