### Installation

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Instructions for installing the SeuratIntegrate package from GitHub.

```APIDOC
## Installation

Install SeuratIntegrate from GitHub.

```r
if (!require("BiocManager", quietly = TRUE))
  install.packages("BiocManager")
if (!require("remotes", quietly = TRUE))
  install.packages("remotes")
remotes::install_github("cbib/Seurat-Integrate", dependencies = NA, repos = BiocManager::repositories())
```
```

--------------------------------

### Install SeuratIntegrate

Source: https://github.com/cbib/seurat-integrate/blob/main/pkgdown/index.md

Installs the SeuratIntegrate package from GitHub. Ensure 'remotes' and 'BiocManager' are installed first.

```R
install.packages(c("remotes", "BiocManager")) # if not installed

remotes::install_github("cbib/Seurat-Integrate", repos = BiocManager::repositories())
```

--------------------------------

### Install kBET Package

Source: https://github.com/cbib/seurat-integrate/blob/main/README.md

Installs the kBET package from GitHub, required for testing k-nearest neighbour batch effects.

```R
remotes::install_github('theislab/kBET')
```

--------------------------------

### Install lisi Package

Source: https://github.com/cbib/seurat-integrate/blob/main/README.md

Installs the 'lisi' package from GitHub for faster Local Inverse Simpson’s Index computation.

```R
remotes::install_github('immunogenomics/lisi')
```

--------------------------------

### Install distances Package

Source: https://github.com/cbib/seurat-integrate/blob/main/README.md

Installs the 'distances' package from CRAN for fast distance computation.

```R
install.packages('distances')
```

--------------------------------

### Install Supporting R Packages

Source: https://github.com/cbib/seurat-integrate/blob/main/pkgdown/index.md

Installs additional R packages required for specific SeuratIntegrate functionalities, such as distance computation, k-nearest neighbor batch effect testing, and LISI computation.

```R
# fast distance computation
install.packages('distances')

# required to test for k-nearest neighbour batch effects
remotes::install_github('theislab/kBET')

# faster Local Inverse Simpson’s Index computation
remotes::install_github('immunogenomics/lisi')
```

--------------------------------

### Setup Python Environments for SeuratIntegrate

Source: https://github.com/cbib/seurat-integrate/blob/main/README.md

Set up necessary conda environments for Python-based integration methods like bbknn, scvi, scanorama, and trVAE. These environments are cached for future use.

```R
library(SeuratIntegrate)

# Create envrionments
UpdateEnvCache("bbknn")
UpdateEnvCache("scvi")     # also scANVI
UpdateEnvCache("scanorama")
UpdateEnvCache("trvae")

# Show cached environments
getCache()
```

--------------------------------

### Run scANVI Integration with IntegrateLayers

Source: https://context7.com/cbib/seurat-integrate/llms.txt

This wrapper runs scANVI semi-supervised integration, using cell type labels to guide batch correction. It outputs a latent space dimensional reduction. Ensure the 'scvi' conda environment is set up first. The integration requires metadata for batch grouping and cell type labels.

```r
library(SeuratIntegrate)
library(Seurat)

# Ensure conda environment is set up first
# UpdateEnvCache("scvi")

# Preprocessing
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run scANVI with cell type guidance
seu <- IntegrateLayers(
  object = seu,
  method = scANVIIntegration,
  features = Features(seu),
  layers = "counts",
  groups = seu[[]],
  groups.name = "First_author",      # Batch variable
  labels.name = "manual_cell_type_short",  # Cell type labels
  labels.null = "Unknown",           # Label for unlabeled cells
  ndims.out = 10,
  max_epochs = 100L,
  verbose = TRUE
)

# Post-processing
seu <- RunUMAP(seu, reduction = "integrated.scANVI", dims = 1:10,
               reduction.name = "umap.scANVI")
```

--------------------------------

### Get raw ASW scores

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Retrieves raw cell-type or batch-adjusted silhouette width (ASW) scores from a Seurat object for further analysis.

```r
asw <- ScoreASW(seu, cell.var = "manual_cell_type_short", what = "pca")
asw_batch <- ScoreASWBatch(seu, batch.var = "First_author",
                            cell.var = "manual_cell_type_short", what = "pca")
```

--------------------------------

### Complete Integration and Benchmarking Workflow

Source: https://context7.com/cbib/seurat-integrate/llms.txt

A comprehensive workflow demonstrating the end-to-end process of data integration, post-processing, scoring, and comparison of multiple integration methods using SeuratIntegrate.

