Reference

Content review status

This page contains unreviewed content created with large language model (LLM) tools.

Reference coverage is incomplete

This page identifies the supported public modules and their ownership, but the site does not yet provide signature-level reference pages for every public object. Until those pages are written, consult the source docstrings and the tensorbids reference for inherited interfaces.

1 API ownership

BITSZarrDataset is a concrete tensorbids.BITSDataset. The distinction is important when writing a library against BITS:

tensorbids owns backend-neutral dataset operations and protocol types, including queries, record sets, relations, indexing, workspaces, fidelity contracts, and lineage.
bitsio owns the concrete open/create path, Zarr and auxiliary stores, sharded-Parquet engine, image-container ingestion, storage layout, content hashing, and reference resolver.
bitsfuse owns filesystem and MONAI integrations. Its types are not part of the bitsio API.

Depend on the narrowest layer required by your library. Accept a tensorbids.BITSDataset or protocol interface when implementation-specific storage behavior is not required.

2 Top-level API

The bitsio package exports the following objects lazily:

Object	Purpose
`BITSZarrDataset`	Concrete dataset using `bitsio` stores, table engine, and resolver
`IngestReport`, `StratumLayout`, `WriteSourceReport`	Structured results from source ingestion
`canonical_tensor_hash`	Content hash over tensor data type, shape, and C-order values
`navigator_content_hash`	Declared or computed content hash for a navigator
`cpu_budget`, `set_cpu_budget`	Process-wide concurrency budget used by storage operations
`__version__`	Installed `bitsio` version

BITSZarrDataset adds these principal implementation-specific operations:

Operation	Purpose
`open()`	Open local, memory, or object-storage roots and select concrete backends
`create()`	Create a writable dataset and write its description
`auto_create()`	Scan a source, create or resume a destination, ingest supported data, and build indexes
`write_source()`	Ingest a previously scanned source manifest
`write_nifti()`, `write_gifti()`, `write_cifti()`, `write_image()`	Decompose supported image containers and author navigators
`write_array()`	Write a tensor directly without authoring an image fidelity contract
`default_geometry()`, `plan_layout()`	Resolve array layout for a container write
`tensor_hash()`	Return or compute the canonical hash of a stored tensor
`warm_backend`	Report the selected TensorStore or zarr-python backend

Methods such as query(), read(), records(), write_table(), index(), open_workspace(), commit(), lineage(), and prov() are inherited from tensorbids.BITSDataset and execute through the components configured by BITSZarrDataset.

3 Public modules

Module	Public surface
`bitsio.stores`	TensorStore and zarr-python tensor backends, content-addressed and packfile auxiliary stores, key-value store helpers, and backend selection
`bitsio.resolver`	`ReferenceResolver`, `REFERENCE_RESOLVER`, layout profiles, slice parsing, array planning, and predicted-size helpers
`bitsio.tables`	`ShardedParquetEngine` and relation-object path construction
`bitsio.codecs`	BITS codec specification parsing and `CodecError`
`bitsio.aux_codec`	Canonical encoding and decoding of auxiliary payload kinds
`bitsio.encode`	Low-level NIfTI, GIfTI, and CIfTI decomposition and encoding helpers
`bitsio.testing`	Resolver test double and mandatory-core-operator coverage check
`bitsio.exceptions`	`BitsioError` hierarchy for configuration, storage, slicing, and source-description errors

Names under bitsio._core are implementation details. Import the re-exported names from the public modules above.

4 Optional dependencies

Extra	Capability
`tensorstore`	TensorStore Zarr v3 backend
`zarr`	zarr-python Zarr v3 backend
`obstore`	obstore transport with the zarr-python backend
`niflash`	Native NIfTI, GIfTI, and CIfTI container support
`s3`, `gcs`, `azure`	Corresponding object-storage filesystem support
`nifti`	NiBabel byte-compatibility oracle used in testing
`testing`	Public testing surface without additional dependencies

PyTorch is a development dependency used by the record-loader examples; the MONAI adapter is installed from bitsfuse[monai].

5 Documentation work still required

The following topics need dedicated reference or how-to pages:

complete signatures, parameter semantics, return types, and exception tables for BITSZarrDataset, including inherited tensorbids methods;
a tested compatibility matrix for backend, transport, object store, and codec combinations;
format-specific authoring and reconstruction behavior for NIfTI, GIfTI, and CIfTI, including byte-fidelity limitations;
validation, freezing, integrity verification, failure recovery, and resumed ingestion;
cache sizing, concurrency, multiprocessing, and backend-specific performance guidance;
resolver conformance testing and extension guidance for libraries that implement additional BITS operators; and
a versioned on-disk layout and compatibility reference for dataset readers that do not use BITSZarrDataset.