Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/satijalab/seurat-wrappers/llms.txt

Use this file to discover all available pages before exploring further.

PaCMAP (Pairwise Controlled Manifold Approximation) is a dimensionality reduction method designed to produce visualizations that faithfully preserve both local and global structure. It constructs three types of point pairs — neighbor pairs, mid-near pairs, and further pairs — and optimizes a low-dimensional embedding by balancing attractive and repulsive forces among them.

​
References

Wang, Y., Huang, H., Rudin, C., & Shaposhnik, Y. (2021). Understanding how dimension reduction tools work: an empirical approach to deciphering t-SNE, UMAP, TriMAP, and PaCMAP for data visualization. Journal of Machine Learning Research, 22(201), 1–73. https://doi.org/10.48550/arXiv.2012.04456 Huang, H., Wang, Y., Rudin, C., & Browne, E. P. (2022). Towards a comprehensive evaluation of dimension reduction methods for transcriptomic data visualization. Communications Biology. https://doi.org/10.1038/s42003-022-03628-x Source: YingfanWang/PaCMAP

​
Installation

PaCMAP is implemented in Python and called from R via reticulate. You must set up a Python environment with the pacmap package before using RunPaCMAP().
We strongly recommend using Anaconda or Miniconda for Python environment management. This ensures a clean, isolated environment and simplifies the connection between R and Python.
1

Create a conda environment with PaCMAP

conda create -n "pacmap" python=3.12
conda activate pacmap
conda install -y conda-forge::pacmap
2

Install R dependencies

# Install reticulate if not already available
install.packages("reticulate")
3

Connect R to the conda environment

Run this at the start of each R session before calling RunPaCMAP().
reticulate::use_condaenv(condaenv = "pacmap", conda = "auto")
If your Conda installation is in a non-default directory, replace "auto" with the path to your conda executable.

​
Key function

RunPaCMAP() — Runs PaCMAP on a Seurat object and stores the embedding as a DimReduc object. Input can be either a set of features (expression values) or existing reduction dimensions (e.g., PCA components).

​
Example

​
Run PaCMAP from variable features

library(Seurat)
library(SeuratData)
library(SeuratWrappers)

reticulate::use_condaenv(condaenv = "pacmap", conda = "auto")

InstallData("pbmc3k")
pbmc3k.final <- LoadData("pbmc3k", type = "pbmc3k.final")

# Prepare the object
pbmc3k.final <- UpdateSeuratObject(pbmc3k.final)
pbmc3k.final <- FindVariableFeatures(pbmc3k.final)

# Run PaCMAP using variable features as input
pbmc3k.final <- RunPaCMAP(
  object   = pbmc3k.final,
  features = VariableFeatures(pbmc3k.final)
)

# Visualize
DimPlot(object = pbmc3k.final, reduction = "pacmap")

​
Run PaCMAP from existing PCA dimensions

You can also pass specific PCA dimensions instead of raw features: 
pbmc3k.final <- RunPaCMAP(object = pbmc3k.final, dims = 2:5)
DimPlot(object = pbmc3k.final, reduction = "pacmap")

​
Visualize gene expression on the PaCMAP embedding

pbmc3k.final <- NormalizeData(pbmc3k.final, verbose = FALSE)
features.plot <- c("CD3D", "MS4A1", "CD8A", "GZMK", "GZMB", "FCGR3A")
FeaturePlot(pbmc3k.final, features.plot, ncol = 2, reduction = "pacmap")

​
Parameters

​
object
Seurat
A Seurat object to run PaCMAP on.
​
reduction
character
default:"pca"
Name of the dimensional reduction to use as input when dims is specified.
​
dims
integer vector
default:"NULL"
Dimensions of the specified reduction to use as input. Specify either dims or features, not both.
​
features
character vector
default:"NULL"
Features (genes) to use as input. Specify either features or dims, not both.
​
assay
character
default:"NULL"
Assay to pull feature data from when features is specified. Defaults to the default assay.
​
layer
character
default:"data"
Layer within the assay to use when features is specified.
​
n_components
integer
default:"2"
Number of PaCMAP components to compute.
​
n.neighbors
integer
default:"NULL"
Number of neighbors in the k-nearest neighbor graph. Defaults to 10 for datasets with fewer than 10,000 cells; for larger datasets defaults to 10 + 15 * (log10(n) - 4).
​
MN_ratio
numeric
default:"0.5"
Ratio of mid-near pairs to neighbor pairs. Controls the balance between local and global structure preservation.
​
FP_ratio
numeric
default:"2"
Ratio of further pairs to neighbor pairs. Controls the repulsive force in the embedding.
​
distance_method
character
default:"euclidean"
Distance metric for constructing the k-nearest neighbor graph.
​
lr
numeric
default:"1"
Learning rate for the AdaGrad optimizer.
​
num_iters
integer
default:"250"
Number of optimization iterations.
​
apply_pca
logical
default:"TRUE"
Whether to apply PCA to the input data before constructing the k-nearest neighbor graph. Recommended — greatly accelerates the process with minimal accuracy loss. Does not affect embedding initialization.
​
init
character
default:"random"
Initialization method for the low-dimensional embedding. One of "pca" or "random".
​
reduction.name
character
default:"pacmap"
Name under which the resulting DimReduc object is stored in the Seurat object.
​
reduction.key
character
default:"PaCMAP_"
Prefix for the column names of the PaCMAP embedding dimensions.
​
seed.use
integer
default:"11"
Random seed for reproducibility.

Build docs developers (and LLMs) love

Get started for freeTalk to us