```APIDOC
## Complete Integration and Benchmarking Workflow

### Description
Full workflow demonstrating integration, post-processing, scoring, and comparison of multiple methods.

### Method
This section outlines a sequence of Seurat and SeuratIntegrate functions.

### Steps
1.  **Load Data**: Load the Seurat object.
2.  **Preprocess**: Normalize data, find variable features, scale data, and run PCA.
3.  **Run Integrations**: Apply multiple integration methods (e.g., ComBatIntegration, HarmonyIntegration).
4.  **Post-process Integrations**: Perform downstream analysis (e.g., UMAP, PCA) for each integration method.
5.  **Build KNN Graphs**: Construct nearest neighbor graphs required for scoring metrics like LISI.
6.  **Cluster Cells**: Perform clustering for metrics like ARI and NMI.
7.  **Score Integrations**: Use functions like `AddScoreASW` and `AddScoreASWBatch` (details in other snippets).
8.  **Scale Scores**: Use `ScaleScores` (details in other snippets).
9.  **Plot Scores**: Use `PlotScores` (details in other snippets) for visualization and comparison.

### Request Example
```r
library(SeuratIntegrate)
library(Seurat)

# Load data
data("liver_small")
seu <- liver_small

# Define variables
batch.var <- "First_author"
cell.var <- "manual_cell_type_short"

# Preprocess
seu[["RNA"]] <- split(seu[["RNA"]], f = seu[[batch.var]])
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run multiple integrations
seu <- DoIntegrate(seu,
  CombatIntegration(layers = "data"),
  HarmonyIntegration(orig = "pca", dims = 1:30),
  use.hvg = TRUE,
  use.future = c(FALSE, FALSE)
)

# Post-process each integration type
# Harmony (DimReduc output) -> direct UMAP
seu <- RunUMAP(seu, reduction = "harmony", dims = 1:30,
               reduction.name = "umap.harmony")

# ComBat (Assay output) -> Scale -> PCA -> UMAP
seu <- ScaleData(seu, assay = "combat.reconstructed")
seu <- RunPCA(seu, assay = "combat.reconstructed", reduction.name = "pca.combat")
seu <- RunUMAP(seu, reduction = "pca.combat", dims = 1:30,
               reduction.name = "umap.combat")

# Build KNN graphs for scoring (required for LISI)
seu <- FindNeighbors(seu, reduction = "pca", dims = 1:30,
                     return.neighbor = TRUE, graph.name = "nn_unint")
seu <- FindNeighbors(seu, reduction = "harmony", dims = 1:30,
                     return.neighbor = TRUE, graph.name = "nn_harmony")
seu <- FindNeighbors(seu, reduction = "pca.combat", dims = 1:30,
                     return.neighbor = TRUE, graph.name = "nn_combat")

# Cluster for ARI/NMI
seu <- FindNeighbors(seu, reduction = "pca", dims = 1:30)
seu <- FindClusters(seu, resolution = 0.5)
seu$clusters_unint <- seu$seurat_clusters

seu <- FindNeighbors(seu, reduction = "harmony", dims = 1:30)
seu <- FindClusters(seu, resolution = 0.5)
seu$clusters_harmony <- seu$seurat_clusters

seu <- FindNeighbors(seu, reduction = "pca.combat", dims = 1:30)
seu <- FindClusters(seu, resolution = 0.5)
seu$clusters_combat <- seu$seurat_clusters
```
```

--------------------------------

### Full Seurat Integration and Benchmarking Workflow

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Demonstrates a comprehensive workflow for single-cell data integration using multiple methods (ComBat, Harmony), followed by post-processing, scoring, and benchmarking. Includes steps for running integrations, generating UMAP and PCA reductions, building KNN graphs, and clustering for ARI/NMI calculation.

```r
library(SeuratIntegrate)
library(Seurat)

# Load data
data("liver_small")
seu <- liver_small

# Define variables
batch.var <- "First_author"
cell.var <- "manual_cell_type_short"

# Preprocess
seu[["RNA"]] <- split(seu[["RNA"]], f = seu[[batch.var]])
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run multiple integrations
seu <- DoIntegrate(seu,
  CombatIntegration(layers = "data"),
  HarmonyIntegration(orig = "pca", dims = 1:30),
  use.hvg = TRUE,
  use.future = c(FALSE, FALSE)
)

# Post-process each integration type
# Harmony (DimReduc output) -> direct UMAP
seu <- RunUMAP(seu, reduction = "harmony", dims = 1:30,
               reduction.name = "umap.harmony")

# ComBat (Assay output) -> Scale -> PCA -> UMAP
seu <- ScaleData(seu, assay = "combat.reconstructed")
seu <- RunPCA(seu, assay = "combat.reconstructed", reduction.name = "pca.combat")
seu <- RunUMAP(seu, reduction = "pca.combat", dims = 1:30,
               reduction.name = "umap.combat")

# Build KNN graphs for scoring (required for LISI)
seu <- FindNeighbors(seu, reduction = "pca", dims = 1:30,
                     return.neighbor = TRUE, graph.name = "nn_unint")
seu <- FindNeighbors(seu, reduction = "harmony", dims = 1:30,
                     return.neighbor = TRUE, graph.name = "nn_harmony")
seu <- FindNeighbors(seu, reduction = "pca.combat", dims = 1:30,
                     return.neighbor = TRUE, graph.name = "nn_combat")

# Cluster for ARI/NMI
seu <- FindNeighbors(seu, reduction = "pca", dims = 1:30)
seu <- FindClusters(seu, resolution = 0.5)
seu$clusters_unint <- seu$seurat_clusters

seu <- FindNeighbors(seu, reduction = "harmony", dims = 1:30)
seu <- FindClusters(seu, resolution = 0.5)
seu$clusters_harmony <- seu$seurat_clusters

seu <- FindNeighbors(seu, reduction = "pca.combat", dims = 1:30)
seu <- FindClusters(seu, resolution = 0.5)
seu$clusters_combat <- seu$seurat_clusters
```

