Package 'SpaceMarkers'

Description

This function calculates interaction scores for a specific pattern pair using the .classify_spots function to determine the region of each spot.

Usage

.calc_IM_scores(
  data,
  pat_hotspots,
  influence_hotspots,
  patternpair,
  avoid_confounders = FALSE,
  ...
)

Arguments

Value

A data frame with interaction scores for the specified pattern pair.

Description

This function computes the threshold for identifying outlier values or hotspots by fitting a normal mixture model to the data.

Usage

.calc_threshold(df, minval = 0.01, maxval = 0.99, method = c("abs", "pct"))

Arguments

Value

A list containing the computed thresholds

Description

Internal function to run the directed SpaceMarkers analysis.

Usage

.directed_SpaceMarkers(
  features,
  data,
  genes = NULL,
  min.gene.expr = 10,
  resolution = c("fullres", "lowres", "hires"),
  version = NULL,
  h5filename = "filtered_feature_bc_matrix.h5",
  spatialDir = "spatial",
  pattern = "scalefactors_json.json",
  sigma = NULL,
  threshold = 4,
  ...
)

Arguments

Value

Interaction scores for the directed workflow.

Description

.find_genes_of_interest Identify genes associated with pattern interaction. This function identifies genes exhibiting significantly higher values of testMat in the Interaction region of the two patterns compared to regions with exclusive influence from either pattern. It uses Kruskal-Wallis test followed by posthoc analysis using Dunn's Test to identify the genes.

Usage

.find_genes_of_interest(testMat, goodGenes, region, fdr.level=0.05,
       analysis=c("enrichment","overlap"),...)

Arguments

Value

a list of genes exhibiting significantly higher values of testMat in the Interaction region of the two #' patterns compared to regions with exclusive influence from either pattern.

Description

The function picks the appropriate histology image file from the spatial directory based on the specified resolution.

Usage

.pick_image(sp_dir, res)

Arguments

Value

a character string of the image file name

Description

This function iterates over the rows of a matrix and performs a t-test comparing two groups of columns. It calculates the t-statistic, p-value, and sample sizes without relying on stats::t.test() for the core logic.

Usage

.row_t_test(in.data, region, min_bins = 50, ...)

Arguments

Value

A matrix with rows corresponding to the features and columns: - statistic: The calculated t-statistic. - p.value: The calculated two-sided p-value. - n1: Number of non-missing observations in group 1 for that row. - n2: Number of non-missing observations in group 2 for that row.

Description

Internal function to run the undirected SpaceMarkers analysis.

Usage

.undirected_SpaceMarkers(
  features,
  data,
  cpus = 1,
  genes = NULL,
  min.gene.expr = 10,
  resolution = c("fullres", "lowres", "hires"),
  version = NULL,
  h5filename = "filtered_feature_bc_matrix.h5",
  spatialDir = "spatial",
  pattern = "scalefactors_json.json",
  sigma = NULL,
  threshold = 4,
  ...
)

Arguments

Value

Interaction scores for the undirected workflow.

Description

Adds spatial features (patterns) to a SpaceMarkersExperiment object's colData after object initialization. When spots differ between the SME and the features, only the common spots are kept and a warning is emitted.

Usage

add_features(sme, features, ...)

Arguments

Value

The SpaceMarkersExperiment with features added to colData and pattern_names updated in the spacemarkers slot.

Examples

set.seed(1)
nb <- 20
sme <- SpaceMarkersExperiment(
    assays = list(logcounts = matrix(rpois(10 * nb, 2), 10, nb,
        dimnames = list(paste0("G", 1:10), paste0("s", seq_len(nb))))),
    spatialCoords = matrix(runif(2 * nb), nb, 2,
        dimnames = list(paste0("s", seq_len(nb)), c("y", "x"))))
feat <- data.frame(Pattern_1 = runif(nb), Pattern_2 = runif(nb),
                   row.names = paste0("s", seq_len(nb)))
sme <- add_features(sme, feat)
spatial_patterns(sme)[1:3, ]

Description

Read (analysis_type(x)) or write (analysis_type(x) <- value) the analysis-type tag stored in x@spacemarkers$analysis. Valid values are "undirected", "directed", or "both". The setter delegates validation to setValidity("SpaceMarkersExperiment", ...).

Usage

analysis_type(x, ...)

analysis_type(x) <- value

## S4 method for signature 'SpaceMarkersExperiment'
analysis_type(x)

## S4 replacement method for signature 'SpaceMarkersExperiment'
analysis_type(x) <- value

Arguments

Value

For the getter, a character string or NULL. For the setter, the modified SpaceMarkersExperiment.

A character string: "undirected", "directed", "both", or NULL.

Examples

sme <- SpaceMarkersExperiment(
    assays = list(logcounts = matrix(rpois(200, 2), 10, 20,
        dimnames = list(paste0("G", 1:10), paste0("s", 1:20)))),
    spatialCoords = matrix(runif(40), 20, 2,
        dimnames = list(NULL, c("y", "x"))))
analysis_type(sme) <- "undirected"
analysis_type(sme)

Description

AnnData-sourced objects (e.g. via zellkonverter::readH5AD() or anndataR::as_SingleCellExperiment()) typically arrive as SingleCellExperiment with spatial coordinates stored as a reducedDim, commonly named "spatial". This coerce method promotes that reducedDim into spatialCoords() and wraps the result as an SME, so a full AnnData -> SME path reads:

Details

sme <- as(zellkonverter::readH5AD(path), "SpaceMarkersExperiment")

If no suitable spatial reducedDim is found, the SME is built with empty spatialCoords; the caller can populate them afterwards.

Value

A SpaceMarkersExperiment carrying the same assays / colData / rowData as from, with the spatial reducedDim promoted to spatialCoords() when present.

Description

Coercion from SpatialExperiment to SpaceMarkersExperiment

Value

A SpaceMarkersExperiment wrapping from, with an empty spacemarkers slot ready to be populated by the pipeline.

Description

This function calculates interaction scores for all pattern pairs using the .calc_IM_scores function. It can run in parallel if BiocParallel is available.

Usage

calculate_gene_scores_directed(
  data,
  pat_hotspots = NULL,
  influence_hotspots = NULL,
  pattern_pairs = NULL,
  ...
)

## S4 method for signature 'SpaceMarkersExperiment'
calculate_gene_scores_directed(
  data,
  pat_hotspots = NULL,
  influence_hotspots = NULL,
  pattern_pairs = NULL,
  ...
)

## S4 method for signature 'ANY'
calculate_gene_scores_directed(
  data,
  pat_hotspots = NULL,
  influence_hotspots = NULL,
  pattern_pairs = NULL,
  ...
)

Arguments

Value

A data frame with interaction scores for all pattern pairs.

Examples

set.seed(1)
nb <- 30
spHotspots <- data.frame(
    barcode = paste0("s", seq_len(nb)),
    x = runif(nb), y = runif(nb),
    Pattern_1 = ifelse(seq_len(nb) <= 10, "Pattern_1", NA),
    Pattern_2 = ifelse(seq_len(nb) > 10 & seq_len(nb) <= 20,
                       "Pattern_2", NA),
    Pattern_3 = ifelse(seq_len(nb) > 20, "Pattern_3", NA))
spInfl <- spHotspots
counts <- matrix(rpois(5 * nb, 3), nrow = 5,
    dimnames = list(paste0("G", 1:5), spHotspots$barcode))
pattern_pairs <- t(utils::combn(c("Pattern_1","Pattern_2","Pattern_3"), 2))
calculate_gene_scores_directed(counts, spHotspots, spInfl,
                               pattern_pairs = pattern_pairs)

Description

Calculate the mean interaction score for a set of genes

Usage

calculate_gene_set_score(
  IMscores,
  gene_sets = NULL,
  weighted = TRUE,
  method = c("geometric_mean", "arithmetic_mean")
)

