---
title: "`FeatSeekR` user guide"
author: 
-   name: Tuemay Capraz
    affiliation: European Molecular Biology Laboratory, Heidelberg
    email: tuemay.capraz@embl.de
package: FeatSeekR
date: "`r Sys.Date()`"
output:  
    BiocStyle::html_document:
        toc_float: true
vignette: >
    %\VignetteIndexEntry{`FeatSeekR` user guide}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignettePackage{FeatSeekR-vignette}
    %\VignetteEncoding{UTF-8}
---



```{r setup, message=FALSE}
library(FeatSeekR)
library(pheatmap)
library(SummarizedExperiment)
```


# Introduction

A fundamental step in many analyses of high-dimensional data is dimension 
reduction. Feature selection is one approach to dimension reduction whose 
strengths include interpretability, conceptual simplicity, transferability 
and modularity.
Here, we introduce the `FeatSeekR` algorithm, which selects features based on 
the consistency of their signal across replicates and their non-redundancy.
It takes a 2 dimensional array (features x samples) of replicated measurements
and returns a `r Biocpkg("SummarizedExperiment")` object storing the selected 
features ranked by reproducibility.

# Installation

```{r, eval=FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("FeatSeekR")
```

# Feature selection on simulated data

Here we simulate a data set with features generated by orthogonal latent 
factors. Features derived from the same latent factor are highly redundant and 
form distinct clusters. The function \code{simData} simulates 10 redundant 
features per latent factor. Replicates are generated by adding independent 
Gaussian noise.

```{r simulate data}
set.seed(111)
# simulate data with 500 conditions, 3 replicates and 5 latent factors 
conditions <- 500
latent_factors <- 5
replicates <- 3

# simData generates 10 features per latent_factor, so choosing latent_factors=5
# will generate 50 features.
# we simulate samples from 500 independent conditions per replicate. setting 
# conditions=500 and replicates=3 will generate 1500 samples, leading to 
# final data dimensions of 50 features x 1500 samples
sim <- simData(conditions=conditions, n_latent_factors=latent_factors,
                replicates=replicates)

# show that simulated data dimensions are indeed 50 x 1500 
dim(assay(sim, "data"))

# calculate the feature correlation for first replicate
data <- t(assay(sim, "data"))
cor <- cor(data, use = "pairwise.complete.obs")

# plot a heatmap of the features and color features according to their 
# generating latent factors
anno <- data.frame(Latent_factor = as.factor(rep(1:5, each=10)))
rownames(anno) <- dimnames(sim)[[1]]
colors        <- c("red", "blue", "darkorange", "darkgreen", "black")
names(colors) <- c("1", "2", "3", "4", "5")
anno_colors <- list(Latent_factor = colors)
range <- max(abs(cor))
pheatmap(cor, treeheight_row = 0 , treeheight_col = 0, 
        show_rownames = FALSE, show_colnames = FALSE,
        breaks = seq(-range, range, length.out = 100), cellwidth = 6, 
        cellheight = 6, annotation_col = anno, annotation_colors = anno_colors, 
        fontsize = 8)
```
We first plot the correlation matrix of the data to visualize feature 
redundancy. As intended by the simulation, the features derived from the 
same latent factor cluster together. This suggests that the true dimension is
indeed lower than the number of features.
We now run `FeatSeekR` to rank the features based on their uniqueness and
reproducibility.

```{r plot top 5}
# select the top 5 features
res <- FeatSeek(sim, max_features=5)

# plot a heatmap of the top 5 selected features 
plotSelectedFeatures(res)
```
We again visualize the selected features by plotting their correlation matrix.
As expected, the top 5 selected features are each from a different latent 
factor and low correlated. This suggests that we were able to obtain a 
compressed version of the data, while keeping most of the contained 
information.




# Session Info

```{r}
sessionInfo()
```