---
title: "Demonstration 1: scRNA-seq Simulation Evaluation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Demonstration 1: scRNA-seq Simulation Evaluation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r knitr-setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)
```

# Introduction

In single-cell RNA sequencing (scRNA-seq), evaluating the quality of simulated count data is important before testing analysis tools such as clustering, batch correction, or differential expression algorithms.

This tutorial shows how to evaluate synthetic scRNA-seq data step-by-step using **`scSimEval`** without needing any artificial ground truth.

---

# 1. Loading the Package and Example Dataset

`scSimEval` includes pre-packaged real and simulated scRNA-seq count matrices (`example_scrna`):

```{r setup}
library(scSimEval)

# Load packaged scRNA-seq example data
data(example_scrna)

# Examine dimensions and structure
cat("Reference scRNA-seq dimensions:", dim(example_scrna$ref), "\n")
cat("Simulated scRNA-seq dimensions:", dim(example_scrna$sim), "\n")
cat("Cell types represented:", levels(example_scrna$cell_types), "\n")
cat("Batches represented:", levels(example_scrna$batch_info), "\n")
```

The dataset consists of:
* `ref`: Feature-by-cell matrix of real experimental scRNA-seq read counts (60 genes $\times$ 80 cells).
* `sim`: Feature-by-cell matrix of simulated counts generated by a simulation method.
* `cell_types`: Factor of cell type labels.
* `batch_info`: Factor of technical batch identifiers.

---

# 2. Step-by-Step Category Evaluation

### 2.1 Distribution Properties & Summary Measures (Categories 1 and 2)

We evaluate how closely the simulated gene expression distributions match the real reference data using `evaluate_simulation_accuracy()`:

```{r dist-eval}
unimodal_res <- evaluate_simulation_accuracy(
  ref_data          = example_scrna$ref,
  sim_data          = example_scrna$sim,
  compute_bivariate = FALSE,
  verbose           = FALSE
)

# Inspect statistical distance metrics for library size
lib_summary <- subset(unimodal_res$metrics_summary_table, Property == "library_size")
head(lib_summary, 6)
```

### 2.2 Cell Clustering and Concordance (Category 3)

We evaluate whether the simulated data preserves distinct cell types in unsupervised and supervised clustering using `evaluate_clustering_metrics()`:

```{r clust-eval}
clust_res <- evaluate_clustering_metrics(
  data       = example_scrna$sim,
  cell_types = example_scrna$cell_types,
  ref_data   = example_scrna$ref
)

# Preview clustering concordance metrics
cat("Average Silhouette Width (Simulated):", round(clust_res$silhouette, 4), "\n")
cat("Davies-Bouldin Index:", round(clust_res$davies_bouldin, 4), "\n")
cat("Adjusted Rand Index (ARI):", round(clust_res$ARI, 4), "\n")
cat("Normalized Mutual Information (NMI):", round(clust_res$NMI, 4), "\n")
```

### 2.3 Batch Effects and Confounder Mixing (Category 4)

We test whether technical batch differences are properly mixed without masking biological differences using `evaluate_batch_metrics()`:

```{r batch-eval}
batch_res <- evaluate_batch_metrics(
  data       = example_scrna$sim,
  batch_info = example_scrna$batch_info,
  cell_types = example_scrna$cell_types,
  verbose    = FALSE
)

# Preview batch mixing metrics
cat("Batch Shannon Entropy:", round(batch_res$shannon_entropy, 4), "\n")
cat("Principal Component Regression (PCR R2):", round(batch_res$pcr_r2, 4), "\n")
cat("Cross-Batch Transfer Accuracy:", round(batch_res$cross_batch_accuracy, 4), "\n")
```

### 2.4 Differential Expression (DEG) Fidelity (Category 5)

We assess marker gene effect sizes and top marker overlap using `evaluate_deg_fidelity()`:

```{r deg-eval}
deg_res <- evaluate_deg_fidelity(
  ref_data      = example_scrna$ref,
  sim_data      = example_scrna$sim,
  ref_celltypes = example_scrna$cell_types,
  sim_celltypes = example_scrna$cell_types
)

# Display DEG summary metrics
head(deg_res$deg_summary_table)
```

### 2.5 Trajectory and Lineage Dynamics (Category 6)

We infer developmental pseudotime and lineage branching directly from scRNA-seq expression counts using `evaluate_trajectory_metrics()`:

```{r traj-eval}
traj_res <- evaluate_trajectory_metrics(
  ref_data       = example_scrna$ref,
  sim_data       = example_scrna$sim,
  cell_types_ref = example_scrna$cell_types,
  cell_types_sim = example_scrna$cell_types
)

cat("Pseudotime Spearman Correlation:", round(traj_res$pseudotime_correlation, 4), "\n")
cat("Lineage Tree Branch Height RMSE:", round(as.numeric(traj_res$tree_height_rmse), 4), "\n")
```

---

# 3. Master Unimodal Pipeline: `evaluate_simulation_accuracy`

Instead of running individual steps, execute the entire unimodal evaluation suite in a single coordinated command:

```{r master-eval}
eval_res <- evaluate_simulation_accuracy(
  ref_data          = example_scrna$ref,
  sim_data          = example_scrna$sim,
  elapsed_time      = 12.5,
  memory_mb         = 340.2,
  compute_bivariate = FALSE,
  verbose           = FALSE
)

# Preview tidy evaluation summary
head(eval_res$metrics_summary_table)
```

---

# 4. Diagnostic Visualizations

`scSimEval` includes built-in functions for high-resolution diagnostic plotting:

```r
# 14-Panel Comparative Distribution QC Plot
plot_distribution_qc(
  ref_data = example_scrna$ref,
  sim_data = example_scrna$sim,
  title    = "scRNA-seq Simulation Quality Control"
)
```

---

# 5. Conclusion

This demonstration illustrates how `scSimEval` comprehensively assesses scRNA-seq simulations across distributions, zero patterns, clustering, batch integration, marker genes, and trajectory dynamics without requiring artificial ground-truth labels.

```{r session-info}
sessionInfo()
```