Metadata-Version: 2.4
Name: lensed_umap
Version: 0.1.3
Summary: Untangle UMAP with filters.
Author-email: Jelmer Bot <jelmer.bot@uhasselt.be>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/vda-lab/lensed_umap
Project-URL: Issues, https://github.com/vda-lab/lensed_umap/issues
Keywords: umap,dimensionality reduction,data visualization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=2
Requires-Dist: pandas>=2.2
Requires-Dist: scipy>=1.9
Requires-Dist: scikit-learn>=1.1
Requires-Dist: umap-learn>=0.5
Requires-Dist: numba>=0.57
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Provides-Extra: docs
Requires-Dist: nbsphinx>=0.9; extra == "docs"
Requires-Dist: sphinx_rtd_theme>=2.0; extra == "docs"
Requires-Dist: numpydoc>=0.9.0; extra == "docs"
Requires-Dist: matplotlib>=3.8; extra == "docs"
Provides-Extra: notebooks
Requires-Dist: pandas>=2.2; extra == "notebooks"
Requires-Dist: jupyterlab>=4; extra == "notebooks"
Requires-Dist: matplotlib>=3.4; extra == "notebooks"
Requires-Dist: seaborn>=0.12; extra == "notebooks"
Requires-Dist: hvplot>=0.9; extra == "notebooks"
Requires-Dist: datashader>=0.16; extra == "notebooks"
Requires-Dist: holoviews>=1.18; extra == "notebooks"
Requires-Dist: anndata>=0.10; extra == "notebooks"
Dynamic: license-file

[![PyPI version](https://badge.fury.io/py/lensed-umap.svg)](https://badge.fury.io/py/lensed-umap)
[![Tests](https://github.com/vda-lab/lensed_umap/actions/workflows/Tests.yml/badge.svg)](https://github.com/vda-lab/lensed_umap/actions/workflows/Tests.yml)
[![Repository DOI](https://zenodo.org/badge/706249828.svg)](https://zenodo.org/doi/10.5281/zenodo.11193167)

# Lensed UMAP

Lensed UMAP provides three methods that apply lens-functions to a UMAP model.
Lens functions can be used to untangle embeddings along a particular dimension.
This dimension may be part of the data, or come from another information source.
Using lens functions, analysts can update their UMAP models to the questions
they are investigating, effectively viewing their data from different
perspectives. 

## How to use Lensed UMAP

The lensed UMAP package provides functions that operate on (fitted) UMAP
objects.

```python
import numpy as np
import pandas as pd
from umap import UMAP
import lensed_umap as lu
import matplotlib.pyplot as plt

# Load data and extract lens
df = pd.read_csv("./data/five_circles.csv", header=0)
lens = np.log(df.hue)

# Compute initial UMAP model
projector = UMAP(
    repulsion_strength=0.1,  # To avoid tears in projection that
    negative_sample_rate=2,  # are not in the modelled graph!
).fit(df[["x", "y"]])

# Draw intial model
x, y = lu.extract_embedding(projector)
plt.scatter(x, y, 2, lens, cmap="viridis")
plt.axis("off")
plt.show()
```

![Initial UMAP model](docs/_static/initial_umap.png)

```python
# Apply a global lens
lensed = lu.apply_lens(projector, lens, resolution=6)
x, y = lu.extract_embedding(lensed)
plt.scatter(x, y, 2, lens, cmap="viridis")
plt.axis("off")
plt.show()
```

![Lensed model](docs/_static/lensed_umap.png)


## Example Notebooks

A notebook demonstrating how the package works is available at 
[How lensed UMAP Works](https://nbviewer.org/github/vda-lab/lensed_umap/blob/master/notebooks/01_How_lensed_UMAP_works.ipynb).
The other notebooks demonstrate lenses on several data sets and contain the
analyses presented in our paper. The datasets we used as input and the data
generated by our notebooks are stored using [git lfs](https://git-lfs.com/),
which turns the files in this repository into versioned links to the actual data
files. Their documentation explains how to retrieve the actual data files.

## Installing

`lensed_umap` is available on PyPI:

```bash
pip install lensed_umap
```

## Citing

A scientific paper describing our work is available on Arxiv:

```bibtex
@misc{bot2024lens,
  title={Lens functions for exploring UMAP Projections with Domain Knowledge}, 
  author={Daniel M. Bot and Jan Aerts},
  year={2024},
  eprint={2405.09204},
  archivePrefix={arXiv},
  primaryClass={cs.LG}
}
```

## Licensing

The lensed UMAP package has a 3-Clause BSD license.
