Skip to contents

Run C-SIDE spatial differential expression

Source: R/RunCSIDE.R
RunCSIDE.Rd

Run spacexr C-SIDE after RCTD to test cell type-specific spatial or condition-aware differential expression. C-SIDE stores effect and significance results, not spot-level cell-type proportions, so it has no recommended proportion plot. Inspect its stored tables in srt@tools[[tool_name]] or plot an explicit summary column with SpatialSpotPlot().

Usage

RunCSIDE(
  srt,
  rctd_result = NULL,
  explanatory.variable = NULL,
  group.by = NULL,
  condition.by = NULL,
  design = NULL,
  region_list = NULL,
  barcodes = NULL,
  mode = c("auto", "single", "regions", "general", "intercept"),
  assay = NULL,
  layer = "counts",
  celltypes = NULL,
  features = NULL,
  prefix = "CSIDE",
  tool_name = "CSIDE",
  store_results = TRUE,
  verbose = TRUE,
  ...
)

Arguments

srt

Spatial Seurat object used as the RCTD query.

rctd_result

Optional old-api spacexr RCTD object. If NULL, srt@tools[["RCTD"]]$object from RunRCTD() is used.

explanatory.variable

Named numeric vector used by spacexr::run.CSIDE.single(). Names must match spatial spot names.

group.by

Metadata column used to build C-SIDE regions when region_list is not supplied.

condition.by

Binary metadata column converted to a 0/1 explanatory variable for spacexr::run.CSIDE.single().

design

Numeric design matrix used by spacexr::run.CSIDE(). Row names must match barcodes or spatial spot names.

region_list

Named list of barcode vectors used by spacexr::run.CSIDE.regions().

barcodes

Barcodes used by spacexr::run.CSIDE() or spacexr::run.CSIDE.intercept(). If NULL, row names of design or all spatial spots are used where applicable.

mode

C-SIDE mode. "auto" dispatches to "general", "regions", "single", or "intercept" based on the supplied design inputs.

assay

Assay used in srt. If NULL, the default assay is used.

layer

Assay layer used as the spatial expression source.

celltypes

Optional cell types passed to C-SIDE as cell_types.

features

Optional features retained in the normalized result table. C-SIDE itself still applies its own gene filtering through backend parameters such as gene_threshold.

prefix

Prefix for metadata columns.

tool_name

Name used to store detailed C-SIDE results in srt@tools.

store_results

Whether to store detailed RCTD results in srt@tools.

verbose

Whether to print the message. Default is TRUE.

...

Additional named parameters passed to the selected C-SIDE backend, such as cell_type_threshold, gene_threshold, doublet_mode, cell_type_specific, or params_to_test. When using the stored result from RunRCTD() with rctd_mode = "full", doublet_mode defaults to FALSE unless explicitly supplied.

Value

A Seurat object with C-SIDE summary metadata and detailed results stored in srt@tools[[tool_name]] when store_results = TRUE.

Examples

data(visium_human_pancreas_sub)
spatial <- visium_human_pancreas_sub
spatial$region <- cut(
  spatial$x,
  breaks = stats::quantile(spatial$x, probs = seq(0, 1, length.out = 4)),
  include.lowest = TRUE,
  labels = c("left", "middle", "right")
)
spatial$CSIDE_n_sig <- unname(
  c(left = 4, middle = 8, right = 12)[as.character(spatial$region)]
)
spatial$CSIDE_mode <- "regions"
cside_result <- data.frame(
  feature = rownames(spatial)[1:4],
  celltype = rep(c("ductal", "alpha"), each = 2),
  parameter = "right_vs_left",
  logFC = c(1.2, 0.8, -0.9, -1.1),
  statistic = c(4.1, 3.5, -3.2, -3.8),
  p_value = c(0.001, 0.004, 0.006, 0.002),
  q_value = c(0.004, 0.008, 0.010, 0.006),
  significant = TRUE,
  method = "regions"
)
spatial@tools$CSIDE <- list(
  result_table = cside_result,
  parameters = list(mode = "regions", group.by = "region")
)

SpatialSpotPlot(
  spatial,
  group.by = "CSIDE_n_sig",
  overlay_image = FALSE,
  coord.cols = c("x", "y")
)

SpatialSpotPlot(
  spatial,
  features = cside_result$feature[1:2],
  assay = "Spatial",
  layer = "counts",
  overlay_image = FALSE,
  coord.cols = c("x", "y")
)


