saaps 1.4.1
Single Amino Acids Polymorphism Statistics
Keywords: SAP, Information Entropy, OneHot Encoding, Dimension Reduction

# SAAPS
Single Amino Acids Polylimorphism Statistics (SAAPS) is a Python3-based character interface program that can be used and deployed on multiple systems, including Windows, Linux, and MacOS. The software is mainly used to quickly calculate single amino acid polymorphism (SAP), Shannon information entropy at each site of the sequence, and to analyze sequence features and cluster analysis by using Onehot encoding and dimensionality reduction algorithms.

The raw input file of the SAAPS software is very simple, as long as the sequence file after alignment (nucleotide or amino acid), it can be used for processing and analysis. The main workflow of SAAPS is as follows: Firstly, by analyzing the characteristics of each sequence, the SAPs and Shannon information entropy of each point are calculated, and the corresponding result figures can be drawn at the same time. Then SAAPS screens the key sites according to the specified information entropy range, and transforms them into quantificable data by using Onehot encoding. Finally, the certain dimensionality reduction algorithm (PCA or t-SNE) is used to calculate the similarity level between sequences and draw the clustering scatter plot.

# 1. Download and install
SAAPS is developed via `Python 3`, and you can get and install in following ways.
### 1.1 Pip method
SAAPS has been distributed to the standard library pf PYPI, and can be easily installed by the tool `pip`.
```
pip install saaps
saaps -h
```
### 1.2 Local installation
In addition to the pip method, you can download and install it using the file `setup.py`.
You need to download the repository, and then run:
```
python setup.py install
saaps -h
```

# 2. Getting help
You can use "-h" or "--help" to get the help document. The following is a brief introduction to the each parameter of SAAPS:

**Input Options**
Parameter | Description
--------- | ----------
-i, --input | the path of input file
-sr, --shannon_result | the path of shannon result

**Basic Options**
Parameter | Description
--------- | ----------
-dg, --delete_gap | delete the columns containing gaps in sequences
-t, --translate | translate nucleotides to amino acids
-cs, --cut_start | the start fragment/site of target sequence
-ce, --cut_end | the end fragment/site of target sequence
-osn, --output_seq_name | output sequence names
-csn, --change_seq_name | change the sequence names

**Polymorphism Options**
Parameter | Description
--------- | ----------
-cp, --compute_ppm | compute polymorphism
-pp, --plot_ppm | plot polymorphism figure

**Plotting Options**
Parameter | Description
--------- | ----------
-fw, --figure_width | the width of figure
-fh, --figure_height | the height of figure
-fname, --figure_name | the name of figure
-c, --color | the palette of figure
-pac, --print_all_colors | print all sipported palettes
-dpi, --DPI | the dpi of the figure
-fm, --figure_format | the format of figure
-tp, --transparent | make the background of the figure transparent
-sl, --scatter_label | display scatter plot labels

**Shannon Entropy Options**
Parameter | Description
--------- | ----------
-sha, --shannon | compute shannon entropy
-smax, --shannon_max | the maximum of the shannon value (IC)
-smin, --shannon_min | the minimum of the shannon value (IC)
-pic, --plot_ic | plot IC scatter figure

**Dimension Reduction Options**
Parameter | Description
--------- | ----------
-oh, --onehot | OneHot Encoding
-pca, --PCA | dimensionality reduction by PCA
-tsne, --TSNE | dimensionality reduction by t-SNE
-tpp, --tSNE_perplexity | the perplexity in t_SNE, default is 3
-tlr, --tSNE_learn_rate | the learning rate in t_SNE, default is 200
-tni, --tSNE_n_iter | the n_iter in t_SNE, default is 5000
-trs, --tSNE_random_state | the random state in t_SNE, default is 1
-pc, --plot_cluster | plot clustering scatter plot

**Output Options**
Parameter | Description
--------- | ----------
-o, --output_dir | the directory path of output file, the default is the current user document folder
-pre, --prefix | the prefix of the output file name

# 3. Examples
This chapter uses the test data ('testSeq.txt' in the test folder) provided by the software as an example to describe the main functions of SAAPS. Note that all sample files in this manual are generated by the software using test data (**" testSeq.txt "**), and users can follow the tutorial to learn it before exploring other features on their own.
## 3.1 Preparation for raw materials
Users needs to prepare an alignment sequence file (nucleotide or amino acid file), the alignment process can be completed by MAFFT and other software, and the format of the sequence file after alignment should be "sequence name + (line/multiple lines) sequence body" structure. The aligned sequence file should look like this:

```
>TestSeqNo.1 Sequence1  
GPQSGAIYVG……LWLDEEAMEQ
>TestSeqNo.2 Sequence2
GPLGQQSGAV……LWLDDEVMEQ
...
```