## S4 method for signature 'SpaceMarkersExperiment'
calculate_gene_set_score(
  IMscores,
  gene_sets = NULL,
  weighted = TRUE,
  method = c("geometric_mean", "arithmetic_mean")
)

## S4 method for signature 'ANY'
calculate_gene_set_score(
  IMscores,
  gene_sets = NULL,
  weighted = TRUE,
  method = c("geometric_mean", "arithmetic_mean")
)

Arguments

Details

This function computes mean interaction scores for given gene sets across cell interactions. It supports both geometric and arithmetic means, and can weight gene contributions based on their presence in multiple gene sets.

Value

A matrix of mean interaction scores for genes in each gene set, with attributes for log p-value sums and number of genes for later fisher combination

Examples

set.seed(1)
IMscores <- data.frame(
    gene = rep(paste0("G", 1:6), 2),
    effect_size = runif(12),
    p.value = runif(12),
    cell_interaction = rep(c("A_near_B", "B_near_A"), each = 6))
gene_sets <- list(set1 = c("G1","G2","G3"), set2 = c("G4","G5","G6"))
calculate_gene_set_score(IMscores, gene_sets = gene_sets,
                         method = "arithmetic_mean")

Description

This function computes specificity scores for given gene sets across cell types or spatial patterns. It uses fold-change scores and p-values to weight gene contributions, and supports both geometric and arithmetic means.

Usage

calculate_gene_set_specificity(
  data,
  spPatterns = NULL,
  gene_sets = NULL,
  weighted = TRUE,
  method = c("geometric_mean", "arithmetic_mean")
)

## S4 method for signature 'SpaceMarkersExperiment'
calculate_gene_set_specificity(
  data,
  spPatterns = NULL,
  gene_sets = NULL,
  weighted = TRUE,
  method = c("geometric_mean", "arithmetic_mean")
)

## S4 method for signature 'ANY'
calculate_gene_set_specificity(
  data,
  spPatterns = NULL,
  gene_sets = NULL,
  weighted = TRUE,
  method = c("geometric_mean", "arithmetic_mean")
)

Arguments

Details

Calculate Gene Set Specificity Scores

• Genes not present in the data are excluded.

• Genes with all zero expression are removed.

• Fold-change scores and p-values are calculated using .calculate_all_fc_scores.

• Scores are normalized and weighted by p-value significance.

• For each gene set, scores are aggregated using the specified method and gene weights.

Value

A numeric matrix of gene set specificity scores (gene sets x cell types).

Examples

set.seed(1)
nb <- 30
counts <- matrix(rpois(6 * nb, 3), nrow = 6,
    dimnames = list(paste0("G", 1:6), paste0("s", seq_len(nb))))
spPatterns <- data.frame(
    barcode = paste0("s", seq_len(nb)),
    x = runif(nb), y = runif(nb),
    A = runif(nb), B = runif(nb))
gene_sets <- list(set1 = c("G1","G2"), set2 = c("G4","G5"))
calculate_gene_set_specificity(counts, spPatterns, gene_sets,
                               method = "arithmetic_mean")

Description

This function computes the spatial influence of a specified pattern

Usage

calculate_influence(spPatterns, optParams = NULL, ...)

## S4 method for signature 'SpaceMarkersExperiment'
calculate_influence(spPatterns, optParams = NULL, ...)

## S4 method for signature 'data.frame'
calculate_influence(spPatterns, optParams = NULL, ...)

Arguments

Value

A data frame with the spatial influence of the specified pattern

Examples

set.seed(1)
spPatterns <- data.frame(
    barcode = paste0("s", 1:50),
    x = runif(50), y = runif(50),
    Pattern_1 = runif(50), Pattern_2 = runif(50))
optParams <- matrix(c(0.1, 4, 0.1, 4), nrow = 2,
    dimnames = list(c("sigmaOpt", "threshOpt"),
                    c("Pattern_1", "Pattern_2")))
inf <- calculate_influence(spPatterns, optParams)
head(inf)

Description

Calculate L-R pair scores using Fisher's method

Usage

calculate_lr_scores(
  ligand_scores,
  receptor_scores = NULL,
  lr_pairs = NULL,
  ligand_test = NULL,
  method = "geometric_mean",
  weighted = TRUE
)

## S4 method for signature 'SpaceMarkersExperiment'
calculate_lr_scores(
  ligand_scores,
  receptor_scores = NULL,
  lr_pairs = NULL,
  ligand_test = NULL,
  method = "geometric_mean",
  weighted = TRUE
)

## S4 method for signature 'ANY'
calculate_lr_scores(
  ligand_scores,
  receptor_scores = NULL,
  lr_pairs = NULL,
  ligand_test = NULL,
  method = "geometric_mean",
  weighted = TRUE
)

Arguments

Details

This function computes L-R pair scores by combining ligand and receptor overexpression scores using either geometric or arithmetic mean. It can also weight L-R pairs based on their presence in multiple pairs to reduce bias from promiscuous ligands or receptors.

Value

Data frame with L-R scores and p-values

Examples

set.seed(1)
lr_pairs <- data.frame(
    ligand          = c("L1", "L2"),
    receptor        = c("R1", "R2"),
    ligand.symbol   = c("L1", "L2"),
    receptor.symbol = c("R1", "R2"),
    row.names       = c("L1_R1", "L2_R2"))
ls <- matrix(runif(4), 2, 2,
             dimnames = list(rownames(lr_pairs),
                             c("A_near_B", "B_near_A")))
rs <- matrix(runif(4), 2, 2,
             dimnames = list(rownames(lr_pairs), c("A", "B")))
calculate_lr_scores(ls, rs, lr_pairs = lr_pairs,
                    method = "arithmetic_mean", weighted = FALSE)

Description

Calculate the overlap scores between patterns in hotspots

Usage

calculate_overlap_directed(
  pat_hotspots,
  influence_hotspots = NULL,
  patternList = NULL,
  method = c("relative-abundance", "differential-abundance", "absolute")
)

## S4 method for signature 'SpaceMarkersExperiment'
calculate_overlap_directed(
  pat_hotspots,
  influence_hotspots = NULL,
  patternList = NULL,
  method = c("relative-abundance", "differential-abundance", "absolute")
)

## S4 method for signature 'data.frame'
calculate_overlap_directed(
  pat_hotspots,
  influence_hotspots = NULL,
  patternList = NULL,
  method = c("relative-abundance", "differential-abundance", "absolute")
)

Arguments

Details

The function calculates the overlap scores between patterns hotspots using the specified method. The default method is "relative-abundance"

Value

A data frame with columns pattern, influence and overlapping abundance

Examples

hotspots <- data.frame(x = c(1,2,3,4,5),
                        y = c(1,2,3,4,5),
                        barcode = c("A","B","C","D","E"),
                        pattern1 = c(1,0,1,0,1),
                        pattern2 = c(1,1,0,0,1))
influence_hotspots <- data.frame(x = c(1,2,3,4,5),
                       y = c(1,2,3,4,5),
                      barcode = c("A","B","C","D","E"),
                      pattern1 = c(0,1,1,0,0),
                      pattern2 = c(0,1,0,1,1))
calculate_overlap_directed(pat_hotspots = hotspots, influence_hotspots = influence_hotspots)

Description

Calculate the overlap scores between patterns in hotspots

Usage

calculate_overlap_undirected(
  hotspots,
  patternList = NULL,
  method = c("Szymkiewicz-Simpson", "Jaccard", "Sorensen-Dice", "Ochiai", "absolute")
)

## S4 method for signature 'SpaceMarkersExperiment'
calculate_overlap_undirected(
  hotspots,
  patternList = NULL,
  method = c("Szymkiewicz-Simpson", "Jaccard", "Sorensen-Dice", "Ochiai", "absolute")
)

