From 3043d3e9709a7f0d504d587ce2f6ff90037d29cb Mon Sep 17 00:00:00 2001 From: spomlol <77454330+CedricHermansBIT@users.noreply.github.com> Date: Tue, 29 Sep 2026 00:25:57 +0200 Subject: [PATCH 1/3] docs: organise user guides by research task rather than upgrade phase --- README.md | 10 +++++----- docs/README.md | 18 ++++++++++++++++++ ...ase-b-guide.md => prediction-confidence.md} | 8 ++++---- ...e-c-guide.md => structural-verification.md} | 14 +++++++------- ...hase-a-results.md => validation-results.md} | 2 +- docs/wwpdb-validation.md | 8 ++++---- 6 files changed, 39 insertions(+), 21 deletions(-) create mode 100644 docs/README.md rename docs/{phase-b-guide.md => prediction-confidence.md} (94%) rename docs/{phase-c-guide.md => structural-verification.md} (93%) rename docs/{phase-a-results.md => validation-results.md} (98%) diff --git a/README.md b/README.md index 17e678f..2acfd34 100644 --- a/README.md +++ b/README.md @@ -67,13 +67,13 @@ Rscript scripts/ramplotr-batch.R --input structures/ --output results/ --report The offline command produces per-residue CSV, machine-readable JSON and a batch summary; `--report` additionally requests SVG and standalone HTML reports. For a compatible multi-model structure, add `--ensemble-models 20`. Use `--help` for all options, including declared prediction provenance and an optional matching wwPDB validation XML. -See the [batch-analysis instructions](docs/phase-c-guide.md#offline-batch-mode) for examples and resource limits. +See the [batch-analysis instructions](docs/structural-verification.md#offline-batch-mode) for examples and resource limits. ## Scientific interpretation RamplotR's **residue-aware mode** evaluates general residues, glycine, proline and pre-proline against their corresponding bundled reference distributions. The selected plotting background is independent of those residue-specific classification calculations. The original density references trace back to the distributions discussed by [Lovell et al. (2003)](https://pubmed.ncbi.nlm.nih.gov/12557186/); other bundled reference datasets can also be selected. -**RamplotR region labels are not interchangeable with MolProbity or wwPDB classifications.** They use different reference populations, residue treatments and region definitions. Our [independent validation results](docs/phase-a-results.md), [reproducible protocol](docs/wwpdb-validation.md) and [pinned experimental-structure corpus](validation/manifest.csv) document agreement in calculated angles as well as differences in classification. For deposited experimental structures, attach the official report for the **same structure and model** when making independent quality assessments. +**RamplotR region labels are not interchangeable with MolProbity or wwPDB classifications.** They use different reference populations, residue treatments and region definitions. Our [independent validation results](docs/validation-results.md), [reproducible protocol](docs/wwpdb-validation.md) and [pinned experimental-structure corpus](validation/manifest.csv) document agreement in calculated angles as well as differences in classification. For deposited experimental structures, attach the official report for the **same structure and model** when making independent quality assessments. For predictions, pLDDT and PAE describe model confidence rather than experimental verification. ESMFold normally provides pLDDT but not PAE; experimental thermal B-factors are **never** automatically interpreted as prediction confidence. The native ω, χ1 and Cβ measurements are descriptive, and visualising a density map is not a quantitative map–model fit measurement. @@ -82,9 +82,9 @@ The default RamplotR teal contour palette provides consistent, recognisable publ ## Documentation - [Interactive inspection, colours, comparisons and exports](docs/inspection-user-guide.md) -- [AlphaFold, ColabFold and ESMFold confidence analysis](docs/phase-b-guide.md) -- [Geometry, official wwPDB evidence, cryo-EM overlays, ensembles and batch mode](docs/phase-c-guide.md) -- [Independent wwPDB validation protocol and benchmark results](docs/wwpdb-validation.md) · [Results](docs/phase-a-results.md) +- [AlphaFold, ColabFold and ESMFold confidence analysis](docs/prediction-confidence.md) +- [Geometry, official wwPDB evidence, cryo-EM overlays, ensembles and batch mode](docs/structural-verification.md) +- [Independent wwPDB validation protocol and benchmark results](docs/wwpdb-validation.md) · [Results](docs/validation-results.md) - [Performance and large-structure benchmarks](docs/benchmark-results.md) · [Scaling results](docs/scaling-results.md) Developers can run the pure-R scientific regression suite from the repository root with `Rscript tests/scientific.R`. Additional tests cover structure parsing, validation imports, confidence formats, geometry, ensembles and the batch CLI. GitHub Actions also exercises the application in a real browser and runs the scientific tests on Ubuntu and Windows. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8b730b2 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,18 @@ +# RamplotR documentation + +Choose a guide by the research task you want to perform. The [main README](../README.md) introduces the application, screenshots and installation. + +## Working with structures + +- [Interactive inspection and publication-ready figures](inspection-user-guide.md): linked Ramachandran plot, residue table, sequence navigator, 3D viewer, comparison and exports. +- [AlphaFold, ColabFold and ESMFold confidence](prediction-confidence.md): model imports, pLDDT and linked PAE inspection. +- [Structural verification, cryo-EM overlays and ensembles](structural-verification.md): measured backbone/side-chain geometry, independent official reports, maps and offline batch processing. + +## Scientific validation and performance + +- [Independent wwPDB validation method](wwpdb-validation.md) and [five-structure results](validation-results.md). +- [Benchmark results](benchmark-results.md), [scaling study](scaling-study.md) and [scaling measurements](scaling-results.md). + +## Development records + +[Implementation and verification history](development/README.md) is kept separately from the user guides. Its historical notes describe what changed during development, not different current application modes. diff --git a/docs/phase-b-guide.md b/docs/prediction-confidence.md similarity index 94% rename from docs/phase-b-guide.md rename to docs/prediction-confidence.md index e60669a..5f4129c 100644 --- a/docs/phase-b-guide.md +++ b/docs/prediction-confidence.md @@ -1,8 +1,8 @@ -# Phase B: analysing AlphaFold and ESMFold predictions +# AlphaFold and ESMFold prediction confidence -RamplotR preserves its existing structure-analysis workflow. Prediction -confidence is **additional evidence**, not a replacement for the experimental -or stereochemical validation completed in Phase A. +RamplotR adds model-confidence evidence to its existing structure-inspection +workflow. Confidence complements stereochemical analysis and experimental +validation; it cannot replace either. ## Loading a prediction diff --git a/docs/phase-c-guide.md b/docs/structural-verification.md similarity index 93% rename from docs/phase-c-guide.md rename to docs/structural-verification.md index dd29c41..c40c8c0 100644 --- a/docs/phase-c-guide.md +++ b/docs/structural-verification.md @@ -1,8 +1,8 @@ -# Phase C: structural verification, ensembles and batch analysis +# Structural verification, ensembles and batch analysis -Phase C extends the established RamplotR Ramachandran analysis without -changing its reference densities, four-region labels, or the historical -`v0.1.0-legacy` release. +These workflows extend RamplotR's Ramachandran analysis without changing its +reference densities or four-region labels. The historical +`v0.1.0-legacy` release remains available for reproducibility. ## Extended native geometry @@ -42,7 +42,7 @@ the source file's MD5 checksum in its HTML report. The original RamplotR contour interpretation and the wwPDB/MolProbity reference systems are **not equivalent**. The independent outlier-rich -[Phase A results](phase-a-results.md) explicitly show genuine discrepancies. +[independent validation results](validation-results.md) explicitly show genuine discrepancies. Importing a report does not rewrite the original region classification. Do not attach experimental wwPDB validation reports to an unrelated AlphaFold/ESMFold prediction, even if their sequences are similar. @@ -118,7 +118,7 @@ For an ESMFold prediction, explicitly set `--prediction-source esmfold`; never request this for an experimental structure. For AlphaFold 2/3, the CLI can read declared pLDDT from compatible B-factor files; AF3 confidence sidecar parsing remains available in the -interactive Phase B uploader. +interactive prediction uploader. Use `--no-json` to avoid the optional jsonlite dependency; `--report` requires htmltools and an SVG-capable R graphics device, while wwPDB XML @@ -132,7 +132,7 @@ The outputs record the current model, file MD5 checksum, reference file MD5, R/Bio3D versions, chosen scientific mode and prediction provenance where declared. The HTML report distinguishes computed geometry from imported independent evidence and prints model-ensemble statistics when available. -Use the pinned Phase A corpus and reference-validation reports before +Use the pinned independent wwPDB corpus and reference-validation reports before making formal validation-performance claims. Avoid presenting any visual density overlay or geometric heuristic as an official experimental fit or MolProbity-equivalent score. diff --git a/docs/phase-a-results.md b/docs/validation-results.md similarity index 98% rename from docs/phase-a-results.md rename to docs/validation-results.md index eba9a1a..1c265ef 100644 --- a/docs/phase-a-results.md +++ b/docs/validation-results.md @@ -1,4 +1,4 @@ -# Phase A: observed independent wwPDB validation results +# Independent wwPDB validation: five-structure results **Date:** September 28, 2026. **Version:** original bundled reference distributions, residue-aware classification, model 1. All samples were diff --git a/docs/wwpdb-validation.md b/docs/wwpdb-validation.md index f778857..d21f54c 100644 --- a/docs/wwpdb-validation.md +++ b/docs/wwpdb-validation.md @@ -1,4 +1,4 @@ -# Phase A: independent wwPDB Ramachandran validation +# Independent wwPDB Ramachandran validation RamplotR now supports residue-matched comparison against **official wwPDB validation XML**, separately from its existing independent Bio3D angle @@ -76,7 +76,7 @@ reproduced results; it fails if source hashes, finite angles or class counts change without explicit review. Preserve exact source files and results in a versioned release or DOI-backed archive for publication. -See the [initial independently measured five-structure results](phase-a-results.md), +See the [initial independently measured five-structure results](validation-results.md), including the seven 2DQ4 wwPDB outliers not identified by the existing RamplotR original reference distributions. @@ -86,5 +86,5 @@ Only model 1 and unambiguous residue identities are compared. Alternate conformations, aliases, modified residues and missing atoms reduce comparable coverage rather than being silently declared matched. Comparative results are specific to the original RamplotR references. -The AlphaFold and ESMFold confidence workflows belong to Phase B and -are not substitutes for independently measured experimental coordinates. +AlphaFold and ESMFold confidence provide complementary prediction evidence; +they are not substitutes for independently measured experimental coordinates. From b27c9a3176d248fcf0a8267fc4b2d01a5e38e4b1 Mon Sep 17 00:00:00 2001 From: spomlol <77454330+CedricHermansBIT@users.noreply.github.com> Date: Tue, 29 Sep 2026 00:26:38 +0200 Subject: [PATCH 2/3] docs: archive implementation history separately from current user guides --- docs/development/README.md | 12 ++++++++++++ .../independent-validation.md} | 12 ++++++------ .../interface-and-inspection.md} | 4 ++-- docs/{ => development}/interface-refresh.md | 8 ++++---- .../prediction-confidence.md} | 4 ++-- .../scientific-upgrade.md} | 10 +++++----- .../structural-verification.md} | 18 +++++++++++------- 7 files changed, 42 insertions(+), 26 deletions(-) create mode 100644 docs/development/README.md rename docs/{phase-a-worklog.md => development/independent-validation.md} (77%) rename docs/{upgrade-inspection-worklog.md => development/interface-and-inspection.md} (88%) rename docs/{ => development}/interface-refresh.md (93%) rename docs/{phase-b-worklog.md => development/prediction-confidence.md} (92%) rename docs/{upgrade-worklog.md => development/scientific-upgrade.md} (78%) rename docs/{phase-c-worklog.md => development/structural-verification.md} (63%) diff --git a/docs/development/README.md b/docs/development/README.md new file mode 100644 index 0000000..1e875c4 --- /dev/null +++ b/docs/development/README.md @@ -0,0 +1,12 @@ +# Development and verification history + +These records document the implementation of RamplotR's current capabilities. They are retained for traceability and are **not** separate application versions or user workflows. Start with the [user documentation](../README.md) instead. + +- [Scientific corrections, reference handling and performance](scientific-upgrade.md) +- [Interactive interface and linked residue inspection](interface-and-inspection.md) +- [Earlier interface design and browser verification](interface-refresh.md) +- [Independent experimental validation](independent-validation.md) +- [AlphaFold and ESMFold prediction-confidence integration](prediction-confidence.md) +- [Extended geometry, wwPDB evidence, ensemble and batch implementation](structural-verification.md) + +The [historical release tag](https://github.com/BiKC/RamplotR/tree/v0.1.0-legacy) remains available for reproducing earlier analyses. diff --git a/docs/phase-a-worklog.md b/docs/development/independent-validation.md similarity index 77% rename from docs/phase-a-worklog.md rename to docs/development/independent-validation.md index cd8dcd7..fde2685 100644 --- a/docs/phase-a-worklog.md +++ b/docs/development/independent-validation.md @@ -1,4 +1,4 @@ -# Phase A: independent structural validation +# Independent experimental validation: implementation record Base: main at a09d3eed4800bbe5c3aea37869fb181ea8fc8a6f. Historical version v0.1.0-legacy and reference grids are unchanged. @@ -8,17 +8,17 @@ Base: main at a09d3eed4800bbe5c3aea37869fb181ea8fc8a6f. Historical version v0.1. - [x] Test XML parsing, stable residue matching, alt locations, insertion codes, missing angles and unequal classification vocabularies. - [x] Add a public manifest and an easy-to-run verification workflow; fail CI on coverage/angle regressions, not on genuine differences between reference models. - [x] Document why the four-region, four-reference-group RamplotR original method is not directly MolProbity-equivalent to its three regions and six groups. -- [x] Pass Ubuntu/Windows scientific regression, independent five-structure wwPDB validation, structure-validation benchmark and full live-browser CI, and merge PR #13 into main. ESMFold and AlphaFold are explicitly Phase B. +- [x] Pass Ubuntu/Windows scientific regression, independent five-structure wwPDB validation, structure-validation benchmark and full live-browser CI, and merge PR #13 into main. AlphaFold and ESMFold prediction confidence are documented separately. ## Independent findings -[Five-structure results](phase-a-results.md) and -[pinned SHA256 source manifests](../validation/baseline-source-hashes-2026-09-28.csv) +[Five-structure results](../validation-results.md) and +[pinned SHA256 source manifests](../../validation/baseline-source-hashes-2026-09-28.csv) were generated from official wwPDB validation reports. 2DQ4's seven official outliers are not classified as outliers by the original RamplotR references. The independent numerical geometry and group-specific class comparisons are -tested separately. Do not claim MolProbity-equivalent categories. Phase B -includes AlphaFold and ESMFold predicted-model confidence integration. +tested separately. Do not claim MolProbity-equivalent categories. Prediction-confidence analysis for AlphaFold and ESMFold is documented +in the separate [prediction-confidence guide](../prediction-confidence.md). Completed integration: https://github.com/BiKC/RamplotR/pull/13 Reviewed independent validation workflow: https://github.com/BiKC/RamplotR/actions/runs/36476627652 diff --git a/docs/upgrade-inspection-worklog.md b/docs/development/interface-and-inspection.md similarity index 88% rename from docs/upgrade-inspection-worklog.md rename to docs/development/interface-and-inspection.md index 27b22e0..d8099e7 100644 --- a/docs/upgrade-inspection-worklog.md +++ b/docs/development/interface-and-inspection.md @@ -1,4 +1,4 @@ -# RamplotR inspection and publication upgrade +# Interactive inspection and publication tools: implementation record Branch: `upgrade/inspection-visualization-reporting` (integration PR #12). Historical reference: `v0.1.0-legacy` is unchanged; all scientific reference grids are preserved. @@ -22,7 +22,7 @@ Historical reference: `v0.1.0-legacy` is unchanged; all scientific reference gri - [Structure validation and benchmark](https://github.com/BiKC/RamplotR/actions/runs/36470803613) - [Live Shiny browser test and visual-preview artifact](https://github.com/BiKC/RamplotR/actions/runs/36470803548) -These runs confirm the implemented regression and browser scenarios. Independent agreement of every RamplotR region classification against MolProbity is separate future validation, not a claim from these tests. Hosted deployments must be updated separately from merging the GitHub repository. +These runs confirm the implemented regression and browser scenarios. Independent wwPDB comparisons have since been performed and are documented in the [validation results](../validation-results.md). These are method comparisons, not a claim of identical RamplotR and MolProbity classifications. Hosted deployments must be updated separately from merging the GitHub repository. ## Scientific boundaries diff --git a/docs/interface-refresh.md b/docs/development/interface-refresh.md similarity index 93% rename from docs/interface-refresh.md rename to docs/development/interface-refresh.md index 1b95c70..5534437 100644 --- a/docs/interface-refresh.md +++ b/docs/development/interface-refresh.md @@ -1,6 +1,6 @@ -# Interface refresh +# Interactive interface: design and verification record -The interface refresh changes the layout and plotting presentation without +This historical record describes the layout and plotting changes without changing backbone extraction, reference grids or scientific classifications. The historical application remains available as v0.1.0-legacy. @@ -71,6 +71,6 @@ In a browser, check both a wide desktop window and a mobile-width window: 5. Test a structure with many chains and a structure with missing angles, then download a PNG with the Plotly toolbar. -The old README screenshot is historical; capture a new screenshot from a -running app before replacing it. The shinyapps.io deployment is separate +The [main README](../../README.md) now contains curated screenshots generated +from the real browser tests. The shinyapps.io deployment is separate from merging changes into the GitHub repository. diff --git a/docs/phase-b-worklog.md b/docs/development/prediction-confidence.md similarity index 92% rename from docs/phase-b-worklog.md rename to docs/development/prediction-confidence.md index ad175de..fb769d9 100644 --- a/docs/phase-b-worklog.md +++ b/docs/development/prediction-confidence.md @@ -1,6 +1,6 @@ -# Phase B — AlphaFold and ESMFold confidence integration +# Prediction confidence: implementation record -Base: main `99fd7f38c17e88dce28b043560ecd5a147d647ea`. Scientific Phase A and historical tag stay unchanged. +Base: main `99fd7f38c17e88dce28b043560ecd5a147d647ea`. Independent validation and the historical tag remain unchanged. - [x] Native prediction provenance and per-residue pLDDT extraction from AlphaFold and ESMFold B-factors; experimental B-factors must never be relabelled confidence. - [x] Optional AlphaFold DB accession retrieval and JSON confidence sidecar uploads (AlphaFold 2 PAE and AlphaFold 3 full confidence/summary JSON). diff --git a/docs/upgrade-worklog.md b/docs/development/scientific-upgrade.md similarity index 78% rename from docs/upgrade-worklog.md rename to docs/development/scientific-upgrade.md index 4fa2147..6aeb69c 100644 --- a/docs/upgrade-worklog.md +++ b/docs/development/scientific-upgrade.md @@ -1,6 +1,6 @@ # RamplotR upgrade worklog -This log records the main changes and their verification status. Work happens in separately scoped commits. The published historical baseline is preserved as `v0.1.0-legacy` (commit `aa3eba2180d505f4dc01c9c2bf977cef00b3252a`). +This historical log records early scientific changes and verification. For current usage, see [the documentation index](../README.md). Some unchecked historical proposals were subsequently implemented in other pull requests; refer to the current user guides for available features. Work happens in separately scoped commits. The published historical baseline is preserved as `v0.1.0-legacy` (commit `aa3eba2180d505f4dc01c9c2bf977cef00b3252a`). ## Completed in PR #2 @@ -8,7 +8,7 @@ This log records the main changes and their verification status. Work happens in 2. Deterministic density thresholds and reusable reference grids. 3. Atom-based backbone torsions that respect peptide connectivity, chain boundaries and insertion codes. -## Phase 2: CI, inputs, reproducibility +## Regression testing, input handling and reproducibility - [x] Keep scientific changes in their own commits, merged without squashing. - [x] Add a two-platform R regression workflow for existing scientific test scripts. @@ -21,7 +21,7 @@ This log records the main changes and their verification status. Work happens in The scientific classifications are tied to the bundled reference densities. Do not claim MolProbity-equivalent outlier percentages without a separate benchmark. New methods and reference datasets will be versioned. -## Phase 3: scientific comparisons and timing +## Scientific comparisons and timing - [x] Provide a repeatable analysis/timing script recording the structure, reference dataset, software environment and per-stage elapsed time. - [x] Provide an independent torsion-angle comparison with Bio3D for PDB accessions without insertion codes. @@ -29,14 +29,14 @@ The scientific classifications are tied to the bundled reference densities. Do n - [ ] Run scaling benchmarks on large PDB/mmCIF inputs and record benchmark output. - [ ] Compare region labels against independently generated structural-validation reports; numerical thresholds differ across implementations. -## Phase 4: larger-structure performance and paper preparation +## Larger-structure performance and manuscript planning - [x] Preallocate and vectorize backbone extraction (PR #5). - [x] Cache immutable classification reference profiles (PR #6). - [x] Correct independent validation identifier matching and enforce coverage (PR #7). - [x] Run a same-runner 6VXX scaling pilot with 1x, 3x and 10x replicated complexes and record peak RSS, warm/cold stage timings and software metadata. - See [measured results](scaling-results.md) and [run 36430181464](https://github.com/BiKC/RamplotR/actions/runs/36430181464). + See [measured results](../scaling-results.md) and [run 36430181464](https://github.com/BiKC/RamplotR/actions/runs/36430181464). - [ ] Run paired same-host comparisons of legacy and current algorithms, including peak RSS. - [ ] Compare RamplotR region labels against independent MolProbity-style reports. - [ ] Prepare the methods, validation tables and figures for the arXiv preprint once validation is complete. diff --git a/docs/phase-c-worklog.md b/docs/development/structural-verification.md similarity index 63% rename from docs/phase-c-worklog.md rename to docs/development/structural-verification.md index 6447e07..83c8902 100644 --- a/docs/phase-c-worklog.md +++ b/docs/development/structural-verification.md @@ -1,15 +1,19 @@ -# Phase C — structural verification and research workflows +# Structural verification and batch processing: implementation record -Base: `dad437d132c58452caa46950d644172e19b2eaa6` (Phase A and Phase B merged into `main`). Preserve scientific reference grids and `v0.1.0-legacy`. +Base: `dad437d132c58452caa46950d644172e19b2eaa6` (the independent-validation and prediction-confidence work already integrated into `main`). Preserve scientific reference grids and `v0.1.0-legacy`. ## Work packages -- [ ] **Extended geometry**: compute interpretable omega cis/trans/twisted peptide flags and independent side-chain chi1 and Cβ geometry. Use explicit methodology and missing-value semantics; for authoritative rotamer/clash results, import wwPDB validation results rather than claim an ad hoc calculation is MolProbity-equivalent. -- [ ] **Experimental evidence**: allow optional local official wwPDB validation XML and show its residue-specific rotamer/clash/outlier annotations; link to source and show differences against the native RamplotR region. Optional NGL density-map view for local cryo-EM maps with user-controlled contours, not an unvalidated map/model fit score. -- [ ] **Ensembles**: compare coherent NMR/prediction models residue by residue using circular angle statistics, coverage and class-change summaries. Identify missing/misaligned atom records, not index-only matching. -- [ ] **Batch interface**: a scriptable offline R command, safe output directories, per-residue CSV/JSON and standalone HTML/SVG exports; consistent options and provenance. Structure and reference files remain local. -- [ ] Tests on synthetic fixtures and genuine multimeric/NMR samples, CI and docs. Keep advanced controls optional; no extra permanent tabs without need. +- [x] **Extended geometry**: compute interpretable omega cis/trans/twisted peptide flags and independent side-chain chi1 and Cβ geometry. Use explicit methodology and missing-value semantics; for authoritative rotamer/clash results, import wwPDB validation results rather than claim an ad hoc calculation is MolProbity-equivalent. +- [x] **Experimental evidence**: allow optional local official wwPDB validation XML and show its residue-specific rotamer/clash/outlier annotations; link to source and show differences against the native RamplotR region. Optional NGL density-map view for local cryo-EM maps with user-controlled contours, not an unvalidated map/model fit score. +- [x] **Ensembles**: compare coherent NMR/prediction models residue by residue using circular angle statistics, coverage and class-change summaries. Identify missing/misaligned atom records, not index-only matching. +- [x] **Batch interface**: a scriptable offline R command, safe output directories, per-residue CSV/JSON and standalone HTML/SVG exports; consistent options and provenance. Structure and reference files remain local. +- [x] Tests on synthetic fixtures and genuine multimeric/NMR samples, CI and docs. Keep advanced controls optional; no extra permanent tabs without need. ## Methodological limits Independent wwPDB classifications and MolProbity rotamers/clashscores have different algorithms/reference populations and must not be relabelled as new native RamplotR reference classifications. Experimental B factors are not pLDDT. Map visuals are qualitative unless a validated map-fit engine is integrated. Aggregate ensemble measurements require matching residue IDs and explicitly report missing data. AlphaFold/ESMFold predictions remain supported, with their provenance retained. + +## Integration + +Implemented and verified in [PR #15](https://github.com/BiKC/RamplotR/pull/15). This is an archived implementation checklist; current usage and scientific limits are described in the [structural-verification guide](../structural-verification.md). From 3a89b98d2a3a0a13f7f6275ac0a82a5c7aa0b124 Mon Sep 17 00:00:00 2001 From: spomlol <77454330+CedricHermansBIT@users.noreply.github.com> Date: Tue, 29 Sep 2026 00:27:10 +0200 Subject: [PATCH 3/3] test: remove legacy phase names from validation and browser workflow files --- .github/workflows/scientific-tests.yml | 2 +- .github/workflows/ui-preview.yml | 3 ++- .github/workflows/wwpdb-validation.yml | 6 +++--- docs/validation-results.md | 2 +- docs/wwpdb-validation.md | 2 +- scripts/curate-readme-screenshots.py | 8 +++++++- ...er.cjs => structure-verification-browser.cjs} | 16 ++++++++-------- tests/{phase-a-baseline.R => wwpdb-baseline.R} | 4 ++-- 8 files changed, 25 insertions(+), 18 deletions(-) rename tests/{phase-c-browser.cjs => structure-verification-browser.cjs} (92%) rename tests/{phase-a-baseline.R => wwpdb-baseline.R} (96%) diff --git a/.github/workflows/scientific-tests.yml b/.github/workflows/scientific-tests.yml index 7a0c18d..e399a76 100644 --- a/.github/workflows/scientific-tests.yml +++ b/.github/workflows/scientific-tests.yml @@ -40,7 +40,7 @@ jobs: - name: Install optional official wwPDB XML parser run: Rscript -e 'install.packages("xml2", repos="https://cloud.r-project.org")' shell: bash - - name: Verify Phase C geometry, ensembles and offline CLI + - name: Verify geometry, ensembles and offline CLI run: | Rscript tests/geometry.R Rscript tests/experimental.R diff --git a/.github/workflows/ui-preview.yml b/.github/workflows/ui-preview.yml index a7f074f..b0c0c50 100644 --- a/.github/workflows/ui-preview.yml +++ b/.github/workflows/ui-preview.yml @@ -6,6 +6,7 @@ on: - "shinyRam/app.R" - "shinyRam/www/**" - "tests/ui-browser.cjs" + - "tests/structure-verification-browser.cjs" - "tests/reports.R" - "tests/model-integration.R" - "shinyRam/R/**" @@ -74,7 +75,7 @@ jobs: - name: Verify AlphaFold and ESMFold uploads in the live browser run: node tests/prediction-browser.cjs - name: Verify official wwPDB evidence, density UI and NMR ensemble - run: node tests/phase-c-browser.cjs + run: node tests/structure-verification-browser.cjs - name: Archive desktop/mobile screenshot previews and logs if: always() uses: actions/upload-artifact@v4 diff --git a/.github/workflows/wwpdb-validation.yml b/.github/workflows/wwpdb-validation.yml index a6d489d..9889348 100644 --- a/.github/workflows/wwpdb-validation.yml +++ b/.github/workflows/wwpdb-validation.yml @@ -8,7 +8,7 @@ on: - "benchmarks/wwpdb_helpers.R" - "benchmarks/compare_wwpdb.R" - "tests/wwpdb.R" - - "tests/phase-a-baseline.R" + - "tests/wwpdb-baseline.R" - "validation/**" - ".github/workflows/wwpdb-validation.yml" pull_request: @@ -17,7 +17,7 @@ on: - "benchmarks/wwpdb_helpers.R" - "benchmarks/compare_wwpdb.R" - "tests/wwpdb.R" - - "tests/phase-a-baseline.R" + - "tests/wwpdb-baseline.R" - "validation/**" - ".github/workflows/wwpdb-validation.yml" workflow_dispatch: @@ -79,7 +79,7 @@ jobs: env: ACCESSION: ${{ matrix.accession }} run: | - Rscript tests/phase-a-baseline.R "$ACCESSION" "benchmarks/output/wwpdb/$ACCESSION" + Rscript tests/wwpdb-baseline.R "$ACCESSION" "benchmarks/output/wwpdb/$ACCESSION" - name: Add independent validation summary if: success() shell: bash diff --git a/docs/validation-results.md b/docs/validation-results.md index 1c265ef..fda440a 100644 --- a/docs/validation-results.md +++ b/docs/validation-results.md @@ -40,7 +40,7 @@ The independent source XML and coordinate CIF are archived with every CI artifact, along with all joined residues, reference-group confusion matrices, source checksums and R session metadata. All input hashes and quantitative snapshots are additionally pinned in the repository; -[tests/phase-a-baseline.R](../tests/phase-a-baseline.R) fails if an +[tests/wwpdb-baseline.R](../tests/wwpdb-baseline.R) fails if an official source changes without review or if the same pinned sources produce different numbers. diff --git a/docs/wwpdb-validation.md b/docs/wwpdb-validation.md index d21f54c..0a2f7d9 100644 --- a/docs/wwpdb-validation.md +++ b/docs/wwpdb-validation.md @@ -71,7 +71,7 @@ runs all five samples. It stores full source and output artifacts for 90 days. [Versioned baseline outputs](../validation/baseline-2026-09-28.csv), [exact source SHA256 hashes](../validation/baseline-source-hashes-2026-09-28.csv), and [independent outlier examples](../validation/2dq4-wwpdb-outlier-examples.csv) -are pinned in the repository. Run `tests/phase-a-baseline.R` against the +are pinned in the repository. Run `tests/wwpdb-baseline.R` against the reproduced results; it fails if source hashes, finite angles or class counts change without explicit review. Preserve exact source files and results in a versioned release or DOI-backed archive for publication. diff --git a/scripts/curate-readme-screenshots.py b/scripts/curate-readme-screenshots.py index 9e8a38c..d667304 100644 --- a/scripts/curate-readme-screenshots.py +++ b/scripts/curate-readme-screenshots.py @@ -20,13 +20,19 @@ "residue-inspection.png": ("desktop-residue-zoom.png", (5, 165, 1420, 1120)), "all-chains.png": ("all-chains-expanded.png", (380, 1030, 1040, 1690)), "prediction-pae.png": ("prediction-af2-pae.png", (355, 1390, 1300, 2180)), - "ensemble.png": ("phase-c-ensemble.png", (380, 812, 1340, 1570)), + "ensemble.png": ("verification-ensemble.png", (380, 812, 1340, 1570)), } def main(): DEST.mkdir(parents=True, exist_ok=True) for name, (original, bounds) in EXAMPLES.items(): path = SOURCE / original + # Accept older successful workflow artifacts when regenerating + # documentation for historic revisions. + if name == "ensemble.png" and not path.is_file(): + legacy = SOURCE / "phase-c-ensemble.png" + if legacy.is_file(): + path = legacy if not path.is_file(): raise FileNotFoundError(f"Missing {path}; rerun the real browser tests.") with Image.open(path) as picture: diff --git a/tests/phase-c-browser.cjs b/tests/structure-verification-browser.cjs similarity index 92% rename from tests/phase-c-browser.cjs rename to tests/structure-verification-browser.cjs index 575172c..61c94d5 100644 --- a/tests/phase-c-browser.cjs +++ b/tests/structure-verification-browser.cjs @@ -1,4 +1,4 @@ -// Phase C live Shiny smoke test. Fixtures are synthetic, not claims about +// Experimental verification live Shiny smoke test. Fixtures are synthetic, not claims about // experimental map fit or official wwPDB assessments. const fs=require("node:fs"),path=require("node:path"); const assert=require("node:assert/strict"); @@ -61,7 +61,7 @@ const puppeteer=require("puppeteer-core"); document.querySelector(".ram-official-summary")&& document.querySelector(".ram-official-summary").textContent .includes("Matched 1 of"),{timeout:30000}); - await page.screenshot({path:path.join(output,"phase-c-wwpdb.png"), + await page.screenshot({path:path.join(output,"verification-wwpdb.png"), fullPage:true}); // Mock only volume parsing to test local map controls deterministically. // Physical map alignment still requires a genuine CCP4 map and review. @@ -119,8 +119,8 @@ const puppeteer=require("puppeteer-core"); stageAvailable:typeof window.getNGLStage==="function" && !!window.getNGLStage("NGL") })); - console.error("Phase C map controls:",JSON.stringify(diagnostics)); - await page.screenshot({path:path.join(output,"phase-c-map-failure.png"), + console.error("Experimental verification map controls:",JSON.stringify(diagnostics)); + await page.screenshot({path:path.join(output,"verification-map-failure.png"), fullPage:true}); throw error; } @@ -181,13 +181,13 @@ const puppeteer=require("puppeteer-core"); notifications:[...document.querySelectorAll(".shiny-notification")] .map(node=>node.textContent) })); - console.error("Phase C ensemble diagnostics:",JSON.stringify(details)); - await page.screenshot({path:path.join(output,"phase-c-ensemble-failure.png"), + console.error("Experimental verification ensemble diagnostics:",JSON.stringify(details)); + await page.screenshot({path:path.join(output,"verification-ensemble-failure.png"), fullPage:true}); throw error; } - await page.screenshot({path:path.join(output,"phase-c-ensemble.png"), + await page.screenshot({path:path.join(output,"verification-ensemble.png"), fullPage:true}); - console.log("Phase C wwPDB import, NGL overlay and NMR ensemble passed."); + console.log("Experimental verification wwPDB import, NGL overlay and NMR ensemble passed."); }finally{await browser.close();} })().catch(error=>{console.error(error);process.exitCode=1;}); diff --git a/tests/phase-a-baseline.R b/tests/wwpdb-baseline.R similarity index 96% rename from tests/phase-a-baseline.R rename to tests/wwpdb-baseline.R index d830eb2..c957de9 100644 --- a/tests/phase-a-baseline.R +++ b/tests/wwpdb-baseline.R @@ -1,10 +1,10 @@ # Exact-source reproducibility gate for the independent experimental cohort. -# Usage: Rscript tests/phase-a-baseline.R ACCESSION OUTPUT_DIR +# Usage: Rscript tests/wwpdb-baseline.R ACCESSION OUTPUT_DIR # This is run after benchmarks/compare_wwpdb.R has saved its provenance, # per-residue comparison and scientific summary. args <- commandArgs(trailingOnly = TRUE) if (length(args) != 2L) - stop("Usage: Rscript tests/phase-a-baseline.R ACCESSION OUTPUT_DIR") + stop("Usage: Rscript tests/wwpdb-baseline.R ACCESSION OUTPUT_DIR") id <- toupper(args[[1L]]) folder <- args[[2L]] expect <- read.csv("validation/baseline-2026-09-28.csv",