Update README.md

Author: Luissolis2020

README.md

@@ -9,3 +9,121 @@ Any restrictions to use for profit or non-academics: Alternative commercial lice
 This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 
 Please contact Dr. Hani Z. Girgis (hzgirgis@buffalo.edu) if you need more information.
+
+EnhancerDetector is a deep learning-based classification tool for predicting the presence of enhancers in DNA sequences. It uses species-specific convolutional neural networks (CNNs) trained on experimentally validated datasets for human, mouse, and Drosophila melanogaster (fly). Class activation mapping (CAM) can optionally be used to visualize the regions in each sequence that most influenced the model’s decision.
+
+## Files:
+Models: Contains trained CNN models for each supported species (human, mouse, and fly) used by EnhancerDetector. The fly model uses an ensemble of three classifiers. The folder also includes indexers for converting DNA to numerical format.
+
+Output: This folder stores the outputs generated by EnhancerDetector, including enhancer predictions and class activation maps.
+
+Test_Input: This folder contains test input files for EnhancerDetector. These files demonstrate the required input format and can be used to test if the tool is functioning correctly. input_human.fasta contains a list of hg38 human sequences in FASTA format. input_mouse.fasta contains a list of mm10 mouse sequences in FASTA format. input_fly.fasta contains a list of dm6 melanogaster sequences in FASTA format.
+
+EnhancerDetector.ipynb: This Jupyter notebook contains the code to run EnhancerDetector. If you are comfortable using Jupyter notebooks, you can modify the parameters in the first few cells and execute the notebook to generate an output evaluation from EnhancerDetector.
+
+## Tool:
+EnhancerDetector.py: This python code contains the code to run EnhancerDetector. This code is to be executed via terminal, it takes a input fasta file along with a input for whether the user wants class activation maps generated, which species model to use and a output directory.
+
+## Requirements:
+EnhancerDetector uses several libraries:
+
+Python version: 3.10.13 (main, Sep 11 2023, 13:44:35) [GCC 11.2.0]
+
+TensorFlow version: 2.13.0
+
+Biopython version: 1.83
+
+NumPy version: 1.24.3
+
+Matplotlib version: 3.8.3
+
+NOTE: These are the version the program was created on, future versions of these libraries may or may not work.
+
+## Parameters:
+EnhancerDetector uses four parameters:
+
+--species: choose between human, mouse and fly. This will determine which model to use for which species you want to evaluate.
+
+--input: the input directory of the fasta file
+
+--cam: this will determine if Class Activation Maps are generated for the given sequences.
+
+--outdir: the output dirctory that the output of both the evaluation and cams will be placed in.
+
+## To Run Tool:
+1. Clone EnhancerDetector and head to where it was cloned.
+
+2. Make sure EnhancerDetector is unzipped.
+
+3. Run EnhancerDetector.py
+   > python EnhancerDetector.py --species human --input human_sequences.fa --outdir Output
+
+4. Results will be saved in the Output/ folder as Model_Output.txt, which lists each input sequence and its predicted enhancer probability.
+
+5. If you want a CAM model generated for the input sequences run:
+   > python EnhancerDetector.py --species human --input human_sequences.fa --cam --outdir Output
+
+6. In the output folder, the generated CAM is called sequence_CAM.pdf
+
+   Opening it will show a heatmap for the given sequence, the dark red regions show the main area that influenced EnhancerDetector's final decision. Please read the main paper for more details.
+
+If you wish to run EnhancerDetector via the jupyter notebook:
+
+1. Open EnhancerDetector.ipynb
+
+2. Locate the third cell then locate and edit the following parameters:
+
+   similar_sequences_file = directory_of_input/sequences.fa
+   
+   network = f'{model_folder}/{Species_Folder}/model.keras'
+   
+   indexer_dir      = f'{model_folder}/{Species_Folder}/indexer.pkl'
+
+4. If you want a CAM model generated then locate the second cell and locate output_cam_pdf.
+
+    Set this parameter to output_cam_pdf = True
+
+5. If you want to change the output directory locate and edit output_dir with your output directory.
+
+6. For the Fly Model in the third cell you will see the use_fly parameter, just set that to True and it will automatically use those models.
+
+7. Once you edit the parameters, run the entire notebook and the outputs will be generated in the output directory.
+
+## To Run our Tests:
+1. Look inside the Test_Input folder, inside are three fasta files:
+
+   input_human.fasta = Includes ten human sequences in fasta format, the first five are likely enhancers while the last five are non-enhancers.
+
+   input_mouse.fasta = Includes ten mouse sequences in fasta format, the first five are likely enhancers while the last five are non-enhancers.
+
+   input_fly.fasta = Includes ten fly sequences in fasta format, the first five are likely enhancers while the last five are non-enhancers.
+
+3. In the main directory run EnhancerDetector.py
+   For Human
+   > python EnhancerDetector.py --species human --input input_human.fa --outdir Output
+
+   For Mouse
+   > python EnhancerDetector.py --species mouse --input input_mouse.fa --outdir Output
+
+   For Fly
+   > python EnhancerDetector.py --species fly --input input_fly.fa --outdir Output
+
+   If you want to generate a CAM output for each sequence run:
+   For Human
+   > python EnhancerDetector.py --species human --input input_human.fa --cam --outdir Output
+
+   For Mouse
+   > python EnhancerDetector.py --species mouse --input input_mouse.fa --cam --outdir Output
+
+   For Fly
+   > python EnhancerDetector.py --species fly --input input_fly.fa --cam --outdir Output
+
+5. Inside the Output folder will be the results and CAM models for each given sequence.
+
+6. If you want to use the jupyter notebook then open EnhancerDetector.ipynb
+
+7. By default the similar_sequences_file should already be set to the human test cases. Change the parameters to the mouse/fly and switch the use_fly to True if using the fly.
+
+8. Set output_cam_pdf to true if you want to generate the CAM models.
+
+9. Run the entire notebook and the outputs will be generated in the Output folder.