--------------------------------

### Run scVI Integration with IntegrateLayers

Source: https://context7.com/cbib/seurat-integrate/llms.txt

This wrapper runs scVI integration, outputting a latent space dimensional reduction. It's recommended to use raw counts and all features for this method. Ensure the 'scvi' conda environment is set up first. The integration requires metadata for batch grouping and allows customization of network architecture and training parameters.

```r
library(SeuratIntegrate)
library(Seurat)

# Ensure conda environment is set up first
# UpdateEnvCache("scvi")

# Preprocessing
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run scVI integration
# Recommended: use raw counts and all features
seu <- IntegrateLayers(
  object = seu,
  method = scVIIntegration,
  features = Features(seu),          # All features recommended
  layers = "counts",                 # Raw counts recommended
  groups = seu[[]],
  groups.name = "First_author",
  ndims.out = 10,                    # Latent space dimensions
  n_hidden = 128L,
  n_layers = 1L,
  max_epochs = 100L,
  batch_size = 128L,
  torch.intraop.threads = 4L,
  model.save.dir = NULL,             # Set path to save model
  verbose = TRUE
)

# Post-processing on scVI latent space
seu <- RunUMAP(seu, reduction = "integrated.scVI", dims = 1:10,
               reduction.name = "umap.scVI")
```

--------------------------------

### Run Scanorama Integration

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Integrates datasets using the Scanorama method. Requires normalized counts and variable features. Outputs a new reduction named 'integrated.scanorama'.

```r
seu <- IntegrateLayers(
  object = seu,
  method = ScanoramaIntegration,
  layers = "data",                    # Normalized counts
  features = VariableFeatures(seu),
  ncores = 4L,                        # Parallel threads
  ndims.out = 100L,                   # Output dimensions
  knn = 20L,                          # KNN parameter
  sigma = 15L,                        # Smoothing parameter
  verbose = TRUE
)

# Post-processing - Scanorama outputs both reduction and assay
seu <- RunUMAP(seu, reduction = "integrated.scanorama", dims = 1:50,
               reduction.name = "umap.scanorama")
```

--------------------------------

### Run BBKNN Integration with IntegrateLayers

Source: https://context7.com/cbib/seurat-integrate/llms.txt

This wrapper runs BBKNN integration, outputting a batch-corrected KNN graph and optionally ridge regression corrected data. Ensure the 'bbknn' conda environment is set up first. The integration uses PCA dimensions and requires metadata for batch grouping.

```r
library(SeuratIntegrate)
library(Seurat)

# Ensure conda environment is set up first
# UpdateEnvCache("bbknn")

# Preprocessing
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run BBKNN integration
seu <- IntegrateLayers(
  object = seu,
  method = bbknnIntegration,
  orig = "pca",
  groups = seu[[]],                  # Metadata data frame
  groups.name = "First_author",      # Batch variable name
  ndims.use = 30L,                   # PCA dimensions to use
  ridge_regression = TRUE,           # Enable ridge regression
  verbose = TRUE
)

# BBKNN outputs graphs - run UMAP with umap-learn
reticulate::use_condaenv("umap_0.5.4")
seu <- RunUMAP(
  seu,
  graph = "bbknn_ridge.residuals_connectivities",
  umap.method = "umap-learn",
  reduction.name = "umap.bbknn"
)
```

--------------------------------

### ScanoramaIntegration

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Performs integration using Scanorama manifold alignment.

```APIDOC
## ScanoramaIntegration

### Description
Wrapper to run Scanorama manifold alignment integration on Seurat V5 objects. Outputs both a dimensional reduction and corrected counts.

### Method
`ScanoramaIntegration`

### Parameters
- **object** (Seurat) - Required - The input Seurat object.
- **method** (function) - Required - The integration method, `ScanoramaIntegration`.
- **orig** (string) - Required - The name of the reduction to use for integration (e.g., "pca").
- **groups** (data.frame) - Required - Metadata data frame containing batch information.
- **groups.name** (string) - Required - The name of the metadata column to use for batch correction.
- **ndims.use** (integer) - Required - The number of dimensions to use from the original reduction.
- **verbose** (boolean) - Optional - Whether to print verbose output. Defaults to `TRUE`.

### Request Example
```r
library(SeuratIntegrate)
library(Seurat)

