Add preflight guardrails for descriptor/graph/CG workflows

[roshan2004]

What

Featurisation paths run happily on imperfect input and quietly return degraded results — a structure with no explicit bonds gets a graph whose edges were guessed from distances, one with no residue numbers loses every residue-level feature, and a huge structure asked for an atom-level dense matrix tries to allocate gigabytes.

Preflight reads the cheap signals MolScope already computes (quality_report, and with deep=True prepare_structure) and turns the ones that matter into explicit, workflow-scoped warnings before the expensive step runs. It changes no results.

What it flags

• inferred bonds — connectivity guessed from covalent radii, not read from the file (graph edges, CG bonds)
• missing metadata — no residue numbers / atom names / chains → residue-level features unavailable
• no hydrogens, alternate locations / partial occupancy, bad/blank element symbols, multiple models
• large dense matrices — atom counts where atom-level distance work allocates ~N² floats (reports the estimate)
• with deep=True (proteins): chain breaks, missing backbone, residue gaps, truncated side chains, non-standard residues, plus a net-charge note

Opt-in everywhere (default off, no behaviour change)

ms.preflight(source, workflow="graph", deep=True)   # -> PreflightReport
mol.preflight(workflow="descriptors")
mol.to_graph(preflight=True)        # same graph, warnings emitted first
mol.descriptors(preflight=True)     # values unchanged
mol.coarse_grain(preflight=True)

molscope preflight 3ptb.pdb                      # all warnings + topology checks
molscope preflight 1ubq.pdb --workflow graph     # only what affects to_graph()
molscope export "data/*.pdb" --to pyg -o g/ --preflight   # warn per structure

--preflight is also on analyze and coarse-grain. PreflightReport has .ok, .codes(), .messages(), .summary(), .to_dict(), .emit().

Tests & docs

• tests/test_preflight.py — 21 tests (each warning code, workflow scoping, deep topology, method integration via pytest.warns, all CLI surfaces). preflight.py patch coverage 91%.
• Full suite: 915 passed, 21 skipped (no regressions); ruff check clean.
• Docs: README command/capability tables + workflow section, a "Preflight guardrails" section in the structure-QC guide, API reference, CHANGELOG.

(Recreated from #117, which GitHub auto-closed when its stacked base branch was deleted on merge of #116; rebased onto current main as a single clean commit.)

[read-the-docs-community]

Documentation build overview

📚 molscope | 🛠️ Build #33069753 | 📁 Comparing 1e6d87a against latest (0e6c15f)

  🔍 Preview build  

2 files changed

± api-reference/index.html
± user-guide/structure-qc/index.html

[codecov]

Codecov Report

❌ Patch coverage is 88.41463% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
molscope/preflight.py	87.38%	8 Missing and 6 partials ⚠️
molscope/cli.py	88.09%	3 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!