README.md

Comparative Embedding Visualization with cev

cev is an interactive Jupyter widget for comparing a pair of 2D embeddings with shared labels.
Its novel metric allows to surface differences in label confusion, neighborhood composition, and label size.

_{The figure shows data from Mair et al. (2022) that were analyzed with Greene et al.'s (2021) FAUST method.
The embeddings were generated with Greene et al.'s (2021) annotation transformation and UMAP.}

cev is implemented with anywidget and builds upon jupyter-scatter.

Quick Start

The cev package has a cli to quickly try out a demo of comparison widget in JupyterLab. It requires uv to be installed.

uvx --python 3.11 cev demo # Downloads datasets and launches Jupyter Lab

Installation

Warning: cev is new and under active development. It is not yet ready for production and APIs are subject to change.

pip install cev

Getting Started

import pandas as pd
from cev.widgets import Embedding, EmbeddingComparisonWidget

umap_embedding = Embedding.from_ozette(df=pd.read_parquet("../data/mair-2022-tissue-138-umap.pq"))
ozette_embedding = Embedding.from_ozette(df=pd.read_parquet("../data/mair-2022-tissue-138-ozette.pq"))

umap_vs_ozette = EmbeddingComparisonWidget(
    umap_embedding,
    ozette_embedding,
    titles=["Standard UMAP", "Annotation-Transformed UMAP"],
    metric="confusion",
    selection="synced",
    auto_zoom=True,
    row_height=320,
)
umap_vs_ozette

See notebooks/getting-started.ipynb for the complete example.

Development

We use uv for development.

uv run jupyter lab

Commands Cheatsheet

Command	Action
uv run ruff format	Format the source code.
uv run ruff check	Check the source code for formatting issues.
uv run pytest	Run unit tests with pytest in base environment.

Release

releases are triggered via tagged commits

git tag -a vX.X.X -m "vX.X.X"
git push --follow-tags

License

cev is distributed under the terms of the Apache License 2.0.

Citation

If you use cev in your research, please cite the following preprint:

@article{manz2024general,
  title = {A General Framework for Comparing Embedding Visualizations Across Class-Label Hierarchies},
  author = {Trevor Manz and Fritz Lekschas and Evan Greene and Greg Finak and Nils Gehlenborg},
  url = {https://doi.org/10.1109/TVCG.2024.3456370},
  doi = {10.1109/TVCG.2024.3456370},
  journal = {IEEE Transactions on Visualization and Computer Graphics},
  series = {VIS ’24},
  publisher = {IEEE},
  year = {2024},
  month = {9},
  pages = {1-11}
}