vitessce-python

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

vitessce-python

★ 67 Open GitHub ↗

Python API and Jupyter widget for Vitessce

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# vitessce-python

[![PyPI](https://img.shields.io/pypi/v/vitessce)](https://pypi.org/project/vitessce)
[![docs](https://img.shields.io/badge/docs-📖-57B4E9.svg)](https://vitessce.github.io/vitessce-python/)

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/vitessce/vitessce-python/main?filepath=docs/notebooks/widget_pbmc.ipynb)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/vitessce/vitessce-python/blob/main/docs/notebooks/widget_on_colab.ipynb)
[![Open in molab](https://marimo.io/molab-shield.svg)](https://molab.marimo.io/github/vitessce/vitessce-python/blob/main/docs/notebooks/widget_on_colab.ipynb)

Python API and Jupyter widget facilitating interactive visualization of spatial single-cell data with [Vitessce](https://github.com/vitessce/vitessce).

## Installation

To install with pip:

$ pip install 'vitessce[all]'

## Getting started

Explore our [example notebooks](./docs/notebooks/).
These contain demos of different use cases and integrations with single-cell data analysis packages.

## Development

For a development installation (requires NodeJS and NPM),

$ git clone https://github.com/vitessce/vitessce-python.git
    $ cd vitessce-python
    $ uv sync --extra dev --extra docs --extra all

Alternatively, use conda:

$ conda create -n vitessce-dev python=3.12
    $ conda activate vitessce-dev
    $ pip install -e ".[dev,docs,all]"
    
Troubleshooting SpatialQuery installation on macOS:
    
    $ # Use the macOS clang instead of from homebrew.
    $ CC=/usr/bin/clang CXX=/usr/bin/clang++ pip install -e ".[dev,docs,all,sq]"

## Linting and testing

```sh
uv run flake8
uv run pytest
```

### Formatting

One file:

```sh
uv run autopep8 --in-place --aggressive ./path/to/file.py
```

All `.py` files:

```sh
find . -name '*.py' -exec uv run autopep8 --in-place --aggressive '{}' \;
```

## Documentation

```sh
uv run make html
```

## Deployment

To deploy a new version, increment the version of the Python package in [`pyproject.toml`](./pyproject.toml).

Then, when you push or merge the code with the incremented versions to `main`, the GitHub Action `deploy.yml` workflow will build and push the package to PyPI.

## Troubleshooting

### Check JavaScript console

Check the JavaScript console in the web browser for error messages. To do so, shift+right click in Jupyter, then click Inspect element. You may need to enable your browser's develop mode in its preferences for this option to appear when you right-click.

### Check your Python environment

Check that you have activated the correct conda or other virtual environment as you expect.
When sharing errors, it can be helpful to share the current versions of packages in the environment, e.g., by `conda list` or `pip list`.

### Restart Kernel and Clear All Outputs, then refresh the browser tab

To ensure that older widget JavaScript output is not causing conflicts with newer JavaScript output (which may persist via notebook outputs even without running notebook cells), clear old outputs by Kernel -> Restart Kernel and Clear All Outputs. Then refresh the browser tab (containing Jupyter) to ensure all JavaScript outputs are fresh.

This is also typically required when running `!pip install vitessce[all]` from within a Jupyter notebook cell in the same session as running `vc.widget()` for the first time.
The Kernel restart/Output clearing is required when a new Jupyter widget is installed in the environment, otherwise Jupyter will not yet recognize the newly-installed widget (as the notebook was opened with a different set of Jupyter widgets installed, and widget discovery is performed only at certain stages in the notebook lifecycle).

### Check the widget configuration

If the widget renders successfully, you can get its current configuration by

```py
vw = vc.widget()
vw
```

```py
vw.config
```

### Usage when Jupyter is running on a remote machine

If Jupyter is running on a remote machine, then use `proxy=True`. You may need to specify `host_name` as well (`widget` should be able to detect this but the plain `display` cannot).

```py
vw = vc.widget(proxy=True)
vw
```

```py
vc.display(proxy=True, host_name="http://localhost:8888")
```

For more information see the [data location options documentation](https://python-docs.vitessce.io/data_options.html).

### Ensure that Vitessce and Jupyter are installed in the same environment

With the environment activated, run `pip list` on the command line:

```
Package                       Version
----------------------------- -----------
...
jupyterlab                    3.x.x
...
vitessce                      3.x.x
```

## Resources

- [ipywidget docs: Building a Custom Widget](https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20Custom.html)
- [ipywidget docs: Low Level Widget Tutorial](https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20Low%20Level.html)
- [ipywidget example: ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet)
- [ipywidget example (with React): ipymaterialui](https://github.com/maartenbreddels/ipymaterialui)
- [ipywidget example (with React): higlass-python](https://github.com/higlass/higlass-python)
- [ipywidget cookiecutter](https://github.com/jupyter-widgets/widget-cookiecutter)
- [Sphinx: Getting Started](https://www.sphinx-doc.org/en/master/usage/quickstart.html)
- [Read the Docs Sphinx Theme](https://github.com/readthedocs/sphinx_rtd_theme)
- [jupyter server proxy](https://jupyter-server-proxy.readthedocs.io/en/latest/arbitrary-ports-hosts.html)

## Getting/Offering Help

If you have a specific bug or feature request, please feel free to open an [issue](https://github.com/vitessce/vitessce-python/issues/new).  Otherwise our [discussions](https://github.com/vitessce/vitessce-python/discussions) section is a great place to get help or offer it.  If you aren't sure if something is a bug or not, don't have all the reproduction steps, or just have a general question, feel free to open a discussion post.

vitessce-python

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README