Map Bulk Phenotype to Spatial Transcriptomics via Interpretable Modeling

Perform interpretable phenotype projection from bulk transcriptomic phenotypes to spatial transcriptomics data using elastic net modeling and SHAP-based spatial mapping.

Usage

SpatialPhenoMap(
  bulk_decon,
  bulk_pheno,
  family = c("cox", "binomial", "gaussian"),
  coord,
  resolution = "spot",
  sample_information_decon = NULL,
  sample_information_cellType = NULL,
  k = 50,
  r = 2,
  p = 0,
  size = 1,
  n_perm = 10,
  seed = 2025,
  nfolds = 10
)

Arguments

bulk_decon

A matrix or data.frame with bulk samples (rows) and cell type proportions (columns), typically from deconvolution.

bulk_pheno

A named vector of bulk phenotypes. Can be binary labels (e.g., 0/1), survival time, or continuous traits. Names must match rownames(bulk_decon).

family

Modeling family. One of "cox" (survival), "binomial" (classification), or "gaussian" (regression).

coord

A named list of spatial coordinate matrices for each spatial sample (data.frame with x, y).

resolution

Spatial resolution. One of "spot" (e.g., 10x Visium) or "single_cell" (e.g., MERFISH, CosMx).

sample_information_decon

A list of spot-level cell type proportions (only used if resolution = "spot"). Each entry is a data.frame with rows as spots and columns as cell types.

sample_information_cellType

A list of single-cell annotations (only used if resolution = "single_cell"). Each entry is a character vector of cell types.

k

Number of spatial neighbors to consider for KNN-based feature construction. Default is 50.

r

Number of spatial shells/layers for context expansion. Default is 2.

p

SHAP value threshold for phenotype labeling and significance testing. Default is 0.

size

Point size used in visualization plots. Default is 1.

n_perm

Number of permutations for significance estimation. Default is 10.

seed

Random seed for reproducibility. Default is 2025.

nfolds

Number of cross-validation folds for elastic net modeling. Default is 10.

Value

A list containing:

pred_score

A data.frame of prediction scores and assigned phenotype labels.

cell_type_distribution

Feature matrix used for prediction.

model

Trained elastic net model object.

Author

Bin Duan

Examples

if (FALSE) { # \dontrun{

data("osmFISH_metadata_cellType")
data("osmFISH_bulk_decon")
data("osmFISH_bulk_pheno")
data("osmFISH_bulk_coordinate")

result <- SpatialPhenoMap(
  bulk_decon = osmFISH_bulk_decon,
  bulk_pheno = osmFISH_bulk_pheno,
  family = "binomial",
  coord = osmFISH_bulk_coordinate,
  resolution = "single_cell",
  sample_information_cellType = osmFISH_metadata_cellType
)
} # }