Software and datasets

sc3D installation: The package supports Python ≥ 3.8 and is distributed on PyPI. We recommend creating a dedicated mamba/conda environment and installing sc3D via pip:

mamba create -n sc3d python=3.13

mamba activate sc3d

pip install sc-3D

Alternatively, clone the repository (git clone https://github.com/GuignardLab/sc3D.git) and install in developer mode with pip install -e. For macOS machines with M1 chips, use miniforge to ensure compatibility.

Dependencies: sc3D depends on numpy, scipy, pandas, anndata, scanpy, matplotlib, and napari. Installing jupyter is recommended to run the example notebooks.

Data requirements: Input datasets must be stored as .h5ad anndata objects containing spatial coordinates and gene expression matrices. The x-y coordinates should be stored in obsm['X_spatial'], the array (slice) identifier in obs['orig.ident'], the tissue or cell cluster label in obs['predicted.id'], and gene names as indices or in var['feature_name'].

Slice ordering is inferred from the obs['orig.ident'] field by extracting numeric sequences from the identifier string using a regular expression. Specifically, sc3D identifies all contiguous numeric substrings separated by non-numeric characters and assigns the slice number based on the numeric sequence at position array_id_num_pos. By default (array_id_num_pos = -1), the last numeric sequence in the identifier is used.

For example, identifiers such as coverslip_03, sliceA5, or E8p5_slice_012 yield numeric sequences 03, 5, and 8, 5, 12, respectively. With the default setting, these would be interpreted as slice numbers 3, 5, and 12. If a different numeric component should define slice order, users can specify the appropriate index via the array_id_num_pos parameter.

These column name and parsing behaviors can be customized via the parameters tissue_id, array_id, pos_id, gene_name_id and pos_reg_id. Example of unregistered datasets [14] are available from Figshare ( https://figshare.com/s/9c73df7fd39e3ca5422d).

Output formats: The workflow produces registered .h5ad files containing 3D coordinates and interpolation layers, .sc3d objects used by sc3D-viewer, and optional .h5ad files representing extracted slices or downsampled datasets. The napari-sc3D-viewer plugin (installed via pip install napari-sc3D-viewer) loads these files for interactive exploration.

Hardware requirements and alternatives

sc3D is fully CPU-based and does not require GPU acceleration. For large datasets (for example, on the order of ~500,000 beads), ≥16 GB of RAM is recommended to perform registration and interpolation without downsampling; however, smaller memory configurations can still be used by downsampling the dataset or by limiting interpolation and visualization steps. While this protocol was tested on a local workstation (macOS system, 10-core CPU, 32 GB RAM), sc3D relies exclusively on standard Python scientific libraries and can be executed without modification on cloud or high-memory compute nodes. Detailed tested hardware and software specifications are provided in the reproducibility note.

Procedure