Rename pair_fidelity to observation_fidelity; document feature columns

Rename the edge fidelity field across the API model, query, and data table,
document the experimental-context and state-cluster columns, and refresh the
database introduction.

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

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

@@ -141,7 +141,7 @@ async def get_data(filters: FilterParams):
                 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,
-                pair_fidelity=getattr(row, "pair_fidelity", None) or None,
+                observation_fidelity=getattr(row, "observation_fidelity", None) or None,
             ))
 
         return DataResponse(

backend/app/protein/data_loader.py

@@ -175,7 +175,7 @@ class DataManager:
                    CAST(e.structure_sim AS REAL) AS structure_sim,
                    e."delta_Rosetta", e."delta_FoldX", e."delta_EvoEF2",
                    e."delta_RM", e."delta_RM+",
-                   e.state_id_B, e.state_fidelity, e.avg_sim, e.pair_fidelity
+                   e.state_id_B, e.state_fidelity, e.avg_sim, e.observation_fidelity
             FROM edge e
             {where_sql}
             LIMIT ?

backend/app/protein/models.py

@@ -118,7 +118,7 @@ class DataRecord(BaseModel):
     state_id_b: Optional[str] = None
     state_fidelity: Optional[str] = None
     avg_sim: Optional[str] = None
-    pair_fidelity: Optional[str] = None
+    observation_fidelity: Optional[str] = None
 
 
 class DataResponse(BaseModel):

backend/assets/MuSProt_documentation.md

@@ -1,7 +1,6 @@
 # MuSProt Dataset Documentation
 
-**MuSProt** (Multistate Protein Database) is a large-scale structural database capturing conformational diversity across protein chains derived from the Protein Data Bank (PDB). It encodes pairwise structural relationships between chain instances sharing the same UniProt annotation, enabling systematic analysis of protein flexibility, binding effects, and functional variation.
-
+**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
@@ -33,6 +32,7 @@ Each row represents a single protein chain instance (one PDB entry + 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 |
@@ -40,6 +40,11 @@ Each row represents a single protein chain instance (one PDB entry + chain).
 | `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 |
@@ -47,6 +52,7 @@ Each row represents a single protein chain instance (one PDB entry + chain).
 | `RM+` | FLOAT | RosettaMembrane+ energy score |
 | `ranked_functions` | TEXT | JSON-encoded list of ranked GO/functional annotations |
 
+
 ---
 
 ### Table: `edge`
@@ -67,6 +73,11 @@ Each row represents a pairwise structural comparison between two chain instances
 | `delta_EvoEF2` | FLOAT | EvoEF2 energy difference (B − A) |
 | `delta_RM` | FLOAT | RosettaMembrane energy difference (B − A) |
 | `delta_RM+` | FLOAT | RosettaMembrane+ 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` |
 
 ---
 

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

@@ -126,8 +126,8 @@ export const DataTable: React.FC<DataTableProps> = ({ data, loading, total, filt
               <th onClick={() => handleSort('avg_sim')}>
                 State avg. similarity {getSortIcon('avg_sim')}
               </th>
-              <th onClick={() => handleSort('pair_fidelity')}>
-                Observation fidelity {getSortIcon('pair_fidelity')}
+              <th onClick={() => handleSort('observation_fidelity')}>
+                Observation fidelity {getSortIcon('observation_fidelity')}
               </th>
               <th onClick={() => handleSort('structure_sim')}>
                 Observation similarity {getSortIcon('structure_sim')}
@@ -165,7 +165,7 @@ export const DataTable: React.FC<DataTableProps> = ({ data, loading, total, filt
                 <td className="font-mono">{record.state_id_b ?? <span className="placeholder">—</span>}</td>
                 <td>{record.state_fidelity ?? <span className="placeholder">—</span>}</td>
                 <td>{record.avg_sim ?? <span className="placeholder">—</span>}</td>
-                <td>{record.pair_fidelity ?? <span className="placeholder">—</span>}</td>
+                <td>{record.observation_fidelity ?? <span className="placeholder">—</span>}</td>
                 <td className="numeric">{record.structure_sim != null ? record.structure_sim.toFixed(3) : <span className="placeholder">—</span>}</td>
               </tr>
             ))}

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

@@ -334,10 +334,13 @@ export function ProteinDashboard() {
               <section className="px-1">
                 <h1 className="text-2xl font-semibold text-slate-900">MuSProt — Multistate Protein Database</h1>
                 <p className="mt-2 max-w-4xl text-slate-600 leading-relaxed">
-                  MuSProt is a large-scale structural database capturing conformational diversity across
-                  protein chains derived from the Protein Data Bank (PDB). It encodes pairwise structural
-                  relationships between chain instances that share the same UniProt annotation, enabling
-                  systematic analysis of protein flexibility, binding effects, and functional variation.
+                  <span className="font-semibold text-slate-900">MuSProt</span> (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.
                 </p>
               </section>
 

frontend/src/types/protein.ts

@@ -96,7 +96,7 @@ export interface DataRecord {
   state_id_b?: string | null;
   state_fidelity?: string | null;
   avg_sim?: string | null;
-  pair_fidelity?: string | null;
+  observation_fidelity?: string | null;
 }
 
 export interface DataResponse {