## 3.2 Sequence preprocessing
Before the subsequent analysis, it is usually necessary to format the sequence, such as whether the nucleotide sequence needs to be translated into amino acids, whether the sequence name needs to be changed, and so on. This allows us to get the best results in the subsequent analysis and drawing. Here we use the example of modifying the sequence name:  
### 3.2.1 Output sequence names  

```
saaps -i your/seq/path -osn -o your/output/path
```  

**Code explaination**: `-i your/seq/path` indicates that the matched sequence file is passed. `-osn` indicates the sequence name in the output sequence file. By default, the output is in a `.csv` table. `-o your/output/path` indicates the output path. If this parameter is not specified, the result will be output in the default path.After the program is executed, a file named `SeqName.csv` will be generated, which can be used for users to modify the sequence names individually. It is recommended to save the modified new names in the second column, so that subsequent programs can modify the sequence names in batches. The format of the file is as follows:  

|Old_Name||
|---|---|
|>TestSeqNo.1 Sequence1||
|>TestSeqNo.1 Sequence2||
|...||  

### 3.2.2 Change sequence names  

```
saaps -i your/seq/path -csn your/names/file/path -o your/output/path
```
**Code explaination**:In this step, `-csn your/names/file/path` represents the matching table of the old and new names in the sequence, which is the table output in the previous step. The pairing table format for the sequence names is as follows:  

|Old_Name|New_Name|
|---|---|
|>TestSeqNo.1 Sequence1|>Seq1|
|>TestSeqNo.1 Sequence2|>Seq2|
|...|...|  

The modified sequence file is named "NewNameSeq.txt" by default. The comparison between the original sequence file and the modified sequence file is as follows:

|Old Seq File|New Seq File|
|---|---|
|>TestSeqNo.1 Sequence1|>Seq1|
|GPQSGAIYVG……LWLDEEAMEQ|GPQSGAIYVG……LWLDEEAMEQ|
|...|...|  

## 3.3 Polymorphism analysis  
Although SAAPS was developed only for the analysis of SAP, the basis of polymorphism analysis is statistical analysis of the symbols and frequencies of each site in the sequence, so SAAPS can also be applied to sequences such as nucleotides.

```
saaps -i your/seq/path -cp -pp -o your/output/path
```

**Code explaination**:`-csn your/names/file/path` represents the matching table of the old and new names in the sequence, which is the table output in the previous step. `-cp` represents to activate the computational polymorphism function. `-pp` represents that the polymorphism result is plotted.

The statistical result of polymorphism analysis will generate three files named `Concise_Result.txt`, `Detail_Result.txt`, and `Seq_Matrix.csv`. If the drawing parameter (`-pp`) is set, A resulting graph (default) named `SAPs.pdf` is generated accordingly. The main result files are explained as follows:  

**Concise_Result.txt**: a concise result of polymorphism analysis, which mainly records the frequency of amino acids at each site, and is also an input file for the subsequent calculation of information entropy at each point. The format is shown as follows (part) :

```
Site 1	(G, 15, 100.00%)			
Site 2	(K, 7, 46.67%)	(R, 1, 6.67%)	(C, 1, 6.67%)	…
…	…	…	…	…
```

**Detail_Result.txt**: detailed result of polymorphism analysis, which records the sequence name of each amino acid at each site. Its file content is shown below (part) :

|col1|col2|col3|coln|
|---|---|---|---|
|Site1|(G: All Sequences)|||
|Site2|(P: >Seq2,>Seq1)|(K: >Seq10,>Seq15,>Seq7,>Seq13,>Seq9,>Seq12,>Seq14)|...|
|Site3|(F: Most Sequences)|(L: >Seq2)|...|
|...|...|...|...|  

**Seq_Matrix.csv**: indicates the sequence amino acid matrix. The main contents of the table are as follows (part) :  

|Seq1|Seq2|Seq3|Seq4|Seq5|Seq6|Seq7|...|
|---|---|---|---|---|---|---|---|
|G|G|G|G|G|G|G|...|
|P|P|A|A|A|A|K|...|
|...|...|...|...|...|...|...|...|

**SAPs.pdf**: Polymorphism distribution map. The example figure is shown below, and users can customize the resulting graph according to the drawing parameters provided by the software:  

![SAPs.png](test/SAPs.png)  

## 3.4 Shannon entropy calculation  
In the SAAPS calculation results, information content (IC value) is used to replace information entropy, and the higher the IC value, the more conservative the amino acid at the site. During SAAPS information entropy analysis, two result files, `Shannon_log.txt` and `Shannon_IC_Result.csv`, are generated by default.  

```
saaps -i your/Concise/result/path -sha -pic -o your/output/path
```

