Awesome
.. -- mode: rst --
|conda_version|_ |conda_downloads|_ |pypi_version|_ |pypi_downloads|_
.. |pypi_version| image:: https://img.shields.io/pypi/v/humap.svg .. _pypi_version: https://pypi.python.org/pypi/humap/
.. |pypi_downloads| image:: https://pepy.tech/badge/humap .. _pypi_downloads: https://pepy.tech/project/humap
.. |conda_version| image:: https://anaconda.org/conda-forge/humap/badges/version.svg .. _conda_version: https://anaconda.org/conda-forge/humap
.. |conda_downloads| image:: https://anaconda.org/conda-forge/humap/badges/downloads.svg .. _conda_downloads: https://anaconda.org/conda-forge/humap
.. image:: images/humap-2M.gif :alt: HUMAP exploration on Fashion MNIST dataset
===== HUMAP
Hierarchical Manifold Approximation and Projection (HUMAP) is a technique based on UMAP <https://github.com/lmcinnes/umap/>
_ for hierarchical dimensionality reduction. HUMAP allows to:
- Focus on important information while reducing the visual burden when exploring huge datasets;
- Drill-down the hierarchy according to information demand.
The details of the algorithm can be found in our paper on ArXiv <https://arxiv.org/abs/2106.07718>
_. This repository also features a C++ UMAP implementation.
Installation
HUMAP was written in C++ for performance purposes, and provides an intuitive Python interface. It depends upon common machine learning libraries, such as scikit-learn
and NumPy
. It also needs the pybind11
due to the interface between C++ and Python.
Requirements:
- Python 3.6 or greater
- numpy
- scipy
- scikit-learn
- pybind11
- pynndescent (for reproducible results)
- Eigen (C++)
If you have these requirements installed, use PyPI:
.. code:: bash
pip install humap
Alternatively (and preferable), you can use conda to install:
.. code:: bash
conda install humap
If using pip:
HUMAP depends on Eigen <https://eigen.tuxfamily.org/>
_. Thus, make it sure to place the headers in /usr/local/include if using Unix or C:\Eigen if using Windows.
Manual installation:
For manually installing HUMAP, download the project and proceed as follows:
.. code:: bash
python setup.py bdist_wheel
.. code:: bash
pip install dist/humap*.whl
Usage examples
The simplest usage of HUMAP is as it follows:
Fitting the hierarchy
.. code:: python
import humap
from sklearn.datasets import fetch_openml
X, y = fetch_openml('mnist_784', version=1, return_X_y=True)
# build a hierarchy with three levels
hUmap = humap.HUMAP([0.2, 0.2])
hUmap.fit(X, y)
# embed level 2
embedding2 = hUmap.transform(2)
Refer to notebooks/ for complete examples.
C++ UMAP implementation
You can also fit a one-level HUMAP hierarchy, which essentially fits UMAP projection.
.. code:: python
umap_reducer = humap.UMAP()
embedding = umap_reducer.fit_transform(X)
Citation
Please, use the following reference to cite HUMAP in your work:
.. code:: bibtex
@misc{marciliojr_humap2021,
title={HUMAP: Hierarchical Uniform Manifold Approximation and Projection},
author={Wilson E. Marcílio-Jr and Danilo M. Eler and Fernando V. Paulovich and Rafael M. Martins},
year={2021},
eprint={2106.07718},
archivePrefix={arXiv},
primaryClass={cs.LG}
}
License
HUMAP follows the 3-clause BSD license and it uses the open-source NNDescent implementations from EFANNA <https://github.com/ZJULearning/efanna>
_.
E-mail me (wilson_jr at outlook.com) if you like to contribute.
......