[](https://badge.fury.io/py/lensed-umap)
[](https://github.com/vda-lab/lensed_umap/actions/workflows/Tests.yml)
[](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()
```
```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()
```
## 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/vda-lab/lensed_umap",
"name": "lensed-umap",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Jelmer Bot",
"author_email": "jelmer.bot@uhasselt.be",
"download_url": "https://files.pythonhosted.org/packages/2b/48/58ea955e3bfc8cf86db3c1cfdc20c5b435b9f0f69af8d6b70f919eb6c07b/lensed_umap-0.1.2.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/lensed-umap)\n[](https://github.com/vda-lab/lensed_umap/actions/workflows/Tests.yml)\n[](https://zenodo.org/doi/10.5281/zenodo.11193167)\n\n# Lensed UMAP\n\nLensed UMAP provides three methods that apply lens-functions to a UMAP model.\nLens functions can be used to untangle embeddings along a particular dimension.\nThis dimension may be part of the data, or come from another information source.\nUsing lens functions, analysts can update their UMAP models to the questions\nthey are investigating, effectively viewing their data from different\nperspectives. \n\n## How to use Lensed UMAP\n\nThe lensed UMAP package provides functions that operate on (fitted) UMAP\nobjects.\n\n```python\nimport numpy as np\nimport pandas as pd\nfrom umap import UMAP\nimport lensed_umap as lu\nimport matplotlib.pyplot as plt\n\n# Load data and extract lens\ndf = pd.read_csv(\"./data/five_circles.csv\", header=0)\nlens = np.log(df.hue)\n\n# Compute initial UMAP model\nprojector = UMAP(\n repulsion_strength=0.1, # To avoid tears in projection that\n negative_sample_rate=2, # are not in the modelled graph!\n).fit(df[[\"x\", \"y\"]])\n\n# Draw intial model\nx, y = lu.extract_embedding(projector)\nplt.scatter(x, y, 2, lens, cmap=\"viridis\")\nplt.axis(\"off\")\nplt.show()\n```\n\n\n\n```python\n# Apply a global lens\nlensed = lu.apply_lens(projector, lens, resolution=6)\nx, y = lu.extract_embedding(lensed)\nplt.scatter(x, y, 2, lens, cmap=\"viridis\")\nplt.axis(\"off\")\nplt.show()\n```\n\n\n\n\n## Example Notebooks\n\nA notebook demonstrating how the package works is available at \n[How lensed UMAP Works](https://nbviewer.org/github/vda-lab/lensed_umap/blob/master/notebooks/01_How_lensed_UMAP_works.ipynb).\nThe other notebooks demonstrate lenses on several data sets and contain the\nanalyses presented in our paper. The datasets we used as input and the data\ngenerated by our notebooks are stored using [git lfs](https://git-lfs.com/),\nwhich turns the files in this repository into versioned links to the actual data\nfiles. Their documentation explains how to retrieve the actual data files.\n\n## Installing\n\n`lensed_umap` is available on PyPI:\n\n```bash\npip install lensed_umap\n```\n\n## Citing\n\nA scientific paper describing our work is available on Arxiv:\n\n```bibtex\n@misc{bot2024lens,\n title={Lens functions for exploring UMAP Projections with Domain Knowledge}, \n author={Daniel M. Bot and Jan Aerts},\n year={2024},\n eprint={2405.09204},\n archivePrefix={arXiv},\n primaryClass={cs.LG}\n}\n```\n\n## Licensing\n\nThe lensed UMAP package has a 3-Clause BSD license.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause license",
"summary": "Untangle UMAP with lenses.",
"version": "0.1.2",
"project_urls": {
"Code": "https://github.com/vda-lab/lensed_umap",
"Homepage": "https://github.com/vda-lab/lensed_umap",
"Issue tracker": "https://github.com/vda-lab/lensed_umap/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "354410b699349e5bbf637e44388a11a6fd99e4eefcbfc9a3d5928171d1a1ec41",
"md5": "01c5a1ee32bac7b8d3501d1cc5b04058",
"sha256": "24eaf8897b5e2eda9e7ec9d601054f95d91762b95fa7f3f89bc5d0d48cd7569a"
},
"downloads": -1,
"filename": "lensed_umap-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01c5a1ee32bac7b8d3501d1cc5b04058",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13231,
"upload_time": "2024-07-11T08:51:22",
"upload_time_iso_8601": "2024-07-11T08:51:22.240293Z",
"url": "https://files.pythonhosted.org/packages/35/44/10b699349e5bbf637e44388a11a6fd99e4eefcbfc9a3d5928171d1a1ec41/lensed_umap-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2b4858ea955e3bfc8cf86db3c1cfdc20c5b435b9f0f69af8d6b70f919eb6c07b",
"md5": "35bba2e9ff3949cb70d8b7b3696dcd0d",
"sha256": "40ebc4b5085874cb62f3e7aacbf4a026e66b67db930ca3dcf90148b264ce8705"
},
"downloads": -1,
"filename": "lensed_umap-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "35bba2e9ff3949cb70d8b7b3696dcd0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 47727,
"upload_time": "2024-07-11T08:51:23",
"upload_time_iso_8601": "2024-07-11T08:51:23.291584Z",
"url": "https://files.pythonhosted.org/packages/2b/48/58ea955e3bfc8cf86db3c1cfdc20c5b435b9f0f69af8d6b70f919eb6c07b/lensed_umap-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-11 08:51:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vda-lab",
"github_project": "lensed_umap",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.23"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.1.1"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.9"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.1"
]
]
},
{
"name": "umap-learn",
"specs": [
[
">=",
"0.5.4"
]
]
},
{
"name": "numba",
"specs": [
[
">=",
"0.57.1"
]
]
}
],
"lcname": "lensed-umap"
}
JSON
