U-Chrom

Universal Chromatin structure data analysis toolkit.

U-Chrom provides a unified framework for 3D chromatin structure analysis. The core data structure is a structure table — genomic bins mapped to 3D coordinates (chrom, start, end, x, y, z) — which can be obtained from either sequencing-based data (Hi-C, Dip-C) via 3D reconstruction, or imaging-based data (ORCA, MERFISH, DNA seqFISH+) via chromatin tracing.

On top of this common interface, U-Chrom implements:

• Reconstruction from sparse Hi-C contacts (Nuc Dynamics, GEM, MDS/SMACOF)

• Structure identification — loops (ArcFISH-style per-axis F-test), TADs (directionality index), compartments (placeholder)

• Geometric features — distance matrices, contact frequency, radius of gyration

• Interactive 3D browser built on PyVista + PyQt5

• Population-level aggregation plots (median distance matrix, contact map, Rg histogram)

Quick start

pip install u-chrom

from uchrom import ChromData

# Import FOF-CT imaging data
cd = ChromData.from_fofct("example-data/core.csv")

# ArcFISH-style loop calling (GPU-accelerated)
from uchrom.strc.loop import call_loops_axiswise_f
loops = call_loops_axiswise_f(cd, chrom="chr17", device="auto")

# Persist
cd.write("data.h5cd")

Launch the interactive 3D browser:

python -m uchrom.browser data.h5cd

Getting started

• Installation
• Concepts
• Example data

Tutorials — Core & I/O

• ChromData — the core data container
• Importing FOF-CT imaging data
• Importing PyHiM chromatin trace tables
• Takei 2025 cerebellum — ChromData walkthrough + paper reproductions
• Takei 2025 auto-discovery example

Tutorials — Reconstruction (recon)

• 3D reconstruction from Hi-C data
• GEM-FISH — joint Hi-C + FISH 3-D reconstruction

Tutorials — Imaging & tracing (im)

• Spot-to-fiber tracing with jie on seqFISH+ data

Tutorials — Structure identification (strc)

• Loop calling on tracing data
• TAD calling
• Single-cell domain calling with FISHnet
• A/B compartment calling

Tutorials — Embedding (emb)

• FastHigashi cell embedding

User guide

• ChromData
  • Construction
  • Attributes
  • Subsetting
  • On-demand distance matrix
  • I/O
  • Why not AnnData?
• I/O and file formats
  • Supported inputs
  • Reconstruction output: save_particles
  • FOF-CT import details
  • .h5cd format versioning
• Imaging & tracing (uchrom.im)
  • When to use uchrom.im.trace.align_spots
  • The jie algorithm in one paragraph
  • Known limitations
• 3D reconstruction
  • Nuc Dynamics (single-cell)
  • GEM (single-cell, energy minimisation)
  • Bulk MDS (PyTorch, whole-genome)
  • Programmatic API
• Structure identification
  • Loop calling
  • TAD calling
  • A/B compartment calling
  • Where results live
• Multi-omics Auto-discovery
  • Schema
  • Runner
  • Verified Notebook Exports
  • Notebook-first Code Agent
  • PantheonOS
• Iterative Auto-discovery Design
  • Motivation
  • High-level Architecture
  • Relationship to ChromData
  • IdeaGraph
  • External Knowledge Layer
  • Agent Scheduling
  • Dynamic Frontiers
  • Diversity and Novelty
  • Evidence-driven Follow-up
  • Notebook Agent Contract
  • Storage Layout
  • Proposed Implementation Phases
  • Open Questions
  • Summary
• Interactive 3D browser
  • Main areas
  • Layers and subsetting
  • Rendering
  • Trace statistics
  • Multi-canvas mode
  • Session save / load
  • Known issues

API reference

• API reference

Project

• Changelog
• License