cupid-webapp

Sito web per la predizione di interazioni tra RNA non codificanti

La piattaforma unisce in un unico flusso operativo:

1. Modellazione Fisica (Termodinamica): Calcolo della stabilità strutturale (Minimum Free Energy - MFE) e predizione delle strutture secondarie (notazione Dot-Bracket) tramite la suite ViennaRNA (RNAfold e RNAcofold).
2. Deep Learning & Foundation Models: Estrazione di rappresentazioni vettoriali dense (embeddings a 640 dimensioni con pooling medio e massimo a 2560 dimensioni) tramite il modello biologico RNA-FM, ed inferenza predittiva supervisionata tramite la rete neurale miRInter-Trans (InteractionNN).
3. Rendering Vettoriale Interattivo: Generazione server-side di strutture 2D con VARNAcmd (VARNA.jar) ed esplorazione client-side con auto-framing geometrico dinamico, zoom fino al 1500%, traslazione 2D ed esportazione nativa in SVG vettoriale.

---

1. Requisiti e Installazione

Il backend computazionale richiede Python (consigliato Python 3.10+) e un ambiente Java per l'esecuzione del motore grafico.

Prerequisiti di Sistema

• Java Runtime Environment (JRE): Necessario per l'esecuzione in background di VARNA.jar tramite subprocess.
• ViennaRNA: Binding Python della libreria nativa C/C++ per i calcoli bioinformatici.

Installazione Dipendenze Python

1. Creare e attivare un ambiente virtuale:

   python3 -m venv .venv
   source .venv/bin/activate  # Su Linux/macOS
   # .venv\Scripts\activate   # Su Windows

2. Registrare la cartella locale di RNA-FM in modalità modificabile (editable):

   pip install -e ./RNA-FM

3. Installare le dipendenze di produzione mappate nel file requirements.txt:

   pip install -r requirements.txt

---

2. Mappatura dei File del Progetto

Il codice sorgente è organizzato secondo il principio di responsabilità singola (SRP) e separazione frontend/backend:

PROGETTO_RNA/
│
├── 🐍 BACKEND (Python - FastAPI & PyTorch)
│   ├── main.py                <-- Orchestratore API REST, CORS e mount dei file statici
│   ├── models.py              <-- Schemi Pydantic per la validazione strongly-typed del JSON
│   ├── vienna_service.py      <-- Calcoli MFE e Dot-Bracket (RNAfold e RNAcofold)
│   ├── varna_service.py       <-- Generatore SVG vettoriale tramite Java subprocess
│   ├── embedding_manager.py   <-- Modello RNA-FM, Chunking per sequenze lunghe e Caching RAM
│   ├── prediction_service.py  <-- Rete neurale miRInter-Trans, routing pesi e inferenza PyTorch
│   └── pesi/                  <-- Checkpoint pre-addestrati (.pth) per classe molecolare
│       ├── mirnamirna.pth     <-- Pesi specifici per coppie miRNA-miRNA
│       ├── mirnalncrna.pth    <-- Pesi specifici per coppie miRNA-lncRNA
│       └── mirnasnorna.pth    <-- Pesi specifici per coppie miRNA-snoRNA
│
├── 🌐 FRONTEND (JavaScript Vanilla ES6+ & Tailwind CSS)
│   ├── index.html             <-- Interfaccia responsive in Tailwind CSS
│   ├── fasta_parser.js        <-- Lettura asincrona, normalizzazione T->U, warning e Regex FASTA
│   ├── ui_components.js       <-- Builder dinamico di template HTML (Card 2D e Plance)
│   ├── svg_interactive.js     <-- Manipolazione SVG, auto-framing getBBox(), zoom e download Blob
│   ├── results_renderer.js    <-- Popolamento tabella riepilogativa e iniezione viste 2D
│   └── app.js                 <-- Coordinatore eventi UI e dispatch delle chiamate fetch()
│
└── 📦 DIPENDENZE E STRUMENTI
    ├── requirements.txt       <-- Mappatura esatta delle librerie Python
    ├── VARNA.jar              <-- Visualizzatore Java per il rendering 2D dell'RNA
    └── RNA-FM/                <-- Repository del Biological Foundation Model

---

3. Avvio dell'Applicazione

Una volta predisposto l'ambiente e scaricati i pesi nella cartella pesi/, avviare il server Uvicorn dalla cartella radice:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

L'interfaccia grafica sarà accessibile da browser all'indirizzo:

http://localhost:8000