## S4 method for signature 'data.frame'
calculate_overlap_undirected(
  hotspots,
  patternList = NULL,
  method = c("Szymkiewicz-Simpson", "Jaccard", "Sorensen-Dice", "Ochiai", "absolute")
)

Arguments

Details

The function calculates the overlap scores between patterns hotspots using the specified method. The default method is "Szymkiewicz-Simpson" overlap coefficient.

Value

A data frame with columns pattern1, pattern2 and overlapScore

Examples

hotspots <- data.frame(x = c(1,2,3,4,5),
                        y = c(1,2,3,4,5),
                        barcode = c("A","B","C","D","E"),
                        pattern1 = c("pattern1",NA,"pattern1",NA,"pattern1"),
                        pattern2 = c("pattern2","pattern2",NA,NA,"pattern2"))
calculate_overlap_undirected(hotspots)
calculate_overlap_undirected(hotspots, c("pattern1","pattern2"))

Description

This function computes the thresholds for all columns in a data frame. The data frame could be an spPatterns object or an spInfluence object.

Usage

calculate_thresholds(df, minvals = 0.01, maxvals = 0.99, ...)

Arguments

Value

A list containing the computed thresholds for each pattern

Examples

set.seed(1)
spPatterns <- data.frame(
    barcode = paste0("s", 1:50),
    x = runif(50), y = runif(50),
    Pattern_1 = rnorm(50), Pattern_2 = rnorm(50))
calculate_thresholds(spPatterns)

Description

Take the three matrices produced by calculate_lr_scores + calculate_gene_set_score + calculate_gene_set_specificity and reshape them into a single long-format data frame keyed by interaction and source/target cell-type pair. Ligand and receptor gene names are pulled from lrpairs; multi-gene complexes are flattened with underscores.

Column names in ligand_scores that start with near_ are converted to to_ so they line up with the LR-score columns.

Missing LR scores are kept as NA (not coerced to 0). Callers choosing to plot zero-score interactions should filter or impute explicitly.

Usage

create_lr_dataframe(
  lrscores,
  ligand_scores,
  receptor_scores,
  lrpairs,
  complex_sep = ", "
)

Arguments

Value

A data frame with one row per interaction × source/target pair, containing:

source_cell_type

Source cell type.

ligand

Ligand gene(s), underscore-separated.

receptor

Receptor gene(s), underscore-separated.

target_cell_type

Target cell type.

ligand_score

From ligand_scores.

receptor_score

From receptor_scores.

score

LR score from lrscores.

interaction

Interaction ID (rowname of lrpairs).

source_to_target

Convenience paste0(source_cell_type, "_to_", target_cell_type).

Note

Cell-type names must not contain the substrings "_to_" or "_and_"; the function parses cell types out of column-name keys built from those separators.

Examples

lrpairs <- data.frame(
    ligand   = c("L1", "L2"),
    receptor = c("R1, R2", "R3"),
    row.names = c("L1_R1_R2", "L2_R3"))
lr <- matrix(c(0.4, 0.7, 0.1, NA),
             nrow = 2, dimnames = list(rownames(lrpairs),
                                       c("A_to_B", "B_to_A")))
lig <- matrix(c(0.5, 0.6, 0.2, 0.3),
              nrow = 2, dimnames = list(rownames(lrpairs),
                                        c("A_near_B", "B_near_A")))
rec <- matrix(c(0.7, 0.8, 0.9, 0.6),
              nrow = 2, dimnames = list(rownames(lrpairs),
                                        c("A", "B")))
create_lr_dataframe(lr, lig, rec, lrpairs)

Description

A vector with genes selected based on previous runs of SpaceMarkers on the Visium 10x breast ductal carcinoma spatial transcriptomics dataset

Format

A vector with 114 pre-selected genes

Value

a vector of genes

Description

Read (directed_scores(x)) or write (directed_scores(x) <- value) the data.frame of directed interaction scores stored in x@spacemarkers$results$directed_scores.

Usage

directed_scores(x, ...)

directed_scores(x) <- value

## S4 method for signature 'SpaceMarkersExperiment'
directed_scores(x)

## S4 replacement method for signature 'SpaceMarkersExperiment'
directed_scores(x) <- value

Arguments

Value

For the getter, a data.frame of directed scores or NULL. For the setter, the modified SpaceMarkersExperiment.

A data.frame of directed interaction scores, or NULL.

Examples

sme <- SpaceMarkersExperiment(
    assays = list(logcounts = matrix(rpois(200, 2), 10, 20,
        dimnames = list(paste0("G", 1:10), paste0("s", 1:20)))),
    spatialCoords = matrix(runif(40), 20, 2,
        dimnames = list(NULL, c("y", "x"))))
directed_scores(sme) <- data.frame(
    gene = paste0("G", 1:5),
    cell_interaction = "Pattern_1->Pattern_5",
    effect_size = runif(5))
head(directed_scores(sme))

Description

Convenience function to find hotspots for all spatial patterns

Usage

find_all_hotspots(
  spPatterns,
  params = NULL,
  outlier = "positive",
  nullSamples = 1000,
  includeSelf = TRUE,
  ...
)

## S4 method for signature 'SpaceMarkersExperiment'
find_all_hotspots(
  spPatterns,
  params = NULL,
  outlier = "positive",
  nullSamples = 1000,
  includeSelf = TRUE,
  ...
)

## S4 method for signature 'data.frame'
find_all_hotspots(
  spPatterns,
  params = NULL,
  outlier = "positive",
  nullSamples = 1000,
  includeSelf = TRUE,
  ...
)

Arguments

Value

A data.frame with one column per pattern containing the pattern name where the spot is a hotspot and NA otherwise, plus the original barcode/x/y columns.

Examples

set.seed(1)
spPatterns <- data.frame(
    barcode = paste0("s", 1:50),
    x = runif(50), y = runif(50),
    Pattern_1 = runif(50), Pattern_2 = runif(50))
hs <- find_all_hotspots(spPatterns, nullSamples = 50)
head(hs)

Description

Convenience function to find hotspots for all spatial patterns or influence dataframes based on provided thresholds

Usage

find_hotspots_gmm(df, threshold = 0.1, ...)

## S4 method for signature 'SpaceMarkersExperiment'
find_hotspots_gmm(
  df,
  threshold = 0.1,
  ...,
  type = c("pattern", "influence"),
  minvals = NULL,
  maxvals = NULL
)

## S4 method for signature 'data.frame'
find_hotspots_gmm(df, threshold = 0.1, ...)

Arguments

Value

a data frame with the same dimensions as the input data frame.

Examples

set.seed(1)
spPatterns <- data.frame(
    barcode = paste0("s", 1:50),
    x = runif(50), y = runif(50),
    Pattern_1 = rnorm(50), Pattern_2 = rnorm(50))
thr <- calculate_thresholds(spPatterns)
hs  <- find_hotspots_gmm(spPatterns, threshold = thr)
head(hs)

Description

This function calculates 'hotspots' which are regions of high spatial influence based on an outlier threshold from a null distribution.

Usage

find_pattern_hotspots(
  spPatterns,
  params = NULL,
  patternName = "Pattern_1",
  outlier = "positive",
  nullSamples = 1000,
  includeSelf = TRUE,
  ...
)

Arguments

Value

a character vector with the spatial feature name if the spatial influence exceeded the threshold for that spot/cell, and NA otherwise

See Also

Other getIntGenes: get_interacting_genes(), get_pairwise_interacting_genes()

Examples

library(SpaceMarkers)
#Visium data links
urls <- read.csv(system.file("extdata","visium_data.txt",
                           package="SpaceMarkers",mustWork = TRUE))
