Update README.md: Revise table of contents, enhance features section, and clarify installation instructions

README.md

@@ -1,110 +1,136 @@
-# Protein Location Predictor
+## Table of Contents
 
-A comprehensive GUI application for predicting protein subcellular localization using state-of-the-art machine learning models including PROST-T5 and ESM-C embeddings.
-
-## Features
-
-- **Multiple Model Support**: Choose from three different prediction models:
-  - PROST-T5: Transformer-based protein language model
-  - ESM-C 300M: Evolutionary Scale Modeling (300M parameters)
-  - ESM-C 600M: Evolutionary Scale Modeling (600M parameters)
+* [Protein Location Predictor](#protein-location-predictor)
 
-- **User-Friendly GUI**: Simple Tkinter-based interface with progress tracking
-- **Sequential Processing**: Process multiple protein sequences from FASTA files
-- **Flexible Output**: Save predictions with confidence scores in text format
-- **Error Handling**: Comprehensive error handling and user feedback
+  * [Features](#features)
+  * [Requirements](#requirements)
 
-## Requirements
+    * [Supported Python Version](#supported-python-version)
+    * [Dependencies ](#dependencies-full-environmentyml)
+    * [Hardware Requirements](#hardware-requirements)
+  * [Installation](#installation)
+  * [Usage](#usage)
 
-### Dependencies
+    * [GUI Mode](#gui-mode)
+  * [Example Input & Output](#example-input--output)
+  * [Model Details](#model-details)
+  * [Project Structure](#project-structure)
+  * [Contributing](#contributing)
 
-The project uses conda for environment management. All dependencies are specified in `environment.yml` and include:
+## Protein Location Predictor
 
-- PyTorch with CUDA support
-- Transformers library
-- ESM models
-- Scikit-learn
-- BioPython
-- NumPy, Joblib
-- Tkinter (GUI components)
+A comprehensive GUI application for predicting protein subcellular localization using state-of-the-art machine learning models including PROST-T5 and ESM-C embeddings.
 
-### Hardware Requirements
+### Features
 
-- **Minimum**: 8GB RAM, CPU-only execution
-- **Recommended**: 16GB+ RAM, NVIDIA GPU with 8GB+ VRAM
-- **Storage**: ~5GB for model weights and cache
+* **Multiple Model Support**: Choose from three different prediction models:
 
-## Installation
+  * PROST-T5: Transformer-based protein language model
+  * ESM-C 300M: Evolutionary Scale Modeling (300M parameters)
+  * ESM-C 600M: Evolutionary Scale Modeling (600M parameters)
+* **User-Friendly GUI**: Simple Tkinter-based interface with progress tracking (see screenshot below)
+* **Sequential Processing**: Process multiple protein sequences from FASTA files
+* **Flexible Output**: Save predictions with confidence scores in text (CSV) format
+* **Error Handling**: Comprehensive error handling and user feedback
 
-**Prerequisites**: Conda must be installed on your system. [Download Conda](https://docs.conda.io/en/latest/miniconda.html)
+### Supported Python Version
 
-1. **Clone the repository from Hugging Face**:
+This project has been tested on **Python 3.10+**.
 
-```bash
-# Make sure git-lfs is installed (https://git-lfs.com)
-git lfs install
+## Requirements
 
-# Clone with all files
-git clone https://huggingface.co/jpuglia/ProteinLocationPredictor
+#### Dependencies (Full environment.yml)
+
+The complete environment definition is located in `environment.yml`. This file includes all necessary packages for PyTorch, Transformers, ESM models, and GUI operation. Here is a brief excerpt:
+
+```yaml
+name: tesisEnv
+channels:
+  - bioconda
+  - anaconda
+  - conda-forge
+  - defaults
+
+# Python version and major packages
+dependencies:
+  - python=3.10.16
+  - pytorch=2.6.0
+  - torchvision=0.21.0
+  - torchtext=0.18.0
+  - transformers=4.46.3
+  - scikit-learn=1.6.1
+  - biopython=1.85
+  - esm=3.1.4
+  - numpy=1.26.4
+  - joblib=1.4.2
+  - tk
+  # plus many others (see full file for complete list)
 ```
 
-**Optional - Clone without large files** (just pointers):
-```bash
-# If you want to clone without large files - just their pointers
-GIT_LFS_SKIP_SMUDGE=1 git clone https://huggingface.co/jpuglia/ProteinLocationPredictor
-```
+To ensure exact reproducibility, use:
 
-2. **Navigate to the project directory**:
 ```bash
-cd ProteinLocationPredictor
+conda env create -f environment.yml
 ```
 
-3. **Create conda environment**:
-```bash
-conda env create -n protein-predictor -f environment.yml
-conda activate protein-predictor
-```
+### Hardware Requirements
 
-4. **Pre-trained models**:
-   - Model files are included in the repository via Git LFS
-   - If you cloned without large files, you'll need to download them separately
+* **Minimum**: 8 GB RAM, CPU-only execution
+* **Recommended**: 16 GB+ RAM, NVIDIA GPU with 8 GB+ VRAM
+* **Storage**: \~5 GB for model weights and cache
 
-## Usage
+## Installation
 
-### Running the GUI Application
+1. **Clone the repository** (with Git LFS for large model files):
 
-```bash
-conda activate protein-predictor
-python gui.py
-```
+   ```bash
+   git lfs install
+   git clone https://huggingface.co/jpuglia/ProteinLocationPredictor
+   ```
 
-### Step-by-Step Instructions
+   If you prefer to skip downloading model weights initially:
 
-1. **Launch the application**
-   - Run the GUI script
-   - The main window will appear with prediction options
+   ```bash
+   GIT_LFS_SKIP_SMUDGE=1 git clone https://huggingface.co/jpuglia/ProteinLocationPredictor
+   ```
 
-2. **Load a FASTA file**
-   - Click "File" → "Load FASTA"
-   - Select your protein sequences file (`.fasta`, `.fa`, or `.fas`)
+2. **Navigate into the project directory**:
 
-3. **Choose a prediction model**
-   - **PROST-T5**
-   - **ESM-C 300M**
-   - **ESM-C 600M**
+   ```bash
+   cd ProteinLocationPredictor
+   ```
+
+3. **Create and activate the Conda environment**:
+
+   ```bash
+   conda env create -f environment.yml
+   conda activate tesisEnv
+   ```
+
+4. **(If skipped above) Download model weights manually**:
+   Model files live in the `Models/` directory. If you used `GIT_LFS_SKIP_SMUDGE`, run:
+
+   ```bash
+   git lfs pull
+   ```
+
+## Usage
 
-4. **Run prediction**
-   - Click the corresponding prediction button
-   - Monitor progress in the progress bar window
-   - Select output directory when prompted
+### GUI Mode
 
-5. **Save results**
-   - Choose location and filename for prediction results
-   - Results are saved in CSV format with confidence scores for each subcellular location
+1. Launch the application:
 
-### Input Format
+   ```bash
+   python gui.py
+   ```
+2. In the menu, click **File → Load FASTA** and select your input file (`.fasta`, `.fa`, or `.fas`).
+3. Choose one of the prediction models (PROST-T5, ESM-C 300M, or ESM-C 600M).
+4. Click **Run Prediction** and monitor the progress bar.
+5. When complete, you will be prompted to choose an output directory and filename.
 
-FASTA files should contain protein sequences in standard format:
+## Example Input & Output
+
+**Input FASTA (********`example/input.fasta`****\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*):**
 
 ```
 >protein_1
@@ -113,117 +139,57 @@ MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG
 MKTIIALSYIFCLVFAHATAKASEQTDNLQWDLAAIDNSGGHNAVDIKQNLQFQCQNNLHGCF
 ```
 
-### Output Format
-
-Results are saved as CSV files with predictions for 6 subcellular locations, ranked by probability:
+**Output CSV (********`example/output.csv`****\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*):**
 
 ```csv
 Sequence_ID,Prediction 1,Prediction 2,Prediction 3,Prediction 4,Prediction 5,Prediction 6
-sp|P0A7V8|RS4_ECOLI,Cytoplasmic (0.9860),CytoplasmicMembrane (0.0081),Periplasmic (0.0029),Extracellular (0.0019),OuterMembrane (0.0007),Cellwall (0.0003)
+protein_1,Cytoplasmic (0.9860),CytoplasmicMembrane (0.0081),Periplasmic (0.0029),Extracellular (0.0019),OuterMembrane (0.0007),Cellwall (0.0003)
+protein_2,SignalPeptide (0.7523),Extracellular (0.1234),CytoplasmicMembrane (0.0645),Cellwall (0.0345),Periplasmic (0.0201),OuterMembrane (0.0052)
 ```
 
-**Predicted Locations:**
-- **Cytoplasmic**: Interior of the cell
-- **CytoplasmicMembrane**: Inner membrane
-- **Periplasmic**: Space between inner and outer membranes
-- **Extracellular**: Outside the cell
-- **OuterMembrane**: Outer membrane
-- **Cellwall**: Cell wall structure
-
 ## Model Details
 
-### PROST-T5
-- **Base Model**: Rostlab/ProstT5
-- **Embedding Dimension**: 1024
-- **Classifier**: Support Vector Machine (SVM)
-- **Memory Usage**: ~4GB GPU/8GB RAM
-
-### ESM-C Models
-- **Base Models**: ESM-C 300M/600M
-- **Embedding Dimension**: Variable (300M: 960, 600M: 1280)
-- **Classifier**: Support Vector Machine (SVM)
-- **Memory Usage**: 300M: ~2GB GPU, 600M: ~4GB GPU
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Out of Memory Errors**
-   - Reduce batch size or use CPU-only mode
-   - Close other applications to free memory
-   - Try smaller model (ESM-C 300M instead of 600M)
-
-2. **Model Loading Errors**
-   - Ensure model files are in the correct `Models/` directory
-   - Check file permissions and integrity
-   - Clear Hugging Face cache: `rm -rf ~/.cache/huggingface/`
-
-3. **CUDA Errors**
-   - Update GPU drivers
-   - Ensure CUDA-compatible PyTorch installation
-   - Fall back to CPU mode if GPU issues persist
-
-### Performance Tips
-
-- **GPU Usage**: Models automatically detect and use GPU when available
-- **Memory Management**: CUDA cache is cleared after each prediction
-- **Sequential Processing**: Sequences are processed one at a time with progress tracking
+| Model        | Embedding Dim. | Classifier | GPU VRAM | RAM Usage |
+| ------------ | -------------- | ---------- | -------- | --------- |
+| PROST-T5     | 1024           | SVM        | \~4 GB   | \~8 GB    |
+| ESM-C (300M) | 960            | SVM        | \~2 GB   | \~6 GB    |
+| ESM-C (600M) | 1280           | SVM        | \~4 GB   | \~10 GB   |
 
 ## Project Structure
 
 ```
 ProteinLocationPredictor/
-├── gui.py                 # Main GUI application
+├── gui.py
 ├── src/
-│   └── my_utils.py       # Core prediction functions
-├── Models/               # Pre-trained model files (via Git LFS)
-│   ├── Prost T5_svm.joblib
-│   ├── Prost T5_le_svm.joblib
+│   └── my_utils.py
+├��─ Models/
+│   ├── ProstT5_svm.joblib
 │   ├── ESMC-300m_svm.joblib
 │   ├── ESMC-600m_svm.joblib
 │   └── ...
-├── environment.yml        # Conda environment specification
-└── README.md            # This file
+├── environment.yml
+├── README.md
+└── doc/
+    └── screenshots/
+        └── gui_example.png
 ```
 
 ## Contributing
 
 1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Citation
-
-If you use this tool in your research, please cite:
-
-```bibtex
-@software{protein_location_predictor,
-  title={Protein Location Predictor},
-  author={Juan Diego Puglia},
-  year={2025},
-  url={https://huggingface.co/jpuglia/ProteinLocationPredictor}
-}
-```
-
-## Acknowledgments
-
-- [Rostlab](https://rostlab.org/) for the PROST-T5 model
-- [Meta AI](https://ai.meta.com/) for the ESM models
-- [Hugging Face](https://huggingface.co/) for model hosting and transformers library
-- [BioPython](https://biopython.org/) for sequence handling utilities
-
-## Contact
-
-For questions, issues, or collaborations, please:
-- Visit the [Hugging Face repository](https://huggingface.co/jpuglia/ProteinLocationPredictor)
-- Open a discussion on the Hugging Face platform
-
----
-
-**Note**: This tool is for research purposes. Please validate predictions with experimental methods for critical applications.
+2. Create a feature branch:
+
+   ```bash
+   git checkout -b feature/amazing-feature
+   ```
+3. Commit your changes:
+
+   ```bash
+   git commit -m "Add amazing feature"
+   ```
+4. Push to your branch:
+
+   ```bash
+   git push origin feature/amazing-feature
+   ```
+5. Open a Pull Request or start a discussion: [Repository Discussions](https://huggingface.co/jpuglia/ProteinLocationPredictor/discussions)