Core

The deepspatial.core module serves as the primary entry point for the DeepSpatial framework. It provides a user-friendly, high-level API designed to facilitate the seamless reconstruction of continuous 3D tissue volumes from discrete 2D spatial transcriptomics slices.

Main Class

DeepSpatial is the primary user-facing class. It orchestrates internal dataset states, model weights, and the mapping statistics required for physical coordinate space transformations.

DeepSpatial

DeepSpatial: Reconstructing True 3D Spatial Omics at Single-Cell Resolution.

Workflow Methods

The following methods define the standard workflow for 3D volume reconstruction utilizing the DeepSpatial class:

Data Preparation

Prior to modeling, the data pipeline must be initialized. This process extracts the physical coordinate boundaries, writes normalized internal coordinate keys, constructs adjacent-slice UOT pairs, and records the UOT configuration in data_config. The standard pipeline expects cell-type annotations because they are used in UOT, flow matching, and output decoding.

DeepSpatial.setup_data

Prepares the data pipeline and calculates physical normalization statistics.

Model & Training

Configures the GiT architecture and joint continuous Flow Matching dynamics. Spatial coordinates, gene expression, and relaxed one-hot cell-type states use velocity-matching losses; cell type is not trained with cross-entropy. Saved metadata includes data, model, and training configurations.

DeepSpatial.build_model	Instantiates the GiT network architecture and Flow Matching logic.
DeepSpatial.fit	Executes the training loop using PyTorch Lightning.
DeepSpatial.load_checkpoint	Loads model weights and metadata for inference or resuming.

3D Reconstruction

The core generation and inference API. It uses density-aware target depths and depth-dependent parent directions. Forward samples follow the learned ODE from physical time 0, while backward samples use explicit reverse-time integration from physical time 1 without swapping depth endpoints or flipping a forward trajectory. Generated expression is sparsified to the parent cell’s non-zero gene count. There is no oversampling or spatial subset pruning.

DeepSpatial.reconstruct_full_volume	High-level API to reconstruct the entire 3D volume from a list of slices.
DeepSpatial.reconstruct_between_slices	Generates a 3D volume segment between two specific AnnData slices.

The internal generation helper is named _generate_virtual_cells, reflecting its actual role; it does not implement a pruning optimization.