🧬 Peptide Visual Lab (DESY — Landau Group) 🔬

Interactive web app for exploring peptide properties and fibril-forming predictions. Designed with the Landau Group (DESY/CSSB, Professor Meytal Landau's group). Developed with guidance from Dr. Aleksandr Golubev.

---

🏗️ Case-Study Mode
Upload and real computation are disabled in this version.
Use “Load Example Dataset” on the home screen to explore the full interface and workflow with synthetic data that mirrors real outputs.
🔒 The operational laboratory repository remains private; implementation details are summarized below.

---

🎯 Purpose

• 📤 Upload peptide datasets from UniProt (TSV/CSV/XLSX)
• 🧪 Compute biophysical features (Hydrophobicity, Charge, Hydrophobic Moment μH)
• 🔗 Integrate Tango (SSW) and JPred results (when local outputs are provided)
• 📊 Visualize cohorts, rank candidates, and export reports/shortlists

---

💜 Said Azaizah’s Contributions (Expanded)

🧩 Productization & Architecture

• Reframed a stalled prototype into a deployable research tool featuring a React/TypeScript UI, FastAPI backend endpoints, and a normalized data contract for reliable UI rendering.
• Implemented per-run temporary directories, direct binary execution, and a robust parser tolerant of multiple TANGO output formats (tabular/mixed text).
• Executed the JPred → PSIPRED pivot, replacing brittle dependencies with a probability-based secondary-structure pipeline using P(H)/P(E)/P(C) for accurate %Helix/%Beta predictions and segment mapping.

📊 Data & Fallbacks

• Unified column normalization across experiments, ensuring consistent field names, units, and alignment for comparative analytics.
• Added “always-on” sequence-only features — including FF-Helix%, charge, hydrophobicity, and μH — to preserve utility even when predictors are offline.

🎨 UX & Flows

• Designed the Upload → Results → Detail flow, including triage KPIs, sortable tables, cohort radar visualizations, and a badge system (e.g., chameleon flag).
• Added export options (CSV/PDF) and a roadmap for researcher-tunable parameters (thresholds, weights, and audit-safe defaults).

🛡️ Reliability & Privacy

• Architected for local-only computation within lab environments; prepared a secure PSIPRED server deployment plan for broader access.
• Established a cross-platform runner strategy, eliminating hard-coded paths and OS-specific dependencies.

⚙️ In this case-study version, computation is mocked — but the architecture, data normalization, and UX faithfully mirror the live production environment.

---

✨ Key Features

• 🔄 Flexible upload: TSV/CSV/XLSX; optional column mapping
• ✅ Upload QC: invalid sequences reported, download rejected_rows.csv
• 🏷️ Provenance pill: JPred/Tango ON/OFF + hit counts
• 📏 Six core metrics:
  1. 🦎 Chameleon prediction (SSW)
  2. 🌀 Helix segments (JPred)
  3. ⚡ Charge
  4. 💧 Hydrophobicity
  5. 🌊 Hydrophobic moment (μH)
  6. 🧬 FF-Helix (derived flag)
• 📈 Visualizations
  • 📉 Hydrophobicity distribution
  • 🎯 Hydrophobicity vs μH scatter
  • 🦎 Chameleon distribution & cohort radar
  • 📊 Sliding-window profiles (H & μH) with helix overlays
• 🎛️ Smart ranking: sliders for metric weights + Top-N shortlist (CSV)
• 🔍 Per-peptide deep dive: segment track, metrics, interpretations
• 📋 Exports: CSV export; PDF Report (one-click)
• ☁️ Cloud (optional): Save/Load datasets via Firebase Auth + Firestore

---

⚙️ How It Works

1. Backend (backend/ — FastAPI) 🐍

• ✅ Accepts UniProt exports (TSV/CSV/XLSX)
• 🔧 Normalizes headers; derives Length if missing
• 🧮 Computes Charge, Hydrophobicity, μH (sequence-based)
• 🔮 If local results present and enabled:
  • JPred → Helix fragments (Jpred), Helix score (Jpred)
  • Tango → SSW prediction, SSW score
• 🏁 Computes FF flags from cohort thresholds

2. Frontend (ui/ — React + Vite + shadcn/ui + Recharts) ⚛️

• 📤 Upload → 👀 Preview → 🔬 Analyze (calls backend)
• 🗺️ Optional column mapping
• 📊 Renders dashboards, detail pages, and exports

---

🚀 Quick Start (local)

1️⃣ Backend

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Feature flags (safe defaults)
export USE_TANGO=1          # Tango on (works with mac binary today)
export USE_PSIPRED=true     # OK if PSIPRED isn't installed; it will skip cleanly

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

2️⃣ Frontend

cd ui
npm install
echo "VITE_API_BASE_URL=http://127.0.0.1:8000" > .env.local
npm run dev   # open http://127.0.0.1:5173

📤 Upload a UniProt table (CSV/TSV/XLSX) with Entry and Sequence (others optional). 📊 You'll see cohort cards + ranking and a full table. Use Export CSV or Export shortlist.csv.

🔧 Tango & PSIPRED

🥭 Tango (macOS recommended)

1. Put your mac binary at backend/Tango/bin/tango

chmod +x backend/Tango/bin/tango

2. (Apple Silicon only, x86_64 binary) Install Rosetta:

softwareupdate --install-rosetta --agree-to-license

🧠 PSIPRED (optional; Docker)

Build/pull an image tagged psipred-hhblits and set PSIPRED_DB to your Uniclust folder. If not available, backend prints a warning and continues.

📖 Details are in DEPLOYMENT.md.

🌍 Deployment (make it globally accessible)

The backend can keep running locally in your lab and still be reachable worldwide over HTTPS. Choose one:

🅰️ Option A — Lab server + Cloudflare Tunnel (recommended)

• 🏠 Keep backend and Tango/PSIPRED on the lab laptop.
• 🎯 Serve the frontend either:
  • directly from the lab laptop (Nginx), or
  • host the static UI on Firebase Hosting/Vercel and proxy /api to the tunnel URL.
• 🌩️ Use Cloudflare Tunnel to expose http://127.0.0.1:8000 to the internet safely (no open inbound port).

Steps (summary):

1. 🏗️ Build the UI: cd ui && npm run build
2. 🌐 Install Nginx (or any static server) and serve ui/dist at /.
3. 🚇 Install Cloudflare Tunnel (cloudflared), authenticate, and create a tunnel that forwards:
   • /api/* → http://localhost:8000
   • / → local static files (or skip if using Firebase Hosting/Vercel)
4. 🎯 Point your domain DNS (Cloudflare) to the tunnel. You get free HTTPS.

This keeps sensitive tools and data inside your lab while offering a stable public URL.

🅱️ Option B — Cloud VM (Hetzner/AWS) with Docker

• 🖥️ Provision a small VM, install Docker.
• 🐳 Run backend in a container with Tango/PSIPRED binaries mounted (or baked into the image).
• 🌐 Serve UI via Nginx.
• 🔒 Add a domain + Let's Encrypt (or Caddy for auto-TLS).

©️ Option C — Split hosting (very simple)

• ☁️ Frontend on Firebase Hosting (push ui/dist/).
• 🏠 Backend stays on lab laptop. Expose /api via Cloudflare Tunnel and set VITE_API_BASE_URL="https://your-tunnel-domain.example/api" in the hosted UI.

📖 All options are fully described in DEPLOYMENT.md with exact commands and example configs.

🗺️ Roadmap (what's next)

• 🎨 Single-sequence drawer: PSIPRED curves (P(H)/P(E)/P(C)), Tango β-aggregation track, segment ribbons.
• 🔐 Auth + Firestore: sign-in, "previous datasets", cloud export of Tango/PSIPRED outputs (schema and rules outlined in DEV_GUIDE.md).
• 🔍 UniProt fetcher: type a protein or organism → fetch, window peptides to CSV, analyze.

📜 License

This repository is intended for research use. If you need a permissive OSI license, choose Apache-2.0 (recommended) or BSD-3-Clause.

For now, we include a DESY Research License template (LICENSE-DESY-RESEARCH.md). If you plan a public SaaS, consider switching to Apache-2.0.

🙏 Acknowledgements

• 🥭 Tango: Fernandez-Escamilla et al., Nat Biotechnol 22, 1302–1306 (2004).
• 🧠 PSIPRED: Jones, J Mol Biol 292, 195–202 (1999).
• 💜 Thanks to DESY / CSSB (Landau Lab): Said Azaizah & Dr. Aleksandr Golubev for guidance on SSW/FF calculations.