# Ensure conda environment is set up first
# UpdateEnvCache("scanorama")

# Preprocessing (example)
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run Scanorama integration
seu <- IntegrateLayers(
  object = seu,
  method = ScanoramaIntegration,
  orig = "pca",
  groups = seu[[]],
  groups.name = "First_author",
  ndims.use = 30,
  verbose = TRUE
)

# Post-processing (example)
seu <- RunUMAP(seu, reduction = "integrated.scanorama", dims = 1:30,
               reduction.name = "umap.scanorama")
```
```

--------------------------------

### Run Scanorama Integration with IntegrateLayers

Source: https://context7.com/cbib/seurat-integrate/llms.txt

This wrapper runs Scanorama manifold alignment integration, outputting both a dimensional reduction and corrected counts. Ensure the 'scanorama' conda environment is set up first. The integration requires metadata for batch grouping.

```r
library(SeuratIntegrate)
library(Seurat)

# Ensure conda environment is set up first
# UpdateEnvCache("scanorama")

```

--------------------------------

### Run Harmony Integration with IntegrateLayers

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Applies Harmony integration using the IntegrateLayers function. Outputs a corrected dimensional reduction embedding and requires specifying the input reduction.

```r
library(SeuratIntegrate)
library(Seurat)

# Preprocessing
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run Harmony integration with custom parameters
seu <- IntegrateLayers(
  object = seu,
  method = SeuratIntegrate::HarmonyIntegration,
  orig = "pca",           # Input PCA reduction
  dims = 1:30,            # Number of PCA dimensions to use
  new.reduction = "harmony",
  verbose = TRUE
)

# Post-processing: run UMAP on Harmony embedding
seu <- RunUMAP(seu, reduction = "harmony", dims = 1:30, reduction.name = "umap.harmony")

# Visualize
DimPlot(seu, reduction = "umap.harmony", group.by = "First_author")
```

--------------------------------

### Run ComBat Integration with IntegrateLayers

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Applies ComBat batch effect correction using the IntegrateLayers function. Outputs a corrected counts assay and requires preprocessing steps.

```r
library(SeuratIntegrate)
library(Seurat)

# Preprocessing
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run ComBat integration
seu <- IntegrateLayers(
  object = seu,
  method = CombatIntegration,
  layers = "data",                      # Use normalized data
  features = VariableFeatures(seu),
  verbose = TRUE
)

# Access the corrected counts
corrected_assay <- seu[["combat.reconstructed"]]

# Post-processing: scale, PCA, UMAP on corrected counts
seu <- ScaleData(seu, assay = "combat.reconstructed")
seu <- RunPCA(seu, assay = "combat.reconstructed", reduction.name = "pca.combat")
seu <- RunUMAP(seu, reduction = "pca.combat", dims = 1:30, reduction.name = "umap.combat")
```

--------------------------------

### scANVIIntegration

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Performs semi-supervised integration using scANVI.

```APIDOC
## scANVIIntegration

### Description
Wrapper to run scANVI (single-cell ANnotation using Variational Inference) semi-supervised integration. Uses cell type labels to guide batch correction.

### Method
`scANVIIntegration`

### Parameters
- **object** (Seurat) - Required - The input Seurat object.
- **method** (function) - Required - The integration method, `scANVIIntegration`.
- **features** (vector) - Optional - Features to use for integration.
- **layers** (string) - Optional - Layer to use for integration. Raw counts are recommended.
- **groups** (data.frame) - Required - Metadata data frame containing batch information.
- **groups.name** (string) - Required - The name of the metadata column to use for batch correction.
- **labels.name** (string) - Required - The name of the metadata column containing cell type labels.
- **labels.null** (string) - Optional - The label used for unlabeled cells. Defaults to "Unknown".
- **ndims.out** (integer) - Optional - Number of dimensions for the output latent space. Defaults to 10.
- **max_epochs** (integer) - Optional - Maximum number of training epochs. Defaults to 100.
- **verbose** (boolean) - Optional - Whether to print verbose output. Defaults to `TRUE`.

### Request Example
```r
library(SeuratIntegrate)
library(Seurat)

# Ensure conda environment is set up first
# UpdateEnvCache("scvi")

# Preprocessing
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run scANVI with cell type guidance
seu <- IntegrateLayers(
  object = seu,
  method = scANVIIntegration,
  features = Features(seu),
  layers = "counts",
  groups = seu[[]],
  groups.name = "First_author",      # Batch variable
  labels.name = "manual_cell_type_short",  # Cell type labels
  labels.null = "Unknown",           # Label for unlabeled cells
  ndims.out = 10,
  max_epochs = 100L,
  verbose = TRUE
)

# Post-processing
seu <- RunUMAP(seu, reduction = "integrated.scANVI", dims = 1:10,
               reduction.name = "umap.scANVI")
```
```