**Code explaination:** When calculating information entropy, we need to pass the `Concise_Result.txt` file in the previous step of polymorphism analysis, `-sha` means to activate the information entropy calculation function, `-pic` means to draw the information entropy result, and a picture file named `IC-Plot.pdf` is generated in the output path by default.  

**Shannon_log.txt**: indicates the simple statistical result of IC analysis. The contents of the document are as follows (part) :  

 ```
Basic Statistic Information of the Shannon Entropy (IC)
  IC
Count  150
mean  3.8647165333333335
...  ...
```
**Shannon_IC_Result.csv**: IC values of all sites in sequence. The table contains all site IC values, which are convenient for the subsequent drawing of IC figure. The contents of the table are as follows (part) :

|SITE|IC|
|---|---|
|Site1|4.45943|
|Site2|2.52919|
|Site3|3.75947|
|Site4|3.75947|
|...|...|

**IC-Plot.pdf**: Sequence IC scatter figure. The figure is as follows:

![IC-plot](test/IC-Plot.png)

## 3.5 Polymorphism site screening and Onehot encoding

```
saaps -i your/Seq/Matrix/path -sr your/IC/Result/path -smin ICmin -smax ICmax -o your/output/path
```

**Code explaination**:During the Onehot encoding process, the `Seq_Matrix.csv` file from the polymorphism analysis in the previous step and the `Shannon_IC_Result.csv` file from the information entropy calculation need to be passed in. If only the sites within the threshold range need to be converted, You can use `-smin` and `-smax` to set the IC threshold range. In the Onehot encoding step, the software automatically generates 4 files: `OneHot-Original.csv`, `One-Hot-ConciseMatrix.csv`, `OneHot-Transform.csv`, and `One-Hot-ForIntersect.csv`.

**OneHot-Original.csv**: a table of polymorphic loci selected according to the IC threshold range and used for onehot encoding. The file content is shown as follows (part) :

||3|4|5|6|7|8|...|
|---|---|---|---|---|---|---|---|
|>Seq1|Q|S|G|A|I|Y|...|
|>Seq2|L|G|Q|Q|S|G|---|
|...|...|...|...|...|...|...|...|

**One-Hot-ConciseMatrix.csv**: the process file after the Onehot encoding of `OneHot-Original.csv`, where each amino acid is represented by the corresponding binary number. The file content is shown as follows (part) :

||3|...|
|---|---|---|
|Seq1|[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0]|...|
|Seq2|[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]|...|
|...|...|...|

**OneHot-Transform.csv**: the result of upgrading the dimensions according to the `One-Hot-ConciseMatrix.csv` file, in which the binary list of each point is expanded into the corresponding number dimensions, and each dimension only contains the corresponding values in the binary list. The main contents of the file are shown as follows (part) :  

||3_1|3_2|3_3|..|
|---|---|---|---|---|
|Seq1|0|0|0|...|
|Seq2|0|0|0|...|
|...|...|...|...|...|

**One-Hot-ForIntersect.csv**: indicates the record list of sequence polymorphism loci. The table records the amino acids of each sequence at the polymorphic site, which can be used for differential complement analysis of subsequent sets, etc. The contents of the table are as follows (part) :

||3|4|5|6|7|...|
|---|---|---|---|---|---|---|
|>Seq1|3Q|4S|5G|6A|7I|...|
|>Seq2|3L|4G|5Q|6Q|7S|...|
|>Seq3|3F|4G|5Q|6Q|7S|...|
|...|...|...|...|...|...|...|

## 3.6 Dimensionality reduction and clustering
The function of Onehot encoding is to convert classified data into numerical data that can be quantitatively analyzed. After the onehot encoding conversion, the information of each location of each sequence is converted into high-dimensional binary data. Therefore, in order to better analyze the sequence features, we usually adopt a certain dimensionality reduction algorithm to analyze it and observe the relationship between each sequence. Here we take the most commonly used PCA algorithm as an example.


```
saaps -i your/Transform/result/path -pca -pc -o your/output/path
```

**Code explaination**:In the process of dimensionality reduction analysis, the `OneHot-Transform.csv` file in the previous step needs to be passed in; `-pca` indicates that the PCA dimensionality reduction function is activated. `-pc` means to draw a scatter plot based on the dimensionality reduction results. This process produces two result files called `PCA.csv` and `PCA-Plot.pdf`.

**PCA.csv**: PCA calculation result of sequence file. The contents of the document are as follows (part) :

||0|1|2|3|...|
|---|---|---|---|---|---|
|Seq1|6.254129|-2.01068|-0.27758|-0.33611|...|
|Seq2|-0.74108|-0.47749|-0.1452|-1.75072|...|
|...|...|...|...|...|...|...|

**PCA-plot.pdf**: Based on the PCA analysis results, the scatter Plot is generated according to the default parameters, and the example figure is as follows:

![PCA-plot.png](test/PCA-Plot.png)