In saezlab/mistyR: Multiview Intercellular SpaTial modeling framework

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Introduction

The use of mistyR is conceptualized around building a workflow for analysis of spatial omics data by four classes of functions:

[View composition]
[Model training]
[Result processing]
[Plotting]

To construct a workflow r BiocStyle::Githubpkg("saezlab/mistyR") is designed with the use of pipe operators (for example the operator %>% from r BiocStyle::CRANpkg("magrittr")) for chaining functions in mind.

When loading r BiocStyle::Githubpkg("saezlab/mistyR") please consider configuring a future::multisession() parallel execution plan. r BiocStyle::Githubpkg("saezlab/mistyR") will then use all available cores for execution of computationally demanding functions. It is recommended that the user modifies the future::plan() according to their needs.

# MISTy
library(mistyR)
library(future)

# data manipulation
library(dplyr)
library(purrr)
library(distances)

# plotting
library(ggplot2)

plan(multisession)

The following example uses the synthetically generated benchmark data synthetic that is included in the package. The dataset is a list of 10 tibbles, each representing data generated from a random layout of four cell types and empty space on a 100-by-100 grid.

The data was generated by simulating a two-dimensional cellular automata model that focuses on signaling events. The model simulates the production, diffusion, degradation and interactions of 11 molecular species. Note that the dataset contains simulated measurements only for the non-empty spaces.

{width="300px"}

data("synthetic")

ggplot(synthetic[[1]], aes(x = col, y = row, color = type)) +
  geom_point(shape = 15, size = 0.7) +
  scale_color_manual(values = c("#e9eed3", "#dcc38d", "#c9e2ad", "#a6bab6")) +
  theme_void()

str(synthetic[[1]], give.attr = FALSE)

For more information about the underlying model and data generation see help(synthetic) or the [publication].

View composition

The r BiocStyle::Githubpkg("saezlab/mistyR") workflow always starts by defining an intraview (create_initial_view()) containing measurements of the markers that are the target of the modeling at each cell of interest. For the first sample from the synthetic dataset we select all markers except for the ligands for all available cells.

expr <- synthetic[[1]] %>% select(-c(row, col, type, starts_with("lig")))

misty.intra <- create_initial_view(expr)

summary(misty.intra)
summary(misty.intra$intraview)

From the intrinsic view (intraview)[^1] r BiocStyle::Githubpkg("saezlab/mistyR") will model the expression of each marker as a function of the expression of other markers within the cell. We are interested in exploring marker expressions coming from different spatial contexts that are complementary, i.e., that are distinguishable and contribute to the explanation of the overall expression of the markers.

[^1]: You will notice that misty.intra contains an element named misty.uniqueid that is used for caching. If not provided, this id is automatically generated.

r BiocStyle::Githubpkg("saezlab/mistyR") includes two default helper functions for calculating and adding views that take into account the spatial context of the data: add_juxtaview() and add_paraview(). The juxtaview represent a local spatial view and captures the expression of all markers available in the intraview within the immediate neighborhood of each cell. The paraview captures the expression of all markers avainalbe in the intraview in the boarder tissue structure where the importance of the influence is proportional to the inverse of the distance between two cells. To add a paraview in the view composition, we first need information about the location of each cell from the intraview. Using this information we can create and add a paraview with importance radius of 10 to the view composition.

pos <- synthetic[[1]] %>% select(row, col)

misty.views <- misty.intra %>% add_paraview(pos, l = 10)

summary(misty.views)

The calculation of a juxtaview and a paraview can be computationally intensive when there are a large number of cells in the sample. Therefore the calculation is run in parallel with the set future::plan(). The computational time needed for the calculation of the paraview can also be significantly reduced by approximation. Refer to the documentation of this function (help(add_paraview)) for more details.

Other relevant and custom views can be created (create_view()) from an external resource (data.frame, tibble) and added to the view composition. The data should contain and one row per cell in order as in the intraview. For example we can create a view that captures the mean expression of the 10 nearest neighbors of each cell.

# find the 10 nearest neighbors
neighbors <- nearest_neighbor_search(distances(as.matrix(pos)), k = 11)[-1, ]

# calculate the mean expression of the nearest neighbors for all markers
# for each cell in expr
nnexpr <- seq_len(nrow(expr)) %>%
  map_dfr(~ expr %>%
    slice(neighbors[, .x]) %>%
    colMeans())

nn.view <- create_view("nearest", nnexpr, "nn")

nn.view

The created view(s) can be added (add_views()) to an existing view composition one by one or by providing them in a form of a list. Other examples of creating and adding custom views to the composition can be found in the resources in [See also].

extended.views <- misty.views %>% add_views(nn.view)

