Migrate to new MuSProt.db schema (aliased columns, new stats)

Alias renamed edge columns to existing API names in SQL, switch node path to
binding_status/cath_id, use COLLATE NOCASE for the new idx_pdb_chain index, and
refresh the summary stat cards and schema docs for the new DB.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/app/protein/api/routes/protein.py

@@ -1,267 +1,267 @@
-"""Protein API routes."""
-import logging
-import math
-from typing import Dict, List
-
-from fastapi import APIRouter, HTTPException, Query
-
-from app.protein.chain_resolver import (
-    batch_resolve_chains_async,
-    get_cache,
-    resolve_chain_async,
-)
-from app.protein.data_loader import DataManager
-from app.protein import tsv_loader
-from app.protein.models import (
-    ChainMetadata,
-    DataRecord,
-    DataResponse,
-    FilterOptions,
-    FilterParams,
-    SummaryStats,
-)
-
-logger = logging.getLogger(__name__)
-router = APIRouter()
-
-data_manager: DataManager | None = None
-
-
-def set_data_manager(manager: DataManager | None) -> None:
-    """Set the active data manager for route handlers."""
-    global data_manager
-    data_manager = manager
-
-
-def _require_data_manager() -> DataManager:
-    """Return data manager or raise if not initialized."""
-    if data_manager is None:
-        raise HTTPException(
-            status_code=503,
-            detail="Protein data is not initialized yet"
-        )
-    return data_manager
-
-
-@router.get("/")
-async def root():
-    """Root endpoint."""
-    return {
-        "message": "Protein Visualisation API",
-        "version": "1.0.0",
-        "endpoints": {
-            "/filters": "Get available filter options",
-            "/data": "Get filtered protein data",
-            "/summary": "Get aggregate statistics"
-        }
-    }
-
-
-@router.get("/filters", response_model=FilterOptions)
-async def get_filters():
-    """Get available filter options and ranges."""
-    try:
-        manager = _require_data_manager()
-        chains = sorted(manager.get_chain_sample())
-        fd = manager.get_filters_data()
-
-        return FilterOptions(
-            chain_ids=chains[:100],
-            rmsd_range={"min": float(fd["rmsd_min"]), "max": float(fd["rmsd_max"])},
-            tm_score_range={"min": float(fd["tm_min"]), "max": float(fd["tm_max"])},
-            length_range={"min": int(fd["length_min"]), "max": int(fd["length_max"])},
-            clusters=[
-                "cluster_ultra_high", "cluster_very_high", "cluster_high",
-                "cluster_medium", "cluster_low",
-            ],
-            total_records=fd["total_records"],
-        )
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Error getting filters: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-
-
-@router.post("/data", response_model=DataResponse)
-async def get_data(filters: FilterParams):
-    """Get filtered protein data. Searches only by pdb_id_A and auth_asym_id_A."""
-    try:
-        manager = _require_data_manager()
-        limit = filters.limit or 1000
-        fetch_limit = limit * 10 if filters.cluster_id else limit
-
-        df = manager.query_edge(
-            pdb_id_a=filters.pdb_id,
-            auth_asym_id_a=filters.auth_asym_id,
-            chain_ids=filters.chain_ids,
-            rmsd_min=filters.rmsd_min,
-            rmsd_max=filters.rmsd_max,
-            tm_min=filters.tm_score_min,
-            tm_max=filters.tm_score_max,
-            limit=fetch_limit,
-        )
-
-        if filters.cluster_id:
-            df = df[df["cluster_id"] == filters.cluster_id]
-
-        filtered_total = len(df)
-        df = df.head(limit)
-
-        def _safe_float(val):
-            try:
-                v = float(val)
-                return None if math.isnan(v) else round(v, 6)
-            except (TypeError, ValueError):
-                return None
-
-        records = []
-        for row in df.itertuples(index=False):
-            raw_ph = getattr(row, "pH", None)
-            raw_temp = getattr(row, "temp_K", None)
-            records.append(DataRecord(
-                pdb_id_a=row.pdb_id_A,
-                auth_asym_id_a=row.auth_asym_id_A,
-                pdb_id_b=row.pdb_id_B,
-                auth_asym_id_b=row.auth_asym_id_B,
-                tm_score=float(row.TM1) if row.TM1 is not None else 0.0,
-                rmsd=float(row.RMSD) if row.RMSD is not None else 0.0,
-                structure_sim=_safe_float(row.structure_sim),
-                length_a=int(row.length_a) if row.length_a is not None else None,
-                length_b=int(row.length_b) if row.length_b is not None else None,
-                cluster_id=row.cluster_id,
-                exptl_method=getattr(row, "experimental_method", None) or None,
-                pH=_safe_float(raw_ph) if raw_ph else None,
-                temp=_safe_float(raw_temp) if raw_temp else None,
-                binding_status=getattr(row, "base_label", None) or None,
-                chain_composition=getattr(row, "chain_composition", None) or None,
-                delta_rosetta=_safe_float(getattr(row, "delta_Rosetta", None)),
-                delta_foldx=_safe_float(getattr(row, "delta_FoldX", None)),
-                delta_evoef2=_safe_float(getattr(row, "delta_EvoEF2", None)),
-                delta_rw=_safe_float(getattr(row, "delta_RW", None)),
-                delta_rw_plus=_safe_float(getattr(row, "delta_RW_plus", None)),
-                state_id_b=getattr(row, "state_id_B", None) or None,
-                state_fidelity=getattr(row, "state_fidelity", None) or None,
-                avg_sim=getattr(row, "avg_sim", None) or None,
-                observation_fidelity=getattr(row, "observation_fidelity", None) or None,
-            ))
-
-        return DataResponse(
-            data=records,
-            total=manager.get_total(),
-            filtered=filtered_total,
-        )
-
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Error filtering data: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-
-
-@router.get("/summary", response_model=SummaryStats)
-async def get_summary(
-    chain_ids: List[str] = Query(default=None),
-    rmsd_min: float = Query(default=None),
-    rmsd_max: float = Query(default=None),
-    tm_score_min: float = Query(default=None),
-    tm_score_max: float = Query(default=None),
-):
-    """Get aggregate statistics for the dataset or filtered subset."""
-    try:
-        manager = _require_data_manager()
-        stats = manager.get_summary_stats(
-            chain_ids=chain_ids,
-            rmsd_min=rmsd_min,
-            rmsd_max=rmsd_max,
-            tm_min=tm_score_min,
-            tm_max=tm_score_max,
-        )
-        return SummaryStats(
-            total_records=stats["total_records"],
-            unique_chains=stats["unique_chains"],
-            avg_rmsd=float(stats["avg_rmsd"]),
-            avg_tm_score=float(stats["avg_tm_score"]),
-            avg_sequence_length=float(stats["avg_sequence_length"]),
-            rmsd_distribution={str(k): int(v) for k, v in stats["rmsd_distribution"].items()},
-            tm_score_distribution={str(k): int(v) for k, v in stats["tm_score_distribution"].items()},
-            length_distribution={str(k): int(v) for k, v in stats["length_distribution"].items()},
-        )
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Error computing summary: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-
-
-@router.get("/chain/resolve", response_model=ChainMetadata)
-async def resolve_chain_endpoint(
-    pdb_id: str = Query(..., description="4-character PDB ID"),
-    auth_asym_id: str = Query(..., description="Chain identifier (e.g., 'A')"),
-    use_cache: bool = Query(True, description="Use cached data if available")
-):
-    """Resolve chain metadata from RCSB web API."""
-    metadata = await resolve_chain_async(pdb_id, auth_asym_id, use_cache=use_cache)
-    return metadata.model_copy(update={
-        "binding_status": tsv_loader.get_binding_status(pdb_id, auth_asym_id),
-        "chain_composition": tsv_loader.get_chain_composition(pdb_id, auth_asym_id),
-        "cath_id": tsv_loader.get_cath_id(pdb_id, auth_asym_id),
-        "cath_superfamily": tsv_loader.get_cath_superfamily(pdb_id, auth_asym_id),
-        "state_id": tsv_loader.get_state_id(pdb_id, auth_asym_id),
-    })
-
-
-@router.post("/chain/batch-resolve")
-async def batch_resolve_chains_endpoint(
-    chains: List[Dict[str, str]],
-    use_cache: bool = Query(True, description="Use cached data if available")
-):
-    """Batch resolve multiple chains at once."""
-    chain_tuples = []
-    for chain in chains:
-        pdb_id = chain.get("pdb_id")
-        auth_asym_id = chain.get("auth_asym_id")
-        if pdb_id and auth_asym_id:
-            chain_tuples.append((pdb_id, auth_asym_id))
-
-    result = await batch_resolve_chains_async(chain_tuples, use_cache=use_cache)
-    return {
-        key: metadata.model_copy(update={
-            "binding_status": tsv_loader.get_binding_status(*key.split("|")),
-            "chain_composition": tsv_loader.get_chain_composition(*key.split("|")),
-            "cath_id": tsv_loader.get_cath_id(*key.split("|")),
-            "cath_superfamily": tsv_loader.get_cath_superfamily(*key.split("|")),
-            "state_id": tsv_loader.get_state_id(*key.split("|")),
-        })
-        for key, metadata in result.items()
-    }
-
-
-@router.get("/chain/cache/stats")
-async def cache_stats():
-    """Get cache statistics."""
-    cache = get_cache()
-    return {
-        "cached_chains": len(cache.cache),
-        "ttl_hours": cache.ttl.total_seconds() / 3600
-    }
-
-
-@router.get("/chain/functions")
-async def get_chain_functions(
-    pdb_id: str = Query(..., description="4-character PDB ID"),
-    auth_asym_id: str = Query(..., description="Chain identifier (e.g., 'A')"),
-):
-    """Return ranked functional annotations for a chain from node table."""
-    functions = tsv_loader.get_functions(pdb_id, auth_asym_id)
-    if functions is None:
-        raise HTTPException(status_code=404, detail=f"No annotation found for {pdb_id}:{auth_asym_id}")
-    return {"pdb_id": pdb_id.lower(), "chain_id": auth_asym_id.upper(), "functions": functions}
-
-
-@router.post("/chain/cache/clear")
-async def clear_cache():
-    """Clear the chain metadata cache."""
-    cache = get_cache()
-    cache.clear()
-    return {"message": "Cache cleared successfully"}
+"""Protein API routes."""
+import logging
+import math
+from typing import Dict, List
+
+from fastapi import APIRouter, HTTPException, Query
+
+from app.protein.chain_resolver import (
+    batch_resolve_chains_async,
+    get_cache,
+    resolve_chain_async,
+)
+from app.protein.data_loader import DataManager
+from app.protein import tsv_loader
+from app.protein.models import (
+    ChainMetadata,
+    DataRecord,
+    DataResponse,
+    FilterOptions,
+    FilterParams,
+    SummaryStats,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+data_manager: DataManager | None = None
+
+
+def set_data_manager(manager: DataManager | None) -> None:
+    """Set the active data manager for route handlers."""
+    global data_manager
+    data_manager = manager
+
+
+def _require_data_manager() -> DataManager:
+    """Return data manager or raise if not initialized."""
+    if data_manager is None:
+        raise HTTPException(
+            status_code=503,
+            detail="Protein data is not initialized yet"
+        )
+    return data_manager
+
+
+@router.get("/")
+async def root():
+    """Root endpoint."""
+    return {
+        "message": "Protein Visualisation API",
+        "version": "1.0.0",
+        "endpoints": {
+            "/filters": "Get available filter options",
+            "/data": "Get filtered protein data",
+            "/summary": "Get aggregate statistics"
+        }
+    }
+
+
+@router.get("/filters", response_model=FilterOptions)
+async def get_filters():
+    """Get available filter options and ranges."""
+    try:
+        manager = _require_data_manager()
+        chains = sorted(manager.get_chain_sample())
+        fd = manager.get_filters_data()
+
+        return FilterOptions(
+            chain_ids=chains[:100],
+            rmsd_range={"min": float(fd["rmsd_min"]), "max": float(fd["rmsd_max"])},
+            tm_score_range={"min": float(fd["tm_min"]), "max": float(fd["tm_max"])},
+            length_range={"min": int(fd["length_min"]), "max": int(fd["length_max"])},
+            clusters=[
+                "cluster_ultra_high", "cluster_very_high", "cluster_high",
+                "cluster_medium", "cluster_low",
+            ],
+            total_records=fd["total_records"],
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error getting filters: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/data", response_model=DataResponse)
+async def get_data(filters: FilterParams):
+    """Get filtered protein data. Searches only by pdb_id_A and auth_asym_id_A."""
+    try:
+        manager = _require_data_manager()
+        limit = filters.limit or 1000
+        fetch_limit = limit * 10 if filters.cluster_id else limit
+
+        df = manager.query_edge(
+            pdb_id_a=filters.pdb_id,
+            auth_asym_id_a=filters.auth_asym_id,
+            chain_ids=filters.chain_ids,
+            rmsd_min=filters.rmsd_min,
+            rmsd_max=filters.rmsd_max,
+            tm_min=filters.tm_score_min,
+            tm_max=filters.tm_score_max,
+            limit=fetch_limit,
+        )
+
+        if filters.cluster_id:
+            df = df[df["cluster_id"] == filters.cluster_id]
+
+        filtered_total = len(df)
+        df = df.head(limit)
+
+        def _safe_float(val):
+            try:
+                v = float(val)
+                return None if math.isnan(v) else round(v, 6)
+            except (TypeError, ValueError):
+                return None
+
+        records = []
+        for row in df.itertuples(index=False):
+            raw_ph = getattr(row, "pH", None)
+            raw_temp = getattr(row, "temp_K", None)
+            records.append(DataRecord(
+                pdb_id_a=row.pdb_id_A,
+                auth_asym_id_a=row.auth_asym_id_A,
+                pdb_id_b=row.pdb_id_B,
+                auth_asym_id_b=row.auth_asym_id_B,
+                tm_score=float(row.TM1) if row.TM1 is not None else 0.0,
+                rmsd=float(row.RMSD) if row.RMSD is not None else 0.0,
+                structure_sim=_safe_float(row.structure_sim),
+                length_a=int(row.length_a) if row.length_a is not None else None,
+                length_b=int(row.length_b) if row.length_b is not None else None,
+                cluster_id=row.cluster_id,
+                exptl_method=getattr(row, "experimental_method", None) or None,
+                pH=_safe_float(raw_ph) if raw_ph else None,
+                temp=_safe_float(raw_temp) if raw_temp else None,
+                binding_status=getattr(row, "binding_status", None) or None,
+                chain_composition=getattr(row, "chain_composition", None) or None,
+                delta_rosetta=_safe_float(getattr(row, "delta_Rosetta", None)),
+                delta_foldx=_safe_float(getattr(row, "delta_FoldX", None)),
+                delta_evoef2=_safe_float(getattr(row, "delta_EvoEF2", None)),
+                delta_rw=_safe_float(getattr(row, "delta_RW", None)),
+                delta_rw_plus=_safe_float(getattr(row, "delta_RW_plus", None)),
+                state_id_b=getattr(row, "state_id_B", None) or None,
+                state_fidelity=getattr(row, "state_fidelity", None) or None,
+                avg_sim=getattr(row, "avg_sim", None) or None,
+                observation_fidelity=getattr(row, "observation_fidelity", None) or None,
+            ))
+
+        return DataResponse(
+            data=records,
+            total=manager.get_total(),
+            filtered=filtered_total,
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error filtering data: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/summary", response_model=SummaryStats)
+async def get_summary(
+    chain_ids: List[str] = Query(default=None),
+    rmsd_min: float = Query(default=None),
+    rmsd_max: float = Query(default=None),
+    tm_score_min: float = Query(default=None),
+    tm_score_max: float = Query(default=None),
+):
+    """Get aggregate statistics for the dataset or filtered subset."""
+    try:
+        manager = _require_data_manager()
+        stats = manager.get_summary_stats(
+            chain_ids=chain_ids,
+            rmsd_min=rmsd_min,
+            rmsd_max=rmsd_max,
+            tm_min=tm_score_min,
+            tm_max=tm_score_max,
+        )
+        return SummaryStats(
+            total_records=stats["total_records"],
+            unique_chains=stats["unique_chains"],
+            avg_rmsd=float(stats["avg_rmsd"]),
+            avg_tm_score=float(stats["avg_tm_score"]),
+            avg_sequence_length=float(stats["avg_sequence_length"]),
+            rmsd_distribution={str(k): int(v) for k, v in stats["rmsd_distribution"].items()},
+            tm_score_distribution={str(k): int(v) for k, v in stats["tm_score_distribution"].items()},
+            length_distribution={str(k): int(v) for k, v in stats["length_distribution"].items()},
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error computing summary: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/chain/resolve", response_model=ChainMetadata)
+async def resolve_chain_endpoint(
+    pdb_id: str = Query(..., description="4-character PDB ID"),
+    auth_asym_id: str = Query(..., description="Chain identifier (e.g., 'A')"),
+    use_cache: bool = Query(True, description="Use cached data if available")
+):
+    """Resolve chain metadata from RCSB web API."""
+    metadata = await resolve_chain_async(pdb_id, auth_asym_id, use_cache=use_cache)
+    return metadata.model_copy(update={
+        "binding_status": tsv_loader.get_binding_status(pdb_id, auth_asym_id),
+        "chain_composition": tsv_loader.get_chain_composition(pdb_id, auth_asym_id),
+        "cath_id": tsv_loader.get_cath_id(pdb_id, auth_asym_id),
+        "cath_superfamily": tsv_loader.get_cath_superfamily(pdb_id, auth_asym_id),
+        "state_id": tsv_loader.get_state_id(pdb_id, auth_asym_id),
+    })
+
+
+@router.post("/chain/batch-resolve")
+async def batch_resolve_chains_endpoint(
+    chains: List[Dict[str, str]],
+    use_cache: bool = Query(True, description="Use cached data if available")
+):
+    """Batch resolve multiple chains at once."""
+    chain_tuples = []
+    for chain in chains:
+        pdb_id = chain.get("pdb_id")
+        auth_asym_id = chain.get("auth_asym_id")
+        if pdb_id and auth_asym_id:
+            chain_tuples.append((pdb_id, auth_asym_id))
+
+    result = await batch_resolve_chains_async(chain_tuples, use_cache=use_cache)
+    return {
+        key: metadata.model_copy(update={
+            "binding_status": tsv_loader.get_binding_status(*key.split("|")),
+            "chain_composition": tsv_loader.get_chain_composition(*key.split("|")),
+            "cath_id": tsv_loader.get_cath_id(*key.split("|")),
+            "cath_superfamily": tsv_loader.get_cath_superfamily(*key.split("|")),
+            "state_id": tsv_loader.get_state_id(*key.split("|")),
+        })
+        for key, metadata in result.items()
+    }
+
+
+@router.get("/chain/cache/stats")
+async def cache_stats():
+    """Get cache statistics."""
+    cache = get_cache()
+    return {
+        "cached_chains": len(cache.cache),
+        "ttl_hours": cache.ttl.total_seconds() / 3600
+    }
+
+
+@router.get("/chain/functions")
+async def get_chain_functions(
+    pdb_id: str = Query(..., description="4-character PDB ID"),
+    auth_asym_id: str = Query(..., description="Chain identifier (e.g., 'A')"),
+):
+    """Return ranked functional annotations for a chain from node table."""
+    functions = tsv_loader.get_functions(pdb_id, auth_asym_id)
+    if functions is None:
+        raise HTTPException(status_code=404, detail=f"No annotation found for {pdb_id}:{auth_asym_id}")
+    return {"pdb_id": pdb_id.lower(), "chain_id": auth_asym_id.upper(), "functions": functions}
+
+
+@router.post("/chain/cache/clear")
+async def clear_cache():
+    """Clear the chain metadata cache."""
+    cache = get_cache()
+    cache.clear()
+    return {"message": "Cache cleared successfully"}

backend/app/protein/data_loader.py

@@ -1,337 +1,338 @@
-"""
-SQLite-based data loader for protein structure data.
-Reads from MuSProt.db: edge table (pairwise comparisons from CSV)
-and node table (chain annotations from TSV).
-"""
-import json
-import pandas as pd
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Set
-import logging
-
-from app.protein.config import get_database_path, get_summary_path
-from app.protein.database import connect_readonly
-
-logger = logging.getLogger(__name__)
-
-
-def _assign_cluster(tm: float) -> str:
-    if tm >= 0.99:
-        return "cluster_ultra_high"
-    if tm >= 0.95:
-        return "cluster_very_high"
-    if tm >= 0.90:
-        return "cluster_high"
-    if tm >= 0.80:
-        return "cluster_medium"
-    return "cluster_low"
-
-
-class DataManager:
-    """Manages SQL queries against MuSProt.db edge and node tables."""
-
-    def __init__(self, db_path: Optional[Path] = None, **_kwargs):
-        self.db_path = db_path or get_database_path()
-        self._loaded = False
-        self._total_records = 0
-        self._summary: Dict[str, Any] = {}
-
-    def load_data(self) -> None:
-        """Verify DB is accessible and load optional precomputed metadata."""
-        if self._loaded:
-            return
-        summary_path = get_summary_path()
-        if summary_path:
-            self._summary = json.loads(summary_path.read_text(encoding="utf-8"))
-            self._total_records = int(self._summary.get("total_records", 0))
-
-        conn = connect_readonly(self.db_path)
-        try:
-            cur = conn.cursor()
-            cur.execute("SELECT 1 FROM edge LIMIT 1")
-            if not self._total_records:
-                logger.warning(
-                    "No musprot_summary.json found; counting edge rows during startup. "
-                    "Publish the summary sidecar to avoid this scan."
-                )
-                cur.execute("SELECT COUNT(*) FROM edge")
-                self._total_records = cur.fetchone()[0]
-        finally:
-            conn.close()
-        self._loaded = True
-        logger.info(f"DataManager ready: {self._total_records:,} edge records in {self.db_path}")
-
-    def _connect(self):
-        if not self._loaded:
-            raise RuntimeError("Call load_data() first.")
-        return connect_readonly(self.db_path)
-
-    def get_chain_sample(self, limit: int = 500) -> Set[str]:
-        """Return a small chain sample without loading the full node index."""
-        conn = self._connect()
-        try:
-            cur = conn.cursor()
-            cur.execute(
-                "SELECT pdb_id, auth_asym_id FROM node "
-                "WHERE pdb_id IS NOT NULL AND auth_asym_id IS NOT NULL LIMIT ?",
-                (limit,),
-            )
-            return {
-                f"{str(pdb).upper()}_{str(chain).upper()}"
-                for pdb, chain in cur.fetchall()
-            }
-        finally:
-            conn.close()
-
-    def get_filters_data(self) -> Dict[str, Any]:
-        """Return aggregated ranges for filter UI."""
-        if self._summary:
-            return {
-                "tm_min": self._summary["tm_score_range"]["min"],
-                "tm_max": self._summary["tm_score_range"]["max"],
-                "rmsd_min": self._summary["rmsd_range"]["min"],
-                "rmsd_max": self._summary["rmsd_range"]["max"],
-                "length_min": self._summary["length_range"]["min"],
-                "length_max": self._summary["length_range"]["max"],
-                "total_records": self._total_records,
-            }
-
-        conn = self._connect()
-        try:
-            cur = conn.cursor()
-            cur.execute(
-                "SELECT MIN(CAST(TM1 AS REAL)), MAX(CAST(TM1 AS REAL)),"
-                "       MIN(CAST(RMSD AS REAL)), MAX(CAST(RMSD AS REAL))"
-                " FROM edge"
-            )
-            tm_min, tm_max, rmsd_min, rmsd_max = cur.fetchone()
-        finally:
-            conn.close()
-
-        from app.protein import tsv_loader
-        lengths = []
-        for row in tsv_loader._get_index().values():
-            try:
-                lengths.append(int(row["sequence_length"]))
-            except (ValueError, TypeError):
-                pass
-
-        return {
-            "tm_min": tm_min or 0.0,
-            "tm_max": tm_max or 1.0,
-            "rmsd_min": rmsd_min or 0.0,
-            "rmsd_max": rmsd_max or 10.0,
-            "length_min": min(lengths) if lengths else 0,
-            "length_max": max(lengths) if lengths else 0,
-            "total_records": self._total_records,
-        }
-
-    def query_edge(
-        self,
-        pdb_id_a: Optional[str] = None,
-        auth_asym_id_a: Optional[str] = None,
-        chain_ids: Optional[List[str]] = None,
-        rmsd_min: Optional[float] = None,
-        rmsd_max: Optional[float] = None,
-        tm_min: Optional[float] = None,
-        tm_max: Optional[float] = None,
-        limit: int = 1000,
-    ) -> pd.DataFrame:
-        """Query edge table with filters. Returns DataFrame with cluster_id and lengths."""
-        where_clauses: List[str] = []
-        params: List[Any] = []
-
-        if pdb_id_a and auth_asym_id_a:
-            where_clauses.append("LOWER(pdb_id_A) = LOWER(?) AND LOWER(auth_asym_id_A) = LOWER(?)")
-            params.extend([pdb_id_a, auth_asym_id_a])
-        elif chain_ids:
-            sub: List[str] = []
-            for cid in chain_ids:
-                parts = cid.split("_", 1)
-                if len(parts) == 2:
-                    sub.append("(LOWER(pdb_id_A) = LOWER(?) AND LOWER(auth_asym_id_A) = LOWER(?))")
-                    params.extend(parts)
-            if sub:
-                where_clauses.append("(" + " OR ".join(sub) + ")")
-
-        if rmsd_min is not None:
-            where_clauses.append("CAST(RMSD AS REAL) >= ?")
-            params.append(rmsd_min)
-        if rmsd_max is not None:
-            where_clauses.append("CAST(RMSD AS REAL) <= ?")
-            params.append(rmsd_max)
-        if tm_min is not None:
-            where_clauses.append("CAST(TM1 AS REAL) >= ?")
-            params.append(tm_min)
-        if tm_max is not None:
-            where_clauses.append("CAST(TM1 AS REAL) <= ?")
-            params.append(tm_max)
-
-        where_sql = ("WHERE " + " AND ".join(where_clauses)) if where_clauses else ""
-        sql = f"""
-            SELECT e.pdb_id_A, e.auth_asym_id_A, e.pdb_id_B, e.auth_asym_id_B,
-                   CAST(e.TM1 AS REAL) AS TM1,
-                   CAST(e.RMSD AS REAL) AS RMSD,
-                   CAST(e.structure_sim AS REAL) AS structure_sim,
-                   e."delta_Rosetta", e."delta_FoldX", e."delta_EvoEF2",
-                   e."delta_RW", e."delta_RW+",
-                   e.state_id_B, e.state_fidelity, e.avg_sim, e.observation_fidelity
-            FROM edge e
-            {where_sql}
-            LIMIT ?
-        """
-        params.append(limit)
-
-        conn = self._connect()
-        try:
-            df = pd.read_sql_query(sql, conn, params=params)
-        finally:
-            conn.close()
-
-        # Rename columns with special characters so itertuples works cleanly
-        df = df.rename(columns={"delta_RW+": "delta_RW_plus"})
-
-        df["cluster_id"] = df["TM1"].apply(
-            lambda t: _assign_cluster(t) if pd.notna(t) else "cluster_low"
-        )
-
-        from app.protein import tsv_loader
-        df["length_a"] = [
-            tsv_loader.get_sequence(r.pdb_id_A, r.auth_asym_id_A)[1]
-            for r in df.itertuples(index=False)
-        ]
-        df["length_b"] = [
-            tsv_loader.get_sequence(r.pdb_id_B, r.auth_asym_id_B)[1]
-            for r in df.itertuples(index=False)
-        ]
-        node_rows = [
-            tsv_loader.get_node_row(r.pdb_id_B, r.auth_asym_id_B)
-            for r in df.itertuples(index=False)
-        ]
-        df["experimental_method"] = [row.get("experimental_method") if row else None for row in node_rows]
-        df["pH"] = [row.get("pH") if row else None for row in node_rows]
-        df["temp_K"] = [row.get("temp_K") if row else None for row in node_rows]
-        df["base_label"] = [row.get("base_label") if row else None for row in node_rows]
-        df["chain_composition"] = [row.get("chain_composition") if row else None for row in node_rows]
-
-        return df
-
-    def get_summary_stats(
-        self,
-        chain_ids: Optional[List[str]] = None,
-        rmsd_min: Optional[float] = None,
-        rmsd_max: Optional[float] = None,
-        tm_min: Optional[float] = None,
-        tm_max: Optional[float] = None,
-    ) -> Dict[str, Any]:
-        """Compute aggregate statistics via SQL, with optional filters."""
-        if not any([chain_ids, rmsd_min, rmsd_max, tm_min, tm_max]) and self._summary:
-            return self._summary
-
-        where_clauses: List[str] = []
-        params: List[Any] = []
-
-        if chain_ids:
-            sub: List[str] = []
-            for cid in chain_ids:
-                parts = cid.split("_", 1)
-                if len(parts) == 2:
-                    sub.append("(LOWER(pdb_id_A) = LOWER(?) AND LOWER(auth_asym_id_A) = LOWER(?))")
-                    params.extend(parts)
-            if sub:
-                where_clauses.append("(" + " OR ".join(sub) + ")")
-
-        if rmsd_min is not None:
-            where_clauses.append("CAST(RMSD AS REAL) >= ?")
-            params.append(rmsd_min)
-        if rmsd_max is not None:
-            where_clauses.append("CAST(RMSD AS REAL) <= ?")
-            params.append(rmsd_max)
-        if tm_min is not None:
-            where_clauses.append("CAST(TM1 AS REAL) >= ?")
-            params.append(tm_min)
-        if tm_max is not None:
-            where_clauses.append("CAST(TM1 AS REAL) <= ?")
-            params.append(tm_max)
-
-        where_sql = ("WHERE " + " AND ".join(where_clauses)) if where_clauses else ""
-
-        conn = self._connect()
-        try:
-            cur = conn.cursor()
-            cur.execute(
-                f"SELECT COUNT(*), AVG(CAST(RMSD AS REAL)), AVG(CAST(TM1 AS REAL))"
-                f" FROM edge {where_sql}",
-                params,
-            )
-            total, avg_rmsd, avg_tm = cur.fetchone()
-
-            cur.execute(
-                f"SELECT COUNT(DISTINCT LOWER(pdb_id_A) || '_' || LOWER(auth_asym_id_A))"
-                f" FROM edge {where_sql}",
-                params,
-            )
-            unique_chains = cur.fetchone()[0]
-
-            def _dist(col, bins, labels):
-                cases = " ".join(
-                    f"WHEN CAST({col} AS REAL) >= {lo} AND CAST({col} AS REAL) < {hi} THEN '{lbl}'"
-                    for (lo, hi), lbl in zip(zip(bins, bins[1:]), labels)
-                )
-                sql = (
-                    f"SELECT CASE {cases} ELSE '{labels[-1]}' END AS bucket, COUNT(*)"
-                    f" FROM edge {where_sql} GROUP BY bucket"
-                )
-                cur.execute(sql, params)
-                return {r[0]: r[1] for r in cur.fetchall()}
-
-            rmsd_dist = _dist(
-                "RMSD",
-                [0, 0.5, 1.0, 1.5, 2.0, 5.0, 1e9],
-                ["0-0.5", "0.5-1.0", "1.0-1.5", "1.5-2.0", "2.0-5.0", ">5.0"],
-            )
-            tm_dist = _dist(
-                "TM1",
-                [0, 0.5, 0.7, 0.85, 0.95, 1.01],
-                ["0-0.5", "0.5-0.7", "0.7-0.85", "0.85-0.95", "0.95-1.0"],
-            )
-        finally:
-            conn.close()
-
-        from app.protein import tsv_loader
-        lengths = []
-        for row in tsv_loader._get_index().values():
-            try:
-                lengths.append(int(row["sequence_length"]))
-            except (ValueError, TypeError):
-                pass
-        avg_len = sum(lengths) / len(lengths) if lengths else 0.0
-        len_dist = {}
-        for length in lengths:
-            if length <= 100:
-                bucket = "0-100"
-            elif length <= 200:
-                bucket = "100-200"
-            elif length <= 300:
-                bucket = "200-300"
-            elif length <= 500:
-                bucket = "300-500"
-            elif length <= 1000:
-                bucket = "500-1000"
-            else:
-                bucket = ">1000"
-            len_dist[bucket] = len_dist.get(bucket, 0) + 1
-
-        return {
-            "total_records": total or 0,
-            "unique_chains": unique_chains or 0,
-            "avg_rmsd": avg_rmsd or 0.0,
-            "avg_tm_score": avg_tm or 0.0,
-            "avg_sequence_length": avg_len,
-            "rmsd_distribution": rmsd_dist,
-            "tm_score_distribution": tm_dist,
-            "length_distribution": len_dist,
-        }
-
-    def get_total(self) -> int:
-        return self._total_records
+"""
+SQLite-based data loader for protein structure data.
+Reads from MuSProt.db: edge table (pairwise comparisons from CSV)
+and node table (chain annotations from TSV).
+"""
+import json
+import pandas as pd
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+import logging
+
+from app.protein.config import get_database_path, get_summary_path
+from app.protein.database import connect_readonly
+
+logger = logging.getLogger(__name__)
+
+
+def _assign_cluster(tm: float) -> str:
+    if tm >= 0.99:
+        return "cluster_ultra_high"
+    if tm >= 0.95:
+        return "cluster_very_high"
+    if tm >= 0.90:
+        return "cluster_high"
+    if tm >= 0.80:
+        return "cluster_medium"
+    return "cluster_low"
+
+
+class DataManager:
+    """Manages SQL queries against MuSProt.db edge and node tables."""
+
+    def __init__(self, db_path: Optional[Path] = None, **_kwargs):
+        self.db_path = db_path or get_database_path()
+        self._loaded = False
+        self._total_records = 0
+        self._summary: Dict[str, Any] = {}
+
+    def load_data(self) -> None:
+        """Verify DB is accessible and load optional precomputed metadata."""
+        if self._loaded:
+            return
+        summary_path = get_summary_path()
+        if summary_path:
+            self._summary = json.loads(summary_path.read_text(encoding="utf-8"))
+            self._total_records = int(self._summary.get("total_records", 0))
+
+        conn = connect_readonly(self.db_path)
+        try:
+            cur = conn.cursor()
+            cur.execute("SELECT 1 FROM edge LIMIT 1")
+            if not self._total_records:
+                logger.warning(
+                    "No musprot_summary.json found; counting edge rows during startup. "
+                    "Publish the summary sidecar to avoid this scan."
+                )
+                cur.execute("SELECT COUNT(*) FROM edge")
+                self._total_records = cur.fetchone()[0]
+        finally:
+            conn.close()
+        self._loaded = True
+        logger.info(f"DataManager ready: {self._total_records:,} edge records in {self.db_path}")
+
+    def _connect(self):
+        if not self._loaded:
+            raise RuntimeError("Call load_data() first.")
+        return connect_readonly(self.db_path)
+
+    def get_chain_sample(self, limit: int = 500) -> Set[str]:
+        """Return a small chain sample without loading the full node index."""
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            cur.execute(
+                "SELECT pdb_id, auth_asym_id FROM node "
+                "WHERE pdb_id IS NOT NULL AND auth_asym_id IS NOT NULL LIMIT ?",
+                (limit,),
+            )
+            return {
+                f"{str(pdb).upper()}_{str(chain).upper()}"
+                for pdb, chain in cur.fetchall()
+            }
+        finally:
+            conn.close()
+
+    def get_filters_data(self) -> Dict[str, Any]:
+        """Return aggregated ranges for filter UI."""
+        if self._summary:
+            return {
+                "tm_min": self._summary["tm_score_range"]["min"],
+                "tm_max": self._summary["tm_score_range"]["max"],
+                "rmsd_min": self._summary["rmsd_range"]["min"],
+                "rmsd_max": self._summary["rmsd_range"]["max"],
+                "length_min": self._summary["length_range"]["min"],
+                "length_max": self._summary["length_range"]["max"],
+                "total_records": self._total_records,
+            }
+
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            cur.execute(
+                "SELECT MIN(CAST(TM1 AS REAL)), MAX(CAST(TM1 AS REAL)),"
+                "       MIN(CAST(RMSD AS REAL)), MAX(CAST(RMSD AS REAL))"
+                " FROM edge"
+            )
+            tm_min, tm_max, rmsd_min, rmsd_max = cur.fetchone()
+        finally:
+            conn.close()
+
+        from app.protein import tsv_loader
+        lengths = []
+        for row in tsv_loader._get_index().values():
+            try:
+                lengths.append(int(row["sequence_length"]))
+            except (ValueError, TypeError):
+                pass
+
+        return {
+            "tm_min": tm_min or 0.0,
+            "tm_max": tm_max or 1.0,
+            "rmsd_min": rmsd_min or 0.0,
+            "rmsd_max": rmsd_max or 10.0,
+            "length_min": min(lengths) if lengths else 0,
+            "length_max": max(lengths) if lengths else 0,
+            "total_records": self._total_records,
+        }
+
+    def query_edge(
+        self,
+        pdb_id_a: Optional[str] = None,
+        auth_asym_id_a: Optional[str] = None,
+        chain_ids: Optional[List[str]] = None,
+        rmsd_min: Optional[float] = None,
+        rmsd_max: Optional[float] = None,
+        tm_min: Optional[float] = None,
+        tm_max: Optional[float] = None,
+        limit: int = 1000,
+    ) -> pd.DataFrame:
+        """Query edge table with filters. Returns DataFrame with cluster_id and lengths."""
+        where_clauses: List[str] = []
+        params: List[Any] = []
+
+        if pdb_id_a and auth_asym_id_a:
+            where_clauses.append("pdb_id_A = ? COLLATE NOCASE AND auth_asym_id_A = ? COLLATE NOCASE")
+            params.extend([pdb_id_a, auth_asym_id_a])
+        elif chain_ids:
+            sub: List[str] = []
+            for cid in chain_ids:
+                parts = cid.split("_", 1)
+                if len(parts) == 2:
+                    sub.append("(pdb_id_A = ? COLLATE NOCASE AND auth_asym_id_A = ? COLLATE NOCASE)")
+                    params.extend(parts)
+            if sub:
+                where_clauses.append("(" + " OR ".join(sub) + ")")
+
+        if rmsd_min is not None:
+            where_clauses.append("CAST(RMSD AS REAL) >= ?")
+            params.append(rmsd_min)
+        if rmsd_max is not None:
+            where_clauses.append("CAST(RMSD AS REAL) <= ?")
+            params.append(rmsd_max)
+        if tm_min is not None:
+            where_clauses.append("CAST(TM1 AS REAL) >= ?")
+            params.append(tm_min)
+        if tm_max is not None:
+            where_clauses.append("CAST(TM1 AS REAL) <= ?")
+            params.append(tm_max)
+
+        where_sql = ("WHERE " + " AND ".join(where_clauses)) if where_clauses else ""
+        sql = f"""
+            SELECT e.pdb_id_A, e.auth_asym_id_A, e.pdb_id_B, e.auth_asym_id_B,
+                   CAST(e.TM1 AS REAL) AS TM1,
+                   CAST(e.RMSD AS REAL) AS RMSD,
+                   CAST(e.pair_similarity AS REAL) AS structure_sim,
+                   e."delta_Rosetta", e."delta_FoldX", e."delta_EvoEF2",
+                   e."delta_RW", e."delta_RW+",
+                   e.state_id_B, e.state_fidelity,
+                   e.state_similarity AS avg_sim, e.pair_fidelity AS observation_fidelity
+            FROM edge e
+            {where_sql}
+            LIMIT ?
+        """
+        params.append(limit)
+
+        conn = self._connect()
+        try:
+            df = pd.read_sql_query(sql, conn, params=params)
+        finally:
+            conn.close()
+
+        # Rename columns with special characters so itertuples works cleanly
+        df = df.rename(columns={"delta_RW+": "delta_RW_plus"})
+
+        df["cluster_id"] = df["TM1"].apply(
+            lambda t: _assign_cluster(t) if pd.notna(t) else "cluster_low"
+        )
+
+        from app.protein import tsv_loader
+        df["length_a"] = [
+            tsv_loader.get_sequence(r.pdb_id_A, r.auth_asym_id_A)[1]
+            for r in df.itertuples(index=False)
+        ]
+        df["length_b"] = [
+            tsv_loader.get_sequence(r.pdb_id_B, r.auth_asym_id_B)[1]
+            for r in df.itertuples(index=False)
+        ]
+        node_rows = [
+            tsv_loader.get_node_row(r.pdb_id_B, r.auth_asym_id_B)
+            for r in df.itertuples(index=False)
+        ]
+        df["experimental_method"] = [row.get("experimental_method") if row else None for row in node_rows]
+        df["pH"] = [row.get("pH") if row else None for row in node_rows]
+        df["temp_K"] = [row.get("temp_K") if row else None for row in node_rows]
+        df["binding_status"] = [row.get("binding_status") if row else None for row in node_rows]
+        df["chain_composition"] = [row.get("chain_composition") if row else None for row in node_rows]
+
+        return df
+
+    def get_summary_stats(
+        self,
+        chain_ids: Optional[List[str]] = None,
+        rmsd_min: Optional[float] = None,
+        rmsd_max: Optional[float] = None,
+        tm_min: Optional[float] = None,
+        tm_max: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Compute aggregate statistics via SQL, with optional filters."""
+        if not any([chain_ids, rmsd_min, rmsd_max, tm_min, tm_max]) and self._summary:
+            return self._summary
+
+        where_clauses: List[str] = []
+        params: List[Any] = []
+
+        if chain_ids:
+            sub: List[str] = []
+            for cid in chain_ids:
+                parts = cid.split("_", 1)
+                if len(parts) == 2:
+                    sub.append("(pdb_id_A = ? COLLATE NOCASE AND auth_asym_id_A = ? COLLATE NOCASE)")
+                    params.extend(parts)
+            if sub:
+                where_clauses.append("(" + " OR ".join(sub) + ")")
+
+        if rmsd_min is not None:
+            where_clauses.append("CAST(RMSD AS REAL) >= ?")
+            params.append(rmsd_min)
+        if rmsd_max is not None:
+            where_clauses.append("CAST(RMSD AS REAL) <= ?")
+            params.append(rmsd_max)
+        if tm_min is not None:
+            where_clauses.append("CAST(TM1 AS REAL) >= ?")
+            params.append(tm_min)
+        if tm_max is not None:
+            where_clauses.append("CAST(TM1 AS REAL) <= ?")
+            params.append(tm_max)
+
+        where_sql = ("WHERE " + " AND ".join(where_clauses)) if where_clauses else ""
+
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            cur.execute(
+                f"SELECT COUNT(*), AVG(CAST(RMSD AS REAL)), AVG(CAST(TM1 AS REAL))"
+                f" FROM edge {where_sql}",
+                params,
+            )
+            total, avg_rmsd, avg_tm = cur.fetchone()
+
+            cur.execute(
+                f"SELECT COUNT(DISTINCT LOWER(pdb_id_A) || '_' || LOWER(auth_asym_id_A))"
+                f" FROM edge {where_sql}",
+                params,
+            )
+            unique_chains = cur.fetchone()[0]
+
+            def _dist(col, bins, labels):
+                cases = " ".join(
+                    f"WHEN CAST({col} AS REAL) >= {lo} AND CAST({col} AS REAL) < {hi} THEN '{lbl}'"
+                    for (lo, hi), lbl in zip(zip(bins, bins[1:]), labels)
+                )
+                sql = (
+                    f"SELECT CASE {cases} ELSE '{labels[-1]}' END AS bucket, COUNT(*)"
+                    f" FROM edge {where_sql} GROUP BY bucket"
+                )
+                cur.execute(sql, params)
+                return {r[0]: r[1] for r in cur.fetchall()}
+
+            rmsd_dist = _dist(
+                "RMSD",
+                [0, 0.5, 1.0, 1.5, 2.0, 5.0, 1e9],
+                ["0-0.5", "0.5-1.0", "1.0-1.5", "1.5-2.0", "2.0-5.0", ">5.0"],
+            )
+            tm_dist = _dist(
+                "TM1",
+                [0, 0.5, 0.7, 0.85, 0.95, 1.01],
+                ["0-0.5", "0.5-0.7", "0.7-0.85", "0.85-0.95", "0.95-1.0"],
+            )
+        finally:
+            conn.close()
+
+        from app.protein import tsv_loader
+        lengths = []
+        for row in tsv_loader._get_index().values():
+            try:
+                lengths.append(int(row["sequence_length"]))
+            except (ValueError, TypeError):
+                pass
+        avg_len = sum(lengths) / len(lengths) if lengths else 0.0
+        len_dist = {}
+        for length in lengths:
+            if length <= 100:
+                bucket = "0-100"
+            elif length <= 200:
+                bucket = "100-200"
+            elif length <= 300:
+                bucket = "200-300"
+            elif length <= 500:
+                bucket = "300-500"
+            elif length <= 1000:
+                bucket = "500-1000"
+            else:
+                bucket = ">1000"
+            len_dist[bucket] = len_dist.get(bucket, 0) + 1
+
+        return {
+            "total_records": total or 0,
+            "unique_chains": unique_chains or 0,
+            "avg_rmsd": avg_rmsd or 0.0,
+            "avg_tm_score": avg_tm or 0.0,
+            "avg_sequence_length": avg_len,
+            "rmsd_distribution": rmsd_dist,
+            "tm_score_distribution": tm_dist,
+            "length_distribution": len_dist,
+        }
+
+    def get_total(self) -> int:
+        return self._total_records

backend/app/protein/tsv_loader.py

@@ -1,210 +1,210 @@
-"""
-Node table lookup for chain annotations.
-
-Loads the node table from MuSProt.db once on first use and indexes rows
-by (pdb_id_lower, auth_asym_id_upper).  When multiple rows share the same
-key the first occurrence is kept.
-"""
-import ast
-import sqlite3
-import logging
-import zlib
-from functools import lru_cache
-from typing import Dict, List, Optional, Tuple, Any
-
-from app.protein.config import get_database_path, get_node_database_path
-from app.protein.database import connect_readonly
-
-logger = logging.getLogger(__name__)
-
-_Row = Dict[str, str]
-
-# (pdb_id_lower, auth_asym_id_upper) -> relevant fields
-_index: Optional[Dict[Tuple[str, str], _Row]] = None
-
-
-def _load() -> Dict[Tuple[str, str], _Row]:
-    index: Dict[Tuple[str, str], _Row] = {}
-    db_path = get_database_path()
-    conn = connect_readonly(db_path)
-    try:
-        conn.row_factory = sqlite3.Row
-        cur = conn.cursor()
-        cur.execute(
-            'SELECT pdb_id, auth_asym_id, base_label, sequence, sequence_length,'
-            '       CATH_ID, cath_superfamily, Rosetta, FoldX, EvoEF2, RW, "RW+", ranked_functions,'
-            '       state_id, experimental_method, pH, temp_K, chain_composition'
-            ' FROM node'
-        )
-        for row in cur:
-            pdb_id = row["pdb_id"] or ""
-            auth_asym_id = row["auth_asym_id"] or ""
-            key = (pdb_id.lower(), auth_asym_id.upper())
-            if key not in index:
-                index[key] = {
-                    "base_label": row["base_label"] or "",
-                    "sequence": row["sequence"] or "",
-                    "sequence_length": row["sequence_length"] or "",
-                    "CATH_ID": row["CATH_ID"] or "",
-                    "cath_superfamily": row["cath_superfamily"] or "",
-                    "Rosetta": row["Rosetta"] or "",
-                    "FoldX": row["FoldX"] or "",
-                    "EvoEF2": row["EvoEF2"] or "",
-                    "RW": row["RW"] or "",
-                    "RW+": row["RW+"] or "",
-                    "ranked_functions": row["ranked_functions"] or "",
-                    "state_id": row["state_id"] or "",
-                    "experimental_method": row["experimental_method"] or "",
-                    "pH": row["pH"] or "",
-                    "temp_K": row["temp_K"] or "",
-                    "chain_composition": row["chain_composition"] or "",
-                }
-    finally:
-        conn.close()
-
-    logger.info(f"Node index loaded: {len(index):,} entries from {db_path}")
-    return index
-
-
-def _get_index() -> Dict[Tuple[str, str], _Row]:
-    global _index
-    if _index is None:
-        _index = _load()
-    return _index
-
-
-def reset_index() -> None:
-    """Force reload of node index."""
-    global _index
-    _index = None
-    _lookup_node_row.cache_clear()
-
-
-@lru_cache(maxsize=4096)
-def _lookup_node_row(pdb_id: str, auth_asym_id: str) -> Optional[_Row]:
-    """Read one node row without blocking on a full-table in-memory index."""
-    conn = connect_readonly(get_node_database_path())
-    try:
-        conn.row_factory = sqlite3.Row
-        row = conn.execute(
-            'SELECT base_label, sequence, sequence_length, CATH_ID, cath_superfamily,'
-            '       Rosetta, FoldX, EvoEF2, RW, "RW+", ranked_functions,'
-            '       state_id, experimental_method, pH, temp_K, chain_composition'
-            ' FROM node WHERE LOWER(pdb_id) = ? AND UPPER(auth_asym_id) = ? LIMIT 1',
-            (pdb_id.lower(), auth_asym_id.upper()),
-        ).fetchone()
-        if row is None:
-            return None
-        return {
-            key: zlib.decompress(value).decode("utf-8") if isinstance(value, bytes) else value or ""
-            for key, value in ((key, row[key]) for key in row.keys())
-        }
-    finally:
-        conn.close()
-
-
-def _parse_functions(raw: str) -> List[str]:
-    raw = raw.strip()
-    if not raw:
-        return []
-    try:
-        parsed = ast.literal_eval(raw)
-        if isinstance(parsed, list):
-            return [str(f).strip() for f in parsed if str(f).strip()]
-    except (ValueError, SyntaxError):
-        pass
-    return [f.strip() for f in raw.split(";") if f.strip()]
-
-
-def _parse_float(val: str) -> Optional[float]:
-    val = str(val).strip()
-    if not val:
-        return None
-    try:
-        return float(val)
-    except ValueError:
-        return None
-
-
-def get_energy_scores(pdb_id: str, auth_asym_id: str) -> Optional[Dict[str, Any]]:
-    """Return energy scores (Rosetta, FoldX, EvoEF2, RW, RW+) or None if not found."""
-    row = get_node_row(pdb_id, auth_asym_id)
-    if row is None:
-        return None
-    return {
-        "Rosetta": _parse_float(row.get("Rosetta", "")),
-        "FoldX": _parse_float(row.get("FoldX", "")),
-        "EvoEF2": _parse_float(row.get("EvoEF2", "")),
-        "RW": _parse_float(row.get("RW", "")),
-        "RW+": _parse_float(row.get("RW+", "")),
-    }
-
-
-def get_node_row(pdb_id: str, auth_asym_id: str) -> Optional[_Row]:
-    """Return the cached node row for a chain."""
-    key = (pdb_id.lower(), auth_asym_id.upper())
-    return _index.get(key) if _index is not None else _lookup_node_row(*key)
-
-
-def get_binding_status(pdb_id: str, auth_asym_id: str) -> Optional[str]:
-    """Return binding status (base_label: apo/holo) or None if not found."""
-    row = get_node_row(pdb_id, auth_asym_id)
-    if row is None:
-        return None
-    return row.get("base_label") or None
-
-
-def get_chain_composition(pdb_id: str, auth_asym_id: str) -> Optional[str]:
-    """Return chain composition (monomeric/homomeric/heteromeric) or None if not found."""
-    row = get_node_row(pdb_id, auth_asym_id)
-    if row is None:
-        return None
-    return row.get("chain_composition") or None
-
-
-def get_cath_id(pdb_id: str, auth_asym_id: str) -> Optional[str]:
-    """Return CATH_ID or 'uncategorized' if not found."""
-    row = get_node_row(pdb_id, auth_asym_id)
-    if row is None:
-        return "uncategorized"
-    val = row.get("CATH_ID", "").strip()
-    return val if val else "uncategorized"
-
-
-def get_cath_superfamily(pdb_id: str, auth_asym_id: str) -> Optional[str]:
-    """Return CATH superfamily code (e.g. '3.40.190.10') or None if not found."""
-    row = get_node_row(pdb_id, auth_asym_id)
-    if row is None:
-        return None
-    val = row.get("cath_superfamily", "").strip()
-    return val if val else None
-
-
-def get_sequence(pdb_id: str, auth_asym_id: str) -> Tuple[Optional[str], Optional[int]]:
-    """Return (seq_can, sequence_length) from node table, or (None, None) if not found."""
-    row = get_node_row(pdb_id, auth_asym_id)
-    if row is None:
-        return None, None
-    seq = row["sequence"] or None
-    try:
-        length = int(row["sequence_length"]) if row["sequence_length"].strip() else None
-    except ValueError:
-        length = None
-    return seq, length
-
-
-def get_functions(pdb_id: str, auth_asym_id: str) -> Optional[List[str]]:
-    """Return ranked function list for a chain, or None if not in node table."""
-    row = get_node_row(pdb_id, auth_asym_id)
-    if row is None:
-        return None
-    return [f for f in _parse_functions(row["ranked_functions"]) if len(f) > 10]
-
-
-def get_state_id(pdb_id: str, auth_asym_id: str) -> Optional[str]:
-    """Return state_id for a chain, or None if not found."""
-    row = get_node_row(pdb_id, auth_asym_id)
-    if row is None:
-        return None
-    val = row.get("state_id", "").strip()
-    return val if val else None
+"""
+Node table lookup for chain annotations.
+
+Loads the node table from MuSProt.db once on first use and indexes rows
+by (pdb_id_lower, auth_asym_id_upper).  When multiple rows share the same
+key the first occurrence is kept.
+"""
+import ast
+import sqlite3
+import logging
+import zlib
+from functools import lru_cache
+from typing import Dict, List, Optional, Tuple, Any
+
+from app.protein.config import get_database_path, get_node_database_path
+from app.protein.database import connect_readonly
+
+logger = logging.getLogger(__name__)
+
+_Row = Dict[str, str]
+
+# (pdb_id_lower, auth_asym_id_upper) -> relevant fields
+_index: Optional[Dict[Tuple[str, str], _Row]] = None
+
+
+def _load() -> Dict[Tuple[str, str], _Row]:
+    index: Dict[Tuple[str, str], _Row] = {}
+    db_path = get_database_path()
+    conn = connect_readonly(db_path)
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(
+            'SELECT pdb_id, auth_asym_id, binding_status, sequence, sequence_length,'
+            '       cath_id, cath_superfamily, Rosetta, FoldX, EvoEF2, RW, "RW+", ranked_functions,'
+            '       state_id, experimental_method, pH, temp_K, chain_composition'
+            ' FROM node'
+        )
+        for row in cur:
+            pdb_id = row["pdb_id"] or ""
+            auth_asym_id = row["auth_asym_id"] or ""
+            key = (pdb_id.lower(), auth_asym_id.upper())
+            if key not in index:
+                index[key] = {
+                    "binding_status": row["binding_status"] or "",
+                    "sequence": row["sequence"] or "",
+                    "sequence_length": row["sequence_length"] or "",
+                    "cath_id": row["cath_id"] or "",
+                    "cath_superfamily": row["cath_superfamily"] or "",
+                    "Rosetta": row["Rosetta"] or "",
+                    "FoldX": row["FoldX"] or "",
+                    "EvoEF2": row["EvoEF2"] or "",
+                    "RW": row["RW"] or "",
+                    "RW+": row["RW+"] or "",
+                    "ranked_functions": row["ranked_functions"] or "",
+                    "state_id": row["state_id"] or "",
+                    "experimental_method": row["experimental_method"] or "",
+                    "pH": row["pH"] or "",
+                    "temp_K": row["temp_K"] or "",
+                    "chain_composition": row["chain_composition"] or "",
+                }
+    finally:
+        conn.close()
+
+    logger.info(f"Node index loaded: {len(index):,} entries from {db_path}")
+    return index
+
+
+def _get_index() -> Dict[Tuple[str, str], _Row]:
+    global _index
+    if _index is None:
+        _index = _load()
+    return _index
+
+
+def reset_index() -> None:
+    """Force reload of node index."""
+    global _index
+    _index = None
+    _lookup_node_row.cache_clear()
+
+
+@lru_cache(maxsize=4096)
+def _lookup_node_row(pdb_id: str, auth_asym_id: str) -> Optional[_Row]:
+    """Read one node row without blocking on a full-table in-memory index."""
+    conn = connect_readonly(get_node_database_path())
+    try:
+        conn.row_factory = sqlite3.Row
+        row = conn.execute(
+            'SELECT binding_status, sequence, sequence_length, cath_id, cath_superfamily,'
+            '       Rosetta, FoldX, EvoEF2, RW, "RW+", ranked_functions,'
+            '       state_id, experimental_method, pH, temp_K, chain_composition'
+            ' FROM node WHERE LOWER(pdb_id) = ? AND UPPER(auth_asym_id) = ? LIMIT 1',
+            (pdb_id.lower(), auth_asym_id.upper()),
+        ).fetchone()
+        if row is None:
+            return None
+        return {
+            key: zlib.decompress(value).decode("utf-8") if isinstance(value, bytes) else value or ""
+            for key, value in ((key, row[key]) for key in row.keys())
+        }
+    finally:
+        conn.close()
+
+
+def _parse_functions(raw: str) -> List[str]:
+    raw = raw.strip()
+    if not raw:
+        return []
+    try:
+        parsed = ast.literal_eval(raw)
+        if isinstance(parsed, list):
+            return [str(f).strip() for f in parsed if str(f).strip()]
+    except (ValueError, SyntaxError):
+        pass
+    return [f.strip() for f in raw.split(";") if f.strip()]
+
+
+def _parse_float(val: str) -> Optional[float]:
+    val = str(val).strip()
+    if not val:
+        return None
+    try:
+        return float(val)
+    except ValueError:
+        return None
+
+
+def get_energy_scores(pdb_id: str, auth_asym_id: str) -> Optional[Dict[str, Any]]:
+    """Return energy scores (Rosetta, FoldX, EvoEF2, RW, RW+) or None if not found."""
+    row = get_node_row(pdb_id, auth_asym_id)
+    if row is None:
+        return None
+    return {
+        "Rosetta": _parse_float(row.get("Rosetta", "")),
+        "FoldX": _parse_float(row.get("FoldX", "")),
+        "EvoEF2": _parse_float(row.get("EvoEF2", "")),
+        "RW": _parse_float(row.get("RW", "")),
+        "RW+": _parse_float(row.get("RW+", "")),
+    }
+
+
+def get_node_row(pdb_id: str, auth_asym_id: str) -> Optional[_Row]:
+    """Return the cached node row for a chain."""
+    key = (pdb_id.lower(), auth_asym_id.upper())
+    return _index.get(key) if _index is not None else _lookup_node_row(*key)
+
+
+def get_binding_status(pdb_id: str, auth_asym_id: str) -> Optional[str]:
+    """Return binding status (apo/holo) or None if not found."""
+    row = get_node_row(pdb_id, auth_asym_id)
+    if row is None:
+        return None
+    return row.get("binding_status") or None
+
+
+def get_chain_composition(pdb_id: str, auth_asym_id: str) -> Optional[str]:
+    """Return chain composition (monomeric/homomeric/heteromeric) or None if not found."""
+    row = get_node_row(pdb_id, auth_asym_id)
+    if row is None:
+        return None
+    return row.get("chain_composition") or None
+
+
+def get_cath_id(pdb_id: str, auth_asym_id: str) -> Optional[str]:
+    """Return cath_id or 'uncategorized' if not found."""
+    row = get_node_row(pdb_id, auth_asym_id)
+    if row is None:
+        return "uncategorized"
+    val = row.get("cath_id", "").strip()
+    return val if val else "uncategorized"
+
+
+def get_cath_superfamily(pdb_id: str, auth_asym_id: str) -> Optional[str]:
+    """Return CATH superfamily code (e.g. '3.40.190.10') or None if not found."""
+    row = get_node_row(pdb_id, auth_asym_id)
+    if row is None:
+        return None
+    val = row.get("cath_superfamily", "").strip()
+    return val if val else None
+
+
+def get_sequence(pdb_id: str, auth_asym_id: str) -> Tuple[Optional[str], Optional[int]]:
+    """Return (seq_can, sequence_length) from node table, or (None, None) if not found."""
+    row = get_node_row(pdb_id, auth_asym_id)
+    if row is None:
+        return None, None
+    seq = row["sequence"] or None
+    try:
+        length = int(row["sequence_length"]) if row["sequence_length"].strip() else None
+    except ValueError:
+        length = None
+    return seq, length
+
+
+def get_functions(pdb_id: str, auth_asym_id: str) -> Optional[List[str]]:
+    """Return ranked function list for a chain, or None if not in node table."""
+    row = get_node_row(pdb_id, auth_asym_id)
+    if row is None:
+        return None
+    return [f for f in _parse_functions(row["ranked_functions"]) if len(f) > 10]
+
+
+def get_state_id(pdb_id: str, auth_asym_id: str) -> Optional[str]:
+    """Return state_id for a chain, or None if not found."""
+    row = get_node_row(pdb_id, auth_asym_id)
+    if row is None:
+        return None
+    val = row.get("state_id", "").strip()
+    return val if val else None

backend/assets/MuSProt_documentation.md

@@ -1,152 +1,151 @@
-# MuSProt Dataset Documentation
-
-**MuSProt** (Multistate Protein Database) is a million-scale multimodal database for multistate proteins, designed to support programmable protein design and AI model development. It links experimentally observed conformational states of identical protein sequences from the PDB, organizes them into state clusters and transition relationships, and enriches each record with structural similarity, experimental context, state-specific function rankings and transition fidelity labels. Users can search, browse and download MuSProt records to study conformational diversity, state-dependent functions and feasible protein state transitions.
-
----
-
-## Download
-
-The full dataset is distributed as a single SQLite database file (`MuSProt.db`, ~6.3 GB). Download it from the dataset page using the **Download DB** button.
-
-For detailed protein structures and atom coordinates, users are expected to download [Protein Data Bank (PDB)](https://rcsb.org) and fetch from `mmCIF` or `.pdb` files based on the PDB entry and chain ID.
-
----
-
-## Database Schema
-
-The database contains two tables: **`node`** and **`edge`**.
-
----
-
-### Table: `node`
-
-Each row represents a single protein chain instance (one PDB entry + chain).
-
-| Column | Type | Description |
-|---|---|---|
-| `uniprot_id` | TEXT | UniProt accession number |
-| `pdb_id` | TEXT | 4-character PDB entry ID (lowercase) |
-| `auth_asym_id` | TEXT | Author chain identifier (e.g. `A`) |
-| `base_label` | TEXT | Canonical label combining UniProt ID and chain state |
-| `sequence` | TEXT | SEQRES amino acid sequence |
-| `sequence_length` | INT | Number of residues in the chain |
-| `original_metals` | TEXT | Metal ions present in the structure |
-| `original_ligands` | TEXT | Small-molecule ligands present in the structure |
-| `sequence_id` | TEXT | Internal sequence cluster identifier |
-| `state_id` | TEXT | Conformational state cluster this chain is assigned to (`0`, `1`, `2`, …) |
-| `CATH_ID` | TEXT | CATH domain assignment |
-| `cath_class` | TEXT | CATH class (e.g. `1` = Mainly Alpha) |
-| `cath_arch` | TEXT | CATH architecture |
-| `cath_topo` | TEXT | CATH topology |
-| `cath_homology` | TEXT | CATH homology superfamily |
-| `cath_superfamily` | TEXT | Full CATH superfamily code (e.g. `1.10.10.10`) |
-| `domain_length` | INT | Length of the matched CATH domain |
-| `experimental_method` | TEXT | Structure determination method (e.g. `X-RAY DIFFRACTION`, `ELECTRON MICROSCOPY`, `SOLUTION NMR`) |
-| `pH` | FLOAT | pH of the experimental / crystallization condition |
-| `temp_K` | FLOAT | Temperature of the experiment, in Kelvin |
-| `experimental_details` | TEXT | Free-text crystallization / sample-preparation details |
-| `resolution` | FLOAT | Experimental resolution in Å (lower is sharper; empty for methods without a resolution) |
-| `Rosetta` | FLOAT | Rosetta total energy score |
-| `FoldX` | FLOAT | FoldX total energy score |
-| `EvoEF2` | FLOAT | EvoEF2 total energy score |
-| `RW` | FLOAT | Random-Walk (RW) energy score |
-| `RW+` | FLOAT | Random-Walk+ (RWplus) energy score |
-| `ranked_functions` | TEXT | JSON-encoded list of ranked GO/functional annotations |
-| `chain_composition` | TEXT | Quaternary composition of the deposited assembly: `monomeric`, `homomeric`, or `heteromeric` |
-| `non_protein_polymer_binding` | TEXT | Non-protein polymer bound in the structure (`DNA`, `RNA`, or `DNA/RNA`); empty when none is present |
-
-
----
-
-### Table: `edge`
-
-Each row represents a pairwise structural comparison between two chain instances (A and B) that share the same UniProt identity.
-
-| Column | Type | Description |
-|---|---|---|
-| `pdb_id_A` | TEXT | PDB ID of chain A |
-| `auth_asym_id_A` | TEXT | Chain identifier of chain A |
-| `pdb_id_B` | TEXT | PDB ID of chain B |
-| `auth_asym_id_B` | TEXT | Chain identifier of chain B |
-| `TM1` | FLOAT | TM-score of the alignment (chain A as reference) |
-| `RMSD` | FLOAT | Root-mean-square deviation of Cα atoms (Å) |
-| `structure_sim` | FLOAT | Composite structural similarity score |
-| `delta_Rosetta` | FLOAT | Rosetta energy difference (B − A) |
-| `delta_FoldX` | FLOAT | FoldX energy difference (B − A) |
-| `delta_EvoEF2` | FLOAT | EvoEF2 energy difference (B − A) |
-| `delta_RW` | FLOAT | Random-Walk (RW) energy difference (B − A) |
-| `delta_RW+` | FLOAT | Random-Walk+ (RWplus) energy difference (B − A) |
-| `state_id_A` | TEXT | Conformational state cluster of chain A |
-| `state_id_B` | TEXT | Conformational state cluster of chain B |
-| `avg_sim` | TEXT | Average structural similarity within the state cluster (`>0.95` or a numeric value) |
-| `state_fidelity` | TEXT | State-level transition fidelity label: `identical`, `high`, `medium`, or `low` |
-| `observation_fidelity` | TEXT | Observation-level transition fidelity label: `identical`, `high`, `medium`, or `low` |
-
----
-
-## Usage Examples
-
-### Python (sqlite3)
-
-```python
-import sqlite3
-import pandas as pd
-
-conn = sqlite3.connect("MuSProt.db")
-
-# Load all chains for a UniProt entry
-df_nodes = pd.read_sql(
-    "SELECT * FROM node WHERE uniprot_id = 'P00533'",
-    conn
-)
-
-# Find all structural neighbours of a given chain
-df_edges = pd.read_sql(
-    "SELECT * FROM edge WHERE pdb_id_A = '1ivo' AND auth_asym_id_A = 'A'",
-    conn
-)
-
-conn.close()
-```
-
-### Filter by structural similarity
-
-```python
-# Retrieve pairs with high TM-score and low RMSD
-df = pd.read_sql("""
-    SELECT *
-    FROM edge
-    WHERE CAST(TM1 AS REAL) > 0.8
-      AND CAST(RMSD AS REAL) < 2.0
-    LIMIT 1000
-""", conn)
-```
-
-### Join nodes and edges
-
-```python
-# Get full info for both chains in each pair
-df = pd.read_sql("""
-    SELECT
-        e.pdb_id_A, e.auth_asym_id_A,
-        e.pdb_id_B, e.auth_asym_id_B,
-        e.TM1, e.RMSD,
-        nA.sequence_length AS len_A,
-        nB.sequence_length AS len_B,
-        nA.cath_superfamily
-    FROM edge e
-    JOIN node nA ON e.pdb_id_A = nA.pdb_id AND e.auth_asym_id_A = nA.auth_asym_id
-    JOIN node nB ON e.pdb_id_B = nB.pdb_id AND e.auth_asym_id_B = nB.auth_asym_id
-    WHERE nA.uniprot_id = 'P00533'
-    LIMIT 500
-""", conn)
-```
-
----
-
-## Notes
-
-- All numeric fields (energies, TM-score, RMSD, lengths) are stored as `TEXT`; cast them with `CAST(col AS REAL)` or `CAST(col AS INTEGER)` as needed.
-- `ranked_functions` in the `node` table is a JSON string. Parse it with `json.loads()`.
-- The `edge` table is directional: (A→B) and (B→A) are separate rows and may differ slightly in TM-score.
-- Energy delta values represent B − A; a negative delta means chain B is lower energy than chain A.
+# MuSProt Dataset Documentation
+
+**MuSProt** (Multistate Protein Database) is a million-scale multimodal database for multistate proteins, designed to support programmable protein design and AI model development. It links experimentally observed conformational states of identical protein sequences from the PDB, organizes them into state clusters and transition relationships, and enriches each record with structural similarity, experimental context, state-specific function rankings and transition fidelity labels. Users can search, browse and download MuSProt records to study conformational diversity, state-dependent functions and feasible protein state transitions.
+
+---
+
+## Download
+
+The full dataset is distributed as a single SQLite database file (`MuSProt.db`, ~31 GB). Download it from the dataset page using the **Download DB** button.
+
+For detailed protein structures and atom coordinates, users are expected to download [Protein Data Bank (PDB)](https://rcsb.org) and fetch from `mmCIF` or `.pdb` files based on the PDB entry and chain ID.
+
+---
+
+## Database Schema
+
+The database contains two tables: **`node`** and **`edge`**.
+
+---
+
+### Table: `node`
+
+Each row represents a single protein chain instance (one PDB entry + chain).
+
+| Column | Type | Description |
+|---|---|---|
+| `sequence_id` | TEXT | Internal sequence cluster identifier (e.g. `SEQ087470`); shared by chains with the same sequence |
+| `uniprot_id` | TEXT | UniProt accession number |
+| `pdb_id` | TEXT | 4-character PDB entry ID (lowercase) |
+| `auth_asym_id` | TEXT | Author chain identifier (e.g. `A`) |
+| `sequence` | TEXT | SEQRES amino acid sequence |
+| `sequence_length` | INT | Number of residues in the SEQRES sequence |
+| `modeled_sequence` | TEXT | Amino acid sequence actually resolved (modeled) in the structure |
+| `modeled_sequence_length` | INT | Number of modeled residues |
+| `binders` | TEXT | Bound ligand / small-molecule component IDs present in the structure; empty when none |
+| `binding_status` | TEXT | Ligand-binding state of the chain: `apo` or `holo` |
+| `experimental_method` | TEXT | Structure determination method (e.g. `X-RAY DIFFRACTION`, `ELECTRON MICROSCOPY`, `SOLUTION NMR`) |
+| `resolution` | FLOAT | Experimental resolution in Å (lower is sharper; empty for methods without a resolution) |
+| `pH` | FLOAT | pH of the experimental / crystallization condition |
+| `temp_K` | FLOAT | Temperature of the experiment, in Kelvin |
+| `experimental_details` | TEXT | Free-text crystallization / sample-preparation details |
+| `chain_composition` | TEXT | Quaternary composition of the deposited assembly: `monomeric`, `homomeric`, or `heteromeric` |
+| `non_protein_polymer_binding` | TEXT | Non-protein polymer bound in the structure (`DNA`, `RNA`, or `DNA/RNA`); `None` when absent |
+| `initial_release_date` | TEXT | PDB entry initial release date (`YYYY-MM-DD`) |
+| `cath_id` | TEXT | CATH domain assignment; empty when unassigned |
+| `cath_superfamily` | TEXT | Full CATH superfamily code (e.g. `1.10.10.10`) |
+| `state_id` | TEXT | Conformational state cluster this chain is assigned to (`0`, `1`, `2`, …) |
+| `Rosetta` | FLOAT | Rosetta total energy score |
+| `FoldX` | FLOAT | FoldX total energy score |
+| `EvoEF2` | FLOAT | EvoEF2 total energy score |
+| `RW` | FLOAT | Random-Walk (RW) energy score |
+| `RW+` | FLOAT | Random-Walk+ (RWplus) energy score |
+| `ranked_functions` | TEXT | JSON-encoded list of ranked GO/functional annotations |
+| `matching_scores` | TEXT | JSON-encoded list of function-matching scores, aligned with `ranked_functions` |
+
+
+---
+
+### Table: `edge`
+
+Each row represents a pairwise structural comparison between two chain instances (A and B) that share the same UniProt identity.
+
+| Column | Type | Description |
+|---|---|---|
+| `pdb_id_A` | TEXT | PDB ID of chain A |
+| `auth_asym_id_A` | TEXT | Chain identifier of chain A |
+| `pdb_id_B` | TEXT | PDB ID of chain B |
+| `auth_asym_id_B` | TEXT | Chain identifier of chain B |
+| `TM1` | FLOAT | TM-score of the alignment (chain A as reference) |
+| `RMSD` | FLOAT | Root-mean-square deviation of Cα atoms (Å) |
+| `pair_similarity` | FLOAT | Composite structural similarity score for the A–B pair |
+| `delta_Rosetta` | FLOAT | Rosetta energy difference (B − A) |
+| `delta_FoldX` | FLOAT | FoldX energy difference (B − A) |
+| `delta_EvoEF2` | FLOAT | EvoEF2 energy difference (B − A) |
+| `delta_RW` | FLOAT | Random-Walk (RW) energy difference (B − A) |
+| `delta_RW+` | FLOAT | Random-Walk+ (RWplus) energy difference (B − A) |
+| `state_id_A` | TEXT | Conformational state cluster of chain A |
+| `state_id_B` | TEXT | Conformational state cluster of chain B |
+| `state_similarity` | TEXT | Average structural similarity within the state cluster |
+| `state_fidelity` | TEXT | State-level transition fidelity label: `identical`, `high`, `medium`, or `low` |
+| `pair_fidelity` | TEXT | Pairwise (observation-level) transition fidelity label: `identical`, `high`, `medium`, or `low` |
+| `sequence_id` | TEXT | Internal sequence cluster identifier shared by chains A and B |
+
+---
+
+## Usage Examples
+
+### Python (sqlite3)
+
+```python
+import sqlite3
+import pandas as pd
+
+conn = sqlite3.connect("MuSProt.db")
+
+# Load all chains for a UniProt entry
+df_nodes = pd.read_sql(
+    "SELECT * FROM node WHERE uniprot_id = 'P00533'",
+    conn
+)
+
+# Find all structural neighbours of a given chain
+df_edges = pd.read_sql(
+    "SELECT * FROM edge WHERE pdb_id_A = '1ivo' AND auth_asym_id_A = 'A'",
+    conn
+)
+
+conn.close()
+```
+
+### Filter by structural similarity
+
+```python
+# Retrieve pairs with high TM-score and low RMSD
+df = pd.read_sql("""
+    SELECT *
+    FROM edge
+    WHERE CAST(TM1 AS REAL) > 0.8
+      AND CAST(RMSD AS REAL) < 2.0
+    LIMIT 1000
+""", conn)
+```
+
+### Join nodes and edges
+
+```python
+# Get full info for both chains in each pair
+df = pd.read_sql("""
+    SELECT
+        e.pdb_id_A, e.auth_asym_id_A,
+        e.pdb_id_B, e.auth_asym_id_B,
+        e.TM1, e.RMSD,
+        nA.sequence_length AS len_A,
+        nB.sequence_length AS len_B,
+        nA.cath_superfamily
+    FROM edge e
+    JOIN node nA ON e.pdb_id_A = nA.pdb_id AND e.auth_asym_id_A = nA.auth_asym_id
+    JOIN node nB ON e.pdb_id_B = nB.pdb_id AND e.auth_asym_id_B = nB.auth_asym_id
+    WHERE nA.uniprot_id = 'P00533'
+    LIMIT 500
+""", conn)
+```
+
+---
+
+## Notes
+
+- All numeric fields (energies, TM-score, RMSD, lengths) are stored as `TEXT`; cast them with `CAST(col AS REAL)` or `CAST(col AS INTEGER)` as needed.
+- `ranked_functions` in the `node` table is a JSON string. Parse it with `json.loads()`.
+- The `edge` table is directional: (A→B) and (B→A) are separate rows and may differ slightly in TM-score.
+- Energy delta values represent B − A; a negative delta means chain B is lower energy than chain A.

backend/scripts/generate_node_lookup.py

@@ -1,68 +1,68 @@
-"""Generate an indexed read-only node lookup sidecar from MuSProt.db."""
-from __future__ import annotations
-
-import argparse
-import sqlite3
-import zlib
-from pathlib import Path
-
-
-NODE_COLUMNS = (
-    "pdb_id", "auth_asym_id", "base_label", "sequence", "sequence_length",
-    "CATH_ID", "cath_superfamily", "Rosetta", "FoldX", "EvoEF2", "RW", "RW+",
-    "ranked_functions", "state_id", "experimental_method", "pH", "temp_K",
-    "chain_composition",
-)
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("source", type=Path)
-    parser.add_argument("-o", "--output", type=Path, default=Path("MuSProt-node-lookup.db"))
-    args = parser.parse_args()
-
-    output = args.output.resolve()
-    output.unlink(missing_ok=True)
-
-    conn = sqlite3.connect(output)
-    try:
-        conn.execute("PRAGMA journal_mode = OFF")
-        conn.execute("PRAGMA synchronous = OFF")
-        conn.execute(
-            'CREATE TABLE node (pdb_id, auth_asym_id, base_label, sequence BLOB,'
-            ' sequence_length, CATH_ID, cath_superfamily, Rosetta, FoldX, EvoEF2,'
-            ' RW, "RW+", ranked_functions BLOB, state_id, experimental_method, pH, temp_K,'
-            ' chain_composition)'
-        )
-        source = sqlite3.connect(f"file:{args.source.resolve()}?mode=ro", uri=True)
-        try:
-            select_columns = ", ".join(f'"{column}"' for column in NODE_COLUMNS)
-            rows = source.execute(f"SELECT {select_columns} FROM node")
-            placeholders = ", ".join("?" for _ in NODE_COLUMNS)
-            batch = []
-            for row in rows:
-                row = list(row)
-                for index in (3, 12):
-                    row[index] = zlib.compress((row[index] or "").encode("utf-8"), 1)
-                batch.append(row)
-                if len(batch) == 1000:
-                    conn.executemany(f"INSERT INTO node VALUES ({placeholders})", batch)
-                    batch.clear()
-            if batch:
-                conn.executemany(f"INSERT INTO node VALUES ({placeholders})", batch)
-        finally:
-            source.close()
-        conn.execute(
-            "CREATE INDEX idx_node_chain "
-            "ON node(LOWER(pdb_id), UPPER(auth_asym_id))"
-        )
-        conn.execute("ANALYZE")
-        conn.commit()
-    finally:
-        conn.close()
-
-    print(f"Created {output} ({output.stat().st_size:,} bytes)")
-
-
-if __name__ == "__main__":
-    main()
+"""Generate an indexed read-only node lookup sidecar from MuSProt.db."""
+from __future__ import annotations
+
+import argparse
+import sqlite3
+import zlib
+from pathlib import Path
+
+
+NODE_COLUMNS = (
+    "pdb_id", "auth_asym_id", "binding_status", "sequence", "sequence_length",
+    "cath_id", "cath_superfamily", "Rosetta", "FoldX", "EvoEF2", "RW", "RW+",
+    "ranked_functions", "state_id", "experimental_method", "pH", "temp_K",
+    "chain_composition",
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("source", type=Path)
+    parser.add_argument("-o", "--output", type=Path, default=Path("MuSProt-node-lookup.db"))
+    args = parser.parse_args()
+
+    output = args.output.resolve()
+    output.unlink(missing_ok=True)
+
+    conn = sqlite3.connect(output)
+    try:
+        conn.execute("PRAGMA journal_mode = OFF")
+        conn.execute("PRAGMA synchronous = OFF")
+        conn.execute(
+            'CREATE TABLE node (pdb_id, auth_asym_id, binding_status, sequence BLOB,'
+            ' sequence_length, cath_id, cath_superfamily, Rosetta, FoldX, EvoEF2,'
+            ' RW, "RW+", ranked_functions BLOB, state_id, experimental_method, pH, temp_K,'
+            ' chain_composition)'
+        )
+        source = sqlite3.connect(f"file:{args.source.resolve()}?mode=ro", uri=True)
+        try:
+            select_columns = ", ".join(f'"{column}"' for column in NODE_COLUMNS)
+            rows = source.execute(f"SELECT {select_columns} FROM node")
+            placeholders = ", ".join("?" for _ in NODE_COLUMNS)
+            batch = []
+            for row in rows:
+                row = list(row)
+                for index in (3, 12):
+                    row[index] = zlib.compress((row[index] or "").encode("utf-8"), 1)
+                batch.append(row)
+                if len(batch) == 1000:
+                    conn.executemany(f"INSERT INTO node VALUES ({placeholders})", batch)
+                    batch.clear()
+            if batch:
+                conn.executemany(f"INSERT INTO node VALUES ({placeholders})", batch)
+        finally:
+            source.close()
+        conn.execute(
+            "CREATE INDEX idx_node_chain "
+            "ON node(LOWER(pdb_id), UPPER(auth_asym_id))"
+        )
+        conn.execute("ANALYZE")
+        conn.commit()
+    finally:
+        conn.close()
+
+    print(f"Created {output} ({output.stat().st_size:,} bytes)")
+
+
+if __name__ == "__main__":
+    main()

frontend/src/components/datasets/protein/StatsPanel.tsx

@@ -5,32 +5,32 @@ export const StatsPanel: React.FC = () => {
   return (
     <div className="stats-panel">
       <div className="stat-card">
-        <div className="stat-value">64,812</div>
+        <div className="stat-value">102,790</div>
         <div className="stat-label">Sequences with multiple conformational observations</div>
       </div>
 
       <div className="stat-card">
-        <div className="stat-value">11,946</div>
+        <div className="stat-value">24,796</div>
         <div className="stat-label">Sequences with multiple state clusters</div>
       </div>
 
       <div className="stat-card">
-        <div className="stat-value">355,731</div>
+        <div className="stat-value">863,643</div>
         <div className="stat-label">Conformational observations</div>
       </div>
 
       <div className="stat-card">
-        <div className="stat-value">90,745</div>
+        <div className="stat-value">163,869</div>
         <div className="stat-label">Unique state clusters</div>
       </div>
 
       <div className="stat-card">
-        <div className="stat-value">27.6 million</div>
+        <div className="stat-value">113.6 million</div>
         <div className="stat-label">Transition triplets between conformational observations</div>
       </div>
 
       <div className="stat-card">
-        <div className="stat-value">5.7 million</div>
+        <div className="stat-value">24.95 million</div>
         <div className="stat-label">Transition triplets between distinct states</div>
       </div>
     </div>