uchimata-py

This repository contains code for the Python widget version of the uchimata library. Made with anywidget, this allows people to use the functionality in computational notebooks, such as Jupyter Notebook.

Basic usage

The API is still frequently changing. The main feature of the widget right now is the ability to display 3D chromatin models and we're working on capabilities to integrate with other bioinformatics tools.

pip install uchimata

import uchimata as uchi
import numpy as np

BINS_NUM = 1000

# Step 1: Generate random structure, returns a 2D numpy array:
def make_random_3D_chromatin_structure(n):
    position = np.array([0.0, 0.0, 0.0])
    positions = [position.copy()]
    for _ in range(n):
        step = np.random.choice([-1.0, 0.0, 1.0], size=3)  # Randomly choose to move left, right, up, down, forward, or backward
        position += step
        positions.append(position.copy())
    return np.array(positions)

random_structure = make_random_3D_chromatin_structure(BINS_NUM)

# Step 2: Display the structure in an uchimata widget
numbers = list(range(0, BINS_NUM+1))
vc = {
    "color": {
        "values": numbers,
        "min": 0,
        "max": BINS_NUM,
        "colorScale": "Spectral"
    }, 
    "scale": 0.01, 
    "links": True, 
    "mark": "sphere"
}
uchi.Widget(random_structure, vc)

The underlying JS library only supports data in the Apache Arrow format.

In the widget version, on the other hand, we provide interface to load data in many notebook-native formats, such as 2D numpy arrays, or pandas dataframe (with columns named 'x', 'y', 'z').

Quickly test out uchimata with uv:

1. uv run --with uchimata --with numpy --with pyarrow --with jupyterlab jupyter lab
2. make a new notebook
3. copy and paste the code above into an empty cell

Or: run the example in Google Colab.

Contributing

Running tests: uv run pytest