Author: Yuzhou Feng

# Spatial heterogeneity with SPIAT

    library(SPIAT)

Cell colocalisation metrics allow capturing a dominant spatial pattern in an image. However, patterns are unlikely to be distributed evenly in a tissue, but rather there will be spatial heterogeneity of patterns. To measure this, SPIAT splits the image into smaller images (either using a grid or concentric circles around a reference cell population), followed by calculation of a spatial metric of a pattern of interest (e.g. cell colocalisation, entropy), and then measures the Prevalence and Distinctiveness of the pattern.

In this vignette we will use an inForm data file that’s already been formatted for SPIAT with `format_image_to_spe()`, which we can load with `data()`. We will use `define_celltypes()` to define the cells with certain combinations of markers.

    data("simulated_image")

    # define cell types
    formatted_image <- define_celltypes(
        simulated_image,
        categories = c("Tumour_marker","Immune_marker1,Immune_marker2",
                       "Immune_marker1,Immune_marker3",
                       "Immune_marker1,Immune_marker2,Immune_marker4", "OTHER"),
        category_colname = "Phenotype",
        names = c("Tumour", "Immune1", "Immune2", "Immune3", "Others"),
        new_colname = "Cell.Type")

# Localised Entropy

Entropy in spatial analysis refers to the balance in the number of cells of distinct populations. An entropy score can be obtained for an entire image. However, the entropy of one image does not provide us spatial information of the image.

    calculate_entropy(formatted_image, cell_types_of_interest = c("Immune1","Immune2"),
                      feature_colname = "Cell.Type")

    ## [1] 0.9294873

We therefore propose the concept of Localised Entropy which calculates an entropy score for a predefined local region. These local regions can be calculated as defined in the next two sections.

## Fishnet grid

One approach to calculate localised metric is to split the image into fishnet grid squares. For each grid square, `grid_metrics()` calculates the metric for that square and visualise the raster image. Users can choose any metric as the localised metric. Here we use entropy as an example.

For cases where the localised metric is not symmetrical (requires specifying a target and reference cell type), the first item in the vector used for `cell_types_of_interest` marks the reference cells and the second item the target cells. Here we are using Entropy, which is symmetrical, so we can use any order of cell types in the input.

    data("defined_image")
    grid <- grid_metrics(defined_image, FUN = calculate_entropy, n_split = 20,
                         cell_types_of_interest=c("Tumour","Immune3"),
                         feature_colname = "Cell.Type")

After calculating the localised entropy for each of the grid squares, we can apply metrics like percentages of grid squares with patterns (Prevalence) and Moran’s I (Distinctiveness).

For the Prevalence, we need to select a threshold over which grid squares are considered ‘positive’ for the pattern. The selection of threshold depends on the pattern and metric the user chooses to find the localised pattern. Here we chose 0.75 for entropy because 0.75 is roughly the entropy of two cell types when their ratio is 1:5 or 5:1.

    calculate_percentage_of_grids(grid, threshold = 0.75, above = TRUE)

    ## [1] 13

    calculate_spatial_autocorrelation(grid, metric = "globalmoran")

    ## [1] 0.2197134

## Gradients (based on concentric circles)

We can use the `compute_gradient()` function to calculate metrics (entropy, mixing score, percentage of cells within radius, marker intensity) for a range of radii from reference cells. Here, an increasing circle is drawn around each cell of the reference cell type and the desired score is calculated for cells within each circle.

The first item in the vector used for `cell_types_of_interest` marks the reference cells and the second item the target cells. Here, Immune1 cells are reference cells and Immune2 are target cells.

    gradient_positions <- c(30, 50, 100)
    gradient_entropy <-
      compute_gradient(defined_image, radii = gradient_positions,
                       FUN = calculate_entropy,  cell_types_of_interest = c("Immune1","Immune2"),
                       feature_colname = "Cell.Type")
    length(gradient_entropy)

    ## [1] 3

    head(gradient_entropy[[1]])

    ##         Cell.X.Position Cell.Y.Position Immune1 Immune2 total Immune1_log2
    ## Cell_15       109.67027        17.12956       1       0     1            0
    ## Cell_25       153.22795       128.29915       1       0     1            0
    ## Cell_30        57.29037        49.88533       1       0     1            0
    ## Cell_48        83.47798       295.75058       2       0     2            1
    ## Cell_56        35.24227       242.84862       1       0     1            0
    ## Cell_61       156.39943       349.08154       2       0     2            1
    ##         Immune2_log2 total_log2 Immune1ratio Immune1_entropy Immune2ratio
    ## Cell_15            0          0            1               0            0
    ## Cell_25            0          0            1               0            0
    ## Cell_30            0          0            1               0            0
    ## Cell_48            0          1            1               0            0
    ## Cell_56            0          0            1               0            0
    ## Cell_61            0          1            1               0            0
    ##         Immune2_entropy entropy
    ## Cell_15               0       0
    ## Cell_25               0       0
    ## Cell_30               0       0
    ## Cell_48               0       0
    ## Cell_56               0       0
    ## Cell_61               0       0

The `compute_gradient()` function outputs the numbers cells within each radii for each reference cell. The output is formatted as a list of data.frames, one for each specified radii. In each data.frame, the rows show the reference cells. The last column of the data.frame is the entropy calculated for cells in the circle of the reference cell. Users can then an average score or another aggregation metric to report the results.