--------------------------------

### Manage Conda Environments with UpdateEnvCache

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Use UpdateEnvCache to set up and manage conda environments for Python-based integration methods. Call this function once for each method before running integration. getCache() displays current status, reloadCache() reloads from disk, and resetCache() removes a specific environment.

```r
library(SeuratIntegrate)

# Set up conda environments for Python methods (run once)
UpdateEnvCache("bbknn")       # For BBKNN
UpdateEnvCache("scvi")        # For scVI and scANVI
UpdateEnvCache("scanorama")   # For Scanorama
UpdateEnvCache("trvae")       # For trVAE

# View current conda environment status
getCache()

# Reload cache from disk if needed
reloadCache()

# Reset a specific method's environment
resetCache("bbknn")

# Custom conda environment setup
UpdateEnvCache(
  method = "scvi",
  conda.bin = "/path/to/conda",           # Custom conda binary

  conda.env = "my_scvi_env",              # Custom environment name
  overwrite.env = TRUE                     # Overwrite if exists
)
```

--------------------------------

### Score Each Integration Method

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Iterates through different integration methods to add LISI, ASW, ARI, and NMI scores to a Seurat object. Requires pre-defined integration configurations.

```R
for (integ in list(
  list(name = "Unintegrated", red = "pca", clust = "clusters_unint"),
  list(name = "Harmony", red = "harmony", clust = "clusters_harmony"),
  list(name = "ComBat", red = "pca.combat", clust = "clusters_combat")
)) {
  seu <- AddScoreLISI(seu, integration = integ$name,
                       batch.var = batch.var, cell.var = cell.var,
                       reduction = integ$red, dims = 1:30)
  seu <- AddScoreASW(seu, integration = integ$name,
                      cell.var = cell.var, what = integ$red)
  seu <- AddScoreASWBatch(seu, integration = integ$name,
                           batch.var = batch.var, cell.var = cell.var,
                           what = integ$red)
  seu <- AddScoreARI(seu, integration = integ$name,
                      cell.var = cell.var, clust.var = integ$clust)
  seu <- AddScoreNMI(seu, integration = integ$name,
                      cell.var = cell.var, clust.var = integ$clust)
}
```

--------------------------------

### HarmonyIntegration

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Wrapper to run Harmony integration on Seurat V5 objects. Outputs a corrected dimensional reduction embedding.

```APIDOC
## HarmonyIntegration

Wrapper to run Harmony integration on Seurat V5 objects. Outputs a corrected dimensional reduction embedding.

```r
library(SeuratIntegrate)
library(Seurat)

# Preprocessing
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run Harmony integration with custom parameters
seu <- IntegrateLayers(
  object = seu,
  method = SeuratIntegrate::HarmonyIntegration,
  orig = "pca",           # Input PCA reduction
  dims = 1:30,            # Number of PCA dimensions to use
  new.reduction = "harmony",
  verbose = TRUE
)

# Post-processing: run UMAP on Harmony embedding
seu <- RunUMAP(seu, reduction = "harmony", dims = 1:30, reduction.name = "umap.harmony")

# Visualize
DimPlot(seu, reduction = "umap.harmony", group.by = "First_author")
```
```

--------------------------------

### Manage Conda Environments for Python Methods

Source: https://github.com/cbib/seurat-integrate/blob/main/pkgdown/index.md

Uses UpdateEnvCache to create and manage conda environments for Python-based integration methods. Environments are automatically saved and used by SeuratIntegrate.

```R
# create environments:
UpdateEnvCache("bbknn")
UpdateEnvCache("scvi")
UpdateEnvCache("scanorama")
UpdateEnvCache("trvae")
```

--------------------------------

### bbknnIntegration

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Performs batch correction using the BBKNN algorithm.

```APIDOC
## bbknnIntegration

### Description
Wrapper to run BBKNN (Batch-Balanced K-Nearest Neighbors) on Seurat V5 objects. Outputs a batch-corrected KNN graph and optionally ridge regression corrected data.

### Method
`bbknnIntegration`

### Parameters
- **object** (Seurat) - Required - The input Seurat object.
- **method** (function) - Required - The integration method, `bbknnIntegration`.
- **orig** (string) - Required - The name of the reduction to use for integration (e.g., "pca").
- **groups** (data.frame) - Required - Metadata data frame containing batch information.
- **groups.name** (string) - Required - The name of the metadata column to use for batch correction.
- **ndims.use** (integer) - Required - The number of dimensions to use from the original reduction.
- **ridge_regression** (boolean) - Optional - Whether to perform ridge regression correction. Defaults to `FALSE`.
- **verbose** (boolean) - Optional - Whether to print verbose output. Defaults to `TRUE`.

### Request Example
```r
library(SeuratIntegrate)
library(Seurat)

# Ensure conda environment is set up first
# UpdateEnvCache("bbknn")