sp_url <- urls[["visium_url"]][2]
#Remove present Directories if any
unlink(basename(sp_url))
unlink("spatial", recursive = TRUE)
#Obtaining CoGAPS Patterns i.e Spatial Features
cogaps_result <- readRDS(system.file("extdata","CoGAPS_result.rds",
                                   package="SpaceMarkers",mustWork = TRUE))
spFeatures <- slot(cogaps_result,"sampleFactors")
#Obtaining Spatial Coordinates
download.file(sp_url, basename(sp_url), mode = "wb")
untar(basename(sp_url))
spCoords <- load10XCoords(visiumDir = ".", version = "1.0")
rownames(spCoords) <- spCoords$barcode
#Match Dimensions
barcodes <- intersect(rownames(spFeatures),spCoords$barcode)
spCoords <- spCoords[barcodes,]
spFeatures <- spFeatures[barcodes,]
spPatterns <- cbind(spCoords,spFeatures[barcodes,])
spPatterns<-spPatterns[c("barcode","y","x","Pattern_1","Pattern_5")]
data("optParams")
hotspots <- find_pattern_hotspots(
spPatterns = spPatterns,
patternName = "Pattern_1",
params = optParams[,"Pattern_1"],
outlier = "positive",nullSamples = 1000,includeSelf = TRUE)
#Remove present Directories if any
unlink(basename(sp_url))
unlink("spatial", recursive = TRUE)

Description

Get the interaction scores for SpaceMarkers

Usage

get_im_scores(SpaceMarkers)

## S4 method for signature 'SpaceMarkersExperiment'
get_im_scores(SpaceMarkers)

## S4 method for signature 'list'
get_im_scores(SpaceMarkers)

Arguments

Value

A data frame with columns Gene and SpaceMarkersMetric

Examples

# Minimal mock of the list shape get_pairwise_interacting_genes returns:
sm_result <- list(
    list(patterns = c("A","B"),
         interacting_genes = list(data.frame(
             Gene = paste0("G", 1:5),
             SpaceMarkersMetric = sort(runif(5), decreasing = TRUE)))),
    list(patterns = c("A","C"),
         interacting_genes = list(data.frame(
             Gene = paste0("G", 1:5),
             SpaceMarkersMetric = sort(runif(5), decreasing = TRUE)))))
get_im_scores(sm_result)

Description

This function calculates statistically significant genes using a non-parametric Kruskal-Wallis test for genes in any one region of influence and a post hoc Dunn's test is used for analysis of genes between regions.

Usage

get_interacting_genes(
  data,
  spPatterns,
  refPattern = "Pattern_1",
  mode = c("DE", "residual"),
  optParams = NULL,
  reconstruction = NULL,
  hotspots = NULL,
  analysis = c("enrichment", "overlap"),
  minOverlap = 50,
  ...
)

Arguments

Value

a list of data frames with information about the interacting genes of the refPattern and each latent feature pattern matrix (interacting_genes object). There is also a data frame with all of the regions of influence for any two of patterns (the hotspots object).

See Also

Other getIntGenes: find_pattern_hotspots(), get_pairwise_interacting_genes()

Examples

library(SpaceMarkers)
#Visium data links
urls <- read.csv(system.file("extdata","visium_data.txt",
package="SpaceMarkers",mustWork = TRUE))
counts_url <- urls[["visium_url"]][1]
sp_url <- urls[["visium_url"]][2]
#Remove present Directories if any
unlink(basename(sp_url))
unlink("spatial", recursive = TRUE)
files <- list.files(".")[grepl(basename(counts_url),list.files("."))]
unlink(files)
download.file(counts_url,basename(counts_url), mode = "wb")
counts_matrix<-load10XExpr(visiumDir=".",h5filename = basename(counts_url))
#Obtaining CoGAPS Patterns
cogaps_result <- readRDS(system.file("extdata","CoGAPS_result.rds",
package="SpaceMarkers",mustWork = TRUE))
features <- intersect(rownames(counts_matrix),rownames(
    slot(cogaps_result,"featureLoadings")))
barcodes <- intersect(colnames(counts_matrix),rownames(
    slot(cogaps_result,"sampleFactors")))
counts_matrix <- counts_matrix[features,barcodes]
cogaps_matrix <- slot(cogaps_result,"featureLoadings")[features,]%*%
    t(slot(cogaps_result,"sampleFactors")[barcodes,])
#Obtaining Spatial Coordinates
download.file(sp_url, basename(sp_url), mode = "wb")
untar(basename(sp_url))
spCoords <- load10XCoords(visiumDir = ".", version = "1.0")
rownames(spCoords) <- spCoords$barcode
spCoords <- spCoords[barcodes,]
spPatterns <- cbind(spCoords,slot(cogaps_result,
"sampleFactors")[barcodes,])
data("curated_genes")
spPatterns<-spPatterns[c("barcode","y","x","Pattern_1","Pattern_5")]
counts_matrix <- counts_matrix[curated_genes,]
cogaps_matrix <- cogaps_matrix[curated_genes, ]
data("optParams")
SpaceMarkersMode <- "DE"
ref_Pattern <- "Pattern_1"
SpaceMarkers_test <- get_interacting_genes(
    data=counts_matrix,reconstruction=NULL,
    optParams = optParams,
    spPatterns = spPatterns,
    refPattern = "Pattern_1",
    mode="DE",analysis="overlap")
#Remove present Directories if any
unlink(basename(sp_url))
unlink("spatial", recursive = TRUE)
files <- list.files(".")[grepl(basename(counts_url),list.files("."))]
unlink(files)

Description

Performs pairwise analysis to find genes associated with spatial interaction between pairs of spatially varying patterns.

Usage

get_pairwise_interacting_genes(
  data,
  spPatterns = NULL,
  mode = c("DE", "residual"),
  optParams = NULL,
  reconstruction = NULL,
  hotspots = NULL,
  minOverlap = 50,
  analysis = c("enrichment", "overlap"),
  pattern_pairs = NULL,
  ...,
  workers = NULL
)

## S4 method for signature 'SpaceMarkersExperiment'
get_pairwise_interacting_genes(
  data,
  spPatterns = NULL,
  mode = c("DE", "residual"),
  optParams = NULL,
  reconstruction = NULL,
  hotspots = NULL,
  minOverlap = 50,
  analysis = c("enrichment", "overlap"),
  pattern_pairs = NULL,
  ...,
  workers = NULL
)

## S4 method for signature 'ANY'
get_pairwise_interacting_genes(
  data,
  spPatterns,
  mode = c("DE", "residual"),
  optParams = NULL,
  reconstruction = NULL,
  hotspots = NULL,
  minOverlap = 50,
  analysis = c("enrichment", "overlap"),
  pattern_pairs = NULL,
  patternList = NULL,
  ...,
  workers = NULL
)

Arguments

Details

================

Value

a list of data frames for each pattern with 1) names of the patterns (patterns object) 2) data frame with the hotspots of influence for the two patterns (the hotspots object). 3) data frame with the genes associated with the interaction between the two patterns (interacting genes object, empty if insufficient interaction).

See Also

Other getIntGenes: find_pattern_hotspots(), get_interacting_genes()

Examples

library(SpaceMarkers)
#Visium data links
urls <- read.csv(system.file("extdata","visium_data.txt",
package="SpaceMarkers",mustWork = TRUE))
counts_url <- urls[["visium_url"]][1]
sp_url <- urls[["visium_url"]][2]
#Remove present Directories if any
unlink(basename(sp_url))
unlink("spatial", recursive = TRUE)
files <- list.files(".")[grepl(basename(counts_url),list.files("."))]
unlink(files)
download.file(counts_url,basename(counts_url), mode = "wb")
counts_matrix<-load10XExpr(visiumDir=".",
h5filename = basename(counts_url))
#Obtaining CoGAPS Patterns
cogaps_result <- readRDS(system.file("extdata","CoGAPS_result.rds",
package="SpaceMarkers",mustWork = TRUE))
features <- intersect(rownames(counts_matrix),rownames(
    slot(cogaps_result,"featureLoadings")))
