What is U-Chrom?
Chromatin tracing, DNA seqFISH+, single-cell, spatial and bulk Hi-C all describe how the genome is
folded in 3-D — cell by cell — but each comes with its own formats and tools. U-Chrom puts them in
one data model, ChromData (stored as .chromdata.zarr, read from disk or over HTTP one cell
at a time), and builds the analyses, a web browser and a public data atlas on top of it.
| You have… | U-Chrom gives you |
|---|
| Chromatin tracing (FOF-CT, PyHiM) | spot-to-trace alignment, imputation (uc.pp); TADs, loops, compartments from 3-D distances (uc.tl.call_tads / call_loops / call_compartments) |
| Imaging multi-omics (DNA seqFISH+) | spots, chromatin marks and RNA of thousands of cells in one store; cell types, embeddings |
| Single-cell Hi-C | per-cell contact maps, single-cell boundaries and A/B, pseudo-bulk, cell embeddings (FastHigashi), 3-D structures (EMber, NucDynamics) |
| Spatial Hi-C | per-spot contact maps placed in the tissue, with RNA and images; spatial statistics |
| Bulk Hi-C | HiCCUPS / Mustache loops, compartments, 3-D models (MDS, IGM populations, GEM-FISH with imaging) |
Try it without installing
Install
Python ≥ 3.11. The packages are installed from this repository (not on PyPI yet):
git clone https://github.com/u-science-lab/U-Chrom.git && cd U-Chrom
uv pip install -e "packages/uchrom[web]" # analysis library + data model + web browser
# or: pip install -e packages/chromdata -e packages/uchrom-browser -e packages/uchrom
Optional components (add them in the brackets, e.g. "packages/uchrom[web,recon]"):
| Extra | Adds | Needed for |
|---|
recon | uchrom-recon, the native engine (Rust toolchain needed to build) | 3-D reconstruction: EMber, NucDynamics, IGM |
maps | uchrom-maps (Rust) | fast HiCCUPS / Mustache loop calling on Hi-C maps |
emb | FastHigashi (needs NumPy < 2) | uc.tl.embed_higashi |
hic · umap · plot3d | hic-straw · umap-learn · PyVista | reading .hic · UMAP · 3-D plots in Python |
Details, GPU notes and an install check: Installation.
Quick start
1 · Open a dataset of the atlas — read over HTTP, nothing to download first:
import uchrom.datasets as ds
cd = ds.load("takei2025_cerebellum") # DNA seqFISH+, mouse cerebellum
print(cd)
# ChromData (backed: takei2025_cerebellum.chromdata.zarr):
# n_spots=10912638, n_traces=59112, n_cells=1799, n_bins=100049 …
cell = cd.get_cell(cd.cells.index[0]) # one cell: 4,183 spots, 24 traces, 62 tracks
2 · Analyse — chromatin tracing (Takei et al. 2021) → TADs from 3-D distances:
import uchrom as uc
cd = ds.load("takei2021_mesc") # built once from 4DN files (~23 MB): 201 cells
tads = uc.tl.call_tads(cd, chrom="chr3") # ArcFISH; also stored in cd.results["tads.arcfish"]
cd.write("takei2021.chromdata.zarr")
3 · Look — open the result in the web browser (http://127.0.0.1:8765):
uchrom-browser takei2021.chromdata.zarr
Every view follows the cells you select. Here, DNA seqFISH+ of the mouse cerebellum (Takei et al. 2025, from
the atlas) with one Purkinje cell selected: its chromosomes in 3-D among its neighbours, its place in the UMAP,
chromatin marks along chr1 and the radius-of-gyration distribution:
Next: single-cell Hi-C → 3-D structures (uc.tl.reconstruct_sc, extra recon) in the
reconstruction tutorial; cell embeddings from contact maps
(uc.tl.embed_higashi, extra emb) in the Higashi tutorial;
all tutorials run on real data.
The data model in one picture
ChromData
├── cells one row per cell (cell type, position in the tissue, RNA, embeddings in cellm)
│ └── traces one chromosome copy each (imaging) or one chromosome (sequencing)
│ └── spots x, y, z of a locus, with per-spot tracks (chromatin marks, intensities)
├── bins the shared locus axis: chrom, start, end — every modality is indexed on it
└── linked contact maps (.cool / .scool), AnnData, images, … read on demand, per cell
A store opens backed — on disk or over HTTP — and reads one cell, trace or chromosome at a time,
so a 10-million-spot dataset opens in seconds. More: Concepts,
Data model & storage, format spec.
API at a glance
| Module | What | Examples |
|---|
uchrom.datasets | the atlas and every tutorial dataset | ds.load, ds.fetch; python -m uchrom.datasets list / atlas |
uchrom.io | readers and writers | read_pairs, load_cool, read_seqfish_multiomics, write_fofct; ChromData.from_fofct |
uc.pp | imaging preprocessing | align_spots, impute, merge_duplicate_spots |
uc.tl | structures, reconstruction, embeddings | call_tads, call_loops, call_compartments, single_cell_boundaries, pseudobulk, reconstruct_sc, reconstruct_bulk, embed_cells, embed_higashi, cluster_cells |
uchrom.pl | plots (matplotlib) | plot_contact_map, plot_distance_matrix, plot_spatial, plot_structure_3d |
uchrom_browser | the web browser, also driven from Python | uchrom-browser data.chromdata.zarr; ub.connect() |
uc.pp and uc.tl come with import uchrom as uc; import uchrom.io and uchrom.pl explicitly.
Full reference: API.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
