Add experimental counterpart discovery for predicted models

.github/workflows/scientific-tests.yml

@@ -39,6 +39,7 @@ jobs:
       - name: Test browser message handler and source selection
         run: |
           node --check shinyRam/www/custom.js
+          node --check shinyRam/www/experimental-search.js
           node --check shinyRam/www/compare.js
           node --check shinyRam/www/prediction.js
           node tests/compare-ui.test.cjs

README.md

@@ -16,7 +16,7 @@ RamplotR is an open-source R Shiny application that brings backbone geometry, a
 | --- | --- |
 | **Explore a structure** | Interactive φ/ψ plots with several reference-density datasets, native RamplotR density regions and a parallel six-class Rama8000 standard validation that matches the current cctbx/Phenix categories. |
 | **Inspect residues in context** | Synchronized Ramachandran plot, searchable residue table, all-chain sequence navigator and NGL 3D viewer. The issue queue distinguishes Rama8000 outliers from native RamplotR `Not allowed` regions and missing angles. |
-| **Work with predicted models** | Import AlphaFold DB models or upload AlphaFold 2/3, ColabFold and ESMFold structures. Examine pLDDT/PAE and analyse multiple AF2/ColabFold or ESMFold seeds as a prediction ensemble with residue-level φ/ψ, Rama8000 and confidence agreement. |
+| **Work with predicted models** | Import AlphaFold DB models or upload AlphaFold 2/3, ColabFold and ESMFold structures. Examine pLDDT/PAE, analyse multiple AF2/ColabFold or ESMFold seeds as a prediction ensemble, and search experimental PDB counterparts for direct residue-level comparison. |
 | **Examine structural geometry** | Explore peptide ω, side-chain χ1 and descriptive Cβ measurements. Optionally attach the matching deposited structure's official wwPDB validation report for independent rotamer, clash and geometry annotations. |
 | **Inspect experimental evidence** | Overlay a local CCP4/MRC cryo-EM map in the 3D viewer as a qualitative aid, without uploading the map to a separate service. |
 | **Compare models** | Sequence-align chains from two structures; use the Conformational Change Explorer to navigate residue-level wrapped φ/ψ displacement, then inspect paired residues in linked 2D/3D views alongside native and Rama8000 category changes. |
@@ -106,6 +106,7 @@ The default RamplotR teal contour palette provides consistent, recognisable publ
 - [Geometry, official wwPDB evidence, cryo-EM overlays, ensembles and batch mode](docs/structural-verification.md)
 - [Rama8000 standard validation and direct wwPDB comparison](docs/rama8000-validation.md)
 - [Prediction ensemble analysis](docs/prediction-ensembles.md)
+- [Experimental counterpart discovery for predicted models](docs/experimental-counterparts.md)
 - [Independent wwPDB angle-validation protocol](docs/wwpdb-validation.md) · [Results](docs/validation-results.md)
 - [Performance and large-structure benchmarks](docs/benchmark-results.md) · [Scaling results](docs/scaling-results.md)
 - [Shinylive browser deployment and one.com caching](docs/shinylive-deployment.md)

docs/experimental-counterparts.md

@@ -0,0 +1,85 @@
+# Experimental counterpart discovery
+
+RamplotR can search for experimentally determined PDB structures related to a
+loaded predicted protein model and open a selected hit directly in the linked
+Compare workflow.
+
+## Workflow
+
+1. Load an AlphaFold DB, AlphaFold/ColabFold, ESMFold or other declared
+   prediction.
+2. Expand **Experimental counterparts** below the prediction-confidence panel.
+3. Choose the prediction chain and a minimum sequence-identity threshold.
+4. Select **Find experimental structures**.
+5. Review the returned PDB polymer entities, experimental method and resolution.
+6. Open the entry in PDBe for archive context, or choose **Compare in RamplotR**
+   to load the experimental structure as the second model.
+
+When a result is opened in RamplotR, the query chain is selected as the primary
+comparison chain and the matching PDB chain returned by the archive metadata is
+preferred for the experimental structure. The existing Conformational Change
+Explorer then provides wrapped delta-phi/delta-psi values, combined local
+backbone displacement, Rama8000 categories and linked 3D residue inspection.
+
+## Search implementation
+
+The browser sends the selected protein sequence to the public RCSB PDB Search
+API sequence service:
+
+- target: `pdb_protein_sequence`
+- return type: `polymer_entity`
+- content type: experimental structures only
+- default minimum sequence identity: 90%
+- maximum displayed hits: 12
+
+Polymer-entity and entry metadata are then obtained from the RCSB Data API.
+The network requests are made client-side in `experimental-search.js`, so the
+same workflow can be used by the normal Shiny application and the static
+Shinylive/webR deployment without adding a server-side HTTP dependency.
+
+Result cards link to the corresponding current PDBe entry page for archive,
+annotation and validation context.
+
+## Interpretation
+
+A sequence-similar PDB structure is a **candidate experimental counterpart**,
+not proof that it represents the same biochemical state.
+
+Differences can arise from:
+
+- bound ligands or cofactors;
+- mutations, constructs or truncations;
+- oligomeric state;
+- crystallisation or cryo-EM conditions;
+- alternate functional states;
+- experimental uncertainty;
+- genuinely different local conformations.
+
+For that reason RamplotR does not assign a single "agreement score" between a
+prediction and an experimental hit. The search only identifies candidates.
+Interpretation happens in the existing residue-level comparison workflow.
+
+Lowering the identity threshold can be useful for homologous structures, but
+the biological relevance of the comparison becomes increasingly dependent on
+domain architecture and functional context.
+
+## Privacy and browser execution
+
+The selected amino-acid sequence is sent to the public RCSB PDB sequence search
+service when the user explicitly runs the search. Coordinate files uploaded to
+RamplotR are not automatically uploaded to a prediction service by this
+feature. Loading a selected PDB hit uses RamplotR's normal public-accession
+retrieval path.
+
+## Testing
+
+The browser integration test mocks the RCSB sequence and metadata responses so
+continuous integration is deterministic and does not depend on temporary API
+availability. It verifies:
+
+- the request targets protein sequence search;
+- the chosen identity threshold is transmitted;
+- experimental-only search content is requested;
+- candidate metadata and PDBe links render;
+- **Compare in RamplotR** loads the candidate and selects the matching chain;
+- the resulting aligned residues appear in the Conformational Change Explorer.

shinyRam/R/inspection.R

@@ -31,6 +31,25 @@ ram_amino_acid_letters <- c(
   PRO="P", SER="S", THR="T", TRP="W", TYR="Y", VAL="V"
 )
 
+ram_chain_query_sequence <- function(data, chain) {
+  residues <- ram_sequence_data(data)
+  if (!nrow(residues)) return(list(sequence="", residues=residues,
+                                   known_fraction=NA_real_))
+  target <- as.character(chain)
+  rows <- residues$chain == target
+  residues <- residues[rows, , drop=FALSE]
+  if (!nrow(residues)) return(list(sequence="", residues=residues,
+                                   known_fraction=NA_real_))
+  letters <- toupper(as.character(residues$letter))
+  letters[!grepl("^[ACDEFGHIKLMNPQRSTVWY]$", letters)] <- "X"
+  known <- letters != "X"
+  list(
+    sequence=paste0(letters,collapse=""),
+    residues=residues,
+    known_fraction=mean(known)
+  )
+}
+
 ram_sequence_data <- function(data) {
   if (!nrow(data)) return(data.frame(
     chain=character(), resi=integer(), insertion_code=character(),