PANORAMIC tutorial

Contents

1 Introduction

PANORAMIC is designed for multi-sample spatial colocalization analysis. It estimates sample-level spatial effects, then pools them with multilevel meta-analysis to test group-level differences.

Compared with single-sample analyses, PANORAMIC gives you:

• uncertainty-aware pooling across samples
• explicit between-sample / between-patient heterogeneity modeling
• direct two-group contrasts (beta_diff, p_diff, fdr_diff)
• consistent table and plotting utilities for downstream interpretation

This vignette focuses on practical usage:

1. Build a toy multi-sample dataset.
2. Run PANORAMIC stepwise (prepare -> spatial stats -> pooling).
3. Run the one-call workflow helper (panoramic_analyze()).
4. Interpret outputs and generate publication-style plots.

2 Installation

if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}
BiocManager::install("panoramic")

3 Load packages

library(panoramic)
library(SummarizedExperiment)
library(BiocParallel)
library(dplyr)
library(ggplot2)

4 Workflow At A Glance

Step	Function	Primary output	Why it matters
1	panoramic_prepare()	list of prepared SpatialExperiments with cached spatial objects	standardizes per-sample inputs
2	panoramic_spatialstats()	SummarizedExperiment with sample-level yi / vi	quantifies within-sample spatial effects
3	panoramic_meta_mv()	pooled multilevel results + differential contrasts	tests group-level biology
Convenience	panoramic_analyze()	list with prep, stats, pooled, tables	one-call reproducible pipeline

5 Simulate Example Data

We simulate two groups of samples with different spatial structure:

• group1: mostly random cell mixing
• group2: stronger local colocalization for early cell types

set.seed(123)
toy <- panoramic_simulate_dataset(
  n_group1 = 3,
  n_group2 = 3,
  n_cells_group1 = 200,
  n_cells_group2 = 350,
  group_labels = c("group1", "group2"),
  scenario_group1 = "random",
  scenario_group2 = "colocalized",
  seed = 123
)

spe_list <- toy$spe_list
design <- toy$design
design
#>     sample  group
#> 1 sample_1 group1
#> 2 sample_2 group1
#> 3 sample_3 group1
#> 4 sample_4 group2
#> 5 sample_5 group2
#> 6 sample_6 group2

Quick geometric sanity check:

plot_df <- do.call(rbind, lapply(spe_list, function(spe) {
  coords <- SpatialExperiment::spatialCoords(spe)
  data.frame(
    x = coords[, 1],
    y = coords[, 2],
    cell_type = SummarizedExperiment::colData(spe)$cell_type,
    sample_id = SummarizedExperiment::colData(spe)$sample_id,
    stringsAsFactors = FALSE
  )
}))

ggplot(plot_df, aes(x = x, y = y, color = cell_type)) +
  geom_point(size = 0.7, alpha = 0.7) +
  facet_wrap(~ sample_id, nrow = 2) +
  coord_equal() +
  theme_bw() +
  labs(x = "x", y = "y", color = "Cell type")

6 Step 1: Prepare Samples

prep <- panoramic_prepare(
  spe_list = spe_list,
  design = design,
  cell_type = "cell_type",
  min_cells = 5,
  window = "concave"
)
names(S4Vectors::metadata(prep[[1]])$panoramic)
#> [1] "sample_id"    "group_id"     "ppp"          "ppp_rescaled" "marks_tab"   
#> [6] "results"

7 Step 2: Compute Sample-Level Spatial Effects

Default PANORAMIC statistic is stat = "local_comp_enrichment" (percentage-point enrichment vs local null expectation).

radii_um <- c(25)

se <- panoramic_spatialstats(
  prep = prep,
  radii_um = radii_um,
  stat = "local_comp_enrichment",
  nsim = 30,
  seed = 123,
  BPPARAM = BiocParallel::SerialParam()
)
dim(se)
#> [1] 9 6
head(as.data.frame(rowData(se))[, c("ct1", "ct2", "radius_um", "stat")])
#>        ct1 ct2 radius_um                  stat
#> A|A|25   A   A        25 local_comp_enrichment
#> B|A|25   B   A        25 local_comp_enrichment
#> C|A|25   C   A        25 local_comp_enrichment
#> A|B|25   A   B        25 local_comp_enrichment
#> B|B|25   B   B        25 local_comp_enrichment
#> C|B|25   C   B        25 local_comp_enrichment

8 Step 3: Pool Across Samples And Test Group Differences

