---
title: "Modeling spatially resolved omics with mistyR"
author:
- name: Jovan Tanevski
  affiliation: 
  - Heidelberg University and Heidelberg University Hospital, Heidelberg, Germany
  - Jožef Stefan Institute, Ljubljana, Slovenia
  email: jovan.tanevski@uni-heidelberg.de
date: "`r Sys.Date()`"
package: mistyR
resource_files:
  - sm.svg
output:
  BiocStyle::html_document:
    toc_float: true
    df_print: kable
vignette: >
  %\VignetteIndexEntry{Getting started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
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.

```{r setup, message=FALSE}
# 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.

![](sm.svg){width="300px"}

```{r fig.height=2.5, fig.width=3.5}
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.

```{r}
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.

```{r}
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.

```{r}
# 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].

```{r}
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.

```{r}
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".

```{r}
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".

```{r}
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()`.

```{r}
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.

```{r, warning=FALSE}
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.

```{r}
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?**

```{r}
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.

```{r}
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.

```{r}
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.

```{r}
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*

```{r}
misty.results %>% plot_interaction_communities("intra")
```

and the *paraview*.

```{r}
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.


# See also {-}

## More examples {-}

`browseVignettes("mistyR")`

[Online articles](https://saezlab.github.io/mistyR/articles/)

## Publication {-}

*`r format(citation("mistyR"), "textVersion")`*

# Session info {-}

Here is the output of `sessionInfo()` at the point when this document was compiled:

```{r info, echo=FALSE}
sessionInfo()
```

```{r cleanup, include=FALSE}
unlink("results", recursive = TRUE)
```