SPACEc: a streamlined, interactive Python workflow for multiplexed image processing and analysis

Abstract

Multiplexed imaging has transformed our ability to study tissue organization by capturing thousands of cells and molecules in their native context. However, these datasets are enormous, often comprising tens of gigabytes per image, and require complex workflows that limit their broader use. Current tools are often fragmented, inefficient, and difficult to adopt across disciplines. Here we show that SPACEc, a scalable Python platform, streamlines spatial imaging analysis from start to finish. The platform integrates image processing, cell segmentation, and data preprocessing into a single workflow, while improving computational performance through parallelization and GPU acceleration. We introduce innovative methods, including patch proximity analysis, to more accurately map local cellular neighborhoods and interactions. SPACEc also simplifies advanced approaches such as deep-learning annotation, making them accessible through an intuitive interface. By combining efficiency, accuracy, and usability, this platform enables researchers from diverse backgrounds to gain deeper insights into tissue architecture and cellular microenvironments.

SPACEc offers a user-friendly, expert-curated workflow for multiplexed image analysis, enabling researchers to easily perform advanced spatial biology studies and streamline the path from experiment to discovery.

Introduction

Multiplexed imaging allows simultaneous measurement of dozens to thousands of molecular markers (RNA, protein, or metabolome) within single cells with high-resolution spatial positioning^1–4. Technologies such as co-detection by indexing (CODEX), multiplexed ion beam imaging (MIBI), and others that employ multiplexed antibody detection^5–11 provide highly detailed spatial data thanks to the standardization of reagents and procedures^12–15. These collections of detailed spatial data^16–21 have revealed spatial relationships between cells, furthering our understanding of disease states^22,23, tissue organization¹⁵, and cancer progression^24,25. The ability to interpret such relationships hinges on having access to a powerful, yet user-friendly analytical framework. However, many existing codebases for advanced multiplexed image analytics pose substantial challenges, particularly for inexperienced users.

Firstly, one of the major challenges to user-friendly analysis arises from the need to switch between multiple tools and programming languages, which complicates workflows and slows progress. Most existing frameworks focus on either preprocessing (e.g., Steinbock) or specific aspects of spatial data analysis (e.g., Spectre, SPIAT, Giotto, imcRtools)^26–29, leaving gaps in functionality for downstream analyses (Supplementary Tables 1 and 2). Secondly, while a few platforms, such as MCMICRO, offer integrated solutions, they often rely on less common programming languages like NextFlow, which can be a barrier for users with limited computational expertise. Furthermore, while some spatial-omics tools support both sequencing- and imaging-based approaches, advanced spatial analyses beyond neighborhood identification, such as ligand-receptor interaction analysis, are not well-suited for multiplexed spatial proteomic data and often struggle to handle large datasets effectively³⁰.

To address these challenges, we designed the Structured Spatial Analysis for Codex Exploration (SPACEc) framework to enable researchers to unlock the full potential of these multiplexed imaging data using an interactive Python-based analysis pipeline. SPACEc performs image extraction, cell segmentation, single-cell data preprocessing and normalization, interactive quality inspection and annotation, and single-cell spatial analysis. Building on these innovative and re-engineered analytics, SPACEc integrates essential preprocessing steps into a seamless, end-to-end framework. For this, SPACEc includes all essential processing steps (Fig. 1): tissue extraction, cell segmentation, and visualization, data preprocessing and normalization, cell-type annotation, interactive data inspection and exploration, and spatial analysis^20,22,31,32. SPACEc supports standard data formats (e.g., AnnData) and can be used as an end-to-end or fully modular workflow.

Fig. 1. The SPACEc workflow.

A Data for individual tissue images are extracted from the qptiff file into separate tif files. B Image segmentation is performed on individual tif files. C The data frame containing segmented data with quantified marker intensities is filtered, normalized, and saved as an Anndata object. D Each cell in the processed AnnData object is annotated through either unsupervised clustering or machine-learning-based label transfer. E The annotation results are inspected and annotated interactively using TissUUmaps⁴¹. F Spatial analysis, including CN analysis, spatial context mapping, CN interface analysis, patch proximity analysis, and cell-cell interaction analysis, is performed. Results are stored within the AnnData object. The pipeline can be customized to integrate with other tools.

