---
title: "Quick Start Guide"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{Quick Start Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

**scGate** is a powerful R package for marker-based purification of cell types from heterogeneous single-cell RNA-seq datasets. Unlike reference-based methods, scGate does not require training data or reference gene expression profiles.

### Key Features

- **Marker-based gating**: Define cell populations using positive and negative markers
- **Hierarchical models**: Build complex gating strategies similar to flow cytometry
- **Multi-class classification**: Annotate multiple cell types simultaneously
- **Cross-platform**: Works on Windows, macOS, and Linux
- **Integration-friendly**: Compatible with Seurat v4/v5 and batch-corrected data

## Installation

```{r install, eval=FALSE}
# From CRAN (stable version)
install.packages("scGate")

# From GitHub (development version)
# remotes::install_github("Zaoqu-Liu/scGate")
```

## Quick Example

### Load Required Packages

```{r load-packages}
library(scGate)
library(Seurat)
library(ggplot2)
```

### Load Example Data

scGate provides a small example dataset for testing:

```{r load-data}
# Load the built-in example dataset
data(query.seurat)

# Check the data
query.seurat
```

### Create a Simple Gating Model

The simplest way to use scGate is with a single marker:

```{r simple-model}
# Create a model for B cells using MS4A1 (CD20) as marker
bcell_model <- gating_model(name = "Bcell", signature = c("MS4A1"))

# View the model structure
bcell_model
```

### Apply scGate

```{r apply-scgate, eval=FALSE}
# Apply the gating model
# Using pre-computed PCA for speed
query.seurat <- scGate(
  data = query.seurat, 
  model = bcell_model,
  reduction = "pca"  # Use existing PCA
)

# Check results
table(query.seurat$is.pure)
```

### Visualize Results

```{r visualize-basic, eval=FALSE, fig.width=10, fig.height=4}
# Create visualization
p1 <- DimPlot(query.seurat, group.by = "cell_type", label = TRUE, repel = TRUE) +
  ggtitle("Original Annotation") +
  NoLegend()

p2 <- DimPlot(query.seurat, group.by = "is.pure", 
              cols = c("Pure" = "#00ae60", "Impure" = "gray80")) +
  ggtitle("scGate Result")

p1 + p2
```

## Building More Complex Models

### Positive and Negative Markers

For more accurate gating, combine positive and negative markers:

```{r complex-model}
# T cell model with positive (CD3) and negative (CD19) markers
tcell_model <- gating_model(name = "Tcell", signature = c("CD3D", "CD3E"))
tcell_model <- gating_model(
  model = tcell_model, 
  name = "notBcell", 
  signature = c("CD19", "MS4A1"),
  positive = FALSE  # These are negative markers
)

tcell_model
```

### Using Pre-defined Models

scGate provides a database of curated gating models:
```{r get-models, eval=FALSE}
# Download the model database
models_db <- get_scGateDB()

# Available models for human
names(models_db$human$generic)

# Use a pre-defined T cell model
tcell_model <- models_db$human$generic$Tcell
```

## Multi-class Classification

scGate can annotate multiple cell types simultaneously:

```{r multiclass, eval=FALSE}
# Define multiple models
model_list <- list(
  "Bcell" = gating_model(name = "Bcell", signature = c("MS4A1", "CD19")),
  "Tcell" = gating_model(name = "Tcell", signature = c("CD3D", "CD3E"))
)

# Apply all models at once
seurat_obj <- scGate(seurat_obj, model = model_list)

# Results are stored in scGate_multi column
table(seurat_obj$scGate_multi)
```

## Key Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `pos.thr` | Threshold for positive signatures | 0.2 |
| `neg.thr` | Threshold for negative signatures | 0.2 |
| `reduction` | Dimensionality reduction to use | "calculate" |
| `k.param` | Number of neighbors for smoothing | 30 |
| `ncores` | Number of cores for parallel processing | 1 |

## Session Info

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