🇪🇸 Leer en Español  |  🇬🇧 Read in English

High-precision bioinformatics platform for microRNA research and biomarker discovery
_{Genomic Convergence  ·  PubMed Evidence  ·  Functional Enrichment  ·  Automated Scientific Reporting}

     

Overview  ·  Analysis Flow  ·  Features  ·  Tech Stack  ·  Databases  ·  Installation  ·  Roadmap

        

---

---

⚠️ Medical Disclaimer

KENRYU is for Research Use Only (RUO). It is not a substitute for professional medical judgment, individualized patient evaluation, local clinical guidelines, or review by a qualified healthcare professional. Evidence comes from public databases (NCBI, miRTarBase, TargetScan, STRING-DB) and must be rigorously verified before any therapeutic or research intervention. This platform does not store or process PII or PHI.

---

🔬 About the Project

MicroRNAs (miRNAs) are post-transcriptional regulators that control the expression of complex gene networks via targeted silencing. Identifying which genes are simultaneously regulated by multiple miRNAs is fundamental to discovering critical nodes in pathologies such as cancer, cardiovascular diseases, neurodegeneration, and metabolic disorders.

KENRYU automates the entire discovery workflow in one platform:

Step	Action	Sources
1	🔗 Integrate thermodynamic predictions + experimental validation	TargetScan · miRTarBase
2	🎯 Identify dynamic Venn intersection of core regulated genes	Local DB + Harmonizome
3	🧬 Enrich targets functionally with balancing algorithm	KEGG · Reactome · WikiPathways · GO
4	📡 Investigate each core gene across 4 sources in parallel	PubMed · OMIM · ClinVar · ClinicalTrials
5	📄 Generate editable academic report with Vancouver bibliography	PDF · Markdown ZIP · TXT

Unlike traditional pipelines, KENRYU uses a search cascade with fallback (strict → expanded → minimal) and real-time ES→EN translation to overcome PubMed's limitations with non-English queries. Fully optimized for Hugging Face Spaces with robust NCBI eUtils rate-limit handling.

---

⚡ Analysis Flow

Click on each phase to explore the underlying bioinformatics logic.

📥 01. INPUT	📊 02. COLLECTION	🎯 03. VENN CORE
miRNA selection	Multi-source retrieval	Genomic convergence

🧬 STEP 01 — Input & Parameters (Click to expand)

The Start: User enters N miRNAs in standard nomenclature.

• Dynamic Filtering: Define the year window for PubMed evidence.
• Validation: Automatic name cleaning for cross-database compatibility.

🔍 STEP 02 — Multi-Source Collection (Click to expand)

The Engine: Parallel querying of high-fidelity databases.

• TargetScan 8.0: Thermodynamic binding predictions (Local Database).
• miRTarBase: Gold-standard experimental validation via Harmonizome (Remote API).

💎 STEP 03 — Genomic Convergence (Click to expand)

The Logic: Mathematical intersection of regulatory networks.

• Strict Mode: Only genes common to ALL miRNAs.
• N-1 / N-2: Robust consensus for broader discoveries.

🧬 04. ENRICHMENT	📡 05. RESEARCH	📄 06. REPORT
Pathway analysis	Multi-source evidence	Professional output

📊 STEP 04 — Functional Enrichment (Click to expand)

The Context: Identifying biological impact.

• Databases: KEGG, Reactome, WikiPathways, and GO.
• Evidence: Automated PubMed cross-referencing for every significant pathway found.

📚 STEP 05 — Multi-Source Research (Click to expand)

The Evidence: Consolidating real-world scientific data.

• Live queries to ClinVar (variants) and OMIM (disorders).
• ClinicalTrials.gov integration for human-centric research insights.

✨ STEP 06 — Scientific Reporting (Click to expand)

The Result: Professional-grade academic reports.

• Vancouver Style: Auto-generated citations for all integrated sources.
• Multi-Format: Export to PDF, Markdown ZIP with assets, or raw TXT.

---

Consensus Modes

Mode	Description	Use Case
Strict	Genes regulated by ALL miRNAs in the panel	High-confidence core targets
N-1	Genes regulated by at least N-1 miRNAs	Robust regulatory networks
N-2	Genes regulated by at least N-2 miRNAs	Broader pathway exploration

---

🧩 Key Features

🔬 Bioinformatics Analysis

• Dynamic Convergence — Venn intersection of N miRNAs, no hardcoded limit on core gene count
• Balanced Functional Enrichment — fairness algorithm across KEGG, Reactome, WikiPathways, and GO Biological Process
• Volcano plot · Venn diagram · STRING-DB interactome — generated on-the-fly per analysis

📡 Multi-source Research