Tissue extraction and cell segmentation encompass the identification of underlying cellular biology within terabytes of raw imaging data (Fig. 1A, B). For this, SPACEc includes two well-known cell segmentation algorithms, Mesmer³³ and Cellpose³⁴, as well as quality assurance measures with visual feedback to ensure data accuracy. Once single-cell data is segmented and labeled, established standardized processes for normalization are employed (Fig. 1C)³⁵. The SPACEc toolkit also includes clustering options, including Leiden, Louvain, and FlowSOM, for identifying different groups of cell types^36–38 (Fig. 1D). SPACEc offers solutions for accelerating cell-type annotation on large datasets by leveraging GPU-accelerated unsupervised clustering and supervised machine learning (ML) techniques. As such, the computational pipeline can efficiently process large image sizes (ranging from 8 to 40 gigabytes per image). Among the ML methods included for cell type annotations are support vector machines (SVM)³⁹ and STELLAR⁴⁰, a geometric deep learning approach.

For interactive visualization and cell-type label inspection, SPACEc employs TissUUmaps⁴¹, a browser-based, GPU-accelerated tool (Fig. 1E). SPACEc offers five advanced spatial analysis algorithms (Fig. 1F); detailed documentation for these analyses can be found in the Supplementary Note 1. Although SPACEc was designed with CODEX data in mind, the workflow can also easily be used to analyze data from platforms such as MIBI and IMC, allowing for the modular introduction of other analysis approaches (as demonstrated in the online notebooks). SPACEc’s modular design enables future integration with emerging tools such as CellSighter⁴² for deep learning-based cell classification, CellGate⁴³ for unified segmentation and annotation, and Nimbus⁴⁴ for automated staining prediction, allowing users to tailor the pipeline to evolving analytical needs.

