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.

The published PANORAMIC paper describes the default workflow as edge-corrected neighborhood enrichment combined with spatial bootstrap uncertainty estimation and multilevel random-effects meta-analysis (Chang et al., Bioinformatics 42(8): btag546, https://doi.org/10.1093/bioinformatics/btag546).

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:

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

Installation

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

Load packages

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

Workflow At A Glance

Step	Function	Primary output	Why it matters
1	`panoramic_prepare()`	list of prepared `SpatialExperiment`s 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

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")

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"

Step 2: Compute Sample-Level Spatial Effects

The default PANORAMIC statistic is stat = "local_comp_enrichment", which reports edge-corrected neighborhood enrichment on a percentage-point scale relative to a sample-specific null expectation.

For tissue with strong large-scale density variation, an alternative is stat = "local_comp_global_enrichment". It compares local composition with the sample-wide target proportion, corresponding to a random-label null that conditions on the observed cell locations. This can be useful when the scientific question is label mixing within an observed tissue architecture; it should not be interpreted as correcting for spatially varying abundance or as evidence of a direct cell-cell interaction.

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

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"
)

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 14.286040 2.722301e-10 6.125178e-10
#> 2   B   A        25 16.534666 1.912825e-63 1.721542e-62
#> 3   C   A        25  6.785227 2.683109e-04 4.024663e-04
#> 4   A   B        25 15.518254 4.122003e-56 1.854902e-55
#> 5   B   B        25 15.159002 4.826270e-14 1.447881e-13
#> 6   C   B        25  1.975333 2.034912e-01 2.034912e-01
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 14.286040 2.2626618  6.313820 2.722301e-10 6.125178e-10
#> 2   B   A        25 16.534666 0.9833609 16.814443 1.912825e-63 1.721542e-62
#> 3   C   A        25  6.785227 1.8619672  3.644117 2.683109e-04 4.024663e-04
#> 4   A   B        25 15.518254 0.9832724 15.782254 4.122003e-56 1.854902e-55
#> 5   B   B        25 15.159002 2.0114023  7.536534 4.826270e-14 1.447881e-13
#> 6   A   C        25  3.599877 1.0709310  3.361447 7.753537e-04 9.968833e-04
#> 7   C   C        25  3.275934 0.8273925  3.959347 7.515482e-05 1.352787e-04
#>   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            C            A          C -> A
#> 7            C            C          C -> C

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"

Visualization Tools

Forest Plot (Feature-Level)

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

Volcano Plot (Global Differential Overview)

plot_volcano(se_meta)

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"
)

Practical Notes

Start with local_comp_enrichment unless you have a specific reason to use the global-composition or 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.

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.

For methodological details and biological applications in colorectal cancer and head and neck squamous cell carcinoma tissue microarrays, see the published PANORAMIC paper:

Chang J, Espin Perez A, Molina P, Khurana R, Zhang W, Tian L, Plevritis SK. Multi-sample and multi-group spatial colocalization analysis using PANORAMIC. Bioinformatics. 2026;42(8):btag546. https://doi.org/10.1093/bioinformatics/btag546

sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 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.32.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] ggplot2_4.0.3               dplyr_1.2.1                
#>  [3] BiocParallel_1.47.0         SummarizedExperiment_1.43.0
#>  [5] Biobase_2.73.2              GenomicRanges_1.65.4       
#>  [7] Seqinfo_1.3.2               IRanges_2.47.5             
#>  [9] S4Vectors_0.51.10           BiocGenerics_0.59.12       
#> [11] generics_0.1.4              MatrixGenerics_1.25.0      
#> [13] matrixStats_1.5.0           panoramic_0.99.4           
#> 
#> 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.2                   
#>  [7] ggraph_2.2.2                fastmap_1.2.0              
#>  [9] SingleCellExperiment_1.35.2 spatstat.geom_3.8-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.1              rlang_1.3.0                
#> [19] sass_0.4.10                 tools_4.6.1                
#> [21] igraph_2.3.3                yaml_2.3.12                
#> [23] knitr_1.52                  graphlayouts_1.2.5         
#> [25] S4Arrays_1.13.1             labeling_0.4.3             
#> [27] curl_8.0.0                  DelayedArray_0.39.7        
#> [29] RColorBrewer_1.1-3          abind_1.4-8                
#> [31] withr_3.0.3                 purrr_1.2.2                
#> [33] numDeriv_2016.8-1.1         sys_3.4.3                  
#> [35] grid_4.6.1                  polyclip_1.10-7            
#> [37] scales_1.4.0                MASS_7.3-66                
#> [39] spatstat.utils_3.2-5        cli_3.6.6                  
#> [41] rmarkdown_2.32              metafor_5.2-1              
#> [43] otel_0.2.0                  rjson_0.2.23               
#> [45] cachem_1.1.0                ggforce_0.5.0              
#> [47] metadat_1.6-0               parallel_4.6.1             
#> [49] BiocManager_1.30.27         XVector_0.53.0             
#> [51] vctrs_0.7.3                 V8_8.2.0                   
#> [53] Matrix_1.7-6                jsonlite_2.0.0             
#> [55] ggrepel_0.9.8               maketools_1.3.2            
#> [57] magick_2.9.1                spatstat.univar_3.2-0      
#> [59] jquerylib_0.1.4             tidyr_1.3.2                
#> [61] glue_1.8.1                  codetools_0.2-20           
#> [63] gtable_0.3.6                deldir_2.0-4               
#> [65] tibble_3.3.1                pillar_1.11.1              
#> [67] htmltools_0.5.9             R6_2.6.1                   
#> [69] tidygraph_1.3.1             evaluate_1.0.5             
#> [71] lattice_0.23-1              SpatialExperiment_1.23.0   
#> [73] BiocStyle_2.41.0            memoise_2.0.1              
#> [75] bslib_0.12.0                Rcpp_1.1.2                 
#> [77] gridExtra_2.3.1             SparseArray_1.13.3         
#> [79] nlme_3.1-171                xfun_0.61                  
#> [81] buildtools_1.0.0            pkgconfig_2.0.3

PANORAMIC tutorial