Home

Awesome

PaCMAP

Table of Contents

<!-- vscode-markdown-toc --> <!-- vscode-markdown-toc-config numbering=false autoSave=true /vscode-markdown-toc-config --> <!-- /vscode-markdown-toc -->

<a name='Introduction'></a>Introduction

Our work has been published at the Journal of Machine Learning Research(JMLR)!

PaCMAP (Pairwise Controlled Manifold Approximation) is a dimensionality reduction method that can be used for visualization, preserving both local and global structure of the data in original space. PaCMAP optimizes the low dimensional embedding using three kinds of pairs of points: neighbor pairs (pair_neighbors), mid-near pair (pair_MN), and further pairs (pair_FP).

Previous dimensionality reduction techniques focus on either local structure (e.g. t-SNE, LargeVis and UMAP) or global structure (e.g. TriMAP), but not both, although with carefully tuning the parameter in their algorithms that controls the balance between global and local structure, which mainly adjusts the number of considered neighbors. Instead of considering more neighbors to attract for preserving glocal structure, PaCMAP dynamically uses a special group of pairs -- mid-near pairs, to first capture global structure and then refine local structure, which both preserve global and local structure. For a thorough background and discussion on this work, please read our paper.

<a name='ReleaseNotes'></a>Release Notes

Please see the release notes.

<a name='Installation'></a>Installation

<a name='Installfromconda-forgeviacondaormamba'></a>Install from conda-forge via conda or mamba

You can use conda or mamba to install PaCMAP from the conda-forge channel.

conda:

conda install pacmap -c conda-forge

mamba:

mamba install pacmap -c conda-forge

<a name='InstallfromPyPIviapip'></a>Install from PyPI via pip

You can use pip to install pacmap from PyPI. It will automatically install the dependencies for you:

pip install pacmap

If you have any problems during the installation of dependencies, such as Failed building wheel for annoy, you can try to install these dependencies with conda or mamba. Users have also reported that in some cases, you may wish to use numba >= 0.57.

conda install -c conda-forge python-annoy
pip install pacmap

<a name='Usage'></a>Usage

<a name='UsingPaCMAPinPython'></a>Using PaCMAP in Python

The pacmap package is designed to be compatible with scikit-learn, meaning that it has a similar interface with functions in the sklearn.manifold module. To run pacmap on your own dataset, you should install the package following the instructions in installation, and then import the module. The following code clip includes a use case about how to use PaCMAP on the COIL-20 dataset:

import pacmap
import numpy as np
import matplotlib.pyplot as plt

# loading preprocessed coil_20 dataset
# you can change it with any dataset that is in the ndarray format, with the shape (N, D)
# where N is the number of samples and D is the dimension of each sample
X = np.load("./data/coil_20.npy", allow_pickle=True)
X = X.reshape(X.shape[0], -1)
y = np.load("./data/coil_20_labels.npy", allow_pickle=True)

# initializing the pacmap instance
# Setting n_neighbors to "None" leads to an automatic choice shown below in "parameter" section
embedding = pacmap.PaCMAP(n_components=2, n_neighbors=10, MN_ratio=0.5, FP_ratio=2.0) 

# fit the data (The index of transformed data corresponds to the index of the original data)
X_transformed = embedding.fit_transform(X, init="pca")

# visualize the embedding
fig, ax = plt.subplots(1, 1, figsize=(6, 6))
ax.scatter(X_transformed[:, 0], X_transformed[:, 1], cmap="Spectral", c=y, s=0.6)

<a name='UsingPaCMAPinR'></a>Using PaCMAP in R

You can also use PaCMAP in R with the reticulate package. We provide a sample R notebook that demonstrates how PaCMAP can be called in R for visualization.

<a name='Benchmarks'></a>Benchmarks

The following images are visualizations of two datasets: MNIST (n=70,000, d=784) and Mammoth (n=10,000, d=3), generated by PaCMAP. The two visualizations demonstrate the local and global structure's preservation ability of PaCMAP respectively.

MNIST

Mammoth

<a name='Parameters'></a>Parameters

The list of the most important parameters is given below. Changing these values will affect the result of dimension reduction significantly, as specified in section 8.3 in our paper.

The initialization is also important to the result, but it's a parameter of the fit and fit_transform function.

Other parameters include:

<a name='Methods'></a>Methods

Similar to the scikit-learn API, the PaCMAP instance can generate embedding for a dataset via fit, fit_transform and transform method. We currently support numpy.ndarray format as our input. Specifically, to convert pandas DataFrame to ndarray format, please refer to the pandas documentation. For a more detailed walkthrough, please see the demo directory.

<a name='Howtouseuser-specifiednearestneighbor'></a>How to use user-specified nearest neighbor

In version 0.4, we have provided a new option to allow users to use their own nearest neighbors when mapping large-scale datasets. Please see the demo for a detailed walkthrough about how to use PaCMAP with the user-specified nearest neighbors.

<a name='Reproducingourexperiments'></a>Reproducing our experiments

We have provided the code we use to run experiment for better reproducibility. The code are separated into three parts, in three folders, respectively:

After downloading the code, you may need to specify some of the paths in the script to make them fully functional.

<a name='Citation'></a>Citation

If you used PaCMAP in your publication, or you used the implementation in this repository, please cite our paper using the following bibtex:

@article{JMLR:v22:20-1061,
  author  = {Yingfan Wang and Haiyang Huang and Cynthia Rudin and Yaron Shaposhnik},
  title   = {Understanding How Dimension Reduction Tools Work: An Empirical Approach to Deciphering t-SNE, UMAP, TriMap, and PaCMAP for Data Visualization},
  journal = {Journal of Machine Learning Research},
  year    = {2021},
  volume  = {22},
  number  = {201},
  pages   = {1-73},
  url     = {http://jmlr.org/papers/v22/20-1061.html}
}

For PaCMAP's performance on biological dataset, please check the following paper:

@article{huang2022towards,
  title={Towards a comprehensive evaluation of dimension reduction methods for transcriptomic data visualization},
  author={Huang, Haiyang and Wang, Yingfan and Rudin, Cynthia and Browne, Edward P},
  journal={Communications biology},
  volume={5},
  number={1},
  pages={719},
  year={2022},
  publisher={Nature Publishing Group UK London}
}

<a name='License'></a>License

Please see the license file.