SPACEc can be used on CPU and GPUs alike for further speedups. SPACEc operates on Linux, Mac OS, and Windows environments. We also provide Docker files to simplify the building of custom containers. A comprehensive step-by-step guide for installing and using SPACEc is provided on GitHub (https://github.com/nolanlab/SPACEc).

Results

The SPACEc framework

SPACEc pioneers an innovative analytical framework that accelerates and integrates analysis processes and introduces spatial analytics, advancing the field on both fronts. We introduce an innovative high-throughput patch proximity analysis to analyze the cellular microenvironment surrounding structures of interest (e.g., tumor margins, vasculature, and immune niches). Patch proximity analysis shifts the focus from examining the composition of individual tissue units to exploring the environmental differences radiating outward from these units. Previous attempts on patch analysis focused only on single regions (SPIAT) or local accumulations in spatial graphs (imcRtools). Although our analysis follows a similar concept, we innovated an implementation, that is new to the best of our knowledge, to detect patches in all regions of the dataset through spatial, noise-sensitive clustering of assigned labels, allowing for precise identification of individual patches and individual surrounding niches across regions and conditions. This analysis is CPU parallelized and can be performed on high-complexity datasets with high throughput (Supplementary Note 2).

To allow direct interactive adjustment of the clustering without additional coding, we also developed a innovative interactive clustering module with a graphical user interface (GUI) directly embedded into our workflow. The GUI allows users to directly change clustering parameters, such as the resolution of the clustering, without any coding. It is one of the first pipelines incorporating the interactive framework to execute iterative clustering strategies for cell-type assignments. For additional interactive analyses, SPACEc uses TissUUmaps to visualize up to 10⁷ data points simultaneously; general-purpose viewers like Napari, matplotlib, BigDataViewer, and QuPath cannot visualize millions of data points simultaneously due to CPU and RAM constraints^41,45–48. TissUUmaps supports the sharing of visualizations, has HDF5 and anndata compatibility, and facilitates explorative analysis via either a web interface or a standalone application. SPACEc is compatible with existing analysis packages within the scverse ecosystem and can be employed to analyze data from recently developed frameworks for single-cell analysis^30,49–51.

SPACEc underscores the importance of engineered optimization, offering streamlined access to complex analyses while improving their performance, usability, and interpretability for users with limited experience. We have also provided 18 tutorial and example notebooks online to guide users on how to use SPACEc. Enabling end-to-end analysis within a single unified language, Python, simplifies workflows. As a first step, we reimplemented an R-programming language-based cell-cell interaction method²⁰ in Python and significantly improved its performance via parallelization. This approach allows for cell-cell interaction analysis in multiplexed images, even without the need for ligand-receptor pairs, while maintaining statistical power. It overcomes the limitations of a constrained feature parameter space that makes traditional transcriptome-based ligand-receptor analysis infeasible. We also introduced visualization techniques to support intuitively interpreting spatial patterns and relationships. Secondly, we enhanced STELLAR’s performance by replacing its original memory-intensive graph edge index generation with an innovative chunked preprocessing approach, greatly lowering the peak memory demand by 4.2 fold. Our implementation of STELLAR distills this process from a previously multi-step process into one single function. Additional innovative engineering features include the integration of TissUUmaps, a GPU-accelerated browser-based visualization, and a segmentation module that supports tissue extraction from tissue microarrays (TMA).

Application of SPACEc

To illustrate the utility of SPACEc, we processed CODEX Phenocycler datasets (two tissue sections) from healthy and inflamed tonsils. First, the pipeline extracted and labeled individual tonsil tissues from the TMA (Fig. 2A). Mesmer was used to segment the data, the resulting segmentation masks were visualized (Supplementary Fig. 1A), data were filtered and Z-normalized (Supplementary Fig. 1B), and then stored in an anndata format, all within SPACEc. Next, cell types were annotated with Leiden clustering and with cell-type-specific markers (Fig. 2B and Supplementary Fig. 2A). Interactive clustering can further assist with refining the clusters without additional coding (Supplementary Fig. 2B). The cell-type labels were then mapped back to their original spatial coordinates to verify the accuracy of cell-type labels in accordance with the known biology (Fig. 2B). The cell-type compositions can be visualized as a pie chart or stacked bar chart (Supplementary Fig. 2C–E). We also tested the accuracy of annotating cell types via SVM, leveraging annotated healthy tonsil data as training and unannotated inflamed tonsil as test data, and observed similar performance (Supplementary Fig. 2F). Finally, we used TissUUmaps⁴¹ to interactively inspect the labels and conduct preliminary analysis (Fig. 2D and Supplementary Fig. 3).

Fig. 2. An illustration of SPACEc’s workflow with tonsil Phenocycler data.

A In the example, two CODEX-imaged tissue cores were selected from a larger tissue microarray (tonsil and tonsillitis). The two tissues were detected, labeled, extracted, segmented, and visualized individually by SPACEc. A representative image is shown. B UMAP visualization of annotated cells. C Cells from healthy (left) and inflamed (right) tonsils are visualized on original tissue coordinates. Each dot represents a cell. D Region selection using the TissUUmaps Plot Histogram plug-in (top) enables the display of cell-type composition within that region as a histogram (bottom). A representative image is shown. E CNs from healthy (left) and inflamed (right) tonsil visualized on original tissue coordinates. Each dot represents a cell. F Spatial context maps of healthy (left) and inflamed (right) tonsil. Rows show the number of neighborhoods in combinations: row 1, a single neighborhood accounts for at least 85% of the neighborhoods surrounding the window; row 2, two neighborhoods make up more than 85% of the neighborhoods in the window; and row 3 and beyond, multiple neighborhoods are present in the window. G Barycentric plots of window combinations in healthy (left) and inflamed (right) tonsil. H Percentages of cell types that surround all patches in the germinal center CN in healthy (left) and inflamed (right) tonsil. I Cell-cell interactions in healthy (left) and inflamed (right) tonsils were visualized using distance network graphs. Blue edges indicate the cell-type distances that are further, and red edges indicate distances closer in healthy than in inflamed tonsil. The edge width is proportional to the fold change between the healthy and inflamed samples. Iterative shuffling for the expected distribution was run 1000 times.

To showcase the analytic capacity of SPACEc, we performed the advanced spatial analyses incorporated in the pipeline. Six cellular neighborhoods (CNs) were identified and annotated based on enriched cell types (Fig. 2E and Supplementary Fig. 4). The inflamed tonsil has more mature germinal centers than the healthy tonsil, in accordance with the colonization and proliferation of B cells following initial activation of antigen-specific B cells. To inspect higher-level tissue architectural differences, spatial context maps for each tissue were computed (Fig. 2F and Supplementary Fig. 5). Based on the hierarchical layout of the spatial context maps, we selected the interface between three CNs—the Marginal Zone, Germinal Center, and Marginal Zone enriched in B cells and dendritic cells—as an example to demonstrate the utility of the barycentric coordinate plot. These three CN patterns showed a distinguishable occurrence frequency. In a barycentric coordinate plot, we observed that the interface between the Germinal Center CN and the Marginal Zone Enriched in B Cells and Dendritic Cells CN was particularly pronounced in the inflamed tonsil (Fig. 2G and Supplementary Fig. 6), indicating a stronger intersection of CNs involved in immune cell priming and activation.

In addition to delineating the intrinsic tissue architecture, SPACEc can be used to inspect cell-cell and CN-CN interactions. For instance, the composition of cells surrounding a defined tissue structure, such as the germinal center CN, can be calculated. We projected concentric circles radiating in distances from 15 to 25 µm from the border cells and observed an enrichment of CD8⁺ T cells and CD4⁺ T cells surrounding the Germinal Center CN in the inflamed tonsil (Fig. 2H and Supplementary Fig. 7). Similarly, patch proximity analysis can be extended to analyze the CNs composition bordering each CN. Lastly, we looked at the changes in cell-cell interactions between the two conditions (Fig. 2I). To evaluate differences in cell-cell interactions between the two conditions, the distance between pairs of cell types within a threshold (i.e., 100 µm) is calculated, then cell-type labels are randomly permuted within each tissue section to simulate random chance conditions (Supplementary Fig. 8A). Germinal center B cells (GCB) are located closer to dendritic cells in inflamed tonsils compared to healthy tonsils, suggesting increased antigen presentation and enhanced B cell maturation during tonsillitis (Supplementary Fig. 8B, C).

Here, we demonstrate that SPACEc offers a comprehensive and structured Python-based workflow for the analysis of multiplexed images. The pipeline performs essential steps of tissue extraction, cell segmentation, and visualization, data preprocessing and normalization, as well as cell-type annotation. Furthermore, it enables interactive data inspection and spatial analysis with output in various formats. SPACEc incorporates a range of analytical tools to ensure a thorough and versatile analysis process while permitting the flexibility to extend new analyses. With detailed step-by-step instructions, users of all levels can implement the workflow, efficiently navigate spatial landscapes and extract valuable biological insights from highly multiplexed images.

Benchmarking of SPACEc

Finally, we benchmarked SPACEc against other open-source packages (Supplementary Table 1) in (1) run time, (2) accuracy (of machine-learning-based cell-type transfer), and (3) peak memory usage. Furthermore, we also showcased the robustness of SPACEc across different hardware platforms and operating systems. Detailed information is provided in Supplementary Note 2. In summary, SPACEc sets a benchmark in spatial image analysis by combining broad functionality with exceptional computational efficiency and accuracy. It not only offers the most comprehensive suite of features among all compared tools but also substantially outperforms existing methods, achieving up to 31 times faster run time (Supplementary Fig. 9). Engineering innovations, such as a fourfold acceleration in cell-cell interaction computation, make SPACEc uniquely suited for large-scale spatial studies (Supplementary Fig. 10). Its flexible machine-learning-based cell-type annotation consistently achieved the highest F1 score, precision, and recall across all four benchmarked datasets, underscoring its robustness and adaptability (Supplementary Fig. 11). We also demonstrated 1.3–20.8-fold lower peak memory usage across most downstream analyses (Supplementary Fig. 12). Critically, SPACEc delivers consistent, high-performance results across both Mac OS and high-performance Linux platforms, enabling seamless use on consumer hardware and effortless scaling to complex, large datasets (Supplementary Figs. 13 and 14). These advances position SPACEc as a transformative tool that can significantly accelerate discovery in spatial biology.

Methods

Tissue samples

The study was carried out in accordance with relevant guidelines and regulations. This study includes the use of human tissue samples. Usage of tissue samples was approved by the Ethik–Komission der Landesärztekammer Rheinland-Pfalz, No: 2020–14822. Informed consent was obtained from all patients and/or their legal guardians, as applicable. Tonsil cores were collected as part of a larger multi-tumor TMA study⁵². FFPE tissue blocks were retrieved from the tissue archives of the Institute of Pathology, University Medical Center Mainz, Germany, and the Department of Dermatology, University Medical Center Mainz, Germany. The multi-tumor-TMA block was sectioned at 3 µm thickness onto SuperFrost Plus microscopy slides before being processed for CODEX multiplex imaging as previously described¹³.

CODEX multiplexed imaging and processing

CODEX multiplexed imaging was executed according to the CODEX staining and imaging protocol¹³. CODEX imaging involves iteratively annealing and stripping of fluorophore-labeled oligonucleotide barcodes complementary to the barcodes attached to antibodies used to stain the tissue. Each antibody was conjugated to a unique oligonucleotide barcode, after which the tissues were stained with the antibody-oligonucleotide conjugates. The staining patterns were validated by immunohistochemical analysis within positive control tissues of a tumor or human tonsil. Antibody-oligonucleotide conjugates were first tested and titrated in low-plex fluorescence assays, and the signal-to-noise ratio was evaluated, then antibody-oligonucleotide conjugates were tested together in a single CODEX multicycle. The signal-to-noise ratio was again evaluated, and the optimal dilution, exposure time, and appropriate image cycle were determined for each conjugate. The tissue arrays were stained with the validated panels of CODEX antibodies and stored in the storage buffer until imaging.

Before running the CODEX machine, the slide was taken from the storage buffer and placed in PBS for 10 min to equilibrate. After drying the PBS with a tissue, a flow cell was sealed onto the tissue slide. The assembled slide and flow cell were then placed in a PhenoCycler Buffer made from 10× PhenoCycler Buffer & Additive for at least 10 min before starting the experiment. A 96-well reporter plate was prepared with each reporter corresponding to the correct barcoded antibody for each cycle, with up to 3 reporters per cycle per well. The fluorescence reporters were mixed with 1× PhenoCycler buffer, additive, nuclear-staining reagent, and assay reagent according to the manufacturer’s instructions. The automated multiplexed imaging experiment was initiated with the reporter plate, assembled slide, and flow cell placed into the CODEX machine. Each imaging cycle included steps for reporter binding, imaging of three fluorescent channels, and reporter stripping to prepare for the next cycle and set of markers. This was repeated until all markers were imaged. After the experiment, a.qptiff image file containing individual antibody channels and the DAPI channel was obtained. Image stitching, drift compensation, deconvolution, and cycle concatenation are performed within the Akoya PhenoCycler software. The raw imaging data output (tiff, 377.442 nm per pixel for 20× CODEX) is first examined with QuPath software (https://qupath.github.io/) for inspection of staining quality. Any markers that produce unexpected patterns or low signal-to-noise ratios should be excluded from the ensuing analysis. SPACEc accepts multichannel images or folders with named single-channel images as input. Markers with untenable patterns or low signal-to-noise ratios were excluded from further analysis.

Cell segmentation

SPACEc includes two segmentation methods: Deepcell/Mesmer³³ and Cellpose³⁴. If memory permits, we typically recommend segmenting the entire slide to avoid missing edge cells or generating duplicate cell counts. However, for larger images that exceed memory capacity, SPACEc also provides a tiling option to enable efficient segmentation in smaller, manageable sections. We use Mesmer as a stable default in this manuscript. Additionally, SPACEc supports Cellpose due to high performance and access to a wide variety of pre-trained models as part of its “model zoo”. Cellpose enables users to easily train and incorporate their own segmentation models into SPACEc. DeepCell-Mesmer: Mesmer is a deep learning-based cell segmentation algorithm built on the DeepCell framework. It uses a convolutional neural network trained on multiplexed imaging data to simultaneously perform nuclear and whole-cell segmentation. Mesmer employs a multitask learning approach, where the model predicts both nuclear and cytoplasmic boundaries using nuclear and membrane markers as input channels. The method is particularly effective on multiplexed tissue images and achieves high segmentation accuracy across diverse tissue types. Mesmer handles overlapping cells by leveraging multiplexed imaging data that includes both nuclear and membrane markers. Its pretrained model allows for robust, out-of-the-box performance without requiring user-specific retraining. Cellpose: Cellpose is a deep learning-based segmentation algorithm. It operates by predicting spatial vector fields (also called “flows”) that guide each pixel toward the center of the corresponding cell, along with a probability map indicating cell presence. These predicted flows are then used to reconstruct individual cell masks. Even in cases of overlap, these vector fields help assign pixels to the correct cell center by following the dominant flow direction. This mechanism allows Cellpose to segment touching or overlapping cells more accurately than traditional contour-based methods. Unlike task-specific models, Cellpose is trained on a large, heterogeneous dataset, enabling it to generalize well to unseen data without retraining. It supports both nuclear and cytoplasmic segmentation and provides an intuitive user interface and customizable parameters, making it accessible for broad biological applications. SPACEc uses the pre-trained multiplexed imaging model for Mesmer and allows access to the model zoo of Cellpose, which includes models applicable to both general and more specialized use cases. Additionally, SPACEc enables users to import their own Cellpose segmentation models and incorporate them into the pipeline. Users can input multiple channels for segmentation. Both the Mesmer and Cellpose methods require the nuclei channel as a minimum input and allow input of additional markers (for example, HLA-ABC for marking membranes). After segmentation, mean intensities are quantified for each channel in every mask. In this manuscript, we used Mesmer for the cell segmentation.

Normalization

For normalization, SPACEc supports Z-normalization, Log (double Z) normalization, Min-Max normalization, and Arcsihn normalization. Having appropriate normalization schematics is important for meaningful biological comparisons across datasets. Conventionally, Z-normalization is the most robust for CODEX data. However, for other platforms such as MIBI, CyTOF, and IMC, arcsinh normalization is more commonly used. Z Normalization: Individual marker intensities were Z-normalized for all cells within the dataset. This step aimed to standardize the range of each marker, considering variations in fluorescent intensities due to antibody staining strength and exposure times. Log (Double Z) Normalization: Initially, Z normalization was conducted on each marker intensity, followed by another Z normalization applied to each cell. These values were subsequently transformed into probabilities. Finally, a negative log transformation was applied to complement the probabilities. By equalizing signal intensities through the first Z normalization, a comparison of marker Z scores became feasible. Moreover, the second Z normalization helped identify positive markers with high probability among cells, which typically exhibit positivity for only a subset of the numerous markers recognized by antibodies. The negative log transformation of the complement of probability amplifies values with high probabilities, facilitating their utilization in clustering algorithms. Min_Max Normalization: Initially, the 1st and 99th percentiles were determined to set the minimum and maximum values, respectively, for each fluorescent channel. Subsequently, each value in the channel underwent normalization by calculating the difference between the minimum value and the range of values. Capping values at the 99th percentile assists in eliminating artificially high background fluorescent intensities often observed in imaging datasets. Arcsinh Normalization: This technique involved an arcsinh transformation on marker intensities, followed by scaling the resulting values with a user-adjustable cofactor (i.e., 150). Such normalization is suitable for datasets containing low or negative values resulting from background subtraction. In this study, we used Z-normalization as it is most appropriate for CODEX data.

Tonsil data preprocessing

For the tonsil datasets used in this study, we perform Z-score normalization for each CODEX image (sample) per marker. Each image is normalized separately based on its local distribution of marker expression; we subsequently combine these normalized datasets for clustering and cell-type identification. This strategy effectively balances preserving the local biological context with enabling integrated analysis across the entire dataset, which is essential for robust cellular phenotyping in multiplex tissue imaging³⁵. We did not observe a batch effect in this dataset, and therefore, we did not perform any batch correction.

Single-cell matrix preprocessing and cell clustering

In addition to proper normalization, SPACEc also facilitates the removal of artifacts in the data. Very small cells and cells with low DNA marker expression should be excluded from the analysis before z-score normalization and filtering of the cells as previously described³⁵. After pre-processing, the single-cell matrix cells are clustered using Leiden clustering, Louvain, or FlowSOM clustering. Leiden and FlowSOM have previously been validated and benchmarked specifically for cell clustering in multiplexed imaging^35,53. Even though prior literature has shown that Leiden clustering is an improved version of Louvain clustering³⁷, we decided to provide both options. Following cluster assignment generation, differential marker expression analysis combined with expert validation identifies uniquely enriched or differentially expressed markers within each cluster. While clustering is not a substitute for manual annotation, it serves as a complementary tool when combined with expert validation. These marker signatures, along with prior knowledge of cell-type-specific markers, enable users to assign cell-type identities to the clusters. In this manuscript, cells in the tonsil dataset were clustered with a resolution of 0.4 and 10 nearest neighbors. Subsequently, clusters are plotted in a heatmap and manually annotated by an expert based on the marker expression.

Machine-learning-based annotation of cell types

We typically recommend performing cell-type annotation across the entire slide for consistency. However, users also have the flexibility to define and annotate specific regions of interest, depending on their analytical needs. While supporting unsupervised clustering, SPACEc also includes additional methods, e.g., SVM for label transfer. The SVM and k-nearest neighbor classifier are implemented using the standard scikit-learn library. To train a new supervised ML model, users need a processed expression matrix (features × cells) along with corresponding ground truth cell type labels. With this input, users can choose between SVM or k-NN classifiers implemented within SPACEc. The framework also includes evaluation and visualization tools to assess model performance. Once a model meets the user’s performance criteria, it can be applied to new (also called “query”) expression matrices to predict cell type labels. The SVM determines a decision boundary that separates different types of cells based on input protein features. The trained SVM model can then be applied to a new dataset, which has the same or highly overlapping marker features, to transfer the cell-type labels. The k-NN classifier is a simple, non-parametric algorithm used for classification tasks. It assigns a label to a query point based on the majority label of its k closest neighbors in the feature space, using a distance metric such as Euclidean distance. Because it relies on the training data directly for predictions, it is considered a supervised learning method, requiring minimal training but potentially more computation during prediction. STELLAR is a deep learning-based algorithm for cell type annotation and new cell discovery in single-cell data. It uses a graph neural network to integrate known annotations from a training dataset and predict cell types in unannotated data, while also identifying previously unseen cell populations. SVMs and k-NN are implemented per default in SPACEc. However, it can be easily extended to any classifier implemented in scikit-learn. We choose SVMs to their capabilities to learn high-dimensional, non-linear decision boundaries. This can help to distinguish complex cell profiles, but the decision may be hard to interpret. k-NN, on the other hand, classifies cells based on the k most similar cells in the training data, potentially making less complex decisions but providing highly interpretable decisions.

Cellular neighborhood analysis

To compute for cellular neighborhood analysis²², users first select a window size (e.g. 20) of nearest neighbors. Within each window, we quantified the cells of each type, generating vectors representing cell counts. Subsequently, these vectors were subjected to clustering to identify commonly composed neighborhoods. SPACEc assists in a parameter search via an elbow plot so that users can identify the near-optimal number of CNs that provide unique insights into the spatial organization and heterogeneity of cell types within the tissue. Then, a heatmap is used to identify the cell types uniquely enriched in each neighborhood for annotations. Six CNs were selected based on the distinctness of their enriched cell types for the analysis within this manuscript.

Spatial context map

First, a large (e.g. 70) window size of nearest neighbors is selected to create the composition vectors. Within each window, SPACEc identifies the fewest neighborhoods that will make up more than 85 percent of the neighborhoods. This combination informs about prominent associations of neighborhoods in the window, a feature which is termed spatial context. Third, the combinations that pass the filtering criteria are counted and connected to a spatial context map. This hierarchical spatial context map shows different levels of neighborhood combinations and their relative frequencies³².

Cellular neighborhood interface analysis

If users need to zoom in on a specific interface between three CNs, SPACEc can create a barycentric coordinate system of the cells that fall into this interface³². To generate a barycentric coordinate projection, users first need to select three CNs. Thereafter, large windows were applied to every cell (window size of 70 nearest neighbors). Window composition was analyzed in terms of the percentage distribution of CNs. Windows containing less than the user-defined threshold of 90 percent or a user-defined percentage of the three selected neighborhoods were excluded from the analysis.

Patch proximity analysis

SPACEc introduces the patch proximity analysis module to analyze the composition of cells surrounding a biological structure, e.g., an individual CN. This analysis allows users to analyze the niches surrounding both larger structures, such as germinal centers, and fine structures, such as vessels, by adjusting the minimal number of cells per cluster. The patches are detected in spatial single-cell data by running HDBSCAN clustering⁵⁴ over all centroids in a user-defined region that belong to a previously specified CN. The resulting clusters are used as patches, and cells that are not part of a patch are ignored. The outline of the patch is captured by constructing a concave hull around it. To analyze the proximal cells, users can choose between two methods: “hull expansion” or “border cell radius.” Hull expansion is a simpler but faster method that works best on relatively regular structures (e.g. germinal centers). In this approach, the hull is simply expanded outward from the patch by a set of user-defined radii, and cells captured by the expansion are counted as proximal cells. The second method is slower but generally more precise and is recommended for structures with irregular shapes (e.g. vessels). The border cell radius method selects the outermost cells of each patch by identifying the spanning points of the concave hull. To ensure that the patch outline is sufficiently covered by the bordering cells, optionally, up to n (typically 3) nearest neighbors can be added to each edge cell, forming a surrounding group for each patch. Subsequently, the selected cells are used as anchor cells to span user-defined radii around each selected cell. Cells within the radius that do not belong to the patch are counted as cells within spatial proximity. In this example, we used SPACEc’s border cell radius method to examine the immediate environments surrounding germinal center patches within 15, 20, and 25 μm.

Cell-cell interaction analysis

SPACEc adopted an existing R programming-language-based distance permutation analysis²¹ into a parallelized Python function, which significantly accelerates the identification of spatial cell-cell interactions. The distances between each cell type pair are measured and compared against a permuted random distribution of cell types within the region. For this analysis, SPACEc uses Delaunay triangulation on x, y, and region information for computation and permutation. SPACEc also provides all the necessary filters and visualization functions, including a dumbbell plot to compare conditions, as well as a graph-based visualization for complex interactions. More specifically, the distances between cells connected by the edges of a Delaunay triangle in the two-dimensional space are calculated using the following formula: $Distance=\sqrt{{\left(x_1-x_2\right)}^2+{\left(y_1-y_2\right)}^2}$. Cell-to-cell interactions within a user-defined distance threshold (i.e., 265 pixels) are identified. To establish a reference distribution of distances, 1000 iterations of the distance calculation are computed. In each iteration, the cell labels within each region are randomly reassigned to existing x and y positions. The average distances of cell-cell interactions for each region in each permutation are calculated and compared to the observed distances using a Mann–Whitney U Test. The fold enrichment of distances between the observed data compared to the mean distances derived from the permutation test are determined. The log fold changes of distance for each pair of interactions for which p-values are less than 0.05 are plotted.

Statistics & reproducibility

Tumor samples from the TMA were excluded, and only the two tonsil samples were retained for demonstration purposes.

Hardware

All procedures were tested on multiple platforms to ensure wide compatibility. SPACEc is compatible with Mac (Intel, M1, M2, M3), Linux (Ubuntu), and Windows. The platforms were a workstation running Ubuntu 22.4 equipped with an AMD Threadripper 5955wx, 32 GB of RAM, and a Nvidia RTX A4500 GPU; an Intel MacBook Pro (i7 core) with 16 GB of RAM; a M1 MacBook Pro with 32 GB of RAM; a M3 MacBook Pro with 36GB RAM; and a Windows Server 2019 with an AMD Threadripper, 256 GB of RAM and dual RTX 3080.

Reporting summary

Further information on research design is available in the Nature Portfolio Reporting Summary linked to this article.

Author contributions

Y.T. and T.N.K. conceptualized the study. Y.T., T.N.K., M.B. and J.W.H. developed and implemented the algorithms. Analysis was performed by Y.T., T.N.K., M.B., J.W.H. and J.L. Experimental data and biological expertise were provided by M. Haist, D.F., Y.X., G.S., A.J.R., M.T., R.F. and M. Hölzel. The project was supervised by Y.T., G.P.N. and J.W.H.

Peer review

Peer review information

Nature Communications thanks Zhiyuan Yuan and the other, anonymous, reviewer(s) for their contribution to the peer review of this work. A peer review file is available.

Data availability

The raw and processed single-cell data generated in this study have been deposited in the Dryad database under 10.5061/dryad.brv15dvj1. The data are available under open access, and no restrictions apply. The raw data are publicly accessible, and the processed data are also available at Dryad. The data used in this study are provided in the Supplementary Information/Source Data file. A CODEX dataset of healthy and inflamed tonsils is used as an example to demonstrate the entire analytic workflow. The data were generated as part of a previous study using the PhenoCycler Fusion platform. Source data are provided with this paper.

Code availability

All software and code used to produce the findings of this study, including all main and supplemental figures, are available at https://github.com/nolanlab/SPACEc. The DOI for the SPACEc git repository is 10.5281/zenodo.17161689⁵⁵. We have also provided 18 tutorial and example notebooks online to guide users on how to use SPACEc https://spacec.readthedocs.io/en/latest/?badge=latest.

Competing interests

G.P.N. has equity in Akoya Biosciences, Inc. G.P.N. is a member of the scientific advisory board of Akoya Biosciences, Inc. M. Haist is a scientific advisory board member of CellFormatica Inc., outside of the submitted work. The remaining authors declare no competing interests.

Supplementary information

The online version contains supplementary material available at 10.1038/s41467-025-65658-3.