An alternative approach is to combine the results of all the circles (rather than have one for each individual reference cell). Here, for each radii, we simultaneously identify all the cells in the circles surrounding each reference cell, and calculate a single entropy score. We have created a specific function for this - `entropy_gradient_aggregated()`. The output of this function is an overall entropy score for each radii.

    gradient_pos <- seq(50, 500, 50) ##radii
    gradient_results <- entropy_gradient_aggregated(defined_image, cell_types_of_interest = c("Immune3","Tumour"),
                                                    feature_colname = "Cell.Type", radii = gradient_pos)
    # plot the results
    plot(1:10,gradient_results$gradient_df[1, 3:12])

# You can access the vignettes for other modules of SPIAT here:

- Overview of SPIAT
- Data reading and formatting
- Quality control and visualisation
- Basic analysis
- Cell colocalisation
- Tissue structure
- Cellular neighborhood

# Reproducibility

    sessionInfo()

    ## R version 4.6.0 (2026-04-24)
    ## Platform: x86_64-pc-linux-gnu
    ## Running under: Ubuntu 24.04.4 LTS
    ##
    ## Matrix products: default
    ## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    ## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    ##
    ## locale:
    ##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    ##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
    ##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    ##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    ##  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    ## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    ##
    ## time zone: Etc/UTC
    ## tzcode source: system (glibc)
    ##
    ## attached base packages:
    ## [1] stats4    stats     graphics  grDevices utils     datasets  methods
    ## [8] base
    ##
    ## other attached packages:
    ##  [1] SPIAT_1.14.0                SpatialExperiment_1.22.0
    ##  [3] SingleCellExperiment_1.34.0 SummarizedExperiment_1.42.0
    ##  [5] Biobase_2.72.0              GenomicRanges_1.64.0
    ##  [7] Seqinfo_1.2.0               IRanges_2.46.0
    ##  [9] S4Vectors_0.50.0            BiocGenerics_0.58.0
    ## [11] generics_0.1.4              MatrixGenerics_1.24.0
    ## [13] matrixStats_1.5.0           BiocStyle_2.40.0
    ##
    ## loaded via a namespace (and not attached):
    ##   [1] deldir_2.0-4           gridExtra_2.3          rlang_1.2.0
    ##   [4] magrittr_2.0.5         clue_0.3-68            GetoptLong_1.1.1
    ##   [7] otel_0.2.0             ggridges_0.5.7         compiler_4.6.0
    ##  [10] spatstat.geom_3.7-3    png_0.1-9              vctrs_0.7.3
    ##  [13] reshape2_1.4.5         stringr_1.6.0          shape_1.4.6.1
    ##  [16] pkgconfig_2.0.3        crayon_1.5.3           fastmap_1.2.0
    ##  [19] magick_2.9.1           XVector_0.52.0         labeling_0.4.3
    ##  [22] rmarkdown_2.31         tzdb_0.5.0             pracma_2.4.6
    ##  [25] purrr_1.2.2            bit_4.6.0              xfun_0.57
    ##  [28] cachem_1.1.0           jsonlite_2.0.0         goftest_1.2-3
    ##  [31] DelayedArray_0.38.1    spatstat.utils_3.2-2   terra_1.9-11
    ##  [34] cluster_2.1.8.2        parallel_4.6.0         R6_2.6.1
    ##  [37] bslib_0.10.0           stringi_1.8.7          RColorBrewer_1.1-3
    ##  [40] spatstat.data_3.1-9    spatstat.univar_3.1-7  jquerylib_0.1.4
    ##  [43] iterators_1.0.14       Rcpp_1.1.1-1.1         knitr_1.51
    ##  [46] tensor_1.5.1           Matrix_1.7-5           tidyselect_1.2.1
    ##  [49] abind_1.4-8            yaml_2.3.12            codetools_0.2-20
    ##  [52] doParallel_1.0.17      spatstat.random_3.4-5  spatstat.explore_3.8-0
    ##  [55] lattice_0.22-9         tibble_3.3.1           plyr_1.8.9
    ##  [58] withr_3.0.2            S7_0.2.2               Rtsne_0.17
    ##  [61] evaluate_1.0.5         polyclip_1.10-7        elsa_1.1-28
    ##  [64] circlize_0.4.18        pillar_1.11.1          BiocManager_1.30.27
    ##  [67] foreach_1.5.2          plotly_4.12.0          dbscan_1.2.4
    ##  [70] sp_2.2-1               vroom_1.7.1            ggplot2_4.0.3
    ##  [73] scales_1.4.0           gtools_3.9.5           apcluster_1.4.14
    ##  [76] glue_1.8.1             lazyeval_0.2.3         pheatmap_1.0.13
    ##  [79] maketools_1.3.2        tools_4.6.0            data.table_1.18.2.1
    ##  [82] sys_3.4.3              dittoSeq_1.24.0        RANN_2.6.2
    ##  [85] buildtools_1.0.0       cowplot_1.2.0          grid_4.6.0
    ##  [88] tidyr_1.3.2            crosstalk_1.2.2        colorspace_2.1-2
    ##  [91] nlme_3.1-169           raster_3.6-32          mmand_1.7.0
    ##  [94] cli_3.6.6              spatstat.sparse_3.1-0  S4Arrays_1.12.0
    ##  [97] viridisLite_0.4.3      ComplexHeatmap_2.28.0  dplyr_1.2.1
    ## [100] gtable_0.3.6           sass_0.4.10            digest_0.6.39
    ## [103] SparseArray_1.12.0     ggrepel_0.9.8          htmlwidgets_1.6.4
    ## [106] rjson_0.2.23           farver_2.1.2           htmltools_0.5.9
    ## [109] lifecycle_1.0.5        httr_1.4.8             GlobalOptions_0.1.4
    ## [112] bit64_4.8.0

# Author Contributions

AT, YF, TY, ML, JZ, VO, MD are authors of the package code. MD and YF wrote the vignette. AT, YF and TY designed the package.