[vcnainala]

Summary

Adds an Assignment Quickcheck to nmrXiv. Authors check their ¹³C / ¹H assignments against predicted shifts for the sample structure. They get a score per nucleus, an atom-by-atom shift comparison and an assignment check, and can confirm the assignments. The confirmation is shown on the published sample.

The prediction and comparison happen in NMRKit: depends on NFDI4Chem/nmrkit#147 (POST /latest/validate/assignments). The UI wording is engine-neutral, with no nmrshiftdb2 references, so the prediction engine can later be replaced by nmrXiv's own without changing the UI.

What chemists get

• Result banner with a plain-language verdict ("Assignments match the predicted shifts", "Some assignments need checking" …).
• One score card per nucleus: a gauge with the score out of 10, a "Good fit / Needs checking / Poor fit" pill, a bar showing matching, borderline, non-matching and unassigned atoms, and the average deviation. A nucleus with any non-matching atom is never a "Good fit".
• Structure and shift comparison side by side (50/50):
  • The left side shows the structure with the author's carbon and proton labels; protons are drawn explicitly with their atom numbers. Atoms that need checking are highlighted.
  • The right side is one scrollable table for ¹³C and ¹H: δ observed, δ predicted, |Δδ|, environment match (bonds) and HOSE code.
  • Hovering a row highlights its atoms in the structure.
• Assignment check below. Each assigned signal is marked matches / check / does not match. It also flags assignments that may be swapped, equivalence problems, missing signals and a possible referencing offset. The shift comparison and the assignment check are built from the same author assignments, so they always agree.
• Print / save as PDF: an A4 report with the verdict, scores, key findings, structure and properties, per-nucleus tables, the assignment check and a methods section. The file is named <file-name-slug>-quickcheck-nmrxiv-<YYYY-MM-DD_HH-mm>.pdf.
• Confirmation: "I confirm these assignments are correct" requires a note (for example HMBC, NOE or X-ray evidence) when the check is inconsistent.

Inputs

Source	Where
NMRium workspace of the sample (ranges linked to atoms)	submission flow
Mnova SDF export with CHEMICAL_SHIFTS tags	submission flow, public page
NMReDATA (NMREDATA_ASSIGNMENT, NMREDATA_1D_*)	submission flow, public page
Drawn structure plus rows of nucleus, atom numbers and δ	public page

The check runs per sample (study), not per dataset. It needs the ¹³C and ¹H of one compound, which live in separate datasets, and the assignment UI and NMRium already work per sample.

Changes

• Data model: assignment_validations table, AssignmentValidation model, factory, and AssignmentValidationStatus / AssignmentSource enums; Study::assignmentValidations() and the latest / latest-completed relations.
• Readers and client: App\Support\Nmr\Assignments has AssignmentSet, the NMRium, Mnova SDF and NMReDATA readers, a resolver and the NMRKit client.
• ValidateStudyAssignments job:
  • It retries with backoff when the prediction is unavailable; rejected input fails immediately.
  • Users see a fixed, engine-neutral message when the prediction is unavailable. NMRKit's messages for rejected input are still passed through.
• Stale checks: a check becomes stale when the sample's NMRium assignments change (hash of the input). Stale checks can't be confirmed.
• Routes:
  • GET|POST dashboard/studies/{study}/assignment-validation and POST …/{validation}/confirm (editors only)
  • GET api/v1/samples/{study}/assignment-validation (public samples only)
  • POST api/v1/quickcheck (synchronous, nothing stored; limited to 6 per minute and 200 per day per IP)
  • GET /quickcheck (public page)
• UI:
  • QuickcheckReport plus the helpers Utils/quickcheck.js (labelled CXSMILES depiction and highlighting), Utils/quickcheckTerms.js (shared chemist-facing terms) and Utils/quickcheckReportDocument.js (the PDF).
  • SampleQuickcheckPanel in the upload Assignments step (polls while queued), QuickcheckBadge on the public sample page, and Pages/Quickcheck.vue with "Check other assignments" and "Print / save as PDF" side by side.
  • The landing page links to Predict and Quickcheck with two tool cards.
• Config: nmrxiv.assignment_validation.*. The URL defaults to NMRKIT_URL + /latest/validate/assignments; override it with ASSIGNMENT_VALIDATION_URL.

Notes

• The score approximates the nmrshiftdb2 quality mark from the same penalties (flagged as mark_is_approximate in the API).
• The Predict page keeps its "Powered by NMRShiftDB" credit until the nmrXiv prediction engine replaces it.
• Not in this PR: parsing ACS-style assignment strings (they carry no atom indices) and clicking atoms to assign in the upload flow.

Tests

php artisan test tests/Unit/Support/Nmr/Assignments tests/Feature/Study/StudyAssignmentValidationTest.php tests/Feature/API/AssignmentQuickcheckApiTest.php: 26 passed. npm run build and ESLint pass.

Deploy

• php artisan migrate
• NMRKit with feat: assignment validation against nmrshiftdb2 quickcheck nmrkit#147 deployed (including the fix that builds the per-atom report from the author's assignments). Quickchecks stored before that fix keep their old report until they are run again.

[codecov]

Codecov Report

❌ Patch coverage is 90.84746% with 54 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.34%. Comparing base (310d378) to head (c0b0a4c).

Files with missing lines	Patch %	Lines
...pport/Nmr/Assignments/NmredataAssignmentReader.php	78.78%	14 Missing ⚠️
app/Jobs/ValidateStudyAssignments.php	67.85%	9 Missing ⚠️
...port/Nmr/Assignments/NmrkitAssignmentValidator.php	65.21%	8 Missing ⚠️
...pport/Nmr/Assignments/MnovaSdfAssignmentReader.php	85.10%	7 Missing ⚠️
...Controllers/API/AssignmentValidationController.php	84.61%	4 Missing ⚠️
app/Models/AssignmentValidation.php	95.23%	4 Missing ⚠️
...ontrollers/StudyAssignmentValidationController.php	93.18%	3 Missing ⚠️
...Support/Nmr/Assignments/NmriumAssignmentReader.php	97.14%	2 Missing ⚠️
app/Support/Nmr/Assignments/SdfRecord.php	96.15%	2 Missing ⚠️
.../Support/Nmr/Assignments/AssignmentSetResolver.php	97.72%	1 Missing ⚠️

Additional details and impacted files

@@                Coverage Diff                @@
##             development    #1579      +/-   ##
=================================================
+ Coverage          81.03%   81.34%   +0.30%     
- Complexity          4916     5141     +225     
=================================================
  Files                315      331      +16     
  Lines              17985    18575     +590     
=================================================
+ Hits               14575    15110     +535     
- Misses              3410     3465      +55     

Flag	Coverage Δ
unittests	81.34% <90.84%> (+0.30%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.