README.Rmd

---
output: github_document
---

# TIGER

## Introduction
The goal of TIGER is to estimate gene regulatory network and transcription factor 
activities using Bayesian matrix factorization.        
![](TIGER.png)<!-- -->              
Please read and cite the following article when you use TIGER:     
[Joint inference of transcription factor activity and context-specific regulatory networks, Chen&Padi 2022](https://www.biorxiv.org/content/10.1101/2022.12.12.520141v1)

## Installation

TIGER relies on [cmdstanr](https://mc-stan.org/cmdstanr/) for Beyesian Inference. 
You can install the latest beta release of the cmdstanr R package with
``` {r,eval=FALSE}
install.packages("cmdstanr", repos = c("https://mc-stan.org/r-packages/", getOption("repos")))
```
Then, you can use cmdstanr to install [CmdStan](https://mc-stan.org/users/interfaces/cmdstan.html), the shell interface to [Stan](https://mc-stan.org/) with
``` {r,eval=FALSE}
cmdstanr::install_cmdstan()
```
These two steps are usually enough if your C++ toolchain is set up properly. For example, use RTools 4.0 toolchain which contains a g++ 8 compiler and mingw32-make on Windows platform. If you see problems with installation, you can go to cmdstanr [installation](https://mc-stan.org/cmdstanr/articles/cmdstanr.html) for more information.     

After cmdstan is correctly installed, you can install the development version of TIGER with:
``` {r,eval=FALSE}
devtools::install_github("cchen22/TIGER")
```

## Quick start

This is a simple example of TIGER on a small dataset. TIGER requires two inputs -      
1. a normalized expression matrix with rows as genes and column as samples;       
2. a prior network with rows as TFs and column as genes. The network is signed and binarized (e.g., -1,0,1).       

```{r example}
library(TIGER)

##1. load data
expr = TIGER::expr
prior = TIGER::prior

##2. run TIGER with default parameters
ss = TIGER(expr,prior)

##3. print the TFA score in first three samples
tgres = ss$Z
tgres[,1:3]
```

## Wokring with DoRothEA prior
TIGER provides some convenient functions to work with DoRothEA prior database. Firstly, install DoRothEA R package from [Bioconductor](https://bioconductor.org/packages/release/data/experiment/html/dorothea.html)

```{r, eval=FALSE}
BiocManager::install("dorothea")
```
DoRothEA provides regulons for two species - human and mouse. For example,if we have a human cancer expression matrix and want to estimate the TFA in each cancer sample, then we can use the following code to prepare the prior network.

```{r convenient functions}
## load dorothea pancancer database
df = dorothea::dorothea_hs_pancancer

## convert it to TIGER prior format (e.g., adjacency matrix) 
prior = el2adj(df[,-2])
```