---
title: "Introduction to the kmeRs package"
author:
- name: Rafal Urniaz, PhD^[OncoCDx Research Center, London, UK]
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
  # pdf_document
  # md_document:
  #    variant: markdown_github
bibliography: citations.bib
vignette: >
  %\VignetteIndexEntry{Introduction to the kmeRs R package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

Similarity Score Matrix and HeatMap for nucleic and amino acid k-mers. Similarity score is evaluated by Point Accepted Mutation (PAM) and BLOcks SUbstitution Matrix (BLOSUM). Higher similarity score indicates more similar sequences for BLOSUM and less similar sequences for PAM matrix. The 30, 40, 70, 120, 250 and 62, 45, 50, 62, 80, 100 matrix versions are available for PAM and BLOSUM, respectively. Alignment is evaluated by Needleman-Wunsch [@NEEDLEMAN1970443] and Smith-Waterman  [@SMITH1981195]. 


### Load the package first
   
```{r} 
# Import the package 
  library(kmeRs)
```

### Example 1. How to display BLOSUM matrix used for amino acides calculation?

Simply apply the **kmeRs_similarity_matrix** function and mark the appropriate matrix, here BLOSUM62.  

```{r} 
# Simple BLOSUM62 similarity matrix for all amino acid nucleotides
  BLOSUM62 <- kmeRs_similarity_matrix(submat = "BLOSUM62")
# Fancy knitr table
  knitr::kable(BLOSUM62)
```

### Example 2. How to find the most *'different'* k-mer from the given set of k-mers?

In this example, the most *'different'* k-mer to "GATTACA" sequence will be indicated from given set of heptamers. Here, 7 heptamer (being an anagram of the movie title "GATTACA") are given, as follow:  

```{r} 
# Given hexamers
  kmers_given <- c("GATTACA", "ACAGATT", "GAATTAC", "GAAATCT", "CTATAGA", "GTACATA", "AACGATT")
# Matrix calculation 
  kmers_mat <- kmeRs_similarity_matrix(q = c("GATTACA"), x = kmers_given , submat = "BLOSUM62") 
# Fancy knitr table
  knitr::kable(kmers_mat) 
```

Now, applying **kmeRs_score** function the total score is calculated and the matrix is sorted by increasing score value. The lowest value (in case of BLOSUM) indicates the most *'different'* sequence from given k-mers, in contrast to the highest value which indicates the most similar one. 

```{r} 
# Score and sort the matrix  
  kmers_res <- kmeRs_score(kmers_mat)
# Fancy knitr table
  knitr::kable(kmers_res)
```

As can be observed, the most *'different'* sequence to GATTACA is ACAGATT with total score equal to 1 and the most similar to GATTACA sequence is of course GATTACA sequence with the highest score equal to 37. 

### Example 3. How to find the most *'different'* k-mer to whole given set of k-mers? 

In this example, the most *'different'* k-mer to whole given set of heptamers will be indicated. The same heptamers as in example 2 are used. 

```{r} 
# Given hexamers
  kmers_given <- c("GATTACA", "ACAGATT", "GAATTAC", "GAAATCT", "CTATAGA", "GTACATA", "AACGATT")
# Matrix calculation 
  kmers_mat <- kmeRs_similarity_matrix(q = kmers_given, submat = "BLOSUM62")
# Score the matrix and sort by decreasing score 
  kmers_res <- kmeRs_score(kmers_mat)
# Fancy knitr table
  knitr::kable(kmers_res)
  
```

As can be observed, the most *'different'* sequence to all given heptamers is CTATAGA with score equal to 62 and the most similar sequence is GAAATCT with the highest score equal to 97.

### Example 4. How to calculate basic statistics for the matrix?

Applying function **kmeRs_statistics** to the result matrix the basic statistics can be calculated as additional rows. When **summary_statistics_only** is set to TRUE only summary table is returned. It is much more elegant way to present results, especially in case of *'big data'* output.  

```{r}
# Calculate stats 
  kmers_stats <- kmeRs_statistics(kmers_res)
# Fancy knitr table
  knitr::kable(kmers_stats[ ,1:(dim(kmers_stats)[2] - 4) ])
```

### Example 5. How to display a similarity matrix as a heatmap?

Simply applying function **kmeRs_heatmap** to the result matrix.

```{r}
# Heatmap without sum column
  kmeRs_heatmap(kmers_res[, -8])  
```



### Acknowledgement

Special thanks to Jason Lin, PhD from Chiba Cancer Center Research Institute, Chiba, Japan for contribution in 2021 as implementing of heatmap function and update deprecated functions. 

## References