MODELS_ADDED.md

mRNA Scoring Models - Implementation Summary

I've successfully added two mRNA scoring models to the core package as requested.

Models Added

1. RNAstructure MFE Scorer (models/rna_structure_scorer.py)

What it does: Predicts the minimum free energy (MFE) of mRNA secondary structure to assess translation efficiency.

Key features:

• Uses ViennaRNA when available for accurate MFE calculation
• Falls back to GC-content based proxy scoring when ViennaRNA is not installed
• Score range: 0-100 (optimal: 40-70)
• Higher scores indicate stronger secondary structures

Scientific basis: Based on ViennaRNA thermodynamic calculations (Lorenz et al., 2011)

---

2. mRNA Stability Scorer (models/mrna_stability_scorer.py)

What it does: Composite stability prediction combining five established mRNA design principles.

Scoring components:

1. GC Content (30% weight) - Optimal range: 50-60%
2. Codon Adaptation Index (25% weight) - Codon optimization
3. Homopolymer Detection (20% weight) - Penalizes long identical runs
4. 5' UTR Structure (15% weight) - Moderate stability preferred
5. Kozak Consensus (10% weight) - Translation initiation strength

Key features:

• Score range: 0-100 (70+ = excellent, 40-70 = acceptable, <40 = poor)
• Configurable for different organisms (default: human)
• Individual component scores accessible for detailed analysis

Scientific basis:

• Kozak sequence analysis (Mauro & Edelman, 2002)
• CAI methodology (Sharp & Li, 1987)
• mRNA stability research (Presnyak et al., 2015)

---

Files Created

models/
├── rna_structure_scorer.py    # RNAstructure MFE model
├── mrna_stability_scorer.py   # mRNA Stability composite model
├── __init__.py                # Updated to export new models
└── README.md                  # Full documentation

tests/
└── test_models.py             # Added comprehensive tests for both models

demo/
└── demo_models.py             # Demo script showing usage

---

Testing Results

All tests pass successfully:

$ pytest tests/test_models.py::TestRNAStructureMFEScorer -v
$ pytest tests/test_models.py::TestmRNAStabilityScorer -v

8 passed in 0.13s ✓

---

Usage Example

from core.models.sequence import mRNASequence
from models import RNAStructureMFEScorer, mRNAStabilityScorer

# Create a sequence
seq = mRNASequence(
    name="my_mrna",
    source="local",
    five_prime_utr="GTTGCTCCTTCGGGCCTGTGGCGGCT",
    kozak="GCCACCATGG",
    cds="ATGGTGAGCAAGGGCGAGGAG...",
)

# Score with MFE model
mfe_scorer = RNAStructureMFEScorer()
mfe_score = mfe_scorer.score(seq)
print(f"MFE Score: {mfe_score:.1f}/100")

# Score with Stability model
stability_scorer = mRNAStabilityScorer(organism="human")
stability_score = stability_scorer.score(seq)
print(f"Stability Score: {stability_score:.1f}/100")

---

Demo Output

Run the demo to see both models in action:

$ PYTHONPATH=. .venv/bin/python demo/demo_models.py

Sample output:

RNAstructure MFE Scorer
Score: 64.2/100
Interpretation: Optimal structure for translation ✓

mRNA Stability Scorer
Overall Score: 76.2/100
Interpretation: Excellent design ✓

  Component Breakdown:
    GC Content (30%):   100.0/100
    CAI (25%):          63.9/100
    Homopolymers (20%): 65.0/100
    5' UTR (15%):       61.5/100
    Kozak (10%):        80.0/100

---

ModelRegistry Integration

Both models are compatible with the existing ModelRegistry system:

from models import ModelRegistry

registry = ModelRegistry()
registry._register(RNAStructureMFEScorer(), "scoring", "builtin", "")
registry._register(mRNAStabilityScorer(), "scoring", "builtin", "")

# Batch score sequences
results = registry.run_scoring("mRNA Stability", sequences)

---

Dependencies

Required:

• Core Python libraries (no additional dependencies for basic functionality)

Optional (for enhanced features):

• ViennaRNA - For accurate RNA secondary structure prediction
• BioPython - For advanced codon usage analysis

Both models degrade gracefully when optional dependencies are missing.

---

Next Steps

To integrate these models into the UI sidebar:

1. Update ui/components/sidebar.py to show loaded models
2. Implement model loading UI in the "⊕ Load Model" button handler
3. Auto-register built-in models on app startup
4. Add model scoring to the Worklist view

---

References

• ViennaRNA: Lorenz et al. (2011). Algorithms for Molecular Biology, 6:26
• Kozak: Mauro & Edelman (2002). PNAS, 99(19):12031-12036
• CAI: Sharp & Li (1987). Nucleic Acids Research, 15(3):1281-1295
• mRNA Stability: Presnyak et al. (2015). Cell, 160(6):1111-1124