Let the protease say where a glycan must be, and make the localizer honour it

[trishorts]

Draft, parked on the fork. This was smith-chem-wisc#2834, moved here while it is a draft to keep the upstream PR list uncluttered. Its earlier review threads and their answers stay on the upstream PR: smith-chem-wisc#2834. It goes back upstream as a live PR when it is ready.

Base: master -- needs an mzLib release carrying smith-chem-wisc/mzLib#1317's CleavageRequirement before it can build.

Project of origin: cleavageRules

DRAFT, and blocked on a release only. This needs DigestionProduct.GetCleavageObligatedSites, which is in mzLib smith-chem-wisc#1317 (commit cbb749c0). MetaMorpheus consumes mzLib as a package (currently 1.0.591), so CI will be red until smith-chem-wisc#1317 and its parents merge and mzLib ships a release. The code itself is verified: built and fully tested locally against mzLib packed from smith-chem-wisc#1317 (see Verification below).

The gap

A glyco search identifies the peptide backbone naked, then makes up the precursor-mass difference with combinations of glycans and tries arrangements, scoring each by matched fragment ions.

Amino-acid motif is the only thing that says where a glycan may go. I checked every constraint in the glyco tree: motif (ModificationLocalization.ModFits), a skip for residues that already carry a modification, a per-box motif count, and the spectral score — which ranks arrangements but never forbids one. There is no occupancy prior, no known-glycosite handling, and nothing from the enzyme. KnownSite, Obligated, SiteConstraint match nothing in the repo, and no open PR or issue attempts it.

But when the enzyme is a glycoprotease, it has already proved part of what the spectrum is being asked to guess. If OpeRATOR cut this peptide out, its first residue carried a glycan. That is not a hypothesis to be scored — it is a consequence of the peptide existing.

What lands

LocalizationGraph gains obligated sites and enforces them inside the dynamic program, not afterwards.

The DAG's child boxes hold the modifications placed at or before each site, so "this site is occupied" is exactly "the incoming edge increases the modification count" — an edge predicate, needing no new data structure. It is applied on the cached and uncached paths, and at the first column, which has no incoming edge.

GraphCheck learns it too: a box with fewer glycans than the peptide has obligated sites cannot fill them, and without screening it the terminal node becomes unreachable and FinishGraph throws — precisely the case its own comment says never happens in a search.

Two things deliberately not done

Not by pruning the candidate-site list. That expresses the wrong thing — deleting a site says "j is not a candidate", not "k is occupied" — and it breaks GraphCheck's modPos.Count >= NumberOfMods feasibility test, wrongly rejecting multi-glycan boxes.

Not by pre-placing a modification. This is the trap. GetPossibleModSites skips any residue that already carries a modification, so pre-placing one makes the obligated site vanish from the graph — the exact inverse of the intent.

Relatedly, an obligation that is not among the candidate sites is ignored, not treated as unsatisfiable: a site can be missing for reasons unrelated to the protease, and refusing the peptide there would delete a correct answer. Under-constraining forgoes a refinement; over-constraining forbids the truth.

Cost, and what it buys

HasObligatedSites short-circuits both loops, and it is false for every ordinary protease, so a non-glyco or non-glycoprotease run pays nothing.

When it does apply the constraint strictly shrinks the route set — including in GetAllPaths_CalP, the exponential step. And because the localization level (1 / 1b / 2 / 3) is a function of how many routes survive, and the probabilities are re-summed over the same reduced set, constraining the routes is precisely what turns a Level 3 into a Level 2 or 1, with the probabilities staying correct.

Blast radius

One production construction site (GlycoSearchEngine.cs:735). The four-argument LocalizationGraph constructor is kept, so the five existing test call sites are untouched.

Verification

Run against mzLib packed locally from smith-chem-wisc#1317 (9.9.1191) and restored into this branch, which is what CI will do once smith-chem-wisc#1317 ships.

MetaMorpheus solution	compiles clean against the new mzLib
OGlycoTest_ObligatedSiteConstrainsTheRoutes	passes
OGlycoTest_AnObligationNotAmongTheCandidateSitesIsIgnored	passes
Full glyco suite	133 passed, 0 failed
Localization / Search / Index / ModSearch	485 passed, 0 failed

The first test carries a vacuity guard — it asserts that the unconstrained graph admits a route leaving the obligated site empty — so its pass proves the constraint actually eliminated routes rather than finding nothing to do. Assertions are relational (fewer routes; every survivor occupies the obligated site) rather than exact route counts, so they do not re-encode the glycan database.

All five pre-existing LocalizationGraph call sites are in that 133 and unchanged.

Counterpart

mzLib smith-chem-wisc#1317 adds DigestionProduct.GetCleavageObligatedSites, the derivation this consumes. It is derived rather than stored on purpose: the peptide index is cached with a field-based, schema-rigid serializer whose reuse check carries no assembly version, so a new serialized field would silently corrupt indices users already have.

🤖 Generated with Claude Code