Dataset

SpatialDataset(; path=nothing, spill_threshold=64_000_000, metadata=Dict())

Root container for a spatial omics experiment.

Holds named collections of spatial elements (SpatialPoints, SpatialShapes, SpatialImage, SpatialLabels), a graph of CoordinateSystem nodes connected by AbstractTransformation edges, named SpatialRelation objects, and free-form metadata. Follows the SpatialData specification.

All data is backed by a BackingStore Zarr directory. When path is nothing, a temporary directory is used and cleaned up automatically. Supply path to write directly to a persistent location.

ds = SpatialDataset()                          # temp-backed
ds = SpatialDataset(path="/data/exp.zarr")     # persistent-backed

See also

BackingStore, with_dataset, keep!, elements, coord_systems, relations

BackingStore(; path=nothing, spill_threshold=64_000_000)

Disk location for a dataset's Zarr storage, with ownership tracking.

When path is nothing, a temporary directory is created and owned by this store (deleted automatically when the parent SpatialDataset is garbage collected or closed). When path is supplied, the directory is used as-is and the store is not owned — no automatic cleanup occurs.

spill_threshold (bytes) controls when large arrays are written to disk immediately on element attachment rather than held in memory.

See also

SpatialDataset, keep!, with_dataset

with_dataset(f; path=nothing, kw...)

Open a dataset, run f(ds), then close and clean up the backing store.

The dataset is always closed in a finally block, making this safe for temporary analysis workflows that should not leave stale Zarr directories on disk.

result = with_dataset() do ds
    ds["cells"] = cells
    analyze(Expression(), transcripts, cells)
end

See also

keep!, SpatialDataset

keep!(ds, path=ds.backing.path) → ds

Mark the dataset's backing store as permanent, preventing automatic cleanup.

If path differs from the current backing path, the store is copied there first. After keep!, the dataset no longer owns its backing directory — it will not be deleted when ds is garbage collected or closed.

See also

with_dataset, write!

elements(ds) → OrderedDict{String, Any}

Return the ordered dictionary of all named spatial elements in ds.

Values are concrete element types (SpatialPoints, SpatialShapes, SpatialImage, SpatialLabels). Use the typed accessors points, shapes, images, labels to retrieve a specific element with type checking.

coord_systems(ds) → Vector{String}

Return the names of all coordinate systems registered in ds.

transform(ds, src, dst) → AbstractTransformation

Resolve a composed transformation from coordinate system src to dst using the dataset's registered transforms. Delegates to resolve.

relations(ds) → Dict{String, SpatialRelation}
relations(ds, name) → SpatialRelation

Return the dictionary of all named relations, or a specific relation by name.

See also

SpatialRelation, analyze

images(ds, name) → SpatialImage
images(v, name) → SpatialImage  (cropped to view extent)

Retrieve the named SpatialImage from a dataset or dataset view. Raises an error if the element is not a SpatialImage.

See also

labels, points, shapes

labels(ds, name) → SpatialLabels

Retrieve the named SpatialLabels from a dataset or dataset view. Raises an error if the element is not a SpatialLabels.

See also

images, instance_ids

points(ds, name) → SpatialPoints
points(v, name) → SpatialElementView{SpatialPoints}

Retrieve the named SpatialPoints element from a dataset or dataset view. Raises an error if the element exists but is not SpatialPoints.

See also

shapes, images, labels, elements

shapes(ds, name) → SpatialShapes
shapes(v, name) → SpatialElementView{SpatialShapes}

Retrieve the named SpatialShapes element from a dataset or dataset view. Raises an error if the element exists but is not SpatialShapes.

See also

points, images, labels