---
title: "An Introduction to sangeranalyseR"
author: "Author: Kuan-Hao Chao (u7022787@anu.edu.au)"
date: "Last update: `r format(Sys.time(), '%d %B, %Y')`"
output: 
  BiocStyle::html_document:
    toc_float: true
    code_folding: show
    fig_caption: yes
  BiocStyle::pdf_document: default
#bibliography: bibliography.bib
fontsize: 14pt
vignette: >
  %\VignetteIndexEntry{sangeranalyseR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\usepackage[utf8]{inputenc}
  %\VignettePackage{sangeranalyseR}
---
```{r style, echo=FALSE, results="asis", message=FALSE}
BiocStyle::markdown()
knitr::opts_chunk$set(tidy = FALSE,
                      warning = FALSE,
                      message = FALSE)
```

```{r}
library(sangeranalyseR)
```

# Introduction
[sangeranalyseR](https://github.com/roblanf/sangeranalyseR) is an R package for analysing Sanger sequencing reads, especially those from ABIF platform, in pure R environment. There are three levels in [sangeranalyseR](https://github.com/roblanf/sangeranalyseR) which are ***'SangerRead'***, ***'SangerContig'*** and ***'SangerAlignment'***. Users can choose which level to start the analysis. In this documentation, we intoduce analysis workflow step by step in these three levels with examples.

# **SangerRead**
***'SangerRead'*** extends from 'sangerseq' class and stores 'abif' class in [sangerseqR](https://bioconductor.org/packages/release/bioc/html/sangerseqR.html) as well as essential information including quality trimming and chromatogram parameters. It corresponds to a single ABIF file in Sanger sequencing. 

<details class="description"><summary data-open="CLOSE" data-close="MORE DETAILS"></summary>

<h2> 2.1 &nbsp;&nbsp;&nbsp;&nbsp; Create **SangerRead** Instance </h2>
First step is to create a ***'SangerRead'*** instance. Here, we find the the abosulte file path and assign it to `A_chloroticaFdReadFN`.
```{r}
inputFilesPath <- system.file("extdata/", package = "sangeranalyseR")

A_chloroticaFdReadFN <- file.path(inputFilesPath, 
                          "Allolobophora_chlorotica",
                          "RBNII",
                          "Achl_RBNII396-13_1_F.ab1")
```

Now we can create a **'SangerRead'** instance by running `SangerRead` constructor function. 
```{r}
singleRead <- SangerRead(readFeature   = "Forward Read",
                         readFileName  = A_chloroticaFdReadFN)
```

<h2> 2.2 &nbsp;&nbsp;&nbsp;&nbsp; Visualize Trimmed Read </h2>

Second step is to visualize the trimmed read. `qualityBasePlot` triggers a [plot_ly](https://plot.ly/r/) interactive plot for users to check the result of the trimmed read.

<div style="overflow: scroll;">
```{r}
qualityBasePlot(singleRead)
```
</div>

<h2> 2.3 &nbsp;&nbsp;&nbsp;&nbsp; Update Trimming Parameters </h2>
Third step is to change trimming parameters. `SangerRead` constructor function uses default trimming parameters. If users are not satisfied with the trimming result, they can run `updateQualityParam` function to change the trimming parameters inside the ***'SangerRead'*** instance.
```{r  results="hide"}
updateQualityParam(singleRead,
                   TrimmingMethod         = "M1",
                   M1TrimmingCutoff       = 0.0003,
                   M2CutoffQualityScore   = NULL,
                   M2SlidingWindowSize    = NULL)
```

<h2> 2.4 &nbsp;&nbsp;&nbsp;&nbsp; Write FASTA file </h2>
Fourth step is to export DNA sequence to FATA file. `writeFastaSR` let users to write read in ***'SangerRead'*** instance to file in FASTA format.
```{r}
writeFastaSR(singleRead)
```

<h2> 2.5 &nbsp;&nbsp;&nbsp;&nbsp; Generate Report </h2>
Fifth step is to create a static html report for ***'SangerRead'*** instance by running `generateReportSR` function
```{r eval=FALSE}
generateReportSR(singleRead)
```

</details>

---


# **SangerContig**
***'SangerContig'*** contains two lists of ***'SangerRead'*** which are forward and reverse read list. It also contains alignment results and consensus read. It corresponds to a contig in Sanger sequencing.

<details class="description"> <summary data-open="CLOSE" data-close="MORE DETAILS"></summary>

<h2> 3.1 &nbsp;&nbsp;&nbsp;&nbsp;  Create **SangerContig** Instance </h2>
First step is to prepare all reads in the same directory and define the project parameters.  

* `inputFilesParentDir` is the directory storing all raw ABIF files. 
* `contigName` is the name of contigs. All targets share the same contig name.
* `suffixForwardRegExp` is the regular expression for forward read suffix.
* `suffixReverseRegExp` is the regular expression for reverse read suffix. 

```{r}
rawDataDir <- system.file("extdata", package = "sangeranalyseR")
inputFilesParentDir <- file.path(rawDataDir, "Allolobophora_chlorotica", "ACHLO")
contigName <- "Achl_ACHLO006-09"
suffixForwardRegExp <- "_[0-9]*_[F].ab1"
suffixReverseRegExp <- "_[0-9]*_[R].ab1"
```
After defining parameters, users can create ***'SangerContig'*** instance by running `SangerContig` constructor function.
```{r}
sangerContig <- SangerContig(parentDirectory      = inputFilesParentDir,
                             contigName           = contigName,
                             suffixForwardRegExp  = suffixForwardRegExp,
                             suffixReverseRegExp  = suffixReverseRegExp)
```

<h2> 3.2 &nbsp;&nbsp;&nbsp;&nbsp; Launch Shiny App </h2>
Second step is to trigger ***'SangerContig'*** Shiny app. In `SangerContig` constructor function, all forward and reverse reads in this contig share the same trimming parameter by default. It is inconvenient for users to check reads one by one through R command; therefore, we provide a local Shiny app to let users easily browse and change parameters in each read in the ***'SangerContig'*** instance.
```{r eval=FALSE}
launchAppSC(sangerContig)
```

<h2> 3.3 &nbsp;&nbsp;&nbsp;&nbsp; Write FASTA file </h2>
Third step is to export DNA sequence to FATA file. After changing trimming parameters in each read, users can run `writeFastaSC` function to write results into text file in FASTA format.
```{r}
writeFastaSC(sangerContig)
```

<h2> 3.4 &nbsp;&nbsp;&nbsp;&nbsp; Generate Report </h2>
Fourth step is to create a report. Users can create a static html report for the ***'SangerContig'*** instance by running `generateReportSC` function.
```{r eval=FALSE}
generateReportSC(sangerContig)
```

</details>

---

# **SangerAlignment**
***'SangerAlignment'*** contains a list of ***'SangerContig'*** and the alignment results for all contigs. It corresponds to a rebuild DNA sequence fragment in Sanger sequencing. 

<details class="description"> <summary data-open="CLOSE" data-close="MORE DETAILS"></summary>

<h2> 4.1 &nbsp;&nbsp;&nbsp;&nbsp; Create **SangerAlignment** Instance </h2>
First step is to prepare all reads in the same directory and define the project parameters.  

* `inputFilesParentDir` is the directory storing all raw ABIF files. 
* `suffixForwardRegExp` is the regular expression for forward read suffix.
* `suffixReverseRegExp` is the regular expression for reverse read suffix. 

```{r}
rawDir <- system.file("extdata", package="sangeranalyseR")
parentDir <- file.path(rawDir, "Allolobophora_chlorotica", "RBNII")
suffixForwardRegExp <- "_[F]_[0-9]*.ab1"
suffixReverseRegExp <- "_[R]_[0-9]*.ab1"
```
Users can create ***'SangerAlignment'*** instance by running `SangerAlignment` constructor function.
```{r  eval=FALSE}
sangerAlignment <- 
        SangerAlignment(parentDirectory = parentDir,
                        suffixForwardRegExp = suffixForwardRegExp,
                        suffixReverseRegExp = suffixReverseRegExp,)
```

<h2> 4.2 &nbsp;&nbsp;&nbsp;&nbsp; Launch Shiny App </h2>
Second step is to run `launchAppSA` to trigger the local ***'SangerAlignment'*** Shiny app. Users can easily browse all ***'SangerContig'*** instance in ***'SangerAlignment'*** and change ***'SangerRead'*** trimming parameters in each ***'SangerContig'*** instance.

```{r eval=FALSE}
launchAppSA(sangerAlignment)
```

<h2> 4.3 &nbsp;&nbsp;&nbsp;&nbsp; Write FASTA file </h2>
Third step is to run `writeFastaSC` function to write results into text file in FASTA format.
```{r  eval=FALSE}
writeFastaSA(sangerAlignment)
```

<h2> 4.4 &nbsp;&nbsp;&nbsp;&nbsp; Generate Report </h2>
Fourth step is to create a report. Users can create a static html report for the ***'SangerAlignment'*** instance by running `generateReportSA` function.
```{r eval=FALSE}
generateReportSA(sangerAlignment)
```

</details>

---


<style>
details.description[open] summary::after {
  content: attr(data-open);
  color: #d45050;
  border-bottom: 2px solid #d45050;
}

details.description:not([open]) summary::after {
  content: attr(data-close);
  color: #4c9c6b;
  border-bottom: 2px solid #4c9c6b;
}

.description {
border-left: 4px solid #d3d6db;
padding-left: 10px;
}
.description summary{
  font-weight: bold;
  font-size: 10px;
  color: #383838;
}
</style>