Source	What it provides
PubMed	Scientific articles per gene + biological context, year-filtered with cascade fallback
OMIM	Mendelian Inheritance in Man — associated hereditary diseases
ClinVar	Reported pathogenic / likely pathogenic variant count
ClinicalTrials.gov	Active clinical trials where the gene symbol appears in the title

⚡ Robustness & Performance

• 429-aware Retries — automatic NCBI eUtils rate-limit handling with exponential backoff
• Persistent Cache — local_db/analysis_cache.json stores translations, PubMed results, and enrichment across sessions
• ES→EN Mapping — auto-translates biological terms from Spanish presets for effective PubMed queries
• Filter Cascade — strict → expanded → minimal year window fallback

📄 Report Generation

• Professional A4 Editor — WYSIWYG preview with smart height-based pagination
• Vancouver Bibliography — [N] Authors. Title. Journal. Year. PMID: X. URL
• Multi-type Citations — PMID / OMIM / ClinVar / NCT with correct identifier per source
• PDF Export — via window.print() with optimized @media print CSS, footer anchored to each A4 page
• Markdown ZIP Export — Report.md + /assets/ PNGs + README.md — Pandoc/Obsidian/VSCode compatible

---

📸 Screenshots

_{Main interface — Volcano plot, Venn diagram, and STRING-DB interactome generated live. (Note: The clinical interface displays analytical metrics and parameter presets in Spanish for localized environments).}

_{Bioinformatics charts — Functional enrichment visualization}

_{Gene sidebars — Quick access to OMIM, ClinVar, and trial data}

_{Research results — PubMed · OMIM · ClinVar · ClinicalTrials consolidated}

_{Narrative report — Academic synthesis with Vancouver bibliography. The automated export functions render structured clinical narratives, cross-referenced literature insights, and citation indices.}

---

🏗️ Architecture

                    ┌─────────────────────────────────┐
                    │   Frontend (HTML / JS / CSS)    │
                    │  · Paged A4 WYSIWYG Editor      │
                    │  · PDF · Markdown ZIP · TXT     │
                    └────────────┬────────────────────┘
                                 │  POST /api/v1/analyze
                                 ▼
                    ┌─────────────────────────────────┐
                    │  FastAPI Backend — kenryu_engine│
                    │  · Venn Intersection Engine     │
                    │  · Functional Enrichment        │
                    │  · Multi-source Research        │
                    └────────────┬────────────────────┘
                                 │
       ┌──────────┬──────────────┼───────────────┬──────────────────┐
       ▼          ▼              ▼               ▼                  ▼
 ┌──────────┐ ┌──────────┐ ┌─────────┐ ┌─────────────┐ ┌────────────────┐
 │TargetScan│ │miRTarBase│ │ Enrichr │ │NCBI PubMed  │ │ OMIM · ClinVar │
 │ v8 local │ │(Harmoniz)│ │KEGG/GO… │ │  eUtils     │ │  ClinicalTrials│
 └──────────┘ └──────────┘ └─────────┘ └─────────────┘ └────────────────┘
                                 │
                                 ▼
                    ┌─────────────────────────────────┐
                    │  Persistent Cache               │
                    │  local_db/analysis_cache.json   │
                    └─────────────────────────────────┘

---

🛠️ Tech Stack

Backend

Frontend

Deployment

---

🗄️ Integrated APIs & Databases

Source	Function	Type
🧬 TargetScanHuman v8.0	Thermodynamic prediction of binding sites	Local (zip)
🔬 miRTarBase via Harmonizome	Experimental interaction validation (CLIP-seq, Luciferase, WB)	Remote API
📊 Enrichr	Functional enrichment — KEGG / Reactome / WikiPathways / GO	Remote API
📚 NCBI PubMed eUtils	Scientific articles per gene + context with cascade + retries	Remote API
🏥 NCBI OMIM	Associated hereditary diseases by gene symbol	Remote API
🧪 NCBI ClinVar	Reported pathogenic / likely pathogenic variants	Remote API
💊 ClinicalTrials.gov v2	Active clinical trials filtered by gene symbol in title	Remote API
🔗 STRING-DB	Protein-protein interaction network generation	Remote API
🌐 MyGene.info	Clinical gene annotation	Remote API
🔤 MyMemory API	Real-time ES↔EN biological term translation	Remote API

---

📦 Installation

Prerequisites

• Python 3.11+
• pip
• Docker (optional — for containerized deployment)

Local Setup

# 1. Clone the repository
git clone https://github.com/abrangel/Kenryu.git
cd Kenryu

# 2. Create virtual environment (recommended)
python3.11 -m venv venv
source venv/bin/activate      # Linux / macOS
# venv\Scripts\activate       # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Start the server
uvicorn kenryu_engine:app --host 0.0.0.0 --port 7860 --reload

# 5. Open in browser → http://localhost:7860

Docker Deployment

docker build -t kenryu .
docker run -p 7860:7860 -v $(pwd)/local_db:/app/local_db kenryu

