Add multi-file prediction ensemble analysis

[CedricHermansBIT]

Adds multi-file prediction ensemble analysis for independently generated prediction models/seeds.

Supported ensemble inputs

• AlphaFold 2 / ColabFold;
• ESMFold;
• other prediction models with pLDDT stored in B-factors.

The currently loaded compatible prediction can be included as one ensemble member. AlphaFold 3 is intentionally not silently interpreted as AF2: per-model AF3 confidence requires its matching atom/token JSON sidecar and remains a future extension.

Per-residue ensemble analysis

• exact matching by chain, residue number, insertion code and residue identity;
• circular φ/ψ mean and standard deviation;
• number of contributing models;
• native RamplotR region agreement;
• Rama8000 Favored/Allowed/Outlier mode and agreement;
• pLDDT mean, SD, min and max;
• compact prediction-variability map using max circular SD(φ,ψ);
• variability-map and table selections link back to the existing residue inspector and 2D/3D views.

Reproducibility and safeguards

• requires at least two prediction models;
• one structural model per uploaded file;
• up to 30 models analysed per run;
• duplicate coordinate files are rejected by MD5 hash;
• model-level export preserves labels, declared source, residue/outlier/confidence summaries and coordinate MD5;
• larger multi-file uploads are supported while confidence JSON retains its independent 32 MB parser limit.

Interpretation

The UI explicitly labels model-to-model spread as prediction uncertainty/heterogeneity, not experimental dynamics.

Coverage

• unit tests cover circular statistics, residue identity matching, Rama8000 agreement, pLDDT aggregation, labels/provenance and AF3 rejection;
• live browser CI uploads two separate synthetic ESMFold models, renders the variability map/table and tests map → residue selection.

[Copilot]

Copilot review overview

🟡 Changes recommended

Ensemble bounds, loaded multi-model handling, cache invalidation, and duplicate-label provenance exports need correction.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Enforce the documented 2–30 prediction ensemble bounds · New
• Append provenance positionally instead of merging on nonunique labels · New
• Assert nonzero pLDDT disagreement count in the browser test · New

What changed in this PR

Adds multi-file prediction ensemble analysis with residue-level geometry, Rama8000, and pLDDT comparisons.

Changes:

• Implements prediction ensemble aggregation, provenance exports, and safeguards.
• Adds interactive variability maps, linked residue selection, and responsive styling.
• Expands unit, browser, and user documentation coverage.

File	Description
shinyRam/​R/​ensemble.R	Adds prediction ensemble analysis and statistics.
shinyRam/​app.R	Adds upload, analysis, visualization, and export workflows.
shinyRam/​www/​custom.js	Links variability-map clicks to residue selection.
shinyRam/​www/​styles.css	Styles ensemble controls and variability map.
tests/​ensemble.R	Tests aggregation, provenance, and AF3 rejection.
tests/​prediction-browser.cjs	Exercises the ensemble workflow in-browser.
README.md	Advertises prediction ensemble support.
docs/​prediction-ensembles.md	Documents inputs, interpretation, and limitations.
docs/​inspection-user-guide.md	Adds ensemble usage guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.