Documentation

Using indexed CNDB data

Install the current CNDBTools implementation, inspect the trajectories stored in a file, stream selected frames, or download a complete local copy.

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]])