uchrom.datasets

Every dataset U-Chrom knows, as a ChromData (load: an atlas store over HTTP, or a dataset built once from its original files by a registered loader) or as its original files (fetch). See Datasets and the atlas; where each dataset comes from: Datasets: sources and recipes.

Datasets: every dataset U-Chrom knows, as a ChromData — or as its original files.

load gives a ChromData: a store of the public atlas (opened over HTTP, backed: only what a view or an analysis reads is fetched), or a dataset built once from its original files by a registered loader and cached in the data directory:

import uchrom.datasets as ds
cd = ds.load("takei2025_cerebellum")             # the atlas store, https://uchrom-atlas-r2.u-science.org/...
cd = ds.load("kim2020_scihic")                   # 1,931 cells, cell types, per-cell contact maps (linked)

Original files (4DN, GEO, Zenodo, GitHub, UCSC) — what the readers of uchrom.io read, the inputs of the benchmarks — are downloaded once into the data directory ($UCHROM_DATA, else ~/.cache/uchrom) and checked:

path = ds.fetch("takei")                          # .../4DNFIHF3JCBY.csv (Takei 2021 FOF-CT)
ds.list_datasets()                                # what there is, sizes, descriptions

A store of the atlas can be downloaded too, as its one-file copy (.cdz), for offline work; load then reads the local copy:

ds.list_atlas()                                   # id, title, study, organism, cells, modalities, sizes
ds.fetch("stevens2017_mesc")                      # .../atlas/stevens2017_mesc.cdz (26 MB)

Command line: python -m uchrom.datasets list | atlas | load NAME | fetch NAME ... | path NAME.

uchrom.datasets.atlas(name: str, *, root: str | None = None, backed: bool = True, local: bool | None = None, **read_kw)

Open a dataset of the atlas by its id (list_atlas()), backed by default: the one-file copy fetch() downloaded when it is there (local=None; True requires it, False ignores it), else the store over HTTP.

uchrom.datasets.atlas_path(name: str, *, root: Path | None = None) → Path

Where fetch() puts the one-file copy of the atlas store name: <data directory>/atlas/<name>.cdz (whether it is there or not).

uchrom.datasets.data_dir() → Path

Where datasets are downloaded and built: $UCHROM_DATA, else ~/.cache/uchrom.

The layout below it is the same for every dataset (e.g. 4DNFIHF3JCBY.csv, stevens2017_mesc/..., schicar_mop/raw/...), so a folder of earlier downloads can simply be named by UCHROM_DATA.

uchrom.datasets.fetch(name: str, *, root: Path | None = None, extract: bool = True, verbose: bool = True) → Path

Download a dataset into the data directory (files already there are kept) and return path().

A dataset of the registry (list_datasets()) comes from its original source and its md5 sums are checked; an id of the atlas (list_atlas()) gives the store’s one-file copy, <data directory>/atlas/<id>.cdz, which load() then reads instead of the remote store.

uchrom.datasets.files(name: str, *, root: Path | None = None) → List[Path]

The local paths of a dataset’s files (downloaded or not).

uchrom.datasets.list_atlas(root: str | None = None, *, data: Path | None = None)

The datasets of the atlas (chromdata.catalog.DEFAULT_ATLAS unless root) as a table, one row per store: title, study, organism, tissue, assembly, n_cells, modalities, size_mb, download_mb, downloaded (its .cdz is in the data directory — data or data_dir() — fetch()) and url (what load() opens over HTTP).

uchrom.datasets.list_datasets()

The datasets fetch() knows: name, size (MB), whether load() gives it as a ChromData, whether fetch --default (the tutorials’ inputs) includes it, description.

uchrom.datasets.load(name: str, *, root: Path | None = None, backed: bool | None = None, rebuild: bool = False, **read_kw)

A dataset as a ChromData.

• A dataset with a loader (list_datasets(), column load): built once from its original files (fetched with fetch()) into <data directory>/<dataset>/<dataset>.chromdata.zarr with its linked files next to it, then read from there (in memory unless backed=True). rebuild=True builds it again.

• Otherwise a store of the atlas (list_atlas()): its local copy when fetch() downloaded it, else opened over HTTP; backed unless backed=False.

read_kw go to chromdata.ChromData.read() (columns=, tracks=, …).

uchrom.datasets.path(name: str, *, root: Path | None = None) → Path

Where a dataset is: its file if it has one, else the folder its files share; for a store of the atlas, where fetch() puts its one-file copy.