| Title: | Spatial analysis of in situ cytometry data |
|---|---|
| Description: | The spicyR package provides a framework for performing inference on changes in spatial relationships between pairs of cell types for cell-resolution spatial omics technologies. spicyR consists of three primary steps: (i) summarizing the degree of spatial localization between pairs of cell types for each image; (ii) modelling the variability in localization summary statistics as a function of cell counts and (iii) testing for changes in spatial localizations associated with a response variable. |
| Authors: | Nicolas Canete [aut], Ellis Patrick [aut, cre], Nicholas Robertson [ctb], Alex Qin [ctb], Farhan Ameen [ctb], Shreya Rao [ctb] |
| Maintainer: | Ellis Patrick <[email protected]> |
| License: | GPL (>=2) |
| Version: | 1.25.0 |
| Built: | 2026-05-30 09:43:51 UTC |
| Source: | https://github.com/bioc/spicyR |
Produces a dataframe showing L-function metric for each imageID entry.
bind(results, pairName = NULL)bind(results, pairName = NULL)
results |
Spicy test result obtained from spicy. |
pairName |
A string specifying the pairwise interaction of interest. If NULL, all pairwise interactions are shown. |
A data.frame containing the colData related to the results.
data(spicyTest) df <- bind(spicyTest)data(spicyTest) df <- bind(spicyTest)
Perform a simple wilcoxon-rank-sum test or t-test on the columns of a data frame
colTest(df, condition, type = NULL, feature = NULL, imageID = "imageID")colTest(df, condition, type = NULL, feature = NULL, imageID = "imageID")
df |
A data.frame or SingleCellExperiment, SpatialExperiment |
condition |
The condition of interest |
type |
The type of test, "wilcox", "ttest" or "survival". |
feature |
Can be used to calculate the proportions of this feature for each image |
imageID |
The imageID's if presenting a SingleCellExperiment |
Proportions
# Test for an association with long-duration diabetes # This is clearly ignoring the repeated measures... data("diabetesData") diabetesData <- spicyR:::.format_data( diabetesData, "imageID", "cellType", c("x", "y"), FALSE ) props <- getProp(diabetesData) condition <- spicyR:::getImagePheno(diabetesData)$stage names(condition) <- spicyR:::getImagePheno(diabetesData)$imageID condition <- condition[condition %in% c("Long-duration", "Onset")] test <- colTest(props[names(condition), ], condition)# Test for an association with long-duration diabetes # This is clearly ignoring the repeated measures... data("diabetesData") diabetesData <- spicyR:::.format_data( diabetesData, "imageID", "cellType", c("x", "y"), FALSE ) props <- getProp(diabetesData) condition <- spicyR:::getImagePheno(diabetesData)$stage names(condition) <- spicyR:::getImagePheno(diabetesData)$imageID condition <- condition[condition %in% c("Long-duration", "Onset")] test <- colTest(props[names(condition), ], condition)
Converts colPairs object into an abundance matrix based on number of nearby interactions for every cell type.
convPairs(cells, colPair, imageID = "imageID", cellType = "cellType")convPairs(cells, colPair, imageID = "imageID", cellType = "cellType")
cells |
A SingleCellExperiment that contains objects in the colPairs slot. |
colPair |
The name of the object in the colPairs slot for which the dataframe is constructed from. |
imageID |
The image ID if using SingleCellExperiment. |
cellType |
The cell type if using SingleCellExperiment. |
Matrix of abundances
data("diabetesData") images <- c("A09", "A11", "A16", "A17") diabetesData <- diabetesData[ , SummarizedExperiment::colData(diabetesData)$imageID %in% images ] diabetesData_SPE <- SpatialExperiment::SpatialExperiment(diabetesData, colData = SummarizedExperiment::colData(diabetesData) ) SpatialExperiment::spatialCoords(diabetesData_SPE) <- data.frame( SummarizedExperiment::colData(diabetesData_SPE)$x, SummarizedExperiment::colData(diabetesData_SPE)$y ) |> as.matrix() SpatialExperiment::spatialCoordsNames(diabetesData_SPE) <- c("x", "y") diabetesData_SPE <- imcRtools::buildSpatialGraph(diabetesData_SPE, img_id = "imageID", type = "knn", k = 20, coords = c("x", "y") ) pairAbundances <- convPairs(diabetesData_SPE, colPair = "knn_interaction_graph" )data("diabetesData") images <- c("A09", "A11", "A16", "A17") diabetesData <- diabetesData[ , SummarizedExperiment::colData(diabetesData)$imageID %in% images ] diabetesData_SPE <- SpatialExperiment::SpatialExperiment(diabetesData, colData = SummarizedExperiment::colData(diabetesData) ) SpatialExperiment::spatialCoords(diabetesData_SPE) <- data.frame( SummarizedExperiment::colData(diabetesData_SPE)$x, SummarizedExperiment::colData(diabetesData_SPE)$y ) |> as.matrix() SpatialExperiment::spatialCoordsNames(diabetesData_SPE) <- c("x", "y") diabetesData_SPE <- imcRtools::buildSpatialGraph(diabetesData_SPE, img_id = "imageID", type = "knn", k = 20, coords = c("x", "y") ) pairAbundances <- convPairs(diabetesData_SPE, colPair = "knn_interaction_graph" )
This is a subset of the Damond et al 2019 imaging mass cytometry dataset. The data contains cells in the pancreatic islets of individuals with early onset diabetes and healthy controls. The object contains single-cell data of 160 images from 8 subjects, with 20 images per subject.
data("diabetesData")data("diabetesData")
diabetesData_SCE a SingleCellExperiment object
Converted into a SingleCellExperiment format.
Get statistic from pairwise L curve of a single image.
getPairwise( cells, imageID = "imageID", cellType = "cellType", spatialCoords = c("x", "y"), r = NULL, sigma = NULL, from = NULL, to = NULL, cores = 1, minLambda = 0.05, window = "convex", window.length = NULL, edgeCorrect = TRUE, includeZeroCells = FALSE, BPPARAM = NULL, imageIDCol = imageID, cellTypeCol = cellType, spatialCoordCols = spatialCoords, nCores = cores, Rs = r )getPairwise( cells, imageID = "imageID", cellType = "cellType", spatialCoords = c("x", "y"), r = NULL, sigma = NULL, from = NULL, to = NULL, cores = 1, minLambda = 0.05, window = "convex", window.length = NULL, edgeCorrect = TRUE, includeZeroCells = FALSE, BPPARAM = NULL, imageIDCol = imageID, cellTypeCol = cellType, spatialCoordCols = spatialCoords, nCores = cores, Rs = r )
cells |
A SummarizedExperiment that contains at least the variables x and y, giving the location coordinates of each cell, and cellType. |
imageID |
The name of the imageID column if using a SingleCellExperiment or SpatialExperiment. |
cellType |
The name of the cellType column if using a SingleCellExperiment or SpatialExperiment. |
spatialCoords |
The names of the spatialCoords column if using a SingleCellExperiment. |
r |
A vector of the radii that the measures of association should be calculated over. |
sigma |
A numeric variable used for scaling when fitting inhomogenous L-curves. |
from |
The 'from' cellType for generating the L curve. |
to |
The 'to' cellType for generating the L curve. |
cores |
Number of cores to use for parallel processing or a BiocParallel MulticoreParam or SerialParam object. |
minLambda |
Minimum value density for scaling when fitting inhomogeneous L-curves. |
window |
Should the window around the regions be 'square', 'convex' or 'concave'. |
window.length |
A tuning parameter for controlling the level of concavity when estimating concave windows. |
edgeCorrect |
A logical indicating whether to perform edge correction. |
includeZeroCells |
A logical indicating whether to include cells with zero counts in the pairwise association. |
BPPARAM |
{DEPRECATED} A BiocParallel MulticoreParam or SerialParam object. |
imageIDCol |
{DEPRECATED} The name of the imageID column if using a SingleCellExperiment or SpatialExperiment. |
cellTypeCol |
{DEPRECATED} The name of the cellType column if using a SingleCellExperiment or SpatialExperiment. |
spatialCoordCols |
{DEPRECATED} The names of the spatialCoords column if using a SingleCellExperiment. |
nCores |
{DEPRECATED} Number of cores to use for parallel processing or a BiocParallel MulticoreParam or SerialParam object. |
Rs |
{DEPRECATED} A vector of the radii that the measures of association should be calculated over. calculation. |
Statistic from pairwise L-curve of a single image.
data("diabetesData") # Subset by imageID for fast example selected_cells <- diabetesData[ , SummarizedExperiment::colData(diabetesData)$imageID == "A09" ] pairAssoc <- getPairwise(selected_cells)data("diabetesData") # Subset by imageID for fast example selected_cells <- diabetesData[ , SummarizedExperiment::colData(diabetesData)$imageID == "A09" ] pairAssoc <- getPairwise(selected_cells)
Get proportions from a SummarizedExperiment.
getProp(cells, feature = "cellType", imageID = "imageID")getProp(cells, feature = "cellType", imageID = "imageID")
cells |
A SingleCellExperiment, SpatialExperiment or data.frame. |
feature |
The feature of interest |
imageID |
The imageID's |
Proportions
data("diabetesData") prop <- getProp(diabetesData)data("diabetesData") prop <- getProp(diabetesData)
Builds a pairwise scatterplot of marker-marker associations for a single image using the output of 'getPairwise()'.
imageCrossPlot( result, image = NULL, colourGradient = c("#4575B4", "white", "#D73027"), marksToPlot = NULL, limits = NULL )imageCrossPlot( result, image = NULL, colourGradient = c("#4575B4", "white", "#D73027"), marksToPlot = NULL, limits = NULL )
result |
A matrix or data frame produced by 'getPairwise()' where rownames are image IDs and colnames are concatenated marker pairs in the form '"from__to"'. Must contain at least one row with name matching 'image'. |
image |
Character scalar. Which image (row in 'result') to plot. If 'NULL', defaults to the first rowname of 'result'. |
colourGradient |
Character vector of length 3 giving the low, mid, and high colours for a diverging palette used by 'scale_colour_gradient2()'. Default is 'c("#4575B4", "white", "#D73027")'. |
marksToPlot |
Optional character vector of marker names. If supplied, the plot is restricted to rows and columns where both 'from' and 'to' are in this set. |
limits |
Numeric length-2 vector giving the lower and upper caps applied to association values for colour mapping. Use 'NULL' to avoid clamping. Point sizes are clamped to 'c(0, max(abs(limits)))'. |
The function expects 'colnames(result)' to contain '"__"' separating marker names; otherwise an error is thrown. Values are transformed into two aesthetics:
value: the (possibly clamped) signed association used for colour.
size: the (possibly clamped) absolute association used for point size.
The colourbar shows three ticks at lower, 0, and upper
with labels "<lower", "0", and ">upper".
A ggplot2 object.
## Not run: # Minimal example (toy data) set.seed(1) mks <- c("A","B","C") pairs <- as.vector(outer(mks, mks, paste, sep="__")) res <- matrix(rnorm(length(pairs)*2), nrow = 2, dimnames = list(c("img1","img2"), pairs)) p <- imageCrossPlot(res, image = "img1", colourGradient = c("#4575B4","white","#D73027"), marksToPlot = c("A","B","C"), limits = c(-3, 3)) print(p) ## End(Not run)## Not run: # Minimal example (toy data) set.seed(1) mks <- c("A","B","C") pairs <- as.vector(outer(mks, mks, paste, sep="__")) res <- matrix(rnorm(length(pairs)*2), nrow = 2, dimnames = list(c("img1","img2"), pairs)) p <- imageCrossPlot(res, image = "img1", colourGradient = c("#4575B4","white","#D73027"), marksToPlot = c("A","B","C"), limits = c(-3, 3)) print(p) ## End(Not run)
Plots an image with specified from and to cell types.
plotImage( cells, imageToPlot, from, to, imageID = "imageID", cellType = "cellType", spatialCoords = c("x", "y") )plotImage( cells, imageToPlot, from, to, imageID = "imageID", cellType = "cellType", spatialCoords = c("x", "y") )
cells |
A SummarizedExperiment object. |
imageToPlot |
The ID of the image to be plotted. |
from |
The "from" cell type. |
to |
The "to" cell type. |
imageID |
The name of the imageID column in the SummarizedExperiment object. |
cellType |
The name of the cellType column in the SummarizedExperiment object. |
spatialCoords |
The names of the spatialCoords column if using a SingleCellExperiment. |
A ggplot object.
data("diabetesData") plotImage(diabetesData, "A09", from = "acinar", to = "alpha")data("diabetesData") plotImage(diabetesData, "A09", from = "acinar", to = "alpha")
Plots result of signifPlot.
signifPlot( results, fdr = FALSE, type = "bubble", breaks = NULL, comparisonGroup = NULL, colours = c("#4575B4", "white", "#D73027"), marksToPlot = NULL, cutoff = 0.05, contextColours = NULL, contextLabels = waiver() )signifPlot( results, fdr = FALSE, type = "bubble", breaks = NULL, comparisonGroup = NULL, colours = c("#4575B4", "white", "#D73027"), marksToPlot = NULL, cutoff = 0.05, contextColours = NULL, contextLabels = waiver() )
results |
A spicy results object |
fdr |
TRUE if FDR correction is used. |
type |
Whether to make a bubble plot or heatmap. Note: For survival results a bubble plot will be used. |
breaks |
Vector of 3 numbers giving breaks used in legend. The first number is the minimum, the second is the maximum, the third is the number of breaks. |
comparisonGroup |
A string specifying the name of the outcome group to compare with the base group. |
colours |
Vector of colours to use to colour legend. |
marksToPlot |
Vector of marks to include in plot. |
cutoff |
significance threshold for circles in bubble plot. |
contextColours |
Used for |
contextLabels |
Used for |
a ggplot or pheatmap object
data(spicyTest) p <- signifPlot(spicyTest, breaks = c(-3, 3, 0.5)) # plot includes unicode characters, do not use default pdf device ggplot2::ggsave(p, filename = tempfile(), device = cairo_pdf)data(spicyTest) p <- signifPlot(spicyTest, breaks = c(-3, 3, 0.5)) # plot includes unicode characters, do not use default pdf device ggplot2::ggsave(p, filename = tempfile(), device = cairo_pdf)
Plots boxplot for a specified cell-cell relationship
spicyBoxPlot(results, from = NULL, to = NULL, rank = NULL)spicyBoxPlot(results, from = NULL, to = NULL, rank = NULL)
results |
Data frame obtained from spicy. |
from |
Cell type which you would like to compare to the to cell type. |
to |
Cell type which you would like to compare to the from cell type. |
rank |
Ranking of cell type in terms of p-value, the smaller the p-value the higher the rank. |
a ggplot2 boxplot
data(spicyTest) spicyBoxPlot(spicyTest, rank = 1)data(spicyTest) spicyBoxPlot(spicyTest, rank = 1)
Performs spatial tests on spatial cytometry data.
spicy( cells, condition, subject = NULL, covariates = NULL, imageID = "imageID", cellType = "cellType", spatialCoords = c("x", "y"), r = NULL, sigma = NULL, from = NULL, to = NULL, alternateResult = NULL, cores = 1, minLambda = 0.05, weights = TRUE, weightsByPair = FALSE, weightFactor = 1, window = "convex", window.length = NULL, edgeCorrect = TRUE, includeZeroCells = FALSE, verbose = FALSE, BPPARAM = NULL, imageIDCol = imageID, cellTypeCol = cellType, spatialCoordCols = spatialCoords, nCores = cores, Rs = r, ... )spicy( cells, condition, subject = NULL, covariates = NULL, imageID = "imageID", cellType = "cellType", spatialCoords = c("x", "y"), r = NULL, sigma = NULL, from = NULL, to = NULL, alternateResult = NULL, cores = 1, minLambda = 0.05, weights = TRUE, weightsByPair = FALSE, weightFactor = 1, window = "convex", window.length = NULL, edgeCorrect = TRUE, includeZeroCells = FALSE, verbose = FALSE, BPPARAM = NULL, imageIDCol = imageID, cellTypeCol = cellType, spatialCoordCols = spatialCoords, nCores = cores, Rs = r, ... )
cells |
A SummarizedExperiment or data frame that contains at least the variables x and y, giving the location coordinates of each cell, and cellType. |
condition |
A character specifying which column which contains the condition or 'Surv' objects. |
subject |
Vector of subject IDs corresponding to each image if cells is a data frame. |
covariates |
Vector of covariate names that should be included in the mixed effects model as fixed effects. |
imageID |
The name of the imageID column if using a SingleCellExperiment or SpatialExperiment. |
cellType |
The name of the cellType column if using a SingleCellExperiment or SpatialExperiment. |
spatialCoords |
The names of the spatialCoords column if using a SingleCellExperiment. |
r |
A vector of the radii that the measures of association should be calculated over. |
sigma |
A numeric variable used for scaling when fitting inhomogenous L-curves. |
from |
vector of cell types which you would like to compare to the to vector. |
to |
vector of cell types which you would like to compare to the from vector. |
alternateResult |
A pairwise association statistic between each combination of celltypes in each image. |
cores |
Number of cores to use for parallel processing or a BiocParallel MulticoreParam or SerialParam object. |
minLambda |
Minimum value density for scaling when fitting inhomogeneous L-curves. |
weights |
logical indicating whether to include weights based on cell counts. |
weightsByPair |
logical indicating whether weights should be calculated for each cell type pair. |
weightFactor |
numeric that controls the convexity of the weight function. |
window |
Should the window around the regions be 'square', 'convex' or 'concave'. |
window.length |
A tuning parameter for controlling the level of concavity when estimating concave windows. |
edgeCorrect |
A logical indicating whether to perform edge correction. |
includeZeroCells |
A logical indicating whether to include cells with zero counts in the pairwise association calculation. |
verbose |
logical indicating whether to output messages. |
BPPARAM |
{DEPRECATED} A BiocParallel MulticoreParam or SerialParam object. |
imageIDCol |
{DEPRECATED} The name of the imageID column if using a SingleCellExperiment or SpatialExperiment. |
cellTypeCol |
{DEPRECATED} The name of the cellType column if using a SingleCellExperiment or SpatialExperiment. |
spatialCoordCols |
{DEPRECATED} The names of the spatialCoords column if using a SingleCellExperiment. |
nCores |
{DEPRECATED} Number of cores to use for parallel processing or a BiocParallel MulticoreParam or SerialParam object. |
Rs |
{DEPRECATED} A vector of the radii that the measures of association should be calculated over. |
... |
Other options |
Data frame of p-values.
data("diabetesData") # Test with random effect for patient on a pairwise combination of cell # types. spicy(diabetesData, condition = "stage", subject = "case", from = "Tc", to = "Th" ) # Test all pairwise combinations of cell types without random effect of # patient. ## Not run: spicyTest <- spicy(diabetesData, condition = "stage", subject = "case") ## End(Not run) # Test all pairwise combination of cell types with random effect of patient. ## Not run: spicy(diabetesData, condition = "condition", subject = "subject") ## End(Not run)data("diabetesData") # Test with random effect for patient on a pairwise combination of cell # types. spicy(diabetesData, condition = "stage", subject = "case", from = "Tc", to = "Th" ) # Test all pairwise combinations of cell types without random effect of # patient. ## Not run: spicyTest <- spicy(diabetesData, condition = "stage", subject = "case") ## End(Not run) # Test all pairwise combination of cell types with random effect of patient. ## Not run: spicy(diabetesData, condition = "condition", subject = "subject") ## End(Not run)
Results from the call: spicyTest <- spicy(diabetesData, condition = "condition", subject = "subject")
data("spicyTest")data("spicyTest")
spicyTest a spicy object
Plots survival results from spicy.
survBubble( result, fdr = FALSE, cutoff = 0.05, colourGradient = c("#4575B4", "white", "#D73027"), marksToPlot = NULL, contextColours = NULL, contextLabels = waiver() )survBubble( result, fdr = FALSE, cutoff = 0.05, colourGradient = c("#4575B4", "white", "#D73027"), marksToPlot = NULL, contextColours = NULL, contextLabels = waiver() )
result |
A spicyResults object that contains survival results. |
fdr |
TRUE if FDR correction is used. |
cutoff |
Significance threshold for circles in bubble plot. |
colourGradient |
A vector of colours, used to define the low, medium, and high values for the colour scale. |
marksToPlot |
Vector of marks to include in bubble plot. |
contextColours |
Used for |
contextLabels |
Used for |
A ggplot object.
A table of the significant results from spicy tests
topPairs(x, coef = NULL, n = 10, adj = "fdr", cutoff = NULL, figures = NULL)topPairs(x, coef = NULL, n = 10, adj = "fdr", cutoff = NULL, figures = NULL)
x |
The output from spicy. |
coef |
Which coefficient to list. |
n |
Extract the top n most significant pairs. |
adj |
Which p-value adjustment method to use, argument for p.adjust(). |
cutoff |
A p-value threshold to extract significant pairs. |
figures |
Round to 'figures' significant figures. |
A data.frame
data(spicyTest) topPairs(spicyTest)data(spicyTest) topPairs(spicyTest)