3.1 Input data

In this example, we will use a downsampled dataset from an experiment on the human heart. We begin by loading the count data11 Generated by the ST pipeline:

counts <- read.table(
    system.file("extdata", "counts.tsv", package = "SpatialCPie"),
    sep = "\t",
    check.names = FALSE
)
counts[1:5, 1:5]
# >        3x34  3x30  3x31  3x32  3x33
# > ACTB  2.511 2.116 2.910 3.792 2.432
# > CD74  1.744 2.323 1.666 3.061 0.000
# > CFL1  0.000 2.116 1.666 1.909 2.432
# > CST3  3.009 2.664 0.000 3.061 2.925
# > ERBB2 1.744 3.461 0.000 3.473 3.584

To overlay the data on the tissue, we also need to load the tissue image and its corresponding spot data22 Generated by the ST spot detector., which specifies the pixel coordinates of each spot:

tissue <- jpeg::readJPEG(
    system.file("extdata", "he_image.jpg", package = "SpatialCPie")
)
spots <- parseSpotFile(
    system.file("extdata", "spot_data.tsv", package = "SpatialCPie")
)
head(spots)
# >             x        y
# > 11x9 149.3096 119.4788
# > 12x9 166.1704 120.5682
# > 13x9 180.5411 120.4645
# > 14x9 195.2749 120.3607
# > 15x9 209.6456 120.3607
# > 16x9 225.3132 120.9314

3.2 Preprocessing

Typically, it’s good to conduct some data filtering prior to the analysis: This could include removing spots that are outside of the tissue or removing spots or genes that have a low number of reads.

Since the spot file only contains the spots that are under the tissue, we can use it to subset the counts:

counts <- counts[, which(colnames(counts) %in% rownames(spots))]

Let’s also remove all spots and genes that have less than 20 reads in total:

repeat {
    d <- dim(counts)
    counts <- counts[rowSums(counts) >= 20, colSums(counts) >= 20]
    if (all(dim(counts) == d)) {
        break
    }
}

3.3 Computing cluster assignments

The cluster assignments will be calculated during the loading of the gadget. The cluster assignments are labels assigned to each spot over different cluster resolutions, where we use the terminology “(cluster) resolution k” to refer to a partitioning of the spots into \(k\) clusters.

By default, clustering is performed with base::kmeans function at resolution 2:4. The user can specify the number of cluster resolutions with the resolution argument. The algorithm for clustering can also be specified with the assignmentFunction argument. Use ?runCPie for a complete list of function options.

3.4 Visualization

We are now ready to use the gadget to visualize the data:

result <- runCPie(
    counts,
    image = tissue,
    spotCoordinates = spots
)

This opens up the gadget window, which has two main elements: the cluster tree and the spatial array plots. The cluster tree is interactive and by selecting rows of nodes, the corresponding spatial array plots are also displayed. These can be viewed by scrolling down. The information contained in these plots will be discussed in the next section. There are a number of parameters that can be changed within the gadget which affects the visual representation.

To exit the gadget, press the “Done” button. The plots in the gadget and the cluster assignments are stored in the output object, which has the following structure:

str(result, max.level = 1)
# > List of 3
# >  $ clusters:'data.frame':   2400 obs. of  3 variables:
# >  $ treePlot:List of 10
# >   ..- attr(*, "class")= chr [1:2] "gg" "ggplot"
# >  $ piePlots:List of 3

result$treePlot

result$piePlots$`4`

3.5 Sub-clustering

After a “global” analysis of the entire tissue section, it is often interesting to sub-cluster parts of the tissue. This can be achieved via cluster selection in the gadget and subsequent sub-sampling of the clusters that the user wants to re-cluster further.

As a practical example, from the array plot above, we can see that clusters 1 and 4 in resolution 4 appear in mostly the same spatial areas and, from the cluster tree, we can also see that they are mostly derived from the same lower-resolution cluster. Therefore, it could be interesting to sub-cluster the spots assigned to these clusters:

library(dplyr)
subcluster <-
    result$clusters %>%
    filter(resolution == 4, cluster %in% c(1, 4)) %>%
    `$`("unit")
head(subcluster)
# > [1] "3x31"  "30x15" "23x22" "23x23" "23x26" "21x9"

subclusterResult <- runCPie(
    counts = counts[, subcluster],
    image = tissue,
    spotCoordinates = spots
)
subclusterResult$treePlot

The cluster tree indicates that we appear to pick up three different clusters of stromal cells: In resolution 4, clusters 2 and 3 are mostly derived from the same parent cluster and their colors indicate that their expression profiles are similar. In contrast, there is still a clear separation between the clusters in resolution 3. Staking out the spatial and transcriptional differences between these three clusters appears to be a good basis for further analysis.

subclusterResult$piePlots$`3`