The local_db volume persists the analysis cache across container restarts.

Hugging Face Spaces

The repo is fully ready for HF Spaces — the Dockerfile exposes port 7860 and mounts local_db for persistent caching. Simply connect the Space to this GitHub repository.

---

🚀 Usage

Via Web Interface

1. Open production Space or http://localhost:7860
2. Enter miRNAs separated by commas: hsa-miR-33a-5p, hsa-miR-144-3p, hsa-miR-758-3p
3. Select year cutoff (PubMed evidence age filter)
4. Select consensus mode (Strict / N-1 / N-2)
5. Click Execute

Via REST API

curl -X POST "http://localhost:7860/api/v1/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "mirnas": ["hsa-miR-33a-5p", "hsa-miR-144-3p", "hsa-miR-758-3p"],
    "years": 10,
    "mode": "strict"
  }'

📋 Example JSON Response

{
  "common_genes": ["ABCA1", "KPNA3", "SCN1A"],
  "gene_research": {
    "ABCA1": {
      "pubmed": [{"pmid": "...", "term": "...", "year_window": "10y"}],
      "omim":   [{"omim_id": "600046", "title": "..."}],
      "clinvar": {"count": 201, "url": "..."},
      "trials":  [{"nct_id": "NCT01456650", "title": "..."}]
    }
  },
  "enrichment": ["..."],
  "scientific_synthesis": "...",
  "venn_plot":    "data:image/png;base64,...",
  "volcano_plot": "data:image/png;base64,...",
  "ppi_plot":     "data:image/png;base64,..."
}

---

📁 Repository Structure

Kenryu/
├── kenryu_engine.py              # FastAPI backend + bioinformatics logic (~1700 lines)
├── Dockerfile                    # HF Spaces / Docker configuration
├── requirements.txt
│
├── static/
│   ├── index.html                # A4 editor main interface
│   ├── script.js                 # Frontend logic (pagination, PDF/MD export)
│   └── style.css                 # Dark mode · gold/teal accents
│
├── data/
│   ├── targetscan_full.json.zip  # TargetScan v8.0 indexed DB (Git LFS, ~8 MB)
│   └── hsa-miR-*.txt             # Pre-processed per-miRNA example files
│
└── local_db/                     # Runtime cache (auto-created, not in repo)
    └── analysis_cache.json

---

🗺️ Roadmap

✅ Implemented

• Dynamic Venn convergence — Strict / N-1 / N-2 modes
• Balanced functional enrichment — KEGG · Reactome · WikiPathways · GO
• Visualizations — Venn · Volcano · STRING-DB interactome
• Vancouver-style bibliography with multi-source citation types
• Multi-source research — PubMed · OMIM · ClinVar · ClinicalTrials
• Versioned persistent cache across sessions
• 429-aware retries with exponential backoff for NCBI eUtils
• ES→EN mapping for effective PubMed queries
• Professional Markdown ZIP export with separate image assets
• A4 PDF footer correctly anchored across all pages
• Integrated genomic evidence narrative in report body

🔜 Planned

• Support for miRNA isomers (isomiRs)
• DisGeNET integration for gene-disease association
• Structured JSON export for interoperability with other tools
• Side-by-side miRNA panel comparison
• Cross-expression heatmap (genes × miRNAs)
• Batch mode — process multiple panels from CSV
• TargetScan v9.0 integration when available

---

🤝 Contributing

Contributions are welcome. To report bugs, suggest features, or submit pull requests:

1. Fork the repository
2. Create a branch: git checkout -b feat/feature-name
3. Commit with descriptive messages following conventions below
4. Push: git push origin feat/feature-name
5. Open a Pull Request

Commit conventions: feat: · fix: · docs: · refactor: · chore:

When reporting bugs please include: steps to reproduce, expected vs actual behavior, browser console logs (frontend errors), and HF Space logs (backend errors).

---

📜 License

This project is distributed under a Free Academic License for Research and Education. For commercial use, contact the author.

KENRYU integrates data from public sources (NCBI, Enrichr, OMIM, ClinVar, ClinicalTrials.gov, STRING-DB) subject to their respective terms of service. Users are responsible for complying with each database's policies.

---

👤 Author

Cesar Manzo — Clinical Bioinformatics · Genomic Analysis · Translational Medicine

---

🙏 Acknowledgements

• TargetScanHuman — Lewis Lab, Whitehead Institute
• miRTarBase — Chou et al., Nucleic Acids Research
• NCBI — National Center for Biotechnology Information
• Enrichr — Ma'ayan Lab, Mount Sinai
• ClinicalTrials.gov — U.S. National Library of Medicine
• STRING-DB — European Molecular Biology Laboratory

---

_{KENRYU Bioinformatics Engine · 2026
Made with scientific rigor for the genomic research community.}