Skip to contents

spatialCorrelationGeneExpWithinSample

spatialCorrelationGeneExpWithinSample.Rd

Function to calculate Pearson's correlation between rows from one SpatialExperiment dataset. To replace the analytical p-value which results in a high false positive rate for autocorrelated spatial patterns, it calculates empirical p-values from empirical null distributions generated from permuting the data and then smoothing to maintain the original degree of autocorrelation

Usage

spatialCorrelationGeneExpWithinSample(
  input,
  nPermutations = 100,
  delta = NULL,
  maxDistPrctile = 0.25,
  returnPermutations = FALSE,
  assayName = NULL,
  nThreads = 1,
  BPPARAM = NULL,
  verbose = TRUE
)

Arguments

input

SpatialExperiment A SpatialExperiment object. See assayName parameter if the SpatialExperiment object has more than one assay.

nPermutations

integer or double: number of permutations to generate to build the empirical null distribution. This number will determine the precision of the p-value. Default is 100, such that the smallest p-value is 0.01

maxDistPrctile

numeric: percentile of distances between pixels to use as max distance in when calculating variograms. Default = 0.25. At greater distances the variogram is less precise because there are fewer pairs of points with that distance between them. Therefore, since the goal is to minimize the difference between the variogram of X and those of its permutations, the variogram should be subsetted to the percentile that is more robust.

returnPermutations

logical: indicate whether the dataframe returned as output will have a column with the values of the permutations used to calculate the null correlations and the empirical p-value. Default is FALSE

assayName

character or integer A character string or numeric specifying the assay in the SpatialExperiment to use. Default is NULL. If no value is supplied for assayName, then the first assay is used as a default

nThreads

integer: Number of threads for parallelization. Default = 1. Inputting this argument when the BPPARAM argument is NULL would set parallel execution back-end to be BiocParallel::MulticoreParam(workers = nThreads). We recommend setting this argument to be the number of cores available (parallel::detectCores(logical = FALSE)). If BPPARAM argument is not NULL, the BPPARAM argument would override nThreads argument.

BPPARAM

BiocParallelParam: Optional additional argument for parallelization. This argument is provided for advanced users of BiocParallel for further flexibility for setting up parallel-execution back-end. Default is NULL. If provided, this is assumed to be an instance of BiocParallelParam.

verbose

logical: indicate whether to print row number and name to show progress as the function iterates through the rows of the SpatialExperiments to calculate a correlation coefficient and empirical p-value for each row

deltaX

list: List of single numerics or list of numeric vectors to use for delta, the parameter controlling the degree of smoothing in permutations of X. The length of the list should the same as the number of rows in the SpatialExperiment. Delta is a proportion calculated by dividing k neighbors by N total observations (columns) in X, where k is the number of neighbors in the permutation of X that should be within the radius smoothed by the Gaussian kernel to achieve the amount of autocorrelation present in the original X. If a single delta is not known, a sequence of deltas can be inputted and the best delta will be found such that it minimizes the sum of squares of the residuals between the variogram of the permutation generated from the delta and the variogram of the target. Default is NULL. If no value is supplied for deltaX, seq(0.1,0.9,0.1), the sequence of every 0.1 from 0.1 to 0.9, will be used to find the best delta for each row (gene) in X.

deltaY

list: List of single numerics or list of numeric vectors to use for delta, the parameter controlling the degree of smoothing in permutations of Y. deltaY is like deltaX but for permuting data in Y instead of X. Default is NULL. If no value is supplied for deltaY, seq(0.1,0.9,0.1), the sequence of every 0.1 from 0.1 to 0.9, will be used to find the best delta for permutations for each row (gene) in Y.

Value

The output is returned as a data.frame. The rownames are arbitrary. The names of the columns and their contents are as follows:

  • correlationCoefPearson's correlation coefficient.

  • pValueNaivethe analytical p-value naively assuming independent observations

  • pValuePermuteXthe p-value when creating an empirical null from permutations of observations in X

  • pValuePermuteYthe p-value when creating an empirical null from permutations of observations in Y

  • deltaStarMedianXthe median delta star (the delta which minimizes the difference between the variogram of the permutation and the variogram of observations) across permutations of X

  • deltaStarMedianYthe median delta star across permutations of Y

  • deltaStarXlist of delta star for all permutations of X

  • deltaStarYlist of delta star for all permutations of Y

  • nullCorrelationsXcorrelation coefficients for Y and all permuations of X

  • nullCorrelationsYcorrelation coefficients for X and all permuations of Y

  • permutationsX(optional) a N x B matrix, where N is the length of X and B is `nPermutations`. Each column is the resulting values of a permutation of X

  • firstthe name of the first row in the pair

  • secondthe name of the second row in the pair

Examples


data(speKidney)

##### Rasterize to get pixels at matched spatial locations #####
rastKidney <- SEraster::rasterizeGeneExpression(speKidney,
               assay_name = 'counts', resolution = 0.2, fun = "mean",
               BPPARAM = BiocParallel::MulticoreParam(), square = FALSE)

sc_within_sample <- spatialCorrelationGeneExpWithinSample(
                      input = rastKidney,
                      assayName = "A"
                      )
#> Error in (function (classes, fdef, mtable) {    methods <- .findInheritedMethods(classes, fdef, mtable)    if (length(methods) == 1L)         return(methods[[1L]])    else if (length(methods) == 0L) {        cnames <- paste0("\"", vapply(classes, as.character,             ""), "\"", collapse = ", ")        stop(gettextf("unable to find an inherited method for function %s for signature %s",             sQuote(fdef@generic), sQuote(cnames)), domain = NA)    }    else stop("Internal error in finding inherited methods; didn't return a unique method",         domain = NA)})(list("list"), new("standardGeneric", .Data = function (x,     ...) standardGeneric("spatialCoords"), generic = structure("spatialCoords", package = "SpatialExperiment"),     package = "SpatialExperiment", group = list(), valueClass = character(0),     signature = "x", default = NULL, skeleton = (function (x,         ...)     stop(gettextf("invalid call in method dispatch to '%s' (no default method)",         "spatialCoords"), domain = NA))(x, ...)), <environment>): unable to find an inherited method for function ‘spatialCoords’ for signature ‘"list"’
sc_within_sample
#> Error: object 'sc_within_sample' not found