PaCMAP (Pairwise Controlled Manifold Approximation) is a technique for visualization and dimensionality reduction, with the goal of simultaneously preserving the local structure and global structure of the original data in the dimensionality reduction result. The project is maintained by YingfanWang, and the source code is hosted on GitHub.
Purpose and Background Previous dimensionality reduction techniques usually focus on local structure (such as t-SNE, LargeVis, UMAP) or global structure (such as TriMAP), making it difficult to balance both, and requiring careful tuning of the parameters in the algorithm that control the balance between global and local structure. PaCMAP does not preserve global structure by increasing the number of neighbors; instead, it dynamically uses a special type of point pair—mid-near pairs—to first capture global structure and then refine local structure, thereby preserving both simultaneously. This method was published in the Journal of Machine Learning Research (JMLR) and received the John M. Chambers Statistical Software Award as well as the Statistical Programming and Analysis Innovation Award presented by the Statistical Computing Section and the Statistical Programming and Analysis Section of the American Statistical Association.
Main Capabilities PaCMAP optimizes a low-dimensional embedding through three types of point pairs: nearest-neighbor pairs (pair_neighbors), mid-near pairs (pair_MN), and far pairs (pair_FP). The project has also released follow-up work: ParamRepulsor, a parametric dimensionality reduction method accepted at NeurIPS 2024 (based on Parametric PaCMAP, supporting PyTorch GPU, and aimed at online learning and dynamic datasets); and LocalMAP, accepted at AAAI 2025 (Pairwise Controlled Manifold Approximation with Local Adjusted Graph), which makes true clusters easier to identify and separate by dynamically and locally adjusting the graph structure in the final stage. This method will soon be merged into the PaCMAP package.
Usage Installation: It can be installed from the conda-forge channel via conda or mamba, or pacmap can be installed from PyPI via pip. The basic installation includes FAISS as the default KNN backend, and optional KNN backends (annoy, faiss, voyager) are also supported. If you encounter problems during installation, you can try using Install dependencies with conda or mamba; in some cases, using numba >= 0.57 is recommended. Python usage: The pacmap package interface is compatible with scikit-learn, similar to the functions in the sklearn.manifold module. It supports the fit, fit_transform, and transform methods, and currently supports input in numpy.ndarray format (pandas DataFrame needs to be converted to ndarray). R usage: It can be called in R through the reticulate package, an example R notebook is provided, and Seurat Integration is provided to integrate Seurat objects for single-cell genomics. Rust usage: A Rust implementation has been released by @hadronzoo, which does not depend on the Python runtime or environment.
Key parameters n_components (output dimensionality, default 2); n_neighbors (number of nearest neighbors in the KNN graph, default 10, can be set to None for automatic selection: 10 when the sample size is less than 10000, and 10 + 15 * (log10(n) - 4) when the sample size is greater than 10000); MN_ratio (ratio of mid-near pairs to the number of nearest neighbors, n_MN = n_neighbors * MN_ratio, default 0.5); FP_ratio (ratio of farther pairs to the number of nearest neighbors, n_FP = n_neighbors * FP_ratio, default 2); init (initialization of the low-dimensional embedding, can be "pca" or "random" or a user-provided numpy array of shape (N, 2), default "pca"). Other parameters include num_iters (default 450), pair_neighbors/pair_MN/pair_FP (allow users to use their own graphs, default None), verbose (default False), lr (learning rate of the AdaGrad optimizer, default 1), apply_pca (whether to apply PCA to the data before constructing the KNN graph), intermediate (whether to output intermediate-stage optimization results; when True, outputs an array of shape (n, n_components, 13), corresponding to steps [0, 10, 30, 60, 100, 120, 140, 170, 200, 250, 300, 350, 450]), nn_backend (KNN backend, can be "annoy", "faiss", "voyager", default "faiss"), low_dist_thres (only used by LocalMAP, default 10).
Applicable scenarios and limitations PaCMAP is suitable for dimensionality reduction visualization of high-dimensional data. Examples include MNIST (n=70,000, d=784), Mammoth (n=10,000, d=3), COIL-20, COIL-100, FMNIST, Mouse single-cell RNA sequencing, and other datasets, and it can also be used for biological datasets (such as single-cell genomics). Since version 0.4, it has supported user-specified nearest neighbors to map large-scale datasets. The project provides code for reproducing experiments (three folders: data, experiments, and evaluation), and provides a test suite that runs on pull requests and commits to the master branch. For development, UV is recommended for dependency management, and the traditional pip workflow can also be used. For citation, refer to the bibtex provided by the project. Specific functional details, fees, or pricing information are not currently provided.