Update README.md

README.md

@@ -9,10 +9,7 @@ app_file: app.py
 pinned: false
 license: cc-by-nc-nd-4.0
 ---
-
-
-
-<!-- This Github was Made By Nathan Gravel and tested with help of Mariah Salcedo--> 
+<!-- This github was Made by Nathan Gravel --> 
 
 # Phosformer-ST  <img src="https://github.com/gravelCompBio/Phosformer-ST/assets/75225868/f375e377-b639-4b8c-9792-6d8e5e9e6c39" width="60"> 
 
@@ -24,9 +21,6 @@ license: cc-by-nc-nd-4.0
 
    
 
-  
-
-  
 
   
 
@@ -34,14 +28,7 @@ license: cc-by-nc-nd-4.0
 
   
 
-This repository contains the code to run Phosformer-ST locally from the manuscript "Phosformer-ST: explainable machine learning 
-
-uncovers the kinase-substrate interaction landscape" . This readme should also give you the specific versions for all packages used to run Phosformer-ST in a local environment. 
-
-The model was created by Zhongliang Zhou and Wayland Yeung. The Phos-ST webtool is found from this link (https://phosformer.netlify.app/) and was generated by Saber Soleymani.  
-
-  
-
+This repository contains the code to run Phosformer-ST locally described in the manuscript "Phosformer-ST: explainable machine learning uncovers the kinase-substrate interaction landscape". This readme also provides instructions on all dependencies and packages required to run Phosformer-ST in a local environment. 
 </br> 
 
    
@@ -76,60 +63,45 @@ The model was created by Zhongliang Zhou and Wayland Yeung. The Phos-ST webtool
 
    
 
-   
-
-  
-
-- `phos-ST_Example_Code.ipynb`: Jupyter File with example code to run Phosformer-ST 
-
-  
-
-- `modeling_esm.py`: Python file that has the architecture of Phosformer-ST 
-
-  
-
-- `configuration_esm.py`: Python file that has configuration/parameters of Phosformer-ST  
-
   
 
-- `tokenization_esm.py`: Python file that contains code for the tokenizer  
+- `phos-ST_Example_Code.ipynb`: ipynb file with example code to run Phosformer-ST 
 
   
 
+    - `modeling_esm.py`: Python file that has the architecture of Phosformer-ST 
+    
+      
+    
+    - `configuration_esm.py`: Python file that has configuration/parameters of Phosformer-ST  
+    
+      
+    
+    - `tokenization_esm.py`: Python file that contains code for the tokenizer  
   
 
-- `multitask_MHA_esm2_t30_150M_UR50D_neg_ratio_8+8_shift_30_mask_0.2_2023-03-25_90.txt`: this txt file contains a link to a zenodo repository to download the proper folder  
-
   
 
-  - This folder holds the files that contained the training weights for Phosformer-ST to run as advertised 
-
-  - See section below (Downloading this repository) to be shown how to download this folder and where to put it
-    
- 
-- `multitask_MHA_esm2_t30_150M_UR50D_neg_ratio_8+8_shift_30_mask_0.2_2023-03-25_90`: folder of the training weights for Phosformer-ST to run as advertised 
+- `multitask_MHA_esm2_t30_150M_UR50D_neg_ratio_8+8_shift_30_mask_0.2_2023-03-25_90.txt`: this txt file contains a link to the training weights held on the hugging face or zenodo repository 
 
+    - See section below (Downloading this repository) to be shown how to download this folder and where to put it
   
 
-- `phosST.yml`: This file is used to help create an environment for Phos-ST to work 
+- `phosST.yml`: This file is used to help create an environment for Phosformer-ST to work 
 
    
 
-- `README.md`: You're reading it right now 
+- `README.md`: 
 
   
 
-- `LICENSE`: Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International Public License
-  
+- `LICENSE`: Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International Public License 
 
-- `app.py`: Contains the code to get huggingface to work as a webtool (with gradio)
   
 
-- `requirements.txt`: requirements for huggingface to download to get this webtoool to work 
-
+  
 
     
-
   
 
 </br> 
@@ -141,7 +113,6 @@ The model was created by Zhongliang Zhou and Wayland Yeung. The Phos-ST webtool
   
 
     
-
   
 
 ## Installing dependencies with version info    
@@ -225,71 +196,7 @@ Follow along with its recommendation
 Installing torch can be the most complex part  
 
   
-
-  
-
-</br> 
-
-  
-
-  
-
-  
-
-   
-
-### The computer specs that we know that this model can run on (with gpu acceleration) 
-
-  
-
-</br> 
-
-  
-
-**Computer 1** 
-
-  
-
-Ubuntu 22.04.2 LTS 
-
-  
-
-Intel(R) Xeon(R) Bronze 3204 CPU @ 1.90GHz  (6 cores) x (1 thread per core) 
-
-  
-
-64 GB ram 
-
-  
-
-NVIDIA Quadro RTX 5000 (16 GB vRAM)(CUDA Version: 12.1)  
-
-  
-
-</br> 
-
-  
-
-**Computer 2** 
-
-  
-
-Ubuntu 20.04.6 LTS 
-
-  
-
-Intel(R) Xeon(R) Bronze 3204 CPU @ 1.90GHz  (6 cores) x (1 thread per core) 
-
-  
-
-64 GB ram 
-
   
-
-NVIDIA RTX A4000 (16 GB vRAM)(CUDA Version: 12.2)  
-
-  
-
   
 
   
@@ -300,7 +207,6 @@ NVIDIA RTX A4000 (16 GB vRAM)(CUDA Version: 12.2)
 
 </br> 
 
-  
 
    
 
@@ -360,7 +266,7 @@ The `Phosformer-ST_with_trainging_weights` folder should have the following file
 
 
 
-- folder 1 `multitask_MHA_esm2_t30_150M_UR50D_neg_ratio_8+8_shift_30_mask_0.2_2023-03-25_90` (make sure it is unzipped)
+- folder 1 `multitask_MHA_esm2_t30_150M_UR50D_neg_ratio_8+8_shift_30_mask_0.2_2023-03-25_90`
 
 
 
@@ -393,7 +299,7 @@ Once you have a folder with the files/folder above in it you have done all the d
 
 ### PICK ONE of the options below  
 
-### Option 1) Utilizing the PhosformerST.yml file 
+### Main Option) Utilizing the PhosformerST.yml file 
 
 here is a step-by-step guide to set up the environment with the yml file  
 
@@ -417,9 +323,9 @@ conda activate phosST
 
   
 
-### Option 2) Creating this environment without yml file 
+### Alternative option) Creating this environment without yml file 
 
-(This is if torch is being weird with your version of cuda or any other problem) 
+(This is if torch is not working with your version of cuda or any other problem) 
 
 Just type these lines of code into the terminal after you download this repository (this assumes you have anaconda already installed) 
 
@@ -477,11 +383,11 @@ pip3 install torch torchvision torchaudio
 
   
 
-### the terminal line above might look different  for you  
+### the terminal line above might look different for you  
 
   
 
-We provided code to test Phos-ST (see section below) 
+We provided code to test Phosformer-ST (see section below) 
 
   
 
@@ -499,21 +405,19 @@ We provided code to test Phos-ST (see section below)
 
   
 
-## Utilizing the Model with our example 
+## Utilizing the Model with our example code 
 
 All the following code examples is done inside of the `phos-ST_Example_Code.ipynb` file using jupyter lab 
 
   
 
-Once you have your environment resolved just use jupyter lab to access the example code by typing the comand below in your terminal (when you're in the `Phosformer-ST` folder)  
+Once you have your environment resolved just use jupyter lab to access the example code by typing the command below in your terminal (when you're in the `Phosformer-ST` folder)  
 
 ```   
-
 jupyter lab 
-
 ``` 
 
-Once you open the notebook on your browser, run each cell of notebook  
+Once you open the notebook on your browser, run each cell in the notebook  
 
   
 
@@ -521,28 +425,20 @@ Once you open the notebook on your browser, run each cell of notebook
 
   
 
-### Testing Phos-ST with the example code 
-
-There should be a positive control and a negative control example code at bottom of the `phos-ST_Example_Code.ipynb` file. This is here just to sanity check that the model is working. The positive and negative control is running the same code with known examples where Phos-ST should give an answered close to 1 (positive control) or 0 (negative control).  
+### Testing Phosformer-ST with the example code 
 
+There should be a positive control and a negative control example code at the bottom of the `phos-ST_Example_Code.ipynb` file which can be used to test the model. 
   
 
 **Positive Example** 
 
 ```Python 
-
 # P17612 KAPCA_HUMAN 
-
 kinDomain="FERIKTLGTGSFGRVMLVKHKETGNHYAMKILDKQKVVKLKQIEHTLNEKRILQAVNFPFLVKLEFSFKDNSNLYMVMEYVPGGEMFSHLRRIGRFSEPHARFYAAQIVLTFEYLHSLDLIYRDLKPENLLIDQQGYIQVTDFGFAKRVKGRTWTLCGTPEYLAPEIILSKGYNKAVDWWALGVLIYEMAAGYPPFFADQPIQIYEKIVSGKVRFPSHFSSDLKDLLRNLLQVDLTKRFGNLKNGVNDIKNHKWF" 
-
 # P53602_S96_LARKRRNSRDGDPLP 
-
 substrate="LARKRRNSRDGDPLP" 
-
   
-
 phosST(kinDomain,substrate).to_csv('PostiveExample.csv') 
-
 ``` 
 
   
@@ -552,22 +448,15 @@ phosST(kinDomain,substrate).to_csv('PostiveExample.csv')
 **Negative Example** 
 
 ```Python 
-
 # P17612 KAPCA_HUMAN 
-
 kinDomain="FERIKTLGTGSFGRVMLVKHKETGNHYAMKILDKQKVVKLKQIEHTLNEKRILQAVNFPFLVKLEFSFKDNSNLYMVMEYVPGGEMFSHLRRIGRFSEPHARFYAAQIVLTFEYLHSLDLIYRDLKPENLLIDQQGYIQVTDFGFAKRVKGRTWTLCGTPEYLAPEIILSKGYNKAVDWWALGVLIYEMAAGYPPFFADQPIQIYEKIVSGKVRFPSHFSSDLKDLLRNLLQVDLTKRFGNLKNGVNDIKNHKWF" 
-
 # Q01831_T169_PVEIEIETPEQAKTR 
-
 substrate="PVEIEIETPEQAKTR" 
-
   
-
 phosST(kinDomain,substrate).to_csv('NegitiveExample.csv') 
-
 ``` 
 
-Both scores should show up in a csv file in the same folder of this code 
+Both scores should show up in a csv file in the current directory
 
   
 
@@ -577,23 +466,21 @@ Both scores should show up in a csv file in the same folder of this code
 
 ### Inputting your own data for novel predictions 
 
-One can simply take the code from above and modify the string variables `kinDomain` and `substrate` to your prediction of interest 
+One can simply take the code from above and modify the string variables `kinDomain` and `substrate` to make predictions on any given kinase substrate pairs 
 
   
 
-**Formatting of the `kinDomain` and `substrate` for input for phos-ST are as followed:** 
+**Formatting of the `kinDomain` and `substrate` for input for Phosformer-ST are as follows:** 
 
   
 
-  - `kinDomain` should just be the kinase domain (instead of the full sequence), preferably human, and a Serine/Threonine kinases   
-
+  - `kinDomain` should be a human Serine/Threonine kinase domain (not the full sequence).
      
-
-  - `substrate` should be a 15mer with the center residue/char being the Serine or Threonine being phosphorylated 
+  - `substrate` should be a 15mer with the center residue/char being the target Serine or Threonine being phosphorylated 
 
   
 
-Not following these rules will still give you and output at time but does not guarantee a prediction with the accuracy advertised  
+Not following these rules may result in dubious predictions  
 
   
 
@@ -603,154 +490,107 @@ Not following these rules will still give you and output at time but does not gu
 
   
 
-### How to interoperate Phosformer-ST's output 
+### How to interpret Phosformer-ST's output 
 
-This model was trained to use the cutoff of 0.5 as the difference between positive prediction and negative prediction  
+This model outputs a prediction score between 1 and 0.
 
-  
 
-If your custom prediction is above 0.5, the model is predicting the kinase-substrate pair is a positive prediction for a phosphorylation event  
+We trained the model to uses a cutoff of 0.5 to distinguish positive and negative predictions 
 
-  
 
-Though the training data is ultimately based on a positional scanning peptide array, this model only takes into account kinase binding preference. 
+A score of 0.5 or above indicates a positive prediction for peptide substrate phosphorylation by the given kinase
 
   
-
-Combining with other special, temporal, or other biologically relevant filters might be more accurate when modeling protein kinase. 
-
   
 
 </br> 
 
   
-
   
 
-  
+## Troubleshooting 
 
   
 
-### Modifying the code to take in a list of kinase domains and substrates 
-
-Currenly, we have it only predicting one kinase domain + one substrate at a time. One can simply swap out the `helper function to use Phos-ST` code-block with the code-block below. The input arguments now require a list of strings for both the kinase domains and substrates. Make sure the list of both kinases and substrates are the same length and conserve the same format specified in the "Inputting your own data for novel predictions" section of the readme  
-
-```Python 
-
-# P17612 KAPCA_HUMAN listed twice 
-
-kinDomains=["FERIKTLGTGSFGRVMLVKHKETGNHYAMKILDKQKVVKLKQIEHTLNEKRILQAVNFPFLVKLEFSFKDNSNLYMVMEYVPGGEMFSHLRRIGRFSEPHARFYAAQIVLTFEYLHSLDLIYRDLKPENLLIDQQGYIQVTDFGFAKRVKGRTWTLCGTPEYLAPEIILSKGYNKAVDWWALGVLIYEMAAGYPPFFADQPIQIYEKIVSGKVRFPSHFSSDLKDLLRNLLQVDLTKRFGNLKNGVNDIKNHKWF","FERIKTLGTGSFGRVMLVKHKETGNHYAMKILDKQKVVKLKQIEHTLNEKRILQAVNFPFLVKLEFSFKDNSNLYMVMEYVPGGEMFSHLRRIGRFSEPHARFYAAQIVLTFEYLHSLDLIYRDLKPENLLIDQQGYIQVTDFGFAKRVKGRTWTLCGTPEYLAPEIILSKGYNKAVDWWALGVLIYEMAAGYPPFFADQPIQIYEKIVSGKVRFPSHFSSDLKDLLRNLLQVDLTKRFGNLKNGVNDIKNHKWF"] 
+If torch is not installing correctly or you do not have a GPU to run Phosformer-ST on, the CPU version of torch is perfectly fine to use 
 
   
 
-# P53602_S96_LARKRRNSRDGDPLP listed first and Q01831_T169_PVEIEIETPEQAKTR listed second 
-
-substrates=["LARKRRNSRDGDPLP","PVEIEIETPEQAKTR"] 
-
-  
+Using the CPU version of torch might increase your run time so for large prediction datasets GPU acceleration is suggested 
 
   
 
-def phosST(kinaseDomainSeqs,substrate15mers): 
+If you just are here to test if it Phosformer-ST works, the example code should not take too much time to run on the CPU version of torch   
 
-    job = run_model( 
-
-        substrate15mers, 
-
-        kinaseDomainSeqs, 
-
-        model=model,  
-
-        tokenizer=tokenizer,  
-
-        device='cuda',  
-
-        batch_size=10, 
-
-        output_hidden_states=False, 
-
-        output_attentions=False, 
-
-    ) 
-
-     
-
-    #total = dataset.shape[0] 
-
-    results = { 
+  
 
-        'kinase' : [], 
+Also depending on your GPU the `batch_size` argument might need to be adjusted 
 
-        'peptide' : [], 
 
-        'prob' : [], 
+### The model has been tested on the following computers with the following specifications for trouble shooting proposes 
 
-    } 
+  
 
-     
+</br> 
 
-    for n, i in enumerate(job): 
+  
 
-        #sys.stderr.write(f'{n+1} / {total}\r') 
+**Computer 1** 
 
-        results['kinase' ] += [i['kinase']] 
 
-        results['peptide'] += [i['peptide']] 
 
-        results['prob'   ] += [i['probability']] 
+NVIDIA Quadro RTX 5000 (16 GB vRAM)(CUDA Version: 12.1)  
 
-     
+  
 
-    result = pd.DataFrame(results) 
+Ubuntu 22.04.2 LTS 
 
   
 
-    return result 
+Intel(R) Xeon(R) Bronze 3204 CPU @ 1.90GHz  (6 cores) x (1 thread per core) 
 
   
 
-  
+64 GB ram 
 
-  
 
-phosST(kinDomains,substrates).to_csv('BatchExample.csv') 
 
   
 
-  
+</br> 
 
   
 
-  
+**Computer 2** 
 
-``` 
 
-</br> 
+
+NVIDIA RTX A4000 (16 GB vRAM)(CUDA Version: 12.2)  
 
   
 
-</br> 
+Ubuntu 20.04.6 LTS 
 
   
 
-## Troubleshooting 
+Intel(R) Xeon(R) Bronze 3204 CPU @ 1.90GHz  (6 cores) x (1 thread per core) 
 
   
 
-If torch is not installing correctly or you do not have a GPU to run Phos-ST on, the CPU version of torch is perfectly fine to use 
+64 GB ram 
 
   
 
-Using the CPU version of torch might 10x to 1000x your run time so for large prediction datasets GPU acceleration is suggested 
 
-  
 
-If you just are here to test if it phos-ST works, the example code should not take too much time to run on the CPU version of torch   
 
-  
 
-Also depending on your GPU the `batch_size` argument might need to be adjusted
+</br> 
+
 
+## Other accessory tools and resources
+A webtool for Phosformer-ST can be accessed from: https://phosformer.netlify.app/. A huggingface repository can be downloaded from: https://huggingface.co/gravelcompbio/Phosformer-ST_with_trainging_weights. A huggingface spaces app is available at: https://huggingface.co/spaces/gravelcompbio/Phosformer-ST
 
+The github can be found here https://github.com/gravelCompBio/Phosformer-ST/tree/main 
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference