---
title: "Introduction to SelectSim"
author: "Arvind Iyer"
email: "arvind.iyer@unil.ch"
date: "`r Sys.Date()`"
output: 
 rmarkdown::html_vignette:
    css: doc.css
vignette: >
  %\VignetteIndexEntry{Introduction to SelectSim}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

SelectSim infers evolutionary dependencies — co-mutations and mutual exclusivities — between functional alterations across cancer genomes. It estimates expected co-mutation frequencies from individual gene mutation rates and per-sample tumor mutation burden (TMB), then evaluates significance against a permutation null model.

![SelectSim Method](SelectSim_method.png)

This package accompanies the manuscript: Iyer A, Mina M, Petrovic M, Ciriello G (2026). *Evolving patterns of co-mutations from tumor initiation to metastatic progression.* Nature Genetics.

### Installation

- You can install the development version of SelectSim from [GitHub](https://github.com/CSOgroup/SelectSim) with:

``` r
devtools::install_github("CSOgroup/SelectSim",dependencies = TRUE, build_vignettes = TRUE)
```

- For more details on installation refer to [INSTALLATION](https://github.com/CSOgroup/SelectSim/blob/main/INSTALLATION.md)

### Example

- We will run SelectSim algorithm on processed LUAD dataset from TCGA provided with the package.
- Note: This is an example for running a processed data. Check other vignette to process the data to create the run_data object needed as input for SelectSim algorithm.

```{r}
library(SelectSim)
library(dplyr)
## Load the data provided with the package
data(luad_run_data, package = "SelectSim")
```
#### Data Description & Format

- The loaded data is list object which consists of 
  - M: a list object of GAMs which is presence absence matrix of alterations
  - tmb: a list object of tumor mutation burden as data frame with column names (should be) as sample and mutation
  - sample.class a named vector of sample annotations
  - alteration.class a named vector of alteration annotations

```{r}
# Check the data structure
str(luad_run_data)
```

#### Running SelectSim
- We use the function `selectX()` which generates the background model and results.

| Parameter | Description |
|-----------|-------------|
| `M` | List of GAMs and TMB matrices |
| `sample.class` | Named vector of sample covariates |
| `alteration.class` | Named vector of alteration covariates |
| `min.freq` | Minimum number of samples a feature must be mutated in |
| `n.permut` | Number of permutations for the null model |
| `lambda` | Penalty factor for the weight computation |
| `tau` | Fold change threshold for the weight computation |
| `maxFDR` | FDR cutoff for calling significant results |

- The function returns a list object which contains the background model and results.

```{r}
result_obj<- SelectSim::selectX(  M = luad_run_data$M,
                      sample.class = luad_run_data$sample.class,
                      alteration.class = luad_run_data$alteration.class,
                      n.cores = 1,
                      min.freq = 10,
                      n.permut = 1000,
                      lambda = 0.3,
                      tau = 1,
                      save.object = FALSE,
                      verbose = FALSE,
                      estimate_pairwise = FALSE,
                      maxFDR = 0.25)
```

#### Interpreting the results
- Lets look into the results
```{r}
head(result_obj$result[,1:10],n=5)
```

##### Filtering significant hits
```{r}
# Filtering significant hits and counting EDs
result_obj$result %>% filter(nFDR2<=0.25) %>% head(n=2)
result_obj$result %>% filter(nFDR2<=0.25) %>% count(type)
```
##### Plotting a scatter plot of co-mutation
```{r}
# Filtering significant hits and plotting
obs_exp_scatter(result = result_obj$result,title = 'TCGA LUAD')
```


### Session information
```{r}
# Print the sessionInfo
sessionInfo()
```