Comparative Embedding Visualization with cev

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

First, create a virtual environment with all the required dependencies. We highly recommend to use hatch, which installs and sync all dependencies from pyproject.toml automatically.

hatch shell

Alternatively, you can also use conda.

conda env create -n cev python=3.11
conda activate cev

Next, install cev with all development assets.

pip install -e ".[notebooks,dev]"

Finally, you can now run the notebooks with:

jupyterlab

Commands Cheatsheet

If using hatch CLI, the following commands are available in the default environment:

Alternatively, you can devlop cev by manually creating a virtual environment and managing dependencies with pip.

Our CI linting/formatting checks are configured with pre-commit. We recommend installing the git hook scripts to allow pre-commit to run automatically on git commit.

pre-commit install # run this once to install the git hooks

This will ensure that code pushed to CI meets our linting and formatting criteria. Code that does not comply will fail in CI.

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}
}