barcodes <- intersect(colnames(counts_matrix),rownames(
    slot(cogaps_result,"sampleFactors")))
counts_matrix <- counts_matrix[features,barcodes]
cogaps_matrix <- slot(cogaps_result,"featureLoadings")[features,]%*%
    t(slot(cogaps_result,"sampleFactors")[barcodes,])
#Obtaining Spatial Coordinates
download.file(sp_url, basename(sp_url), mode = "wb")
untar(basename(sp_url))
spCoords <- load10XCoords(visiumDir = ".", version = "1.0")
rownames(spCoords) <- spCoords$barcode
spCoords <- spCoords[barcodes,]
spPatterns <- cbind(spCoords,
slot(cogaps_result,"sampleFactors")[barcodes,])
data("curated_genes")
spPatterns<-spPatterns[c("barcode","y","x","Pattern_1",
"Pattern_3","Pattern_5")]
counts_matrix <- counts_matrix[curated_genes,]
cogaps_matrix <- cogaps_matrix[curated_genes, ]
optParams <- matrix(c(6, 2, 6, 2, 6, 2), nrow = 2)
rownames(optParams) <- c("sigmaOpt","threshOpt")
colnames(optParams) <- c("Pattern_1","Pattern_3","Pattern_5")
SpaceMarkersMode <- "DE"
pattern_pairs <- matrix(c("Pattern_1", "Pattern_1", 
           "Pattern_3", "Pattern_5"), nrow=2)
SpaceMarkers <- get_pairwise_interacting_genes(
    data=counts_matrix,reconstruction=NULL,
    optParams = optParams,
    spPatterns = spPatterns,
    mode="DE",analysis="enrichment", pattern_pairs=pattern_pairs)
#Remove present Directories if any
unlink(basename(sp_url))
unlink("spatial", recursive = TRUE)
files <- list.files(".")[grepl(basename(counts_url),list.files("."))]
unlink(files)

Description

This function loads spatial features from a file containing spatial features

Usage

get_spatial_features(filePath, method = NULL, featureNames = ".")

Arguments

Value

a matrix of spatial features with barcodes associated with individual coordinates

Examples

library(SpaceMarkers)
#CoGAPS data filePath
filePath <- system.file("extdata","CoGAPS_result.rds", 
package = "SpaceMarkers",mustWork = TRUE)
spFeatures <- get_spatial_features(filePath, method = "CoGAPS")
head(spFeatures)

Description

This function obtains the width of a spatial kernel density (sigma) from either the user input or from a scale factors .json file. The outlier threshold around the set of spots (threshold) for each pattern is specified by the user (default is 4).

Usage

get_spatial_parameters(
  spatialPatterns,
  visiumDir = ".",
  spatialDir = "spatial",
  pattern = "scalefactors_json.json",
  sigma = NULL,
  threshold = 4,
  resolution = c("fullres", "lowres", "hires"),
  ...
)

Arguments

Value

a numeric matrix of sigmaOpts - the optimal width of the gaussian distribution, and the threshOpt - outlier threshold around the set of spots for each pattern

Examples

library(SpaceMarkers)
# Create test data
cells <- c()
test_num <- 500
for(i in 1:test_num){
    cells[length(cells)+1] <- paste0("cell_",i)
}
spPatterns <- data.frame(barcode = cells,
y = runif(test_num, min=0, max=test_num),
x = runif(test_num, min=0, max=test_num),
Pattern_1 = runif(test_num, min=0, max=1),
Pattern_2 = runif(test_num, min=0, max=1) )
# Call the get_spatial_parameters function with the test data
optParams <- get_spatial_parameters(spPatterns, sigma = 10)

Description

This function uses Morans.I to calculate the optimal width of the kernel density (sigmaOpt) as well as the outlier threshold around the set of spots (threshOpt) for a null distribution.

Usage

get_spatial_params_morans_i(spatialPatterns, ...)

Arguments

Value

a numeric matrix of sigmaOpts - the optimal width of the gaussian distribution, and the threshOpt - outlier threshold around the set of spots for each pattern

Examples

library(SpaceMarkers)
# Create test data
cells <- c()
test_num <- 500
for(i in 1:test_num){
    cells[length(cells)+1] <- paste0("cell_",i)
}
spPatterns <- data.frame(barcode = cells,
y = runif(test_num, min=0, max=test_num),
x = runif(test_num, min=0, max=test_num),
Pattern_1 = runif(test_num, min=0, max=1),
Pattern_2 = runif(test_num, min=0, max=1) )
# Call the get_spatial_params_morans_i function with the test data
optParams <- get_spatial_params_morans_i(spPatterns)

Description

Read (hotspots(x, type)) or write (hotspots(x, type) <- value) the per-type hotspot data.frame stored in metadata(x)$hotspots[[type]]. type selects one of "undirected", "pattern", or "influence".

Usage

hotspots(x, ...)

hotspots(x, type = "undirected") <- value

## S4 method for signature 'SpaceMarkersExperiment'
hotspots(x, type = c("undirected", "pattern", "influence"))

## S4 replacement method for signature 'SpaceMarkersExperiment'
hotspots(x, type = c("undirected", "pattern", "influence")) <- value

Arguments

Value

For the getter, a data.frame or NULL. For the setter, the modified SpaceMarkersExperiment.

A data.frame of hotspot assignments, or NULL.

Examples

sme <- SpaceMarkersExperiment(
    assays = list(logcounts = matrix(rpois(200, 2), 10, 20,
        dimnames = list(paste0("G", 1:10), paste0("s", 1:20)))),
    spatialCoords = matrix(runif(40), 20, 2,
        dimnames = list(NULL, c("y", "x"))))
colnames(sme) <- paste0("s", seq_len(20))
hs <- data.frame(barcode = colnames(sme), x = 1:20, y = 1:20,
                 Pattern_1 = c(rep("hot", 10), rep(NA, 10)))
hotspots(sme, type = "undirected") <- hs
head(hotspots(sme, "undirected"))

Description

Read (influence_map(x)) or write (influence_map(x) <- value) the per-spot influence values stored in metadata(x)$influence.

Usage

influence_map(x, ...)

influence_map(x) <- value

## S4 method for signature 'SpaceMarkersExperiment'
influence_map(x)

## S4 replacement method for signature 'SpaceMarkersExperiment'
influence_map(x) <- value

Arguments

Value

For the getter, a data.frame of per-spot influence values or NULL. For the setter, the modified SpaceMarkersExperiment.

A data.frame of per-spot influence values, or NULL.

Examples

sme <- SpaceMarkersExperiment(
    assays = list(logcounts = matrix(rpois(200, 2), 10, 20,
        dimnames = list(paste0("G", 1:10), paste0("s", 1:20)))),
    spatialCoords = matrix(runif(40), 20, 2,
        dimnames = list(NULL, c("y", "x"))))
colnames(sme) <- paste0("s", seq_len(20))
influence_map(sme) <- data.frame(barcode = colnames(sme),
    x = 1:20, y = 1:20, Pattern_1 = runif(20))
head(influence_map(sme))

Description

Read (interactions(x, pair)) or write (interactions(x) <- value) the per-pattern-pair interaction results stored in metadata(x)$interactions. When pair is supplied to the getter, only that pair's results are returned; otherwise the full named list is returned.

Usage

interactions(x, ...)

interactions(x) <- value

## S4 method for signature 'SpaceMarkersExperiment'
interactions(x, pair = NULL)

## S4 replacement method for signature 'SpaceMarkersExperiment'
interactions(x) <- value

Arguments

Value