# Preprocessing
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run BBKNN integration
seu <- IntegrateLayers(
  object = seu,
  method = bbknnIntegration,
  orig = "pca",
  groups = seu[[]],                  # Metadata data frame
  groups.name = "First_author",      # Batch variable name
  ndims.use = 30L,                   # PCA dimensions to use
  ridge_regression = TRUE,           # Enable ridge regression
  verbose = TRUE
)

# BBKNN outputs graphs - run UMAP with umap-learn
reticulate::use_condaenv("umap_0.5.4")
seu <- RunUMAP(
  seu,
  graph = "bbknn_ridge.residuals_connectivities",
  umap.method = "umap-learn",
  reduction.name = "umap.bbknn"
)
```
```

--------------------------------

### Perform Multiple Data Integrations

Source: https://github.com/cbib/seurat-integrate/blob/main/pkgdown/index.md

Applies multiple integration methods to a Seurat object using the DoIntegrate function. Allows control over input data, features, and method-specific parameters. Note that 'use.future' must be TRUE for Python methods.

```R
seu <- DoIntegrate(seu,
       # ... integrations
         CombatIntegration(layers = "data"),
         HarmonyIntegration(orig = "pca", dims = 1:30),
         ScanoramaIntegration(ncores = 4L, layers = "data"),
         scVIIntegration(layers = "counts", features = Features(seu)),
       # ...
       use.hvg = TRUE,    # `VariableFeatures()`
       use.future = c(FALSE, FALSE, TRUE, TRUE)
)
```

--------------------------------

### UpdateEnvCache, getCache, reloadCache, resetCache

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Functions for managing conda environments required by Python-based integration methods in SeuratIntegrate.

```APIDOC
## Environment Management Functions

### Description
Functions to set up, manage, and view conda environments for Python-based integration methods.

### UpdateEnvCache

Sets up and manages conda environments for Python-based integration methods. This function creates the necessary conda environments with required dependencies.

#### Parameters
- **method** (string) - Required - The name of the method for which to set up the environment (e.g., "bbknn", "scvi", "scanorama", "trvae").
- **conda.bin** (string) - Optional - Path to the conda binary if not in PATH.
- **conda.env** (string) - Optional - Custom name for the conda environment.
- **overwrite.env** (boolean) - Optional - Whether to overwrite an existing environment with the same name.

### getCache

Views the current status of managed conda environments.

### reloadCache

Reloads the conda environment cache from disk.

### resetCache

Resets the conda environment for a specific method.

#### Parameters
- **method** (string) - Required - The name of the method whose environment should be reset.

### Request Example (UpdateEnvCache)
```r
library(SeuratIntegrate)

# Set up conda environments for Python methods (run once)
UpdateEnvCache("bbknn")       # For BBKNN
UpdateEnvCache("scvi")        # For scVI and scANVI
UpdateEnvCache("scanorama")   # For Scanorama
UpdateEnvCache("trvae")       # For trVAE

# View current conda environment status
getCache()

# Reload cache from disk if needed
reloadCache()

# Reset a specific method's environment
resetCache("bbknn")

# Custom conda environment setup
UpdateEnvCache(
  method = "scvi",
  conda.bin = "/path/to/conda",           # Custom conda binary
  conda.env = "my_scvi_env",              # Custom environment name
  overwrite.env = TRUE                     # Overwrite if exists
)
```
```

--------------------------------

### Run trVAE Integration

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Performs integration using the trVAE method, which requires raw counts for its loss function. Supports sequential integration with surgery mode.

```r
seu <- IntegrateLayers(
  object = seu,
  method = trVAEIntegration,
  features = Features(seu),
  layers = "counts",                  # Raw counts for nb/zinb loss
  scale.layer = NULL,
  groups = seu[[]],
  groups.name = "First_author",
  recon.loss = "nb",                  # 'nb', 'zinb', or 'mse'
  ndims.out = 10L,
  n_epochs = 400L,
  use_mmd = TRUE,
  verbose = TRUE
)
```

```r
seu <- IntegrateLayers(
  object = seu,
  method = trVAEIntegration,
  features = Features(seu),
  layers = "counts",
  groups = seu[[]],
  groups.name = "First_author",
  surgery.name = "ID_sample",         # Surgery groups
  surgery.sort = TRUE,
  model.save.dir = "~/trVAE_models"   # Save models
)
```

--------------------------------

### PlotScores

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Visualizes and compares integration performance using various plot types like dot plots, radar plots, and lollipop plots.

