CNDB v2
One indexed file, multiple replicas
New NDB trajectory files use the OpenMiChroM CNDB v2 format. A chromosome file can contain several experimental or simulation replicas. Each replica has its own chromatin types, genomic positions, and coordinate frames.
/Header
/replica1_chr1/types
/replica1_chr1/genomic_position
/replica1_chr1/spatial_position/1
/replica2_chr1/types
/replica2_chr1/genomic_position
/replica2_chr1/spatial_position/1
/_index
The embedded index and the NDB server's HTTP Range support allow CNDBTools to request selected chunks instead of transferring the entire file.
Step 1
Install CNDBTools from OpenMiChroM
The indexed streaming implementation is currently available from the reviewed OpenMiChroM development revision used to create the NDB files.
python -m venv cndb-env
source cndb-env/bin/activate
python -m pip install --upgrade pip
python -m pip install \
"OpenMiChroM @ git+https://github.com/junioreif/OpenMiChroM.git@b7498f2"
Confirm the installation:
python -c "from OpenMiChroM.CndbTools import CndbTools; print('CNDBTools ready')"
Step 2
Inspect a remote file
Detection reads only a small header and the embedded index. It reports the available trajectory names without downloading all coordinate frames.
from OpenMiChroM._structural_io import detect_structural_file
url = (
"https://ndb.rice.edu/d/Cheng_etal_HUVEC_eLife_2020/"
"HUVEC-C01.cndb"
)
info = detect_structural_file(url)
print(info.file_type)
print(info.trajectories)
print(info.range_supported, info.has_embedded_index)
Trajectory names follow the pattern replicaN_chrM. Missing replica numbers in a source publication remain missing; the migration does not synthesize data. A single-trajectory file may report an empty trajectory list because its frames are stored at the file root.
Step 3
Stream XYZ coordinates by frame
Select a trajectory, then request one or more frame IDs. A bead selection further limits the coordinate block returned to Python.
from OpenMiChroM.CndbTools import CndbTools
trajectory = info.trajectories[0] if info.trajectories else None
with CndbTools.from_remote(
h5_url=url,
trajectory=trajectory,
index_cache_path="HUVEC-C01.index.json.gz",
) as tools:
frame_id = tools.frame_ids[0]
xyz = tools.xyz(
frames=[frame_id],
beadSelection=range(100, 200),
)
print(xyz.shape) # (1, 100, 3)
print(tools.types[:5])
print(tools.genomic_positions[100:105])
print(tools.stream_stats())
Some imaging-derived structures contain complete NaN, NaN, NaN coordinate triplets for loci that were not observed in a frame. CNDB preserves those scientific missing-data markers. Use np.isfinite(xyz).all(axis=-1) to build an observed-bead mask.
To save each complete frame as a NumPy XYZ array:
from pathlib import Path
import numpy as np
output = Path("xyz_frames")
output.mkdir(exist_ok=True)
with CndbTools.from_remote(h5_url=url, trajectory=trajectory) as tools:
for frame_id in tools.frame_ids:
xyz = tools.xyz(frames=[frame_id])[0]
np.save(output / f"frame_{frame_id}.npy", xyz)
Iterating over every frame intentionally reads the complete trajectory over time. Use a frame list and bead selection when only a subset is required.
Local analysis
Download the complete CNDB file
curl --fail --location --remote-name \
"https://ndb.rice.edu/d/Cheng_etal_HUVEC_eLife_2020/HUVEC-C01.cndb"
Open the downloaded file with the same trajectory name:
with CndbTools.open(
"HUVEC-C01.cndb",
trajectory="replica1_chr1",
) as local_tools:
xyz = local_tools.xyz(frames=[local_tools.frame_ids[0]])