panoramic_meta_mv() pools sample-level effects and computes differential contrasts between groups.

# Here patient_col and sample_col are both "sample" in toy data.
# In real data, patient_col can differ from sample_col (e.g., multiple cores per patient).

se_meta <- panoramic_meta_mv(
  se,
  patient_col = "sample",
  group_col = "group",
  sample_col = "sample",
  tau_structure = "patient",
  method = "REML",
  group_tau2 = "separate"
)

9 Interpret Pooled And Differential Outputs

Each row in rowData(se_meta) is one feature (ct1, ct2, radius_um) with pooled effects and contrasts.

For differential terms:

• positive beta_diff: stronger spatial effect in group2 vs group1
• negative beta_diff: weaker spatial effect in group2
• small fdr_diff: stronger evidence after multiplicity correction

res <- panoramic_extract_contrast(se_meta)
head(res[, c("ct1", "ct2", "radius_um", "beta_diff", "p_diff", "fdr_diff")])
#>   ct1 ct2 radius_um beta_diff       p_diff     fdr_diff
#> 1   A   A        25 13.557679 9.276207e-08 1.043573e-07
#> 2   B   A        25 15.649632 6.122546e-38 1.836764e-37
#> 3   C   A        25  9.858781 9.285220e-09 1.193814e-08
#> 4   A   B        25 12.296240 1.572884e-25 3.538988e-25
#> 5   B   B        25 12.052931 1.720677e-10 2.581015e-10
#> 6   C   B        25  4.774375 4.457909e-05 4.457909e-05
res %>% dplyr::filter(fdr_diff < 0.05)
#>   ct1 ct2 radius_um  beta_diff   se_diff     z_diff       p_diff     fdr_diff
#> 1   A   A        25  13.557679 2.5387199   5.340360 9.276207e-08 1.043573e-07
#> 2   B   A        25  15.649632 1.2153857  12.876268 6.122546e-38 1.836764e-37
#> 3   C   A        25   9.858781 1.7165725   5.743294 9.285220e-09 1.193814e-08
#> 4   A   B        25  12.296240 1.1774314  10.443275 1.572884e-25 3.538988e-25
#> 5   B   B        25  12.052931 1.8878713   6.384403 1.720677e-10 2.581015e-10
#> 6   C   B        25   4.774375 1.1695110   4.082368 4.457909e-05 4.457909e-05
#> 7   A   C        25 -10.281512 0.7757830 -13.253076 4.330794e-40 1.948857e-39
#> 8   B   C        25 -12.744308 0.7577186 -16.819314 1.761880e-63 1.585692e-62
#> 9   C   C        25  -8.871954 0.9331915  -9.507109 1.960345e-21 3.528622e-21
#>   coloc_source coloc_target coloc_direction
#> 1            A            A          A -> A
#> 2            A            B          A -> B
#> 3            A            C          A -> C
#> 4            B            A          B -> A
#> 5            B            B          B -> B
#> 6            B            C          B -> C
#> 7            C            A          C -> A
#> 8            C            B          C -> B
#> 9            C            C          C -> C

10 One-Call Workflow (panoramic_analyze)

Use panoramic_analyze() when you want a single reproducible entry point for end-to-end runs.

out <- panoramic_analyze(
  spe_list = spe_list,
  design = design,
  cell_type = "cell_type",
  radii_um = radii_um,
  nsim = 20,
  min_cells = 5,
  window = "concave",
  BPPARAM = BiocParallel::SerialParam()
)
names(out)
#> [1] "prep"   "stats"  "pooled" "tables"
names(out$tables)
#> [1] "spatialstats" "meta"         "contrast"

11 Visualization Tools

11.1 Forest Plot (Feature-Level)

plot_forest(
  se_meta,
  ct1 = "A",
  ct2 = "B",
  radius_um = 25,
  group_col = "group"
)

11.2 Volcano Plot (Global Differential Overview)

plot_volcano(se_meta)

11.3 Network Summary

net <- create_spatial_network(
  se_meta,
  fdr_threshold = 0.2,
  directed = FALSE,
  leiden_resolution = 1.0
)
plot_spatial_network(
  se_meta,
  fdr_threshold = 0.2,
  directed = FALSE,
  layout = "fr",
  node_size_by = "degree"
)

12 Practical Notes

• Start with local_comp_enrichment unless you have a specific reason to use L/K-function alternatives.
• Use at least two biological samples per group for stable contrasts.
• Increase nsim for final analyses (the vignette uses modest values for speed).
• Keep sample metadata (sample, group, patient) explicit and consistent early in your workflow.