```APIDOC
## PlotScores

### Description
Visualizes and compares integration performance with multiple plot types.

### Method
`PlotScores`

### Parameters
- **seu** (Seurat Object) - The input Seurat object containing integration scores.
- **plot.type** (string) - The type of plot to generate: "dot" (default), "radar", or "lollipop".
- **split.by.score.type** (boolean) - Whether to separate biological conservation and batch correction scores.
- **order.by** (string) - The metric to order the plots by (e.g., "score").
- **rescale** (string) - The method for rescaling scores for plotting: 'none', 'rank', or 'score'.
- **include.integration** (list of strings) - Integrations to include in the plot.
- **exclude.integration** (list of strings) - Integrations to exclude from the plot.
- **include.score** (list of strings) - Specific scores to include.
- **exclude.score** (list of strings) - Specific scores to exclude.
- **batch.coeff** (numeric) - The weight for batch correction scores.
- **bio.coeff** (numeric) - The weight for bio-conservation scores.
- **recompute.overall.scores** (boolean) - Whether to recompute overall scores before plotting.

### Request Example
```r
# Dot plot
PlotScores(
  seu,
  plot.type = "dot",
  split.by.score.type = TRUE,
  order.by = "score",
  rescale = "rank"
)

# Radar plot
PlotScores(seu, plot.type = "radar", split.by.score.type = TRUE)

# Lollipop plot
PlotScores(seu, plot.type = "lollipop", split.by.score.type = FALSE)
```
```

--------------------------------

### AddScoreASW and AddScoreASWBatch

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Functions to compute the Adjusted Silhouette Width (ASW) for assessing cell-type conservation and batch correction effectiveness after data integration.

```APIDOC
## AddScoreASW

### Description
Computes the Adjusted Silhouette Width (ASW) for each cell to assess cell-type conservation after integration.

### Method
`AddScoreASW`

### Parameters
- **seu** (Seurat Object) - The input Seurat object.
- **integration** (string) - The name of the integration to score (e.g., "Unintegrated").
- **cell.var** (string) - The metadata column containing cell type information.
- **what** (string) - Specifies whether to use PCA reduction or a specific assay layer for scoring (e.g., "pca").
- **metric** (string) - The distance metric to use (e.g., "euclidean").
- **dist.package** (string) - The package to use for fast distance computation (e.g., "distances").
- **verbose** (boolean) - Whether to print verbose output.

## AddScoreASWBatch

### Description
Computes the Adjusted Silhouette Width (ASW) for each cell to assess batch correction effectiveness after integration.

### Method
`AddScoreASWBatch`

### Parameters
- **seu** (Seurat Object) - The input Seurat object.
- **integration** (string) - The name of the integration to score (e.g., "Unintegrated").
- **batch.var** (string) - The metadata column containing batch information.
- **cell.var** (string) - The metadata column containing cell type information.
- **what** (string) - Specifies whether to use PCA reduction or a specific assay layer for scoring (e.g., "pca").
- **per.cell.var** (boolean) - Whether to compute scores per cell type.
- **verbose** (boolean) - Whether to print verbose output.
```

--------------------------------

### DoIntegrate Function

Source: https://context7.com/cbib/seurat-integrate/llms.txt

The main function to run one or multiple integration methods on a Seurat object with a single command. It provides a flexible interface to customize integration-specific parameters and control over associated data and features.

```APIDOC
## DoIntegrate

Main function to run one or multiple integration methods on a Seurat object with a single command. It provides a flexible interface to customize integration-specific parameters and control over associated data and features.

```r
library(SeuratIntegrate)
library(Seurat)

# Load and preprocess data
data("liver_small")
seu <- liver_small

# Split layers by batch for integration
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)

# Standard preprocessing workflow
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run multiple integrations at once
seu <- DoIntegrate(seu,
  # R-based methods (use.future = FALSE)
  CombatIntegration(layers = "data"),
  HarmonyIntegration(orig = "pca", dims = 1:30),
  MNNIntegration(features = 2000),

  # Python-based methods (use.future = TRUE required)
  # ScanoramaIntegration(ncores = 4L, layers = "data"),
  # scVIIntegration(layers = "counts", features = Features(seu)),

  use.hvg = TRUE,           # Use variable features
  use.future = c(FALSE, FALSE, FALSE)  # R methods don't need future
)

# Check the results
names(seu@reductions)   # Will include "harmony"
names(seu@assays)       # Will include "combat.reconstructed", "mnn.reconstructed"
```
```

--------------------------------

### Update Conda Environment Cache with Pre-existing Environment

Source: https://github.com/cbib/seurat-integrate/blob/main/pkgdown/index.md

Updates the SeuratIntegrate conda environment cache with a pre-existing environment. This is useful if automatic environment creation fails or if you have a custom environment.

```R
# save "my_bbknn_env" (for bbknn) to cache
UpdateEnvCache("bbknn", conda.env = "my_bbknn_env")
```

--------------------------------

### Display Conda Environment Cache State

Source: https://github.com/cbib/seurat-integrate/blob/main/pkgdown/index.md

Retrieves and displays the current state of the persistent conda environment cache used by SeuratIntegrate.

```R
getCache()
```

--------------------------------

### scVIIntegration

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Performs integration using scVI (single-cell Variational Inference).

