Add assignCompartments: functionality-constrained compartment-assignment MILP

[edkerk]

assignCompartments — functionality-constrained compartment assignment (MATLAB)

Phase 4 of the assignCompartments work: a MATLAB port of the core assignment MILP, bringing the deterministic, functionality-guaranteeing alternative to predictLocalization into RAVEN.

What it does

A single MILP (built as a COBRA prob and solved via optimizeProb, like gapFillMILP) places the requested reactions into the compartments named in a GSS (gene scoring structure, as from parseScores) while requiring the model's objective to stay producible:

max  Σ score[g,c]·y[g,c] − multiPenalty·Σy − transportCost·Σt
s.t. mass balance over the compartment-expanded network,
     |v[r,c]| ≤ ub·x[r,c]      (Big-M flux gating),
     v_biomass ≥ minGrowth      ← the decisive constraint

Because functionality is a hard constraint, a reaction is placed against its own top score when the network needs it there — pathway coherence is emergent, not heuristic. Mono-localization; passive transports (default ↔ c) are added where needed. The model is merged to a single compartment first (like predictLocalization), then re-distributed.

optimizeProb already sets intTol = 1e-9, so the Big-M flux gating does not leak ghost flux (the bug that bit the standalone Python tool, which used cobra/optlang's loose default).

Validation — tAssignCompartments (3 tests, pass in MATLAB)

• functionality overrides the score — a confined metabolite keeps a reaction in cytosol against its higher m-score;
• score respected — with transports allowed, the reaction follows its score and the model stays functional;
• infeasible growth floor reported (exitFlag = -1).

Scope

Core mono-localization assignment with transports. Gap-fill coupling (a universal candidate set) is deferred to a follow-up. Returns the compartmentalised model, the per-reaction placement, and the added transports.

[github-actions]

Function test results

239 tests   210 ✅  59s ⏱️
 24 suites   29 💤
  1 files      0 ❌

Results for commit b02f80f.