sddb.contract#
The loader contract (version 0.1.0): what a cohort materialised for spatialbatch looks like on disk.
A collection is a spatialbatch.SpatialDatasetCollection: a zarr v3 group with one dataset_<i> group per
cohort member, each written by spatialbatch.write_collection_dataset(). Per dataset:
the table (annbatch layout), rows Morton-sorted on
obsm["spatial"], each cell's centre(x, y)float64 in pixel-index coordinates of the written grid (pixeljhas its centre atj), inside[0, w) x [0, h). It is the centre of mass of the cell's label inlabels/cells, except for then_centroid_fallbackcells that have no pixel there (smaller than a pixel of the written grid), whose centre comes from the source (seeDatasetContract);obs["uid"]andobs["study_id"]of the source member, andobs["label_id"], the integer value of the row's cell inlabels/cells. Withtotalsin the contract:obs["total_counts"], each cell's sum ofXover the"Gene Expression"features, andvar["mean_counts"]andvar["var_counts"], each feature's mean and variance (n - 1degrees of freedom) over the dataset's cells, 0 for a filled feature. A dataset without the flag conforms without them, and itsobs["total_counts"], if any, is not checked;Xinteger counts (an integer dtype, or a float dtype with integral values) over one var index, the same in every dataset: the union of the members' features.var["feature_types"]comes from the source, and the"Gene Expression"rows are Ensembl ids (^ENS).var["present"]says which features this dataset's source measured; a feature it did not measure is all 0 inX.n_features_presentandn_features_filledin the contract count the two;images/<role>, the one image(c, y, x):heuint8 with 3 channels orifuint16 with one channel per name inchannels. One role per collection;labels/cells(y, x)integer on the image's grid, and optionallylabels/tissue. Images and labels are plain arrays, the identity onto the written grid: nocoordinateTransformationsormultiscalesattrs;uns["sddb_contract"], aDatasetContract;uns["spatial"][uid], aSpatialEntry. It follows Squidpy's layout (scalefactors,metadata) but holds no image arrays: the image isimages/<role>of the dataset.
Every sampled cell (sample cells drawn with seed) must have at least one pixel of its label_id, except for
at most n_centroid_fallback of them, and at least 99% of the centroids of those with pixels, rounded to the
pixel, must lie inside their own label: a concave cell's centre of mass can lie outside its mask.
Resolution: on the target grid the image was resampled to mpp_target. A target finer than the native grid
(mpp_native / mpp_target > 1, by any factor) is upsampling, which needs allow_upsample. A dataset whose mpp is
unknown keeps its native grid; a collection mixes the two only if every dataset sets allow_mixed_grids.
This subpackage imports pydantic and is not imported by import sddb; install it with the loader extra.