13 Related Resources

For complementary spatial analysis workflows, see:

• spatstat family (spatstat.geom, spatstat.explore) for point-process spatial statistics.
• SPIAT for spatial histology and tumor microenvironment analyses.
• imcRtools for imaging mass cytometry spatial workflows.
• spicyR for differential spatial localization testing in imaging data.

sessionInfo()
#> R version 4.6.0 RC (2026-04-17 r89917)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.4 LTS
#> 
#> Matrix products: default
#> BLAS:   /home/biocbuild/bbs-3.23-bioc/R/lib/libRblas.so 
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_GB              LC_COLLATE=C              
#>  [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: America/New_York
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats4    stats     graphics  grDevices utils     datasets  methods  
#> [8] base     
#> 
#> other attached packages:
#>  [1] ggplot2_4.0.2               dplyr_1.2.1                
#>  [3] BiocParallel_1.45.0         SummarizedExperiment_1.41.1
#>  [5] Biobase_2.71.0              GenomicRanges_1.63.2       
#>  [7] Seqinfo_1.1.0               IRanges_2.45.0             
#>  [9] S4Vectors_0.49.2            BiocGenerics_0.57.1        
#> [11] generics_0.1.4              MatrixGenerics_1.23.0      
#> [13] matrixStats_1.5.0           panoramic_0.99.3           
#> [15] BiocStyle_2.39.0           
#> 
#> loaded via a namespace (and not attached):
#>  [1] tidyselect_1.2.1            viridisLite_0.4.3          
#>  [3] concaveman_1.2.0            farver_2.1.2               
#>  [5] viridis_0.6.5               S7_0.2.1-1                 
#>  [7] ggraph_2.2.2                fastmap_1.2.0              
#>  [9] SingleCellExperiment_1.33.2 spatstat.geom_3.7-3        
#> [11] tweenr_2.0.3                mathjaxr_2.0-0             
#> [13] digest_0.6.39               lifecycle_1.0.5            
#> [15] spatstat.data_3.1-9         magrittr_2.0.5             
#> [17] compiler_4.6.0              rlang_1.2.0                
#> [19] sass_0.4.10                 tools_4.6.0                
#> [21] igraph_2.2.3                yaml_2.3.12                
#> [23] knitr_1.51                  graphlayouts_1.2.3         
#> [25] S4Arrays_1.11.1             labeling_0.4.3             
#> [27] curl_7.0.0                  DelayedArray_0.37.1        
#> [29] RColorBrewer_1.1-3          abind_1.4-8                
#> [31] purrr_1.2.2                 withr_3.0.2                
#> [33] numDeriv_2016.8-1.1         grid_4.6.0                 
#> [35] polyclip_1.10-7             MASS_7.3-65                
#> [37] scales_1.4.0                spatstat.utils_3.2-2       
#> [39] dichromat_2.0-0.1           tinytex_0.59               
#> [41] cli_3.6.6                   rmarkdown_2.31             
#> [43] metafor_4.8-0               otel_0.2.0                 
#> [45] rjson_0.2.23                ggforce_0.5.0              
#> [47] cachem_1.1.0                metadat_1.4-0              
#> [49] parallel_4.6.0              BiocManager_1.30.27        
#> [51] XVector_0.51.0              vctrs_0.7.3                
#> [53] V8_8.1.0                    Matrix_1.7-5               
#> [55] jsonlite_2.0.0              bookdown_0.46              
#> [57] ggrepel_0.9.8               magick_2.9.1               
#> [59] spatstat.univar_3.1-7       jquerylib_0.1.4            
#> [61] tidyr_1.3.2                 glue_1.8.1                 
#> [63] codetools_0.2-20            gtable_0.3.6               
#> [65] deldir_2.0-4                tibble_3.3.1               
#> [67] pillar_1.11.1               htmltools_0.5.9            
#> [69] R6_2.6.1                    tidygraph_1.3.1            
#> [71] evaluate_1.0.5              lattice_0.22-9             
#> [73] SpatialExperiment_1.21.0    memoise_2.0.1              
#> [75] bslib_0.10.0                Rcpp_1.1.1-1               
#> [77] gridExtra_2.3               SparseArray_1.11.13        
#> [79] nlme_3.1-169                xfun_0.57                  
#> [81] pkgconfig_2.0.3