README_APP.md

# miRBind2 Gradio Web Interface

Interactive web application for predicting miRNA-mRNA binding sites with explainability visualization.

## Features

### Single Prediction Mode
- **Simple Interface:** Enter miRNA and mRNA sequences to get binding predictions
- **Real-time Predictions:** Uses pre-trained Pairwise CNN model (AUPRC: 84.97)
- **Sequence Visualization:** Color-coded nucleotide importance bars
- **SHAP Explainability:** Interactive heatmap showing which positions contribute to binding prediction
- **PDF Reports:** Download comprehensive reports with all visualizations

### Batch Prediction Mode
- **File Upload:** Process multiple pairs from TSV/CSV files
- **Interactive Table:** Browse all predictions with sorting/filtering
- **Click-to-View:** Select any row to see detailed SHAP analysis
- **Progress Tracking:** Real-time progress bar during processing
- **Accuracy Metrics:** Automatic calculation if labels provided

### General
- **Local Execution:** Runs entirely on your machine, no internet required
- **GPU Support:** Automatically uses CUDA if available, falls back to CPU
- **Unified Interface:** Both modes in one app with tabs

## Installation

### Prerequisites

- Python 3.8 or higher
- pip package manager

### Quick Start

1. **Install dependencies:**

```bash
pip install -r requirements.txt
```

2. **Run the application:**

```bash
python app.py
```

3. **Open your browser:**

The app will automatically open at `http://127.0.0.1:7860`

If it doesn't open automatically, copy the URL from the terminal.

## Usage

The app has **two tabs**: **Single Prediction** and **Batch Predictions**

### Tab 1: Single Prediction

1. Enter your **miRNA sequence** (e.g., `UAGCUUAUCAGACUGAUGUUGA`)
2. Enter your **mRNA target sequence**
3. Click **"Predict Binding"**
4. View results:
   - Binding score (0-1)
   - Prediction (BINDING/NO BINDING)
   - Confidence level
   - Download PDF report

#### With Explainability (Single Mode)

1. Check the **"Show SHAP Explainability"** checkbox
2. Run prediction (will take a few seconds longer)
3. View:
   - **Sequence explainability bars:** Per-nucleotide importance
   - **SHAP heatmap:** Position-pair contributions
   - **PDF report:** Download everything

### Tab 2: Batch Predictions

1. **Upload file:** Click "Upload TSV/CSV File"
   - Format: `target_seq`, `mirna_seq`, `label` (optional)
   - See `example_batch.tsv` for reference
2. **Configure:** Check "Compute SHAP" if you want explainability (optional)
3. **Process:** Click "Process File"
4. **Browse:** View results table with all predictions
5. **Detail:** Click any row to see full SHAP analysis

#### Batch Processing Tips

**Fast screening** (100+ pairs):
- Upload file
- Leave SHAP **unchecked**
- Process → Get results in seconds
- Identify interesting pairs from table

**Detailed analysis** (5-20 pairs):
- Upload file with top candidates
- Check SHAP **enabled**
- Process → Click each row for full analysis

### Input Guidelines

- **Accepted nucleotides:** A, T, C, G, U, N
- Both RNA (U) and DNA (T) formats are accepted
- Sequences are automatically:
  - Converted to uppercase
  - U → T conversion
  - Padded to 28 nt (miRNA) and 50 nt (mRNA)
  - Trimmed if too long

### Example Sequences

**miRNA example:**
```
UAGCUUAUCAGACUGAUGUUGA
```

**mRNA target example (with an embedded complementary site for clearer explainability):**
```
GGGCACUUUUUCAACAUCAGUCUGAUAAGCUAAGUGUCUUCCAGGGAAUU
```

## Model Information

**Architecture:** Pairwise CNN with One-Hot Encoding

**Training Data:** AGO2 eCLIP (Manakov et al. 2022)

**Performance:**
- Test AUPRC: 84.97
- Leftout AUPRC: 83.08

**Model Parameters:**
- miRNA length: 28 nucleotides
- Target length: 50 nucleotides
- Embedding dimension: 8
- Filter sizes: [128, 64, 32]
- Kernel sizes: [6, 3, 3]

## Technical Details

### File Structure

```
mirbind2_web/
├── app.py                          # Main Gradio application
├── requirements.txt                # Python dependencies
├── README_APP.md                   # This file
├── miRBind_2.0-main/              # Original miRBind2 repository
│   ├── code/                       # Model and encoding code
│   │   └── pairwise_binding_site_model/
│   │       └── shared/             # Shared utilities
│   └── models/                     # Pre-trained models
│       └── pairwise_onehot_model_20260105_200141.pt
```

### Performance Optimization

- **GPU Acceleration:** Automatically uses CUDA if available
- **Batch Processing:** Efficient tensor operations
- **Caching:** Model loaded once at startup

### SHAP Computation

SHAP (SHapley Additive exPlanations) uses GradientShap to compute feature attributions:
- Compares input against baseline (all zeros)
- Computes gradients to determine importance
- Aggregates across nucleotide pair dimension
- Visualizes as 2D heatmap (miRNA × mRNA positions)

## Troubleshooting

### Model Not Found

If you see `Model not found` error:
```bash
# Check model exists
ls miRBind_2.0-main/models/pairwise_onehot_model_20260105_200141.pt
```

Download from the model repository if missing.

### SHAP Not Available

If SHAP visualization doesn't work:
```bash
pip install captum
```

### Out of Memory (GPU)

If you encounter CUDA out of memory errors:
- Close other GPU-intensive applications
- Or disable SHAP (uncheck the box)
- The model will automatically fall back to CPU

### Port Already in Use

If port 7860 is busy, edit `app.py`:
```python
app.launch(
    server_port=7861,  # Change to different port
    ...
)
```

## Advanced Usage

### Sharing Publicly

To create a temporary public link (for collaboration):

Edit `app.py` line 368:
```python
app.launch(
    share=True,  # Creates public Gradio link
    ...
)
```

**Warning:** This shares your model publicly. Only use for trusted collaborators.

### Custom Model

To use a different model:

1. Update model path in `app.py` (line 50):
```python
model_path = Path(__file__).parent / "path/to/your/model.pt"
```

2. Ensure model type matches (`pairwise_onehot` or `pairwise`)

### Batch Predictions

For multiple predictions, consider using the original inference scripts:
```bash
cd miRBind_2.0-main/code/pairwise_binding_site_model
python -m inference.predict --help
```

## Citation

If you use miRBind2 in your research, please cite:

```
miRBind 2.0: Advanced miRNA Target Prediction
[Citation details to be added]
```

## License

See LICENSE file in the miRBind_2.0-main directory.

## Support

For issues or questions:
- Check the troubleshooting section above
- Review the original miRBind2 repository README
- Open an issue on the GitHub repository

---

**Developed using:** Gradio, PyTorch, Captum (SHAP)