---
title: "Interactive Shiny Studio — Complete User Guide"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
    number_sections: false
vignette: >
  %\VignetteIndexEntry{Interactive Shiny Studio — Complete User Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r knitr-setup, include = FALSE}
knitr::opts_chunk$set(
  collapse   = TRUE,
  comment    = "#>"
)
```

## Overview

The **scSimEval Shiny Studio** is a fully self-contained, browser-based graphical interface that
gives researchers access to all 62 evaluation measures and every visualization in the package —
without writing a single line of R code.

Launch it locally in R with:

```r
library(scSimEval)
launch_scSimEval_app()          # opens in your default browser
```

> **File size limit:** The app accepts uploads up to **10 GB** per file, which comfortably handles
> large-scale single-cell and multiomics datasets.

The studio is organized into **seven primary navigation tabs** in the top navigation bar, plus an
**eight-panel Visualizations module** inside Tab 4. The sections below document every tab,
every control, and all export options in the order they appear in the application.

---

## Tab 1 — Home

The landing page introduces **scSimEval Studio**, explicitly highlighting simulation evaluation across single-cell RNA-seq (scRNA-seq), single-cell ATAC-seq (scATAC-seq), and single-cell multiomics (scRNA-seq + scATAC-seq) datasets against real biological references across 62 evaluation measures without requiring synthetic ground truth.

In the standalone web deployment (`scSimEval_shiny`), a floating Google Analytics all-time pageview counter badge appears at the bottom-right corner, continuously reporting container-lifetime visits without UI latency.

The four **KPI cards** below the hero section display: 62 evaluation measures, 8 biological dimensions, 3 modalities (RNA / ATAC / Co-Assay), and the [0, 1] normalized fidelity scale.

Interactive operational mode cards showcase:
1. **Pre-computed Benchmarks:** 1-click loading of benchmark evaluations across multiple simulators and datasets.
2. **Single-Cell RNA-seq Evaluation:** Count matrix evaluation across statistical, clustering, and technical properties.
3. **Multi-Omics (RNA + ATAC) Evaluation:** Co-assay multiomics benchmarking assessing cross-modal coupling alongside unimodal properties.
4. **Upload Pre-Computed Benchmark Table:** Instant ingestion of previously calculated benchmark tables for reporting.

---

## Tab 2 — Data Hub

Data ingestion and evaluation control centre. It features three comprehensive subtabs:

### Subtab 1: Data Ingestion & Benchmark Studio
Choose one of **four evaluation modes** from the radio button panel on the left sidebar:

#### Mode 1 — Pre-Computed Benchmark (Demo Data)
Click **Load Demo Benchmark** to instantly populate the app with pre-computed multi-dataset results across **Simulator 1 to Simulator 6** across all 62 measures. No file uploads required.

> **Package Example Datasets vs. Shiny App Demo Data:**
> * **R Package Example Datasets (`data/`):** Lightweight, runnable count matrices (`example_scrna`, `example_scatac`, `example_multiomics`, 60 features × 80 cells) designed for rapid command-line testing of individual evaluation functions in R console sessions.
> * **Shiny App Demo Data (`inst/shiny/scSimEvalApp/data/`):** A rich pre-computed benchmark results archive (6 simulators × 62 metrics × 2 datasets = 744 metric observations) accompanied by reference and simulated count matrices (100 genes × 50 cells). This gives web users an immediate, zero-latency tour of all tabs, ranking leaderboards, bubble matrices, and 8 visualization panels without requiring computationally intensive matrix evaluations.

#### Mode 2 — Single-Cell Evaluation (scRNA-seq / scATAC-seq)
Evaluate one or more unimodal count-matrix simulators across single or multiple experimental datasets.
* **Reference Count Matrix:** Real empirical cells. Formats: `.rds`, `.csv`, `.tsv`, `.txt`, `.xlsx`.
* **Number of Single-Cell Simulators (1–6):** Generates matching upload cards with simulator name, simulated count matrix, runtime (seconds), and peak RAM (MiB).
* **Cell Type Labels (Optional):** Vector / factor / 2-column table (`Cell_ID,Cell_Type`). Unlocks +12–15 clustering and biological signal metrics.
* **Batch Annotations (Optional):** Vector / factor / 2-column table (`Cell_ID,Batch`). Unlocks +7 batch mixing metrics.

#### Mode 3 — Multiomics Evaluation (scRNA-seq + scATAC-seq)
* **Paired Co-assay:** Same individual cells in both modalities (10x Multiome, SHARE-seq). All 62 metrics including FOSCTTM, Match@1, and peak-to-gene linkage.
* **Unpaired Profiling:** Separate cells from the same tissue. Population-level cross-modal metrics evaluated; cell-pairing metrics safely skipped.

#### Metric Measurement Capacity by Upload Configuration

The Shiny app dynamically scales the number of quantitative metrics measured based on the uploaded files:

| Experiment Mode | Uploaded Inputs | Metrics Measured | Active Evaluation Categories & Scope |
| :--- | :--- | :---: | :--- |
| **Single-Cell** *(scRNA / scATAC)* | Count Matrix alone *(no metadata)* | **~23 Metrics** | **Cat I** (Distributional, 14 metrics), **Cat II** (Correlations & Zeroes, 6 metrics), **Cat VI** (Trajectory, 2 metrics), **Cat VIII** (Scalability, 2 metrics). |
| **Single-Cell** *(scRNA / scATAC)* | Matrix + Cell Types | **~35–38 Metrics** | *Adds +12–15 metrics:* Unlocks **Cat III** (Cellular Structure / ARI, NMI, AMI, Silhouette) and **Cat V** (Biological Signal / SimBench DE, DP, DV, top DEG Jaccard). |
| **Single-Cell** *(scRNA / scATAC)* | Matrix + Batch Info | **~30 Metrics** | *Adds +7 metrics:* Unlocks **Cat IV** (Batch Mixing / Batch Silhouette, Shannon Entropy, PCR $R^2$, CMS, ISI, Seurat mixing). |
| **Single-Cell** *(scRNA / scATAC)* | **Full Metadata** *(Matrix + Cell Types + Batch)* | **Up to ~55 Metrics** | Unlocks the complete unimodal suite across **Categories I, II, III, IV, V, VI, and VIII**. |
| **Paired Multiomics** *(scRNA + scATAC)* | RNA + ATAC Matrices alone | **~48 Metrics** | Unimodal distributions for both modalities (~40 metrics) PLUS **Cat VII** (Cross-Modal Coupling: FOSCTTM, Match@1, generation, $R_V$, peak-to-gene linkage). |
| **Paired Multiomics** *(scRNA + scATAC)* | **Full Metadata** *(RNA + ATAC + Cell Types + Batch)* | **All 62 Metrics** | Complete multiomics benchmark suite across all 8 canonical categories (**Categories I–VIII**). |
| **Unpaired Multiomics** *(Independent cells)* | RNA + ATAC Matrices alone | **~38–42 Metrics** | Both unimodal distributions plus population coupling (co-expression module fidelity, Network Jaccard, cross-modality correlation). |
| **Unpaired Multiomics** *(Independent cells)* | **RNA + ATAC + Cell Types (+ Batch)** | **Up to ~58 Metrics** | *Essential for unpaired:* Unlocks cluster-matched label transfer, cell-type regulatory linkage, and technical donor integration. |

#### Mode 4 — Upload Pre-Computed Benchmark Table (.rds / .csv)
Load output previously saved from `evaluate_simulation_accuracy()`, `evaluate_multiomics_accuracy()`, or `evaluate_multiple_datasets()`.

### Subtab 2: View Uploaded Data & Matrices
Interactive matrix viewer supporting browsing, filtering, and summary statistics across all loaded biological reference and simulated count matrices.

### Subtab 3: Dataset Properties Summary & HPC Cluster Execution
* **Dataset Properties Summary Table:** Comprehensive per-matrix QC: Cells (N), Features (P), Sparsity (%), Cell Types, Batches, Median Library Size, Median Detected Features, Mean Expression.
* **HPC Cluster Batch Script Generator:** Export automated SLURM, PBS, or Bash cluster execution scripts to run heavy benchmarks offline on compute nodes.

---

## Tab 3 — Comparative Bubble Matrix & Leaderboard

### Subtab 1: Comparative Bubble Matrix Figure
The flagship visualization: every simulator × all 62 metrics in one colour-coded matrix. Bubble **diameter** is proportional to the normalized fidelity score. Scores ≥ 0.96 are rendered as bold square glyphs. Simulators are rank-ordered top-to-bottom by composite average score.
* **Multi-Dataset Selector Bar:** Switch seamlessly between **All Datasets (Cross-Dataset Average)** or inspect individual datasets (**Dataset 1**, **Dataset 2**, ..., **Dataset N**) separately.
* **Minimalist vs Publication Matrix:** Toggle between a sleek, dot-matrix view and a fully annotated publication matrix.
* **Confirmation & Plot Action Button:** Click **Confirm & Generate Plot** to render with app-wide loading indicators.
* **High-Resolution Exports & R Script:** Download 600 DPI JPEG, vector PDF, or a **Download R Script** providing the complete analytical workflow with ggplot2 code.

### Subtab 2: Fidelity Leaderboard
* **Simulator Ranking Cards & Podiums:** Visual podium ranking simulators by overall composite fidelity.
* **Custom Category Weight Sliders:** Interactively adjust the relative importance of each category to recalculate composite rankings according to specific biological priorities.
* **Export Leaderboard:** Download the tidy rankings table as CSV.

---

## Tab 4 — Visualizations

Eight diagnostic sub-panels accessed via the **pill navigation bar**. Every sub-panel is equipped with the **Global Multi-Dataset Selector Bar** (allowing inspection of All Datasets Average or specific datasets), active dataset badges, **Confirm & Generate Plot** buttons, app-wide processing overlays, 600 DPI JPEG / PDF downloads, and a **Download R Script** workflow generator:

* **Sub-panel 1 — Evaluation Summary:** `plot_evaluation_summary()` — rank-ordered horizontal bar chart across all 8 categories and composite score.
* **Sub-panel 2 — Distribution QC:** `plot_distribution_qc()` — grid comparing expression densities, ECDF curves, KS distances, library sizes, and zero-inflation curves between reference and simulated cells.
* **Sub-panel 3 — Scalability Benchmark:** `plot_scalability_benchmark()` — runtime (seconds) and memory (peak RAM in **MiB**) dashboards with Pareto efficiency frontiers, throughput (cells/sec), and resource cost index.
* **Sub-panel 4 — Metric Plots:** `plot_metric_boxplots()` / `plot_category_metric_bars()` / `plot_individual_metric_bar()` — score distribution boxplots and barplots across categories with Raw vs Normalized view toggles.
* **Sub-panel 5 — Metric Heatmap:** `plot_metric_heatmap()` — method × metric grid with exact scores in bold text, direction-aware fill colours, and unsupervised hierarchical clustering.
* **Sub-panel 6 — PCA Ordination:** `plot_metric_pca()` — simulators projected into performance space with discriminating metric vector loadings.
* **Sub-panel 7 — MDS Metric Space:** `plot_metric_mds()` — Multi-Dimensional Scaling ordination mapping simulator algorithmic proximity.
* **Sub-panel 8 — Cell Embeddings (UMAP, t-SNE & PCA):** `compute_dataset_embeddings()` + `plot_dataset_embeddings()` — dimension reduction comparing reference cells directly to simulated cells, with cell-type cluster fidelity metrics.

---

## Tab 5 — Benchmark Results & Export

The central hub for data exploration and multi-format exports:

### Interactive Master Benchmark Scores Table
A full `DT` table with **per-column dropdown search boxes** for instant filtering by Dataset, Method, and Category.
Explicitly displays:
* **Score_Raw:** Raw unnormalized metric values in physical and statistical units (e.g. KS distance, Wasserstein distance, runtime in seconds, peak RAM in **MiB**, Chi-Square values, Pearson correlation).
* **Score:** Direction-aware normalized score $[0, 1]$ where 1.0 represents top fidelity.

### Multi-Format Exports
Export benchmark results in **Excel Workbook (.xlsx)**, **CSV Table (.csv)**, **Tab-delimited (.tsv)**, **R Data Object (.rds)**, or **Complete Archive (.zip)**.

---

## Tab 6 — Help & Getting Started

An in-app reference guide structured into seven sections:
1. **Workflow Architecture & Pipeline** — 4-step pipeline diagram and multi-dataset processing.
2. **The Eight Evaluation Categories** — tabular reference for all 62 metrics, highlighting peak RAM in **MiB**.
3. **Metric Measurement Capacity by Data & Metadata Mode** — detailed reference table documenting metric numbers and unlocked categories.
4. **Score Normalization Pipeline** — direction inversion, min-max scaling, and raw vs normalized score reporting.
5. **Comprehensive Guide to App Tabs** — detailed walkthrough of each application module.
6. **Input Data Formats & Metadata Templates** — matrix structures (genes × cells), cell-type and batch annotation vectors, and sample CSV downloads.
7. **Computational Sizing, RAM (MiB/GiB), & Guidelines** — hardware recommendations contrasting Cloud, Local Workstation, and HPC clusters.

---

## Tab 7 — Contact

Information regarding the development team at Division of Agricultural Bioinformatics, ICAR-IASRI, maintainer contacts, GitHub issues link, and recommended citations.

---

## R API Cross-Reference

Every Shiny control maps directly to a documented R function:

| Shiny Panel | R Function |
|-------------|-----------|
| Data Hub → Single-Cell | `evaluate_simulation_accuracy()` |
| Data Hub → Multiomics | `evaluate_multiomics_accuracy()` |
| Data Hub → Multiple Datasets | `evaluate_multiple_datasets()` |
| Bubble Matrix | `plot_benchmark_bubble_matrix()` |
| Evaluation Summary | `plot_evaluation_summary()` |
| Distribution QC | `plot_distribution_qc()` |
| Scalability Benchmark | `plot_scalability_benchmark()` |
| Metric Plots (all categories) | `plot_metric_boxplots()` |
| Metric Plots (by category) | `plot_category_metric_bars()` |
| Metric Plots (individual) | `plot_individual_metric_bar()` |
| Metric Heatmap | `plot_metric_heatmap()` |
| PCA Ordination | `plot_metric_pca()` |
| MDS Metric Space | `plot_metric_mds()` |
| Cell Embeddings | `compute_dataset_embeddings()` + `plot_dataset_embeddings()` |
| Embedding Quality Metrics | `compute_embedding_quality_metrics()` |

For complete parameter descriptions see the [Reference](../reference/index.html) index.

---

```{r session-info, eval=TRUE, echo=FALSE}
sessionInfo()
```