Add chain_composition + binding status; refresh DB, docs, Fidelity plot

- DB rebuilt from updated annotations: node gains chain_composition and
non_protein_polymer_binding columns (edge unchanged, 27.5M rows).
- Chain metadata: show Chain Composition alongside Binding Status.
- Alternative observations: add Binding status + Chain composition
columns (between pH and ΔRosetta).
- Docs: document chain_composition and non_protein_polymer_binding.
- Refresh Fidelity Distribution plot (cache-bust v=20260625).

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

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

@@ -1,263 +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,
-                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),
-        "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("|")),
-            "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, "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"}

backend/app/protein/data_loader.py

@@ -1,335 +1,337 @@
-"""
-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]
-
-        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("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

backend/app/protein/models.py

@@ -59,6 +59,7 @@ class ChainMetadata(BaseModel):
     polymer_entity_instance: Optional[PolymerEntityInstance] = None
     nonpolymer_entities: Optional[List[NonpolymerEntity]] = None
     binding_status: Optional[str] = None
+    chain_composition: Optional[str] = None
     cath_id: Optional[str] = None
     cath_superfamily: Optional[str] = None
     state_id: Optional[str] = None
@@ -108,6 +109,9 @@ class DataRecord(BaseModel):
     exptl_method: Optional[str] = None
     temp: Optional[float] = None
     pH: Optional[float] = None
+    # Matched-chain (B) annotations from the node table
+    binding_status: Optional[str] = None
+    chain_composition: Optional[str] = None
     # Energy score deltas fetched directly from the edge table
     delta_rosetta: Optional[float] = None
     delta_foldx: Optional[float] = None

backend/app/protein/tsv_loader.py

@@ -1,201 +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'
-            ' 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 "",
-                }
-    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'
-            ' 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_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 _parse_functions(row["ranked_functions"])
-
-
-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, 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 _parse_functions(row["ranked_functions"])
+
+
+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,150 +1,152 @@
-# 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 |
-
-
----
-
-### 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`, ~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.

backend/scripts/generate_node_lookup.py

@@ -1,66 +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",
-)
-
-
-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)'
-        )
-        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", "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()

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

@@ -51,7 +51,7 @@ const ChainBasicInfoCards: React.FC<ChainBasicInfoCardsProps> = ({ metadata, isL
   const chainId = metadata?.chain_id || metadata?.polymer_entity_instance?.auth_asym_id;
 
   return (
-    <div className="h-full w-full border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
+    <div className="h-full w-full border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
       <div className="flex items-start justify-between mb-4">
         <h3 className="text-xl font-semibold text-slate-900">Chain Metadata</h3>
         <div className="flex flex-wrap gap-2">
@@ -68,19 +68,19 @@ const ChainBasicInfoCards: React.FC<ChainBasicInfoCardsProps> = ({ metadata, isL
 
       {/* Chips Row */}
 
-      {/* Compact three-column metadata flow */}
-      <div className="gap-4" style={{ columnCount: 3, columnGap: '1rem' }}>
-        <div className="break-inside-avoid mb-3">
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Protein Name</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono" title={metadata?.entry?.title || ''}>
-            {metadata?.entry?.title || '—'}
-          </div>
-        </div>
-
-        <div className="break-inside-avoid mb-3">
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">PDB ID</div>
-          <div className="text-sm font-semibold text-slate-900">
-            <a 
+      {/* Compact three-column metadata flow */}
+      <div className="gap-4" style={{ columnCount: 3, columnGap: '1rem' }}>
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Protein Name</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono" title={metadata?.entry?.title || ''}>
+            {metadata?.entry?.title || '—'}
+          </div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">PDB ID</div>
+          <div className="text-sm font-semibold text-slate-900">
+            <a 
               href={`https://www.rcsb.org/structure/${pdbId}`}
               target="_blank"
               rel="noopener noreferrer"
@@ -89,33 +89,38 @@ const ChainBasicInfoCards: React.FC<ChainBasicInfoCardsProps> = ({ metadata, isL
               {pdbId || '—'}
               <span className="text-xs">↗</span>
             </a>
-          </div>
-        </div>
-
-        <div className="break-inside-avoid mb-3">
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Chain ID</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono">{chainId || '—'}</div>
-        </div>
-
-        <div className="break-inside-avoid mb-3">
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">UniProt ID</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono">{getUniProtId()}</div>
-        </div>
-
-        <div className="break-inside-avoid mb-3">
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Binding Status</div>
-          <div className="text-sm font-semibold text-slate-900 capitalize">{metadata?.binding_status || '—'}</div>
-        </div>
-
-        <div className="break-inside-avoid mb-3">
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">CATH ID</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono">{metadata?.cath_id || 'uncategorized'}</div>
-        </div>
-
-        <div className="break-inside-avoid mb-3">
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">CATH Domain</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono">
-            {metadata?.cath_superfamily ? (
+          </div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Chain ID</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono">{chainId || '—'}</div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">UniProt ID</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono">{getUniProtId()}</div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Binding Status</div>
+          <div className="text-sm font-semibold text-slate-900 capitalize">{metadata?.binding_status || '—'}</div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Chain Composition</div>
+          <div className="text-sm font-semibold text-slate-900 capitalize">{metadata?.chain_composition || '—'}</div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">CATH ID</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono">{metadata?.cath_id || 'uncategorized'}</div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">CATH Domain</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono">
+            {metadata?.cath_superfamily ? (
               <a
                 href={`https://www.cathdb.info/version/latest/superfamily/${metadata.cath_superfamily}`}
                 target="_blank"
@@ -126,13 +131,13 @@ const ChainBasicInfoCards: React.FC<ChainBasicInfoCardsProps> = ({ metadata, isL
                 <span className="text-xs">↗</span>
               </a>
             ) : '—'}
-          </div>
-        </div>
-
-        <div className="break-inside-avoid mb-3">
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">State ID</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono">{metadata?.state_id || '—'}</div>
-        </div>
+          </div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">State ID</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono">{metadata?.state_id || '—'}</div>
+        </div>
       </div>
     </div>
   );

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

@@ -102,6 +102,12 @@ export const DataTable: React.FC<DataTableProps> = ({ data, loading, total, filt
               <th>
                 pH
               </th>
+              <th onClick={() => handleSort('binding_status')}>
+                Binding status {getSortIcon('binding_status')}
+              </th>
+              <th onClick={() => handleSort('chain_composition')}>
+                Chain composition {getSortIcon('chain_composition')}
+              </th>
               <th onClick={() => handleSort('delta_rosetta')}>
                 ΔRosetta {getSortIcon('delta_rosetta')}
               </th>
@@ -154,6 +160,12 @@ export const DataTable: React.FC<DataTableProps> = ({ data, loading, total, filt
                 <td className="numeric">
                   {formatPH(record.pH)}
                 </td>
+                <td className="capitalize">
+                  {record.binding_status || <span className="placeholder">—</span>}
+                </td>
+                <td className="capitalize">
+                  {record.chain_composition || <span className="placeholder">—</span>}
+                </td>
                 {(['delta_rosetta', 'delta_foldx', 'delta_evoef2', 'delta_rw', 'delta_rw_plus'] as const).map(field => {
                   const val = record[field];
                   return (

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

@@ -1,34 +1,34 @@
-import React from 'react';
-
-const IMG_BASE = '/api/protein/plots';
-const CACHE_BUST = '?v=20260622c';
-
-const plots = [
-  { name: 'Structure Similarity', file: 'Structure-similarity.png' },
-  { name: 'Function Rank Correlation vs. Structure Similarity', file: 'Function-rank-correlation.png' },
-  { name: 'Fidelity Distribution', file: 'Fidelity-distribution.png' },
-  { name: 'Unique State Cluster Distribution', file: 'Unique-state-cluster-distribution.png' },
-];
-
-export const StaticDistributionPlots: React.FC = () => {
-  return (
-    <div style={{ columns: '400px', columnGap: '1.5rem' }}>
-      {plots.map(({ name, file }) => (
-        <div
-          key={file}
-          style={{ breakInside: 'avoid', marginBottom: '1.5rem' }}
-          className="border border-gray-200 rounded-2xl bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300 overflow-hidden"
-        >
-          <div className="px-4 pt-5 pb-2 text-xl font-semibold text-slate-900">{name}</div>
-          <div className="px-4 pb-4">
-            <img
-              src={`${IMG_BASE}/${file}${CACHE_BUST}`}
-              alt={name}
-              style={{ width: '100%', height: 'auto', display: 'block' }}
-            />
-          </div>
-        </div>
-      ))}
-    </div>
-  );
-};
+import React from 'react';
+
+const IMG_BASE = '/api/protein/plots';
+const CACHE_BUST = '?v=20260625';
+
+const plots = [
+  { name: 'Structure Similarity', file: 'Structure-similarity.png' },
+  { name: 'Function Rank Correlation vs. Structure Similarity', file: 'Function-rank-correlation.png' },
+  { name: 'Fidelity Distribution', file: 'Fidelity-distribution.png' },
+  { name: 'Unique State Cluster Distribution', file: 'Unique-state-cluster-distribution.png' },
+];
+
+export const StaticDistributionPlots: React.FC = () => {
+  return (
+    <div style={{ columns: '400px', columnGap: '1.5rem' }}>
+      {plots.map(({ name, file }) => (
+        <div
+          key={file}
+          style={{ breakInside: 'avoid', marginBottom: '1.5rem' }}
+          className="border border-gray-200 rounded-2xl bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300 overflow-hidden"
+        >
+          <div className="px-4 pt-5 pb-2 text-xl font-semibold text-slate-900">{name}</div>
+          <div className="px-4 pb-4">
+            <img
+              src={`${IMG_BASE}/${file}${CACHE_BUST}`}
+              alt={name}
+              style={{ width: '100%', height: 'auto', display: 'block' }}
+            />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+};

frontend/src/types/protein.ts

@@ -63,6 +63,7 @@ export interface ChainMetadata {
   polymer_entity_instance?: PolymerEntityInstance | null;
   nonpolymer_entities?: NonpolymerEntity[] | null;
   binding_status?: string | null;
+  chain_composition?: string | null;
   cath_id?: string | null;
   cath_superfamily?: string | null;
   state_id?: string | null;
@@ -85,6 +86,9 @@ export interface DataRecord {
   exptl_method?: string | null;
   temp?: number | string | null;
   pH?: number | string | null;
+  // Matched-chain (B) node annotations
+  binding_status?: string | null;
+  chain_composition?: string | null;
   // Energy score deltas (searched chain - matched chain)
   delta_rosetta?: number | null;
   delta_foldx?: number | null;