---
title: "Basic Usage"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Basic Usage}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

This vignette demonstrates the basic usage of **recall** for calibrated clustering 
in single-cell RNA-sequencing analysis. The package is compatible with both 
Seurat V4 and V5, and works on all major platforms (Linux, macOS, Windows).

## Setup

```{r setup}
library(Seurat)
library(recall)
```

## Loading Data

You can load your own single-cell data or use publicly available datasets:
```{r load_data}
# Option 1: Load from a 10X Genomics directory
# seurat_obj <- Read10X(data.dir = "path/to/filtered_feature_bc_matrix/")
# seurat_obj <- CreateSeuratObject(counts = seurat_obj)

# Option 2: Load from an RDS file
# seurat_obj <- readRDS("your_seurat_object.rds")

# For this example, we assume you have a Seurat object named 'seurat_obj'
```

## Standard Preprocessing

Before running **recall**, perform standard Seurat preprocessing:

```{r preprocessing}
seurat_obj <- NormalizeData(seurat_obj)
seurat_obj <- FindVariableFeatures(seurat_obj, nfeatures = 2000)
seurat_obj <- ScaleData(seurat_obj)
seurat_obj <- RunPCA(seurat_obj)
seurat_obj <- FindNeighbors(seurat_obj, dims = 1:10)
seurat_obj <- RunUMAP(seurat_obj, dims = 1:10)
```

## Running recall

The **recall** algorithm can be run with a single function call as a drop-in
replacement for the Seurat function `FindClusters`:

```{r run_recall}
seurat_obj <- FindClustersRecall(seurat_obj, resolution_start = 0.8)
```

## Accessing Results

The **recall** clusters are set as the default identities of the returned Seurat object:

```{r check_clusters}
# View cluster distribution
table(Idents(seurat_obj))

# Cluster labels are also stored in metadata
head(seurat_obj@meta.data$recall_clusters)
```

## Visualization

```{r plot_umap}
# UMAP visualization with cluster labels
DimPlot(seurat_obj, label = TRUE)

# Or explicitly specify the recall clusters
DimPlot(seurat_obj, group.by = "recall_clusters", label = TRUE)
```

## Comparison with Standard Clustering

Compare **recall** results with standard Seurat clustering:

```{r comparison}
# Standard Seurat clustering
seurat_standard <- FindClusters(seurat_obj, resolution = 0.8)

# Compare number of clusters
cat("Standard clustering:", length(unique(Idents(seurat_standard))), "clusters\n")
cat("recall clustering:", length(unique(seurat_obj$recall_clusters)), "clusters\n")
```

## Next Steps

For more advanced usage, see:

- [Algorithm & Methodology](methodology.html): Understanding the knockoff filter approach
- [Visualization Guide](visualization.html): Creating publication-quality figures
- [Advanced Usage](advanced-usage.html): Parameter tuning and alternative methods

## Session Info

```{r session_info}
sessionInfo()
```