For the getter, a named list of per-pair results (or a single pair's results when pair is specified). For the setter, the modified SpaceMarkersExperiment.

A named list of per-pair interaction results, or a single pair's results if pair is specified.

Examples

sme <- SpaceMarkersExperiment(
    assays = list(logcounts = matrix(rpois(200, 2), 10, 20,
        dimnames = list(paste0("G", 1:10), paste0("s", 1:20)))),
    spatialCoords = matrix(runif(40), 20, 2,
        dimnames = list(NULL, c("y", "x"))))
interactions(sme) <- list(
    Pattern_1_Pattern_2 = list(interacting_genes = list()))
names(interactions(sme))

Description

Convenience wrapper that reads an .h5ad file and coerces the resulting SingleCellExperiment directly into a SpaceMarkersExperiment. If the AnnData stores spatial coordinates under obsm["spatial"], they are promoted to spatialCoords().

Two readers are supported:

• anndataR — pure-R, no Python/conda dependency, faster on first call. Recommended when available.

• zellkonverter — Bioconductor-standard, uses a basilisk-managed Python environment under the hood.

Both are Suggests dependencies. With reader = "auto" (default), anndataR is preferred when installed; otherwise zellkonverter is used. Pass reader = "zellkonverter" or reader = "anndataR" to force a specific backend.

Usage

load_anndata(file, reader = c("auto", "anndataR", "zellkonverter"), ...)

Arguments

Value

A SpaceMarkersExperiment object.

Examples

# Requires anndataR or zellkonverter installed and a real .h5ad file:
# sme <- load_anndata("path/to/visium.h5ad")

Description

Convenience function that loads expression, coordinates, and optionally spatial features from a 10X Visium directory and assembles them into a SpaceMarkersExperiment object.

Usage

load10X(
  visiumDir,
  features = NULL,
  h5filename = "filtered_feature_bc_matrix.h5",
  resolution = c("fullres", "lowres", "hires"),
  version = NULL,
  ...
)

Arguments

Value

A SpaceMarkersExperiment object.

Examples

# Requires a 10x Visium directory on disk:
# sme <- load10X("path/to/Visium_outs",
#                features = "deconv_features.csv",
#                resolution = "lowres")

Description

This function loads spatial coordinates for each cell from a 10X Visium spatial folder.

Usage

load10XCoords(
  visiumDir,
  resolution = c("fullres", "lowres", "hires"),
  version = NULL
)

Arguments

Value

a data frame of the spatial coordinates ( x and y) for each spot/cell

Examples

library(SpaceMarkers)
#Visium data links
urls <- read.csv(system.file("extdata","visium_data.txt",
package = "SpaceMarkers",mustWork = TRUE))
sp_url <- urls[["visium_url"]][2]
# Spatial Coordinates
download.file(sp_url, basename(sp_url), mode = "wb")
untar(basename(sp_url))
spCoords <- load10XCoords(visiumDir = ".", version = "1.0")
unlink("spatial", recursive = TRUE)
unlink("Visium_Human_Breast_Cancer_spatial.tar.gz")

Description

This loads log-transformed 10X Visium expression data from standard 10X Visium folder.

Usage

load10XExpr(visiumDir = NULL, h5filename = "filtered_feature_bc_matrix.h5")

Arguments

Value

A matrix of class dgeMatrix or Matrix that contains the expression info for each sample (cells) across multiple features (genes)

Examples

library(SpaceMarkers)
#Visium data links
urls <- read.csv(system.file("extdata","visium_data.txt",
package = "SpaceMarkers",mustWork = TRUE))
counts_url <- urls[["visium_url"]][1]
#Remove present Directories if any
files <- list.files(".")[grepl(basename(counts_url),list.files("."))]
unlink(files)
download.file(counts_url,basename(counts_url), mode = "wb")
counts_matrix<-load10XExpr(visiumDir=".",h5filename = basename(counts_url))
files <- list.files(".")[grepl(basename(counts_url),list.files("."))]
unlink(files)

Description

Read (lr_scores(x)) or write (lr_scores(x) <- value) the matrix of ligand-receptor pair scores stored in x@spacemarkers$results$lr_scores.

Usage

lr_scores(x, ...)

lr_scores(x) <- value

## S4 method for signature 'SpaceMarkersExperiment'
lr_scores(x)

## S4 replacement method for signature 'SpaceMarkersExperiment'
lr_scores(x) <- value

Arguments

Value

For the getter, a matrix of LR pair scores or NULL. For the setter, the modified SpaceMarkersExperiment.

A matrix of ligand-receptor pair scores, or NULL.

Examples

sme <- SpaceMarkersExperiment(
    assays = list(logcounts = matrix(rpois(200, 2), 10, 20,
        dimnames = list(paste0("G", 1:10), paste0("s", 1:20)))),
    spatialCoords = matrix(runif(40), 20, 2,
        dimnames = list(NULL, c("y", "x"))))
lr_scores(sme) <- matrix(runif(4), 2, 2,
    dimnames = list(c("LR1", "LR2"), c("P1_P2", "P2_P1")))
lr_scores(sme)

Description

Curated Ligand-receptor interaction genes A list of vectors with genes associated with ligand-receptor interactions from CellChat database

Format

A data frame with LR interaction genes

Value

A list of vectors of LR genes

Description

A dataset with the optimal width of the gaussian distribution (sigmaOpt) and the outlier threshold around the set of spots (thresOpt) for each pattern obtained from CoGAPS. CoGAPS was ran on spatial transcriptomic data from a breast cancer sample.

Format

A data frame with 2 rows and 5 columns:

Pattern_1

immune cell pattern paramters

Pattern_2

Disp.1 parameters

Pattern_3

intraductal carcinoma (DCIS) parameters

Pattern_4

Disp.2 parameters

Pattern_5

invasive carcinoma lesion pattern paramters

Value

A matrix of optimal parameters for patterns identified by CoGAPS

Description

The spot-level counterpart to overlap_scores. Returns a factor with one label per spot, summarizing how each spot relates to a pattern pair given the hotspot information stored on the SME.

Usage

overlap_map(
  x,
  interaction_patterns,
  direction = c("forward", "reverse"),
  directed = NULL,
  interaction_label = NULL
)

Arguments

Details

Undirected (when hotspots(x, "undirected") is present and directed = FALSE or auto-detected). Three levels: <pat1>, "interacting" (override via interaction_label), <pat2>.

Directed (when hotspots(x, "pattern") AND hotspots(x, "influence") are both present). Because a directed analysis runs a separate t-test per direction (pat1 near pat2 vs pat1, and pat2 near pat1 vs pat2), the helper returns one direction at a time — the three-level factor that directly matches that direction's t-test:

• direction = "forward" (default; source = pat1, target = pat2). Levels: <pat1> (the "control" in the t-test), "<pat1> near <pat2>" (the interaction region - the "treatment"), "<pat2> influence" (context: where pat2's influence extends beyond pat1's hotspot).

• direction = "reverse" (source = pat2, target = pat1). Levels are the mirror image: <pat2>, "<pat2> near <pat1>", "<pat1> influence".

Downstream callers (including plot_spatial(..., source = "interaction")) use this helper so the plot and any user-side analysis stay consistent.

Value

A factor with one entry per spot, NA for spots outside any hotspot. Names are the spot barcodes.

Examples

sme <- SpaceMarkersExperiment(
    assays = list(logcounts = matrix(rpois(200, 2), 10, 20,
        dimnames = list(paste0("G", 1:10), paste0("s", 1:20)))),
    spatialCoords = matrix(runif(40), 20, 2,
        dimnames = list(NULL, c("y", "x"))))
colnames(sme) <- paste0("s", seq_len(20))
hs <- data.frame(barcode = colnames(sme), x = 1:20, y = 1:20,
                 Pattern_1 = c(rep("hot", 10), rep(NA, 10)),
                 Pattern_2 = c(rep(NA, 5), rep("hot", 10), rep(NA, 5)))
hotspots(sme, type = "undirected") <- hs
table(overlap_map(sme, c("Pattern_1", "Pattern_2")))

Description

Read (overlap_scores(x)) or write (overlap_scores(x) <- value) the data.frame of pattern overlap scores stored in x@spacemarkers$results$overlap_scores.

Usage

overlap_scores(x, ...)

overlap_scores(x) <- value

## S4 method for signature 'SpaceMarkersExperiment'
overlap_scores(x)

## S4 replacement method for signature 'SpaceMarkersExperiment'
overlap_scores(x) <- value

Arguments

Value

For the getter, a data.frame of pattern overlap scores or NULL. For the setter, the modified SpaceMarkersExperiment.

A data.frame of pattern overlap scores, or NULL.

Examples

sme <- SpaceMarkersExperiment(
    assays = list(logcounts = matrix(rpois(200, 2), 10, 20,
        dimnames = list(paste0("G", 1:10), paste0("s", 1:20)))),
    spatialCoords = matrix(runif(40), 20, 2,
        dimnames = list(NULL, c("y", "x"))))
overlap_scores(sme) <- data.frame(pattern1 = "Pattern_1",
    pattern2 = "Pattern_2", overlapScore = 0.5)
overlap_scores(sme)

Description

Read-only accessor that returns the full list stored in x@spacemarkers$params, including spatial_params, pattern_names, min_gene_expr, mode, analysis, min_overlap, directed, outlier, null_samples, genes, and any other hyperparameters set during analysis.

Usage

params(x, ...)

## S4 method for signature 'SpaceMarkersExperiment'
params(x)

Arguments

Value

The full list of hyperparameters, or NULL if none has been set.

The full list of hyperparameters stored during analysis, including spatial_params, pattern_names, min_gene_expr, mode, analysis, min_overlap, directed, outlier, null_samples, genes, etc. Returns NULL if no parameters have been set.

Examples

sme <- SpaceMarkersExperiment(
    assays = list(logcounts = matrix(rpois(200, 2), 10, 20,
        dimnames = list(paste0("G", 1:10), paste0("s", 1:20)))),
    spatialCoords = matrix(runif(40), 20, 2,
        dimnames = list(NULL, c("y", "x"))))
params(sme)

Description

Visualizes ligand-receptor interactions as a circular plot, allowing for selection of cell types, customization of segment and link appearance, and different modes of representing interactions.

Usage

plot_cell_interaction_circos(
  lr_interactions_df,
  selected_cell_types = NULL,
  cell_order = NULL,
  gap_degree_after_sector = 5,
  track_height_molecules = 0.1,
  molecule_label_cex = 0.6,
  cell_label_cex = 0.9,
  link_transparency = 0.5,
  link_connection_rou = 0.7,
  link_arrowhead_type = "big.arrow",
  link_arrowhead_width = NULL,
  link_arrowhead_length = NULL,
  score_color_palette_fun = NULL,
  split_segments_for_links = TRUE,
  link_buffer_fraction = 0.1,
  scale_link_width_by_score = FALSE,
  score_transform_for_width = function(s) s,
  use_individual_molecule_colors = TRUE,
  default_ligand_color = "lightgreen",
  default_receptor_color = "lightblue",
  individual_ligand_palette_generator = NULL,
  individual_receptor_palette_generator = NULL,
  molecule_segment_border_col = NA,
  inter_molecule_segment_gap = 0.1
)

Arguments

Value

Invisibly returns NULL. The function is called for its side effect of creating a plot.

Examples

if (requireNamespace("circlize", quietly = TRUE) &&
    requireNamespace("RColorBrewer", quietly = TRUE)) {
  lr_data <- data.frame(
    ligand = c("LGF1", "LGF1", "LGF2", "LGF3", "LGF4", "LGF1", "LGF5", "LGF6"),
    receptor = c("REC1", "REC2A", "REC1", "REC3B", "REC1", "REC4", "REC4", "REC2A"),
    source_cell_type = c("CellA", "CellA", "CellB", "CellC",
                          "CellA", "CellD", "CellD", "CellB"),
    target_cell_type = c("CellB", "CellC", "CellB", "CellA",
                          "CellD", "CellA", "CellD", "CellC"),
    score = c(4, 0.9, 0.7, 0.95, 0.6, 0.1, 0.88, 2.5),
    stringsAsFactors = FALSE
  )
  # Basic plot with defaults
  # plot_cell_interaction_circos(lr_data)

  # Plot with selected cell types and custom order
  # plot_cell_interaction_circos(lr_data,
  #                           selected_cell_types = c("CellA", "CellB", "CellD"),
  #                           cell_order = c("CellD", "CellA", "CellB"))
 }

Description

Plot the top SpaceMarkers IMScores

Usage

plot_im_scores(
  df,
  interaction,
  cutOff = 0,
  nGenes = 20,
  geneText = 12,
  metricText = 12,
  increments = 1,
  out = NULL
)

Arguments

Value

A ggplot object showing the top genes ranked by SpaceMarkersMetric for interaction.

Examples

df <- data.frame(Gene = paste0("G", 1:20),
                 Pattern_1_Pattern_2 = sort(runif(20), decreasing = TRUE))
plot_im_scores(df, interaction = "Pattern_1_Pattern_2",
               nGenes = 10)

Description

Plot the overlap scores between patterns in hotspots

Usage

plot_overlap_scores(
  df,
  title = "Spatial Overlap Scores",
  out = NULL,
  fontsize = 15
)

Arguments

Value

A ggplot object

Examples

df <- data.frame(pattern1 = c("pattern1","pattern1","pattern2","pattern2"), 
                 pattern2 = c("pattern1","pattern2","pattern1","pattern2"),
                 overlapScore = c(0.5,0.7,0.3,0.9))
plot_overlap_scores(df)
plot_overlap_scores(df, "Overlap Scores", "overlapScores.png", 15)

Description

Visualizes ligand-receptor interactions focusing on a single source cell type and its outgoing interactions to a specified set of target cell types. Only ligands from the source and relevant receptors on the targets are shown.

Usage

plot_source_to_target_circos(
  lr_interactions_df,
  source_cell_name,
  target_cell_names,
  cell_order = NULL,
  gap_degree_after_sector = 5,
  track_height_molecules = 0.1,
  molecule_label_cex = 0.6,
  cell_label_cex = 0.9,
  link_transparency = 0.5,
  link_connection_rou = 0.7,
  link_arrowhead_type = "triangle",
  link_arrowhead_width = NULL,
  link_arrowhead_length = NULL,
  score_color_palette_fun = NULL,
  split_segments_for_links = TRUE,
  link_buffer_fraction = 0.1,
  scale_link_width_by_score = FALSE,
  score_transform_for_width = function(s) s,
  use_individual_molecule_colors = TRUE,
  default_ligand_color = "lightgreen",
  default_receptor_color = "lightblue",
  individual_ligand_palette_generator = NULL,
  individual_receptor_palette_generator = NULL,
  molecule_segment_border_col = NA,
  inter_molecule_segment_gap = 0.1
)

Arguments

Value

Invisibly returns NULL. The function is called for its side effect of creating a plot.

Examples

if (requireNamespace("circlize", quietly = TRUE) &&
    requireNamespace("RColorBrewer", quietly = TRUE)) {
  lr_data <- data.frame(
    ligand = c("LGF1", "LGF1", "LGF2", "LGF3", "LGF4", "LGF1", "LGF5", "LGF6", "LGF7"),
    receptor = c("REC1", "REC2A", "REC1", "REC3B", "REC1", "REC4", "REC4", "REC2A", "REC5"),
    source_cell_type = c("CellA", "CellA", "CellB", "CellC", 
                         "CellA", "CellD", "CellD", "CellB", "CellA"),
    target_cell_type = c("CellB", "CellC", "CellB", "CellA", 
                         "CellD", "CellA", "CellD", "CellC", "CellE"),
    score = c(4,0.9,0.7,0.95,0.6,0.1,0.88,2.5,3.0),
    stringsAsFactors = FALSE
  )
  # Plot interactions from CellA to CellB and CellC
  # plot_source_to_target_circos(lr_data,
  #                          source_cell_name = "CellA",
  #                          target_cell_names = c("CellB", "CellC"))

  # Custom order and score-based link widths
  # score_pal <- circlize::colorRamp2(c(0, 4), c("white", "blue"))
  # plot_source_to_target_circos(lr_data,
  #                          source_cell_name = "CellD",
  #                          target_cell_names = c("CellA", "CellD"), # Include autocrine
  #                          cell_order = c("CellD", "CellA"),
  #                          scale_link_width_by_score = TRUE,
  #                          score_color_palette_fun = score_pal)
 }

Description

SME-native spatial plot. Extracts coordinates from the SpaceMarkersExperiment, looks up feature_col in colData, rownames (gene expression), or hotspot metadata, and overlays on the tissue image if available. If no image is found, plots on a blank background.

Usage

plot_spatial(
  sme,
  feature_col = NULL,
  hotspot_type = c("undirected", "pattern", "influence"),
  source = c("auto", "colData", "assay", "hotspots", "influence_map", "interaction"),
  interaction_patterns = NULL,
  interaction_label = NULL,
  direction = c("forward", "reverse"),
  image = NULL,
  resolution = c("lowres", "hires", "fullres"),
  colors = NULL,
  point_size = 2.5,
  stroke = 0.05,
  alpha = 0.5,
  title = feature_col,
  bg_color = NULL,
  crop = TRUE,
  text_size = 15
)

Arguments

Value

A ggplot object.

Examples

set.seed(1)
nb <- 40
coord_mat <- matrix(runif(2 * nb), nb, 2,
    dimnames = list(paste0("s", seq_len(nb)), c("y", "x")))
sme <- SpaceMarkersExperiment(
    assays        = list(logcounts = matrix(rpois(5 * nb, 3), nrow = 5,
        dimnames = list(paste0("G", 1:5), rownames(coord_mat)))),
    colData       = data.frame(Pattern_1 = runif(nb),
                               row.names = rownames(coord_mat)),
    spatialCoords = coord_mat)
plot_spatial(sme, feature_col = "Pattern_1", source = "colData")

Description

This function plots spatial data over the complementary histology image of varing resolutions

Usage

plot_spatial_data_over_image(
  visiumDir,
  df,
  feature_col,
  barcode_col = "barcode",
  resolution = c("lowres", "hires", "fullres"),
  version = NULL,
  colors = NULL,
  point_size = 2.5,
  stroke = 0.05,
  alpha = 0.5,
  title = "Spatial Heatmap",
  bg_color = NULL,
  crop = TRUE,
  text_size = 15
)

Arguments

Value

a ggplot object

Examples

# Requires a 10x Visium directory on disk and a per-spot data.frame
# with at least `barcode` plus the column referenced by `feature_col`.
# Sketch:
# df <- data.frame(barcode = c("s1","s2"), Pattern_1 = c(0.2, 0.8))
# plot_spatial_data_over_image(visiumDir = "path/to/visium",
#                              df = df, feature_col = "Pattern_1")

Description

Visualizes ligand-receptor interactions focusing on a single target cell type and its incoming interactions from a specified set of source cell types. Only relevant ligands from the source cells and receptors on the target cell are shown.

Usage

plot_target_from_sources_circos(
  lr_interactions_df,
  source_cell_names,
  target_cell_name,
  cell_order = NULL,
  gap_degree_after_sector = 5,
  track_height_molecules = 0.1,
  molecule_label_cex = 0.6,
  cell_label_cex = 0.9,
  link_transparency = 0.5,
  link_connection_rou = 0.7,
  link_arrowhead_type = "triangle",
  link_arrowhead_width = 0.1,
  link_arrowhead_length = 0.1,
  score_color_palette_fun = NULL,
  split_segments_for_links = TRUE,
  link_buffer_fraction = 0.1,
  scale_link_width_by_score = FALSE,
  score_transform_for_width = function(s) s,
  use_individual_molecule_colors = TRUE,
  default_ligand_color = "lightgreen",
  default_receptor_color = "lightblue",
  individual_ligand_palette_generator = NULL,
  individual_receptor_palette_generator = NULL,
  molecule_segment_border_col = NA,
  inter_molecule_segment_gap = 0.1
)

Arguments

Value

Invisibly returns NULL. The function is called for its side effect of creating a plot.

Examples

if (requireNamespace("circlize", quietly = TRUE) &&
    requireNamespace("RColorBrewer", quietly = TRUE)) {
  # Use the same test data from previous examples
  test_lr_data <- data.frame(
    ligand = c("LGF1","LGF1","LGF2","LGF3","LGF4","LGF1","LGF5","LGF6","LGF5"),
    receptor = c("REC1","REC2","REC1","REC1","REC5","REC4","REC4","REC6","REC2"),
    source_cell_type = c("CellA","CellA","CellB","CellC","CellA","CellD","CellD","CellE","CellD"),
    target_cell_type = c("CellB","CellC","CellA","CellD","CellD","CellA","CellD","CellF","CellA"),
    score = c(4.0,2.5,3.0,2.2,1.5,1.0,3.5,0.5,2.8),
    stringsAsFactors = FALSE
  )
  # Plot interactions from CellB and CellD converging on CellA
  # plot_target_from_sources_circos(test_lr_data,
  #                             source_cell_names = c("CellB", "CellD"),
  #                             target_cell_name = "CellA")

  # Another example: Interactions from CellA and CellC targeting CellD
  # plot_target_from_sources_circos(test_lr_data,
  #                             source_cell_names = c("CellA", "CellC"),
  #                             target_cell_name = "CellD",
  #                             scale_link_width_by_score = TRUE)
 }

Description

Writes a SpaceMarkersExperiment out to an .h5ad file, preserving the full SpaceMarkers analysis state (hotspots, overlap scores, interactions, influence map, kernel parameters) under uns["spacemarkers"]. Reloading with load_anndata() restores that state.

The reader selection logic is identical to load_anndata: anndataR is preferred when installed, zellkonverter is the fallback.

Usage

save_anndata(sme, file, reader = c("auto", "anndataR", "zellkonverter"), ...)

Arguments

Value

The path file, returned invisibly.

Examples

# Requires anndataR or zellkonverter installed:
# sme <- SpaceMarkersExperiment(
#     assays = list(logcounts = matrix(rpois(200, 2), 10, 20,
#         dimnames = list(paste0("G", 1:10), paste0("s", 1:20)))),
#     spatialCoords = matrix(runif(40), 20, 2,
#         dimnames = list(NULL, c("y", "x"))))
# save_anndata(sme, tempfile(fileext = ".h5ad"))

Description

Main dispatcher for SpaceMarkers. Accepts either a SpaceMarkersExperiment object or file paths to features and a Visium directory, and returns interaction scores.

Usage

SpaceMarkers(
  x = NULL,
  features = NULL,
  data = NULL,
  directed = FALSE,
  genes = NULL,
  min.gene.expr = 10,
  resolution = c("fullres", "lowres", "hires"),
  version = NULL,
  h5filename = "filtered_feature_bc_matrix.h5",
  spatialDir = "spatial",
  pattern = "scalefactors_json.json",
  sigma = NULL,
  threshold = 4,
  cpus = 1,
  lr_pairs = NULL,
  returnSME = TRUE,
  ...
)