summary(extended.views)

Views can also be removed from the composition by providing one or more names of views to remove_views(). The intraview and misty.uniqueid cannot be removed with this function.

extended.views %>%
  remove_views("nearest") %>%
  summary()

extended.views %>%
  remove_views("intraview") %>%
  summary()

Model training

Once the view composition is created, the model training is managed by the function run_misty(). By default, models are trained for each marker available in the intraview for each view independently. The results of the model training will be stored in a folder named "results".

misty.views %>% run_misty()

The workflow that we used for the first sample from the synthetic dataset can be easily extended to be applied to all 10 samples to completely reproduce one of the results reported in the [publication]. The results for each sample will be stored in a subfolder of the folder "results".

result.folders <- synthetic %>% imap_chr(function(sample, name) {
  sample.expr <- sample %>% select(-c(row, col, type, starts_with("lig")))
  sample.pos <- sample %>% select(row, col)

  create_initial_view(sample.expr) %>% add_paraview(sample.pos, l = 10) %>%
    run_misty(results.folder = paste0("results", .Platform$file.sep, name))
})

result.folders

Note that by default, r BiocStyle::Githubpkg("saezlab/mistyR") caches calculated views[^2] and trained models, such that in case of repeated running of the workflow they will be retrieved instead of recalculated, thus saving significant computational time. However, the size of the generated cache files can be large. Therefore, the functions that can work with cached files, such as run_misty(), have parameter named cached that can be set to FALSE. Additionally the function clear_cache() provides means to remove cache files.

[^2]: juxtaview and paraview calculated and added by add_juxtaview() and add_paraview() respectively

Result processing

The raw r BiocStyle::Githubpkg("saezlab/mistyR") results are stored in several text files in the output folder for each analyzed sample. The results from one or more samples can be collected, aggregated and coverted to an R object with the function collect_results(), by providing path(s) to folder(s) containing results generated by run_misty().

misty.results <- collect_results(result.folders)

summary(misty.results)

See help(collect_results) for more information on the structure of misty.results.

Plotting

MISTy gives explanatory answers to three general questions. Each question can be answered by looking at the corresponding plot.

1. How much can the broader spatial context explain the expression of markers (in contrast to the intraview)?

This can be observed in the gain in R2 (absolute percentage) (or relative percentage of decrease RMSE) of using the multiview model in contrast to the single intraview only model.

misty.results %>%
  plot_improvement_stats("gain.R2") %>%
  plot_improvement_stats("gain.RMSE")

We can further inspect the significance of the gain in variance explained, by the assigned p-value of improvement based on cross-validation.

misty.results$improvements %>%
  filter(measure == "p.R2") %>%
  group_by(target) %>% 
  summarize(mean.p = mean(value)) %>%
  arrange(mean.p)

In general, the significant gain in R2 can be interpreted as the following:

"We can better explain the expression of marker X, when we consider additional views, other than the intrinsic view."

2.How much do different view components contribute to explaining the expression?

misty.results %>% plot_view_contributions()

As expected most of the contribution to the prediction of the expression of the markers comes from the intraview. However for the markers that we observed significant improvement of variance we can also observe a proportional estimated contribution of the paraview.

3.What are the specific relations that can explain the contributions?

To explain the contributions, we can visualize the importances of markers coming from each view separately as predictors of the expression of all markers.

First, the intraview importances.

misty.results %>% plot_interaction_heatmap(view = "intra", cutoff = 0.8)

These importances are associated to the relationship between markers in the same cell. As we didn't use the information about the cell types in any way during the process of modeling the significant interactions that we see in the heatmap may come from any of the cell types.

Second, the paraview importances.

misty.results %>% plot_interaction_heatmap(view = "para.10", cutoff = 0.5)

These importances are associated to the relationship between markers in the cell and markers in the broader structure (controlled by our parameter l).

We can observe that some interactions in the paraview might be redundant, i.e., they are also found to be important in the intraview. To focus on the interactions coming from the paraview only we can plot the contrast between these results.

misty.results %>% plot_contrast_heatmap("intra", "para.10", cutoff = 0.5)

Futhermore, since the predictor and target markers in both views are the same, we can plot the interaction communities that can be extracted from the estimated interaction pairs from the intraview

misty.results %>% plot_interaction_communities("intra")

and the paraview.

misty.results %>% plot_interaction_communities("para.10", cutoff = 0.5)

When interpreting the results and the plots it is important to note that the relationships captured in the importances are not to assumed or interpreted as linear or casual. Furthermore, the estimated importance of a single predictor - marker pair should not be interpreted in isolation but in the context of the other predictors, since training MISTy models is multivariate predictive task.