---
title: "Getting started with geneticUMAP"
author: "Hanna Wagner, Lisa-Maria Winter, and Dominik Dreiheller"
package: geneticumap
output: rmarkdown::html_document
vignette: >
  %\VignetteIndexEntry{Getting Started with geneticUMAP}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## What geneticUMAP Does

Single-cell RNA sequencing (scRNA-seq) enables the characterization of cellular
heterogeneity at single-cell resolution,but its interpretation relies on
computational workflows for dimensionality reduction and visualization.
These workflows require multiple parameter choices in preprocessing, clustering,
and visualization steps. Although general recommendations exist, suitable
parameter selection remains dataset-specific, leaving manual configuration
susceptible to subjectivity and poor reproducibility when incompletely reported.
We address this gap with geneticUMAP, an objective, dataset-specific
optimization framework for configuring scRNA-seq visualization.
`geneticUMAP` embeds the complete workflow in a genetic algorithm and optimizes
its configuration using the Calinski-Harabasz index to evaluate how well the
intrinsic data structure is preserved in the final visualization.
We applied geneticUMAP to 18 publicly available scRNA-seq datasets that span
different species, tissues, and acquisition protocols.
Across all datasets, optimization improved structure-preserving mappings.
Additionally, we assess the robustness under parameter perturbations and the
biological relevance of the resulting visualizations.
Optimized configurations generally produced more robust visualizations than
default settings and improved agreement with author-provided cell-type
annotations for most datasets.
By automatically identifying a suitable configuration, geneticUMAP eliminates
the need for manual parameter tuning and enables more objective and robust
scRNA-seq data visualizations.

Alongside this R package, geneticUMAP is available as
[web application](https://fermat.informatik.uni-ulm.de/geneticumap).

## Installation

Make sure R is installed on your system. Install the package from Bioconductor:

```{r install, eval=FALSE}
if (!require("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}

BiocManager::install("geneticumap")
```

## Input Data

Provide `run_optimization()` with a directory containing either a 10X Genomics
matrix (`matrix.mtx`, `barcodes.tsv`, and `features.tsv` or `genes.tsv`) or a
10X HDF5 file (`.h5`). If the directory contains an HDF5 file, the package
loads that file. The package applies fixed quality-control filters to every
dataset: cells must have more than 200 and fewer than 2,500 detected features,
and mitochondrial content must be below 5% using the `^MT-` gene-name pattern.

## Run an Optimization

The package includes a small HDF5 dataset* for this reproducible example. The
optimization settings below match the lightweight configuration used by the
package tests.

```{r import-package-and-data, message=FALSE, warning=FALSE, results='hide'}
library(geneticumap)

data_dir <- file.path("..", "tests", "testdata")
results_dir <- file.path(tempdir(), "geneticumap-vignette-results")
```

```{r run-optimization, message=FALSE, warning=FALSE, results='hide'}
optimization_result <- run_optimization(
    data_dir = data_dir,
    results_dir = results_dir,
    mu = 2,
    lambda = 4,
    max_iterations = 2,
    num_processes = 1
)
```

The function writes its results to `results_dir` and returns the optimized
parameters as a named vector. The same parameters are saved in a JSON file
within `results_dir`.

```{r read-parameters}
optimization_result
```

## Result Files

```{r result-files, echo=FALSE}
library(knitr)

df <- data.frame(
    File = c(
        "seurat-params.json",
        "umap-coordinates.tsv",
        "cluster-identities.tsv",
        "scatter-fitness.png",
        "umap-static.png",
        "umap-static-default-seurat.png",
        "umap-interactive.html"
    ),
    What.it.contains = c(
        "Selected values for the six pipeline parameters",
        paste("One row per cell, with its barcode and two UMAP coordinates ",
            "(`umap_1`, `umap_2`)"),
        paste("The Seurat cluster assignment for each cell barcode. These are ",
            "the clusters used to calculate the CH index"),
        "CH fitness across generations",
        "Static UMAP plot for the selected parameter set",
        paste("Static UMAP plot using the package's default parameter set, ",
            "for comparison"),
        paste("Interactive UMAP for the selected settings, with cluster ",
            "labels and hover information for top marker genes")
    ),
    stringsAsFactors = FALSE
)

kable(df, col.names = c("File", "What it contains"))
```

The coordinate and cluster tables can be joined by `cell_id`. Comparing the
two static plots gives a quick visual comparison between the default and
selected settings; open the interactive HTML file for cell-level exploration.

## References

*We retrieved this test dataset from the
[Seurat pipeline](https://satijalab.org/seurat/articles/pbmc3k_tutorial) and
converted to h5. The original source of the dataset is:
[10x Genomics. 3k PBMCs from a Healthy Donor, Single Cell Gene Expression
Dataset by Cell Ranger v1.1.0. 2016](
https://www.10xgenomics.com/welcome?closeUrl=%2Fdatasets&lastTouchOfferName=
3k%20PBMCs%20from%20a%20Healthy%20Donor&lastTouchOfferType=Dataset&product=atera
&redirectUrl=%2Fdatasets%2F3-k-pbm-cs-from-a-healthy-donor-1-standard-1-1-0).


## Session Information

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