uchrom.io

I/O helpers with lazy optional-dependency imports.

Format upgrade

Convert ChromData files to the current container (.chromdata.zarr).

ChromData.read no longer reads the HDF5 .h5cd container (format 1.x and 2.0); this converts such a file once, after which it reads fast and can be backed (ChromData.read(path, backed=True)):

python -m uchrom.io.upgrade old.h5cd new.chromdata.zarr
python -m uchrom.io.upgrade data/*.h5cd --out-dir converted/        # <stem>.chromdata.zarr
python -m uchrom.io.upgrade data/*.h5cd --out-dir converted/ --format cdz

What changes (see docs/source/guide/chromdata_2_0_design.md):

• 1.x → 2.0 data model: bins = the unique spot loci; spots store bin_id instead of chrom/start/end (still available via cd.spots / cd.to_dataframe()); the spot-aligned 1.x tracks split into bin-level tracks (columns constant within every bin) and spot_tracks;

• the container: Zarr v3 + Parquet, spots sorted by (cell, trace, bin) with an index/ of row offsets (index/source_row keeps the original order).

The target format follows the destination suffix (.chromdata.zarr or .cdz). The source is never modified. Older zarr / cdz stores are rewritten in the current layout too.

uchrom.io.upgrade.convert(src: str | Path, dst: str | Path | None = None, *, overwrite: bool = False, coord_dtype: str = 'float64') → dict

the conversion is not specific to .h5cd sources

uchrom.io.upgrade.default_target(src: str | Path, fmt: str = 'zarr', out_dir: str | Path | None = None) → Path

<dir>/<stem>.chromdata.zarr (or .cdz) for src.

uchrom.io.upgrade.file_format_version(path: str | Path) → str

The uchrom_format_version of a ChromData file ("1.0" for an unversioned .h5cd).

uchrom.io.upgrade.main(argv: list | None = None) → int

uchrom.io.upgrade.upgrade_h5cd(src: str | Path, dst: str | Path | None = None, *, overwrite: bool = False, coord_dtype: str = 'float64') → dict

Read src (.h5cd 1.x / 2.0, or any ChromData store) and write it to dst in the current format (.chromdata.zarr / .cdz); a zarr / cdz source is read in its original row order.

dst defaults to <src stem>.chromdata.zarr next to src; its suffix picks the container. coord_dtype is the storage dtype of coords / layers (see ChromData.write()).

Returns a summary: source / target versions and containers, n_spots, n_bins and which tracks are bin- vs spot-level. src is never modified; dst must differ from it.