Metadata-Version: 2.1
Name: mirnaprotpred
Version: 0.1.8
Summary: A pip installable CLI for miRNAProtPred tool
Home-page: https://github.com/somenath-combio/mirnaprotpred
Author: Somenath Dutta, Sudipta Sardar
Author-email: somenath@pusan.ac.kr, sudipta@pusan.ac.kr
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE

# miRNAProtPred

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

A powerful, high-performance bioinformatics framework for discovering, evaluating, and verifying microRNA (miRNA) interactions across DNA, RNA, and protein target sequences.

The `mirnaprotpred` package provides two core modules:
1. **SeqFinder**: A discovery engine to find all potential miRNA interactions across a genome or target sequence.
2. **Validator**: A targeted verification engine to test specific, user-provided miRNAs against a target sequence.

Both modules are powered by a shared, rigorous biological engine that evaluates exact seed matching, wobble pairing, AU-rich context, and RNAduplex thermodynamic stability.

## Features

- **Multi-Sequence Support**: Natively processes DNA, RNA, and Protein sequences. Protein sequences are automatically reversed-mapped to nucleotides via an integrated BLAST search. *Note: Protein mode provides exploratory nucleotide-region inference and should not be interpreted as direct protein-target prediction.*
- **Strict & Relaxed Modes**:
  - `strict`: Identifies only canonical, exact seed interactions.
  - `relaxed`: Discovers flexible interactions including wobble pairings, with biological confidence re-weighting.
- **Thermodynamic Scoring**: Leverages `ViennaRNA` (RNAduplex) to calculate Minimum Free Energy (MFE) structural stability.
- **Multi-Factor Confidence Classification**: Interactions are graded (Very High, High, Medium, Low) based on MFE, motif identity, AU-context accessibility, and cluster density.
- **Targeted Validation**: Provide specific miRNA IDs (inline or via text/FASTA files) to rapidly check for interactions without scanning the entire database.
- **Flexible Output Options**: Terminal-friendly concise summaries, full detailed interaction data, high-confidence filtering, and direct CSV export.

## Installation

To ensure all dependencies (especially `ViennaRNA`) work correctly, we recommend using a Conda environment with Python 3.11.

### Step 1: Create and activate a new Conda environment
```bash
conda create -n mirnaprotpred_env python=3.11 -y
conda activate mirnaprotpred_env
```

### Step 2: Install ViennaRNA
ViennaRNA cannot be installed via pip and must be installed via Conda:
```bash
conda install -c bioconda viennarna -y
```

### Step 3: Install mirnaprotpred
Now you can install the package from PyPI:
```bash
pip install mirnaprotpred
```

### Alternative: Install from Source
If you prefer to install from the repository:
```bash
git clone https://github.com/somenath-combio/mirnaprotpred.git
cd mirnaprotpred
pip install .
```

## Usage: SeqFinder

Use `SeqFinder` to scan an entire sequence and discover **all** potential miRNA interactions.

```bash
SeqFinder <target_sequence_or_fasta> [options]
```

### Examples
```bash
# Scan a FASTA genome file
SeqFinder examples/sars.fasta

# Relaxed mode to include wobble pairings
SeqFinder examples/sars.fasta --mode relaxed

# View detailed raw output for all interactions
SeqFinder examples/sars.fasta --output raw

# View only High and Very High confidence interactions
SeqFinder examples/sars.fasta --output highconf

# Save results automatically to CSV
SeqFinder examples/sars.fasta --output raw --out results.csv

# Direct sequence input
SeqFinder "AUGCAUGCAUGCAUGC"
```

## Usage: Validator

Use the `validator` to check if **specific** miRNAs interact with your target.

```bash
validator <miRNA_IDs> <target_sequence_or_fasta> [options]
```

The validator provides a simple YES/NO summary by default, but can output the full `SeqFinder` interaction data using `--details`.

### Examples
```bash
# Inline comma-separated miRNAs
validator hsa-miR-21-5p,hsa-miR-122-5p examples/sars.fasta

# Read miRNAs from a text file (one per line)
validator examples/mirnas.txt examples/sars.fasta

# Extract miRNA IDs from a FASTA file and validate them
validator known_mirnas.fasta examples/sars.fasta

# Show full detailed interaction data for the matched miRNAs
validator examples/mirnas.txt examples/sars.fasta --details

# Save results automatically to CSV
validator examples/mirnas.txt examples/sars.fasta --out validation.csv
```

## How It Works

1. **Input Processing**: The engine detects whether the input is DNA, RNA, or Protein. If Protein, a `tblastn` search is performed against the NCBI database to retrieve the corresponding nucleotide region.
2. **Motif Discovery**: The Boyer-Moore string matching algorithm rapidly identifies potential binding sites using canonical or relaxed seed variants.
3. **Contextual Evaluation**: The 20nt flanking regions are evaluated for AU content, which correlates with structural accessibility.
4. **Structural Analysis**: `ViennaRNA` calculates the optimal secondary structure and minimum free energy (MFE) between the miRNA and the target site.
5. **Clustering & Ranking**: Competing seeds at the same locus are clustered, scored using a composite biological metric, and the optimal interaction is selected.
6. **Confidence Classification**: Results are categorized based on stringent biological thresholds (e.g., `Very High` confidence requires strict identity, strong MFE, and high AU context).

## Output Columns (Detailed Mode)

- **miRNA_ID / description**: The matched human miRNA.
- **CTS**: Complementary Target Sequence (the matching region on your input).
- **CTS_start**: 1-based start coordinate of the interaction.
- **RNAduplex_MFE**: Thermodynamic stability (Minimum Free Energy, more negative is stronger).
- **AU_Context**: Accessibility score based on AU richness in flanking regions.
- **motif_identity / match_type**: Structural identity of the seed interaction (Exact vs Wobble).
- **Confidence_Level**: Biological confidence (Very High, High, Medium, Low).

## Authors

- Somenath Dutta (somenath@pusan.ac.kr)
- Sudipta Sardar (sudipta@pusan.ac.kr)

## Citation

If you use this tool in your research, please cite:
*(Citation details pending publication)*

## License

MIT License
