---
title: " LIANA Orthology Conversion"
author:
  - name: Daniel Dimitrov
    affiliation:
        - Saezlab, Heidelberg University
    email: daniel.dimitrov@uni-heidelberg.de
date: "`r Sys.Date()`"
output: 
  BiocStyle::html_document:
      self_contained: true
      toc: true
      toc_float: true
      toc_depth: 3
      code_folding: show
vignette: >
  %\VignetteIndexEntry{Homology Conversion with LIANA}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

LIANA's OmniPath resource was largely compiled from CCC databases with a human focus,
as such LIANA works with human gene symbols by default.

Nevertheless, one could run LIANA with any other organism, provided a dictionary
is available to map human genesymbols to those of species X.

In this vignette, we provide an example how this could be achieved using the [`HomoloGene`](https://www.ncbi.nlm.nih.gov/homologene)
database via OmnipathR with LIANA's `generate_homologs` function. 

Note that LIANA provides a mouse Consensus (MouseConsensus) resource, using the 
homology-conversion approach described here.


## Loading prerequisites
```{r load_prereq, message=FALSE, warning=FALSE}
library(tidyverse)
library(OmnipathR)
library(liana)
library(magrittr)

liana_path <- system.file(package = "liana")
testdata <-
    readRDS(file.path(liana_path, "testdata", "input", "testdata.rds"))

# Convert testdata to putative mouse symbols
# Note that we explicitly provide this tutorial to avoid any such conversions when working with real data
# We simply do this here to provide an example
rownames(testdata@assays$RNA@counts) <- stringr::str_to_title(rownames(testdata@assays$RNA@counts))
rownames(testdata@assays$RNA@data) <- stringr::str_to_title(rownames(testdata@assays$RNA@data))
```

It is also recommended to ensure that you have the latest OmnipathR version installed:
```{r omni, eval=FALSE}
remotes::install_github("saezlab/OmnipathR")
```


## Internally available organisms

LIANA's `generate_homologs` function uses OmnipathR's `homologene_download` 
function to obtain a human to x species dictionary.

Here, we check the organisms which are currently available.

One must simply choose the `ncbi_taxid` and pass it as `target_organism` parameter
to the `generate_homologs` function below.
```{r show_taxid}
show_homologene()
```


## Convert to Orthologues and Example LIANA run
```{r orthology, warning=FALSE, message=FALSE, fig.width=11, fig.height=8}
# Here, we will convert LIANA's Consensus resource to murine symbols
op_resource <- select_resource("Consensus")[[1]]

# Generate orthologous resource
ortholog_resource <- generate_homologs(op_resource = op_resource,
                                       target_organism = 10090) # mouse

# Run LIANA with the orthologous resource
liana_res <- liana_wrap(testdata,
                        resource = 'custom', # resource has to be set to 'custom' to work with external resources
                        external_resource = ortholog_resource, # provide orthologous resource
                        method=c('sca', 'natmi') # run only with sca and natmi for comp. time
                        )

# aggregate
liana_res <- liana_res %>%
    liana_aggregate()

# Plot example
liana_res %>%
    filter(source=="B") %>%
    filter(target %in% c("NK", "CD8 T")) %>%
    liana_dotplot(source_groups = "B",
                  target_groups = c("NK", "CD8 T"),
                  ntop = 15)
```


Conversion is trickier than anticipated. In the sense that, there will be genes
without matching homologs, while others will have multiple matching homologs.
These issues are further complicated when working with complexes, as is the case
for the interactions in LIANA. Some ligandâ€“receptor interactions can also 
be species-specific. 

Thus, we suggest that if possible to check literature for support of the predicted
edges when using orthology conversion.

Notably, the `generate_homologs` function was designed to be very flexible,
but by default will be relatively conservative. So, please refer to its
documentation for more information.



## Generating an External Dictionary
In order to convert a human resource to any other organism, we need a dictionary
which maps human gene symbols to their orthologs from another species, which 
might not be available via OmniPath. 

An alternative widely used database for this purpose is [BioMart](https://www.ensembl.org/biomart/martview/ef9109352b17a0704bd49683fe42ac81).


## An example dictionary (generated /w homologene) for murine symbols is included in liana
```{r hidden_load, warning=FALSE, message=FALSE}
symbols_dict <- readRDS(file.path(liana_path, "human_mouse_orthologues.RDS"))
head(symbols_dict)
```

One can then simply pass the `symbols_dict` to the `symbols_dict` param to
`generate_homologs`, instead of specifying a tax id in `target_organism`.

Automatic conversion comes with some limitation, we thus also refer the user to
external curated databases (e.g. murine CellChatDB), which can also be used 
with LIANA.