data(panc8_sub)
set.seed(1234)
spatial <- spatial[, sample(seq_len(ncol(spatial)), 120)]
#> Warning: Not validating Centroids objects
#> Warning: Not validating Centroids objects
#> Warning: Not validating FOV objects
#> Warning: Not validating FOV objects
#> Warning: Not validating FOV objects
#> Warning: Not validating FOV objects
#> Warning: Not validating FOV objects
#> Warning: Not validating FOV objects
#> Warning: Not validating Seurat objects
reference <- panc8_sub[, panc8_sub$celltype %in% c("ductal", "alpha", "beta")]
reference <- Seurat::FindVariableFeatures(reference, nfeatures = 300, verbose = FALSE)
features_use <- intersect(
  SeuratObject::VariableFeatures(reference),
  rownames(spatial)
)
spatial <- RunRCTD(
  spatial,
  reference = reference,
  reference_label = "celltype",
  features = features_use,
  rctd_mode = "full",
  max_cores = 1,
  min_cells = 25,
  verbose = FALSE
)
#> Warning: Reference: some nUMI values are less than min_UMI = 100, and these cells will be removed. Optionally, you may lower the min_UMI parameter.
#> Begin: process_cell_type_info
#> process_cell_type_info: number of cells in reference: 694
#> process_cell_type_info: number of genes in reference: 97
#> 
#> ductal   beta  alpha 
#>    211    304    179 
#> End: process_cell_type_info
#> create.RCTD: getting regression differentially expressed genes: 
#> get_de_genes: ductal found DE genes: 24
#> get_de_genes: beta found DE genes: 7
#> get_de_genes: alpha found DE genes: 51
#> get_de_genes: total DE genes: 82
#> create.RCTD: getting platform effect normalization differentially expressed genes: 
#> get_de_genes: ductal found DE genes: 27
#> get_de_genes: beta found DE genes: 8
#> get_de_genes: alpha found DE genes: 55
#> get_de_genes: total DE genes: 90
#> fitBulk: decomposing bulk
#> chooseSigma: using initial Q_mat with sigma =  1
#> Likelihood value: 1190.26935943939
#> Sigma value:  0.84
#> Likelihood value: 1171.98624432823
#> Sigma value:  0.69
#> Likelihood value: 1160.45015220248
#> Sigma value:  0.61
#> Likelihood value: 1157.8207338082
#> Sigma value:  0.59
#> Likelihood value: 1157.67089523128
#> Sigma value:  0.59
spatial <- spatial[, rownames(spatial@tools$RCTD$weights)]
#> Warning: Not validating Centroids objects
#> Warning: Not validating Centroids objects
#> Warning: Not validating FOV objects
#> Warning: Not validating FOV objects
#> Warning: Not validating FOV objects
#> Warning: Not validating FOV objects
#> Warning: Not validating FOV objects
#> Warning: Not validating FOV objects
#> Warning: Not validating Seurat objects
spatial <- RunCSIDE(
  spatial,
  group.by = "region",
  celltypes = c("ductal", "alpha"),
  gene_threshold = 0.00005,
  cell_type_threshold = 5,
  verbose = FALSE
)
#> Warning: run.CSIDE.general: some parameters are set to the CSIDE vignette values, which are intended for testing but not proper execution. For more accurate results, consider using the default parameters to this function.
#> run.CSIDE.general: running CSIDE with cell types ductal, alpha
#> run.CSIDE.general: configure params_to_test = 1, 2, 3, 
#> filter_genes: filtering genes based on threshold = 5e-05
#> set_global_Q_all: begin
#> set_global_Q_all: finished
#> 1
#> 2
#> 3
#> 4
#> 5
#> 6
#> 7
#> 8
#> 9
#> 10
#> 11
#> 12
#> 13
#> 14
#> 15
#> 16
#> 17
#> 18
#> 19
#> 20
#> 21
#> 22
#> 23
#> 24
#> 25
#> 26
#> 27
#> 28
#> 29
#> 30
#> 31
#> 32
#> 33
#> 34
#> 35
#> 36
#> 37
#> 38
#> 39
#> 40
#> 41
#> 42
#> 43
#> 44
#> 45
#> 46
#> 47
#> 48
#> 49
#> 50
#> 51
#> 52
#> 53
#> 54
#> 55
#> 56
#> 57
#> 58
#> 59
#> 60
#> 61
#> 62
#> 63
#> 64
#> 65
#> 66
#> 67
#> 68
#> 69
#> 70
#> 71
#> 72
#> 73
#> 74
#> 75
#> 76
#> 77
#> 78
#> 79
#> 80
#> 81
#> 82
#> 83
#> 84
#> 85
#> 86
#> 87
#> 88
#> 89
#> 90
#> 91
#> 92
#> 93
#> 94
#> 95
#> 96
#> 97