```APIDOC
## scVIIntegration

### Description
Wrapper to run scVI (single-cell Variational Inference) deep learning integration on Seurat V5 objects. Outputs a latent space dimensional reduction.

### Method
`scVIIntegration`

### Parameters
- **object** (Seurat) - Required - The input Seurat object.
- **method** (function) - Required - The integration method, `scVIIntegration`.
- **features** (vector) - Optional - Features to use for integration. All features are recommended.
- **layers** (string) - Optional - Layer to use for integration. Raw counts are recommended.
- **groups** (data.frame) - Required - Metadata data frame containing batch information.
- **groups.name** (string) - Required - The name of the metadata column to use for batch correction.
- **ndims.out** (integer) - Optional - Number of dimensions for the output latent space. Defaults to 10.
- **n_hidden** (integer) - Optional - Number of neurons in hidden layers. Defaults to 128.
- **n_layers** (integer) - Optional - Number of hidden layers. Defaults to 1.
- **max_epochs** (integer) - Optional - Maximum number of training epochs. Defaults to 100.
- **batch_size** (integer) - Optional - Batch size for training. Defaults to 128.
- **torch.intraop.threads** (integer) - Optional - Number of intra-op threads for PyTorch. Defaults to 4.
- **model.save.dir** (string) - Optional - Path to save the trained scVI model. Defaults to `NULL`.
- **verbose** (boolean) - Optional - Whether to print verbose output. Defaults to `TRUE`.

### Request Example
```r
library(SeuratIntegrate)
library(Seurat)

# Ensure conda environment is set up first
# UpdateEnvCache("scvi")

# Preprocessing
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run scVI integration
# Recommended: use raw counts and all features
seu <- IntegrateLayers(
  object = seu,
  method = scVIIntegration,
  features = Features(seu),          # All features recommended
  layers = "counts",                 # Raw counts recommended
  groups = seu[[]],
  groups.name = "First_author",
  ndims.out = 10,
  n_hidden = 128L,
  n_layers = 1L,
  max_epochs = 100L,
  batch_size = 128L,
  torch.intraop.threads = 4L,
  model.save.dir = NULL,             # Set path to save model
  verbose = TRUE
)

# Post-processing on scVI latent space
seu <- RunUMAP(seu, reduction = "integrated.scVI", dims = 1:10,
               reduction.name = "umap.scVI")
```
```

--------------------------------

### Scale and Visualize Integration Scores

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Scales the computed integration scores relative to a reference integration and then generates a dot plot visualization. Assumes scores have been added to the Seurat object.

```R
seu <- ScaleScores(seu, ref = "Unintegrated")
PlotScores(seu, plot.type = "dot", rescale = "rank")
```

--------------------------------

### Calculate and Add Performance Scores

Source: https://github.com/cbib/seurat-integrate/blob/main/pkgdown/index.md

Calculates a specific performance score (e.g., RegressPC) for integration results and optionally adds it to the Seurat object. Requires specifying the reduction method used.

```R
# save the score in a variable
rpca_score <- ScoreRegressPC(seu, reduction = "pca")

# or save the score in the Seurat object
seu <- AddScoreRegressPC(seu, integration = "unintegrated", reduction = "pca")
```

--------------------------------

### Score Integration Results

Source: https://github.com/cbib/seurat-integrate/blob/main/README.md

Calculates and saves integration scores using ScoreRegressPC or AddScoreRegressPC. The unintegrated version should also be scored for comparative analysis.

```R
# save the score in a variable
rpca_score <- ScoreRegressPC(seu, reduction = "[dimension_reduction]")  #e.g. "pca"

# or save the score in the Seurat object
seu <- AddScoreRegressPC(seu, integration = "[name_of_integration]", reduction = "[dimension_reduction]")
```

--------------------------------

### Scale and Plot Performance Scores

Source: https://github.com/cbib/seurat-integrate/blob/main/pkgdown/index.md

Scales the performance scores between zero and one, standardizing their direction for easier comparison. Then, plots the scaled scores to visualize and compare integration performance.

```R
# scale
seu <- ScaleScores(seu)

# plot
PlotScores(seu)
```

--------------------------------

### Run MNN Integration with IntegrateLayers

Source: https://context7.com/cbib/seurat-integrate/llms.txt

Applies Mutual Nearest Neighbors (MNN) correction using the IntegrateLayers function. Outputs a corrected counts assay and requires specifying the number of features and nearest neighbors.

```r
library(SeuratIntegrate)
library(Seurat)

# Preprocessing
data("liver_small")
seu <- liver_small
seu[["RNA"]] <- split(seu[["RNA"]], f = seu$First_author)
seu <- NormalizeData(seu)
seu <- FindVariableFeatures(seu)
seu <- ScaleData(seu)
seu <- RunPCA(seu)

# Run MNN integration
seu <- IntegrateLayers(
  object = seu,
  method = MNNIntegration,
  features = 2000,        # Number of HVGs to select
  k = 20,                 # Number of nearest neighbors for MNN
  verbose = TRUE
)

```