mptool 1.0.2__tar.gz → 1.2.0__tar.gz

{mptool-1.0.2 → mptool-1.2.0}/CHANGELOG.md

@@ -3,6 +3,300 @@
 All notable changes to this project will be documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+## [1.2.0] — 2026-11-03
+
+A minor release: `sample_mps` reports how many draws returned each MP and
+takes a draw budget, sampling with single-reaction deletion is faster, and
+preprocessing scales to large models. Two fixes can change results.
+`fastercc` no longer reports some functional reactions as blocked, so
+preprocessing keeps reactions that 1.1.0 removed, and runs on iML1515,
+iCHOv1 or Recon3D under the affected bounds can find MPs that 1.1.0 could
+not. With a `requirements` callback that returns zero-flux IDs, a reaction
+the main LP needs is no longer deleted.
+
+### Added
+
+- `sample_mps(return_counts=True)` returns `(mps, acceptance, counts)`,
+  where `counts[i]` is the number of completed draws that returned
+  `mps[i]`, so `sum(counts)` is the denominator of `acceptance`. With
+  `return_mapping=True` as well, the mapping stays last. The default return
+  is unchanged. Export bundles from `sample_mps` also write `counts.csv`,
+  one `count,reaction_id,...` line per MP in `mps.txt`'s order.
+- `sample_mps(max_draws=N)` and `--max-draws N` stop a run after N completed
+  draws, duplicates included. A run stops at whichever of `n_samples`,
+  `max_draws` and `max_t` comes first, and `n_samples=0` is allowed with
+  `max_draws` alone. A seeded run stopped by `max_draws` is reproducible,
+  unlike one stopped by `max_t`. This gives runs where `n_samples` exceeds
+  the drawable MPs a stop other than `max_t` (#7). The docstring states
+  how many draws find every MP or reaction above a given draw frequency.
+
+### Changed
+
+- `sample_mps` with single-reaction deletion (`chunks=None`) is faster:
+  each deletion LP now weights the candidates' fluxes by their rank in the
+  draw's ordering instead of summing them, so more reactions are deleted
+  without a solve. On the 12 benchmark model and subset pairs a draw took
+  0.45–0.93 of its former time. A draw returns the same MP as before, so
+  seeded runs sample the same MPs.
+- `make_forward_irreversible` on a Gurobi model, and so `preprocess_model`,
+  `enumerate_mps` and `sample_mps`, takes time linear in the model's size
+  instead of quadratic: it reads each reversed reaction's own column instead
+  of scanning every constraint for it. On a 77 643-reaction model it took
+  under 2 s instead of 1 011 s. The model it builds is unchanged.
+
+### Fixed
+
+- `fastercc` could report functional reactions as blocked, and so
+  `preprocess_model`, `enumerate_mps`, `sample_mps` and `fva` treated them
+  as blocked: preprocessing removed them, and FVA gave them bounds (0, 0).
+  Its second stage maximized and minimized the plain sum of the remaining
+  candidates' fluxes, which is 0 in every solution for reactions whose
+  fluxes cancel, such as an exchange and the transport reaction that is its
+  only partner (v1 = −v2). It also stopped trying a direction once that
+  direction had found nothing, even after the other direction shrank the
+  candidate set. It now uses random positive weights from a fixed seed, and
+  stops only when both directions find nothing for the same candidates.
+  `fastercc` now matches a max/min LP test of every reaction on all six
+  benchmark models. 1.1.0's `preprocess_model` removed 2 functional
+  reactions from iML1515 under the benchmark bounds, 4–6 from iCHOv1 and
+  10–12 from Recon3D, so MPs through them could not be found. `fastercc`
+  takes 0.7–1.2 of its former time.
+- With a `requirements` callback, `enumerate_mps` and `sample_mps` deleted a
+  reaction without a solve whenever the callback listed it as zero-flux. The
+  callback gets an unsolved copy and may check other conditions than the
+  main LP, such as growth on another medium, so a reaction the main LP needs
+  could be deleted and the returned set was then not a pathway. A reaction is
+  now skipped only if it is in the callback's set *and* carries no flux in
+  mptool's own LP solution. Callbacks that return no zero-flux IDs, or that
+  re-solved the main problem to honour the old contract, sample the same
+  MPs; enumeration with such a callback may find them in another order.
+
+## [1.1.0] — 2026-10-06
+
+A minor release: a new rule for `adaptive=True`, compressed sampling that
+draws MPs with the same distribution as uncompressed, and the fixes from a
+pre-release review.  Several fixes can change results, and several inputs
+that were silently dropped now warn or raise.  `conv_tol` and `conv_window`
+are deprecated.  See "Seeded runs and `export` bundles from 1.0.x" under
+Changed for what replays differently.
+
+### Added
+
+- `sample_mps` raises a `UserWarning` when no key of `weights` names a reaction
+  in the sampled subset.  Keys that match nothing are still ignored, so one
+  weights table can cover several models, but when none matches every reaction
+  gets weight 0 and the weights silently do nothing.  Typical causes are gene
+  IDs, or preprocessed IDs passed with `preprocess=True`.
+
+### Changed
+
+- `adaptive=True` uses a new rule (#8).  After each new distinct MP, a reaction
+  that occurs in at least one distinct MP found so far keeps its user weight,
+  and every other one gets N times it, N being the number of distinct MPs
+  found.  The old rule gave N/count, which favours rare reactions.  It made
+  the bias of sampled MPs worse on every measured instance with 30 or more
+  MPs, and it stalled the search for reactions not yet seen.  The new rule
+  finds every reaction that occurs in some MP 2–5x faster than uniform
+  orderings at genome scale.  In simulation with user weights, it was never
+  slower than the same weights alone.  Once all such reactions have been seen,
+  it samples as `adaptive=False`.  It does not reduce the bias toward MPs with
+  few reactions of their own.  A reaction with weight 0, or missing from
+  `weights`, is never boosted.
+- With compression, `sample_mps` now draws MPs with the same distribution as
+  without it, with or without `weights`, when it preprocesses the model
+  itself (`preprocess=True`, the default).  Without compression, a chain of
+  fully coupled reactions is removed, or found to be needed, as soon as the
+  first of its members is tried.  A merged cluster used to be ordered as one
+  reaction, and with `weights` it carried the sum of the weights of every
+  reaction merged into it, which held on to it harder the more reactions it
+  merged.  Now each subset member draws its own key from its weight (every
+  member counts as 1 without `weights`), and the cluster is placed at the
+  earliest; reactions merged in from outside the subset do not count.  On
+  e_coli_core the total variation between per-MP frequencies with and without
+  compression fell from 0.19 to 0.02 without weights, and is 0.015 with
+  log-normal weights, against 0.02 between seeds.  Under the old sum, equal
+  weights and no weights differed by 0.24.  A model compressed beforehand
+  and sampled with `preprocess=False` has no mapping, so each merged
+  reaction is still ordered as one reaction.
+- Seeded runs and `export` bundles from 1.0.x that used compression (the
+  default) or `adaptive=True` can give different MPs when rerun with this
+  version.  Runs with neither give the same MPs, except weighted runs whose
+  keys tied (see Fixed) and `method='direct'` runs that returned sets that
+  are not MPs (see Fixed).
+
+- `load_bounds`, `load_weights` and `load_mapping` raise `ValueError`,
+  naming file and line, on a non-blank line that does not parse.  Such
+  lines used to be skipped, so a file separated by `;` or tabs, as Excel
+  writes CSV under most European regional settings, loaded as `{}` without
+  a word.  Blank lines are still skipped.
+- `preprocess_model`, `enumerate_mps` and `sample_mps` name bounds keys
+  that match no reaction of the model in a `UserWarning`.  They are still
+  ignored, so one bounds table can cover several models.
+- `create_lp` raises `ValueError` on a COBRA model with constraints other
+  than metabolite balances, or variables other than reaction fluxes, such
+  as those added with `add_cons_vars`.  It used to drop them, so mptool
+  solved a different model from cobrapy: with `PGI <= 2` added to
+  e_coli_core, FBA gave 0.8739 against cobrapy's 0.8676.  Every model
+  shipped with the tests and benchmarks builds as before.
+
+- The CLI refuses `--no-verbose` without `--export`: such a run printed
+  nothing and wrote nothing.
+- `rerun` raises a `UserWarning` when the bundle was recorded with another
+  mptool version, since seeded results can differ between versions.
+- `enumerate_mps`, `sample_mps` and the CLI reject an infinite `max_t`.  0
+  already means no limit, and `sample_mps` with `n_samples=0` accepted
+  `max_t=inf` as a stop criterion that never fires.
+
+### Deprecated
+
+- `sample_mps`'s `conv_tol` and `conv_window` (and the CLI's `--conv-tol` and
+  `--conv-window`) will be removed in a future major release, and
+  `conv_tol > 0` raises a `FutureWarning`.  The change in reaction frequencies
+  they watch shrinks as 1/N by arithmetic, so the check stops at a roughly
+  fixed number of distinct MPs rather than when the estimates settle.  At
+  `conv_tol=0.1` that was 71–98 distinct MPs on every genome-scale instance
+  measured, whether it had 146 MPs or 655.  The check still works until it is
+  removed.  Passing `conv_window` (or `--conv-window`) without `conv_tol`
+  raises the warning too; it was a silent no-op.  The CLI words the warning
+  in terms of its own flags, and no longer passes `--conv-window`'s default
+  on every run.
+
+### Fixed
+
+- Weighted sampling lost the weights' effect for very small or very large
+  weights, so results depended on the scale of the weights.  Keys were
+  computed as `u ** (1 / w)`, which rounds to 0 for small weights (from about
+  1e-2: 47% of keys at w = 1e-3, 99.9% at 1e-6) and to 1 for weights around
+  1e14 and up.  Tied keys then fell back to column order.  This affected, for
+  example, weights normalized to sum to 1 on a genome-scale model, where
+  about 70% of keys tied at w = 5e-4.  With every weight near
+  1e-6, each draw had the same ordering, and a run could not find a second
+  MP.  Keys are now `log(u) / w`, which orders the same without rounding, so
+  scaling every weight by 1e-6 or 1e6 gives the same seeded MPs.  Seeded
+  runs whose keys did not tie are unchanged.
+
+- With `preprocess=False`, `enumerate_mps` and `sample_mps` failed when the
+  model had a blocked reaction (bounds 0, 0) anywhere before the last subset
+  reaction in column order.  Blocked reactions are removed before the search,
+  which renumbers the columns after them, but the internal sets of subset and
+  essential reactions kept the old numbering: gurobipy hashes a variable by its
+  column index.  The search then usually stopped with `GurobiError:
+  Constraint has no bool value`.  A lookup in such a set can also miss a
+  member without raising, so a wrong result without an error is possible too,
+  though none was observed.  `preprocess=True` runs were not affected, because
+  preprocessing removes blocked reactions before these sets are built.
+
+- `enumerate_mps` and `sample_mps` read a generator `subset` twice, so the
+  search got an empty subset and returned no MPs with `complete=True`.  Any
+  iterable now works, and an empty generator raises like any empty subset.
+- Subset IDs that name no reaction of the model were dropped silently, so a
+  typo, or original IDs passed with `preprocess=False` to a compressed model,
+  shrank the subset without a word: the latter gave 2 MPs instead of 33 on
+  e_coli_core, with `complete=True`.  `enumerate_mps`, `sample_mps`,
+  `preprocess_model`, `validate_mps`, `fastcc`, `fastercc` and
+  `make_forward_irreversible` (on a Gurobi model) now name them in a
+  `UserWarning` and go on with the rest, and raise `ValueError` when none
+  names a reaction.
+- A stop limit left on the caller's Gurobi model (`TimeLimit`,
+  `IterationLimit`, `WorkLimit`, `Cutoff` and the other termination
+  parameters except the memory limits) was copied onto every LP of a run.
+  A feasibility LP that stops early is read as infeasible, so such a limit
+  could turn a feasible model infeasible mid-search and give wrong MPs or
+  MCSs with `complete=True`.  mptool now resets these parameters on its own
+  copies.  `validate_mps`, which solves on the caller's model, applied them
+  too: with `TimeLimit=0` it judged every MP invalid.  It now clears them for
+  its solves and restores every parameter it changes, and the objective
+  constant, which it used to leave at 0.  It also flushes the caller's
+  pending changes before it reads anything, so it no longer reverts them.
+- With `method='direct'`, the per-solve `TimeLimit` stayed on the solved
+  model, so an `export` bundle's `settings.prm` carried it and `rerun`
+  applied it to the replay.
+- Compression could delete a real stoichiometric coefficient.  An entry of a
+  merged reaction is the sum of its members' coefficients, each scaled by
+  the member's coupling ratio, and every entry below `merge_tol` (1e-6) was
+  zeroed as cancellation noise.  An entry that only one member contributes
+  to cancels with nothing, but a small ratio can still push it below 1e-6
+  (a ratio of 1e-3 takes 5e-4 to 5e-7).  Zeroing it decoupled that
+  metabolite from the cluster, and the MPs and MCSs changed.  Only entries
+  with two or more contributing members are thresholded now.  No such
+  entry was found on e_coli_core, iIT341, iMM904, iML1515, iCHOv1 or
+  Recon3D, so their compressed models are unchanged.
+- `enumerate_mps(method='direct')` could return sets that are not MPs and
+  miss real ones, with `complete=True`.  An indicator counted as off up to
+  Gurobi's integrality tolerance (1e-5), which let a reaction with upper
+  bound 1000 carry 0.01 of flux the MP did not list; its no-good cut then
+  excluded real MPs.  On e_coli_core with biomass fixed at 0.01, 20 of the
+  33 returned sets were not MPs.  The MILP now runs at the tightest
+  tolerance (1e-9), and every solution is checked before it is accepted.
+  One that fails is dropped, the run reports `complete=False`, and a
+  `UserWarning` says MPs may be missing.  This still happens when the
+  fluxes an MP needs are small relative to its reactions' upper bounds (on
+  e_coli_core, from biomass 1e-4 down).  The iterative method is exact.
+- The MPs the CLI prints (and `verbose=True` prints from `enumerate_mps`
+  and `sample_mps`) lacked the essential reactions, which are added after
+  the search, so they were not the MPs the run returns.  Without `--export`
+  the printed lines are the only output.  They now include the essentials,
+  and sampling no longer says the essentials were added to "MPs and MCs".
+- With `export=True`, a `requirements` lambda or closure was rejected only
+  when the bundle was written, after the whole search.  It is now rejected
+  before the search starts.
+- `export=True` failed after the whole search when the bounds held numpy
+  scalars such as `float32` or `int64`, and left a truncated
+  `manifest.json` that `rerun` took for a finished bundle.  numpy scalars
+  are now written as numbers, and `manifest.json` is written under a
+  temporary name and moved into place, so a failed write leaves none.
+- An export bundle's `settings.prm` recorded the exporter's Gurobi licence
+  ID, and any Compute Server setting on the caller's model.  Licence and
+  connection parameters (licence ID, user name, WLS, Cloud, Compute Server
+  and token server) are now left out.  Gurobi 12.0.2 already omitted the
+  secrets themselves.
+- `translate_mps` and `translate_mcs` with a `subset` of COBRA reactions or
+  Gurobi variables, such as the README's `model.boundary`, returned empty
+  MPs and no cuts: the subset was compared with reaction IDs as given.  They
+  now accept the same subset forms as `enumerate_mps`.
+- The file readers (`load_set`, `load_sets`, `load_bounds`, `load_weights`,
+  `load_mapping`) kept the byte-order mark that Excel's "CSV UTF-8" puts at
+  the start of a file as part of the first ID, so that reaction silently
+  left the subset, or its bound or weight was not applied.
+
+### Documentation
+
+- The README, `sample_mps`'s docstring and the CLI help no longer claim that
+  adaptive weights reduce length bias, and the README cites [1] for the
+  uniform sampler only; nothing on weighted or adaptive sampling is
+  published.  They now say what a weight means: relative, on any scale, 0 or
+  missing for "remove whenever possible" and never boosted, and the full
+  weight on each direction of a reversible reaction.  An MP is never drawn
+  while another MP's weight-0 reactions are a proper subset of its own, so 0
+  excludes wherever an alternative exists while a small positive weight only
+  disfavours.  They also say that sampled MPs favour MPs with few reactions
+  of their own, and that frequencies over the distinct MPs found approach the
+  true ones as more are found.
+- `sample_mps`'s docstring said duplicates are discarded with a warning; they
+  are discarded silently, and the acceptance rate reports them.
+- The README's back-translation example expanded `mapping[r]` by hand, which
+  drops the `_rev` naming of reversed reactions and keeps out-of-subset
+  reactions merged into clusters; it now uses `translate_mps` and
+  `translate_mcs` with the enumerated subset.  It and the enumeration
+  example no longer pass `compress=True, tighten=True` as if they were
+  opt-in; both are defaults.
+- `n_samples` counts distinct MPs, and a run without `max_t` never ends if
+  fewer can be drawn (for example when weights of 0 make some undrawable).
+  The docstring, the README and the CLI help now say so.
+- Docstrings and messages that misstated the code:
+  - With `preprocess=False`, only subset reactions must have `lb >= 0`,
+    not every reaction of the model.
+  - The warning for a run cut short before its first MP no longer
+    suggests raising `max_mps`, which cannot help and which `sample_mps`
+    does not have.
+  - `--seed` gives identical results only without `--max-t`.
+  - `preprocess_model` is idempotent in its subset and mapping. With
+    `compress=True`, a second pass tightens the merged reactions' bounds,
+    without changing the feasible set.
+  - A compressed model's merged reactions keep structural bounds.
+
 ## [1.0.2] — 2026-09-29
 
 A bug-fix release.  No API change.  Both fixes can change results: iterative

{mptool-1.0.2 → mptool-1.2.0}/CITATION.cff

@@ -3,8 +3,8 @@ message: "If you use this software, please cite both the software and the paper
 title: mptool
 abstract: Enumeration and sampling of minimal pathways in metabolic (sub)networks.
 type: software
-version: 1.0.2
-date-released: 2026-09-29
+version: 1.2.0
+date-released: 2026-11-03
 license: MIT
 repository-code: "https://gitlab.com/csb.ethz/mptool"
 url: "https://gitlab.com/csb.ethz/mptool"

{mptool-1.0.2 → mptool-1.2.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ETH Zurich, Ove Øyås
+Copyright (c) 2019-2026 Ove Øyås, ETH Zurich
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{mptool-1.0.2 → mptool-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mptool
-Version: 1.0.2
+Version: 1.2.0
 Summary: Enumeration and sampling of minimal pathways in metabolic (sub)networks.
 Home-page: https://gitlab.com/csb.ethz/mptool
 Author: Ove Øyås
@@ -24,7 +24,7 @@ Requires-Dist: networkx>=2.4
 Requires-Dist: numpy>=1.21.0
 Requires-Dist: scipy>=1.7.3
 Provides-Extra: test
-Requires-Dist: pytest>=4.6.9; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: furo; extra == "docs"
@@ -45,7 +45,7 @@ This repository contains a Python package with implementations of methods for me
 
 Minimal pathways (MPs) are minimal sets of reactions that need to be active (have non-zero flux) in a metabolic (sub)network to satisfy all constraints on the network as a whole [1]. They can also be defined as the set of *support-minimal* flux patterns from elementary flux vectors (EFVs) [2].
 
-An MP can be found by direct minimization of a mixed-integer linear program (MILP) or by iterative minimization of multiple linear programs (LPs). Both approaches are implemented for enumeration (`enumerate_mps`): the iterative method (default) additionally enumerates minimal cut sets (MCSs), using either a binary integer program (`mcs_method='bip'`, default) [3] or a Berge minimal-hitting-set enumerator (`mcs_method='berge'`). Iterative enumeration can be accelerated by a graph defined by the known MPs to predict unknown MPs (`graph=True`) and by deleting reactions in multiple-reaction chunks rather than one at a time (`chunks`). Random sampling of MPs (`sample_mps`), for when complete enumeration is infeasible, is always iterative; by default it draws uniform random orderings and deletes a single reaction at a time (`weights=None`, `chunks=None`), and can optionally bias the ordering with per-reaction weights, delete in chunks, and update the weights adaptively to reduce length bias [1]. Sampling returns the sampled MPs together with an acceptance rate (the fraction of completed draws — those producing a valid MP — that yield a previously-unseen MP).
+An MP can be found by direct minimization of a mixed-integer linear program (MILP) or by iterative minimization of multiple linear programs (LPs). Both approaches are implemented for enumeration (`enumerate_mps`): the iterative method (default) additionally enumerates minimal cut sets (MCSs), using either a binary integer program (`mcs_method='bip'`, default) [3] or a Berge minimal-hitting-set enumerator (`mcs_method='berge'`). Iterative enumeration can be accelerated by a graph defined by the known MPs to predict unknown MPs (`graph=True`) and by deleting reactions in multiple-reaction chunks rather than one at a time (`chunks`). Random sampling of MPs (`sample_mps`), for when complete enumeration is infeasible, is always iterative: by default it draws uniform random orderings and deletes a single reaction at a time (`weights=None`, `chunks=None`) [1]. It can optionally bias the ordering with per-reaction weights, delete in chunks, and favour reactions not yet seen in a sampled MP (`adaptive=True`). Sampled MPs favour MPs with few reactions of their own; see [Sampling](#sampling). Sampling returns the sampled MPs together with an acceptance rate (the fraction of completed draws — those producing a valid MP — that yield a previously-unseen MP).
 
 ## Requirements
 
@@ -87,11 +87,13 @@ for the full option lists.
 
 ### Back-translating compressed CLI output
 
-The reaction IDs the CLI prints are in mptool's *preprocessed* namespace, not
-your input model's. With compression on (the default) these include fused
-flux-coupled clusters (`A+B`); reversible candidate reactions are also split
-into a forward half and a reverse half (`X_rev`), regardless of compression.
-Bare stdout output is always in this preprocessed namespace.
+The CLI prints each MP as it is found, essential reactions included, so the
+printed MPs are the ones the run returns. Without `--export` they are the only
+output, which is why `--no-verbose` requires `--export`. Their reaction IDs are
+in mptool's *preprocessed* namespace, not your input model's. With compression
+on (the default) these include fused flux-coupled clusters (`A+B`); reversible
+candidate reactions are also split into a forward half and a reverse half
+(`X_rev`), regardless of compression.
 
 To map these IDs back to your original model, pass `--export`: the run bundle
 then contains `mapping.csv` — a headerless `new_id,orig_id,coef` table —
@@ -134,23 +136,29 @@ mps, mcs, complete = mpt.enumerate_mps(model, subset=subset,
                                        mcs_method='berge')
 
 # Direct MILP minimization: finds one MP per solve; no MCSs returned.
+# Can miss MPs when the fluxes an MP needs are small relative to its
+# reactions' upper bounds; it then warns and returns complete=False.
+# The iterative method is exact.
 mps, mcs, complete = mpt.enumerate_mps(model, subset=subset,
                                        method='direct', graph=False)
 
-# Lossless FVA-based compression applied before enumeration.  Returned
-# MPs use compressed reaction IDs; back-translate via the mapping.
-mps, mcs, complete, mapping = mpt.enumerate_mps(
-    model, subset=subset,
-    preprocess_kwargs={'compress': True, 'tighten': True},
-    return_mapping=True,
-)
+# Lossless FVA-based compression is on by default, so the MPs above use
+# compressed reaction IDs (see Back-translation below).  Without it:
+mps, mcs, complete = mpt.enumerate_mps(
+    model, subset=subset, preprocess_kwargs={'compress': False})
 ```
 
 ### Sampling
 
 When complete enumeration is infeasible, random sampling is more practical.
-`sample_mps` runs until either `n_samples` MPs have been collected or `max_t`
-seconds have elapsed (at least one is required). `max_t` budgets the sampling
+`sample_mps` runs until `n_samples` distinct MPs have been collected,
+`max_draws` draws have completed, or `max_t` seconds have elapsed, whichever
+comes first (at least one is required). Duplicates do not count toward
+`n_samples`, so if the model has fewer distinct MPs than that — or fewer that
+can be drawn: a reaction with weight 0 can make MPs undrawable — a run with
+neither `max_t` nor `max_draws` never ends. Set one of them unless you know
+there are enough; a seeded run stopped by `max_draws` is reproducible, one
+stopped by `max_t` is not. Interrupting a run loses the MPs found so far. `max_t` budgets the sampling
 loop only — preprocessing runs before the clock starts, so total runtime is
 preprocessing plus `max_t`. The same holds for `max_t` in `enumerate_mps`. It
 returns a 2-tuple
@@ -158,7 +166,9 @@ returns a 2-tuple
 frequencies and convergence statistics can be recomputed directly from it)
 and `acceptance` is the acceptance rate — the fraction of completed draws
 that yielded a new MP rather than a duplicate (a low rate signals the MP
-space is nearly exhausted; prefer `enumerate_mps` then). The full model is
+space is nearly exhausted; prefer `enumerate_mps` then). With
+`return_counts=True` it returns `(mps, acceptance, counts)`, where
+`counts[i]` is the number of draws that returned `mps[i]`. The full model is
 used here (no `subset` argument).
 
 ```python
@@ -176,30 +186,76 @@ mps, acceptance = mpt.sample_mps(model, n_samples=100, chunks=4)
 weights = {r.id: random.random() for r in model.reactions}
 mps, acceptance = mpt.sample_mps(model, n_samples=100, weights=weights)
 
-# Adaptive sampler: weights are updated after each sample to reduce
-# length bias and improve coverage of the MP space.
+# Adaptive sampler: reactions not yet seen in a sampled MP are kept longer,
+# so every reaction that occurs in some MP is found sooner.
 mps, acceptance = mpt.sample_mps(model, n_samples=0, adaptive=True, max_t=60)
-```
 
-### Back-translation when `compress=True`
+# A fixed number of draws, with how many of them returned each MP.
+mps, acceptance, counts = mpt.sample_mps(model, n_samples=0, max_draws=1000,
+                                         return_counts=True)
+```
 
-With `compress=True` the returned MPs use compressed reaction IDs (e.g.
-`'ACONTa+ACONTb'` for a flux-coupled cluster, or `'X_rev'` for the reverse
-half of a reversible reaction). `return_mapping=True` appends the
-preprocessed→original mapping to the return tuple. Each merged reaction maps
-to a `{original_id: coefficient}` dict; signs encode direction.
+Sampled MPs are not a uniform sample of the MP space. A draw is the MP that
+avoids the earliest reactions it can along the ordering, so MPs with few
+reactions of their own are drawn more often, and so, for example, are MPs
+that share few reactions with others. Frequencies counted per draw are
+therefore biased. `mps` holds each distinct MP once, and frequencies over the
+distinct MPs found approach the true ones as more of them are found. Neither
+weights nor `adaptive=True` removes this bias.
+
+**Weights** are relative: reaction `r` is kept longer than `s` with odds
+`w_r : w_s`, so any scale works (raw scores such as BLAST bit scores
+included) and multiplying every weight by the same factor changes nothing. A
+reaction with weight 0, or missing from `weights`, is tried before every
+positive-weight reaction and removed whenever possible; list a reaction to
+give it a say. An MP is never drawn while another MP's weight-0 reactions
+are a proper subset of its own, and every other MP can be drawn, so 0
+excludes wherever an alternative exists while a small positive weight only
+disfavours. Each direction of a reversible reaction carries the full weight.
+Keys that name no reaction in the subset are ignored, but a `UserWarning` is
+raised when none of them does.
+
+With `preprocess=True` (the default), compression does not change the
+distribution of sampled MPs, though a given seed gives different MPs with and
+without it. Without compression, a chain of fully coupled reactions is
+removed, or found to be needed, as soon as the first of them is tried. With
+it, each subset member of a merged cluster draws its own key from its weight
+(every member counts as 1 without `weights`), and the cluster is placed at
+the earliest. This needs the mapping that preprocessing returns, so a model
+compressed beforehand and sampled with `preprocess=False` orders each merged
+reaction as one reaction, and its sampled MPs are distributed differently.
+
+**`adaptive=True`** multiplies the weight of every reaction that is in none
+of the distinct MPs found so far by N, the number found, and leaves the
+others at their weight (1 without `weights`; for a merged cluster, every
+member's weight). The boost starts with the second distinct MP, and a weight
+of 0 stays 0. Once every reaction that occurs in some MP has been seen,
+sampling continues as without `adaptive`. `conv_tol` and `conv_window` are
+deprecated: their check stops at a roughly fixed number of distinct MPs
+rather than when estimates settle.
+
+### Back-translation
+
+The returned MPs and MCSs use preprocessed reaction IDs: with compression
+(the default) a flux-coupled cluster is one reaction such as
+`'ACONTa+ACONTb'`, and with or without it the reverse half of a reversible
+reaction is `'X_rev'`. `return_mapping=True` appends the
+preprocessed→original mapping to the return tuple. Each preprocessed reaction
+maps to a `{original_id: coefficient}` dict; signs encode direction.
 
 ```python
 mps, mcs, complete, mapping = mpt.enumerate_mps(
-    model, subset=subset,
-    preprocess_kwargs={'compress': True, 'tighten': True},
-    return_mapping=True,
-)
+    model, subset=subset, return_mapping=True)
 
-# Expand a single MP back to original reaction IDs (union over members):
-original_ids = {orig for r in next(iter(mps)) for orig in mapping[r]}
+orig_mps = mpt.translate_mps(mps, mapping, subset=subset)
+orig_mcs = mpt.translate_mcs(mcs, mapping, subset=subset)
 ```
 
+Pass the same `subset` you enumerated over. The translation then names
+reversed reactions as `X_rev`, as in the preprocessed MPs, and leaves out
+reactions outside the subset that compression merged into a cluster with
+subset reactions. Expanding `mapping[r]` by hand does neither.
+
 ## Preprocessing
 
 `enumerate_mps` and `sample_mps` preprocess the model internally — copying it,
@@ -221,7 +277,11 @@ mps, mcs, complete = mpt.enumerate_mps(
 
 This is useful when the same model is reused across multiple
 enumeration / sampling calls — preprocessing is the expensive step and
-running it once amortises its cost.
+running it once amortises its cost. For sampling, note that `sample_mps` with
+`preprocess=False` has no mapping, so on a compressed model it orders each
+merged reaction as one reaction, and the sampled MPs are not distributed as
+without compression (see [Sampling](#sampling)). Pass `compress=False` to
+`preprocess_model` if that matters.
 
 ## Writing requirements functions
 
@@ -239,9 +299,11 @@ the callback runs, so a callback that inspects solution values must call
 `model.optimize()` itself. It returns a 2-tuple `(feasible, zero_flux_ids)`:
 
 - `feasible` (`bool`): True if the active reactions satisfy the criterion.
-- `zero_flux_ids` (`set[str]`): Reaction ID strings known to carry zero flux
-  under the current state; these can be pruned without re-solving the LP.
-  Return an empty set if no such information is available.
+- `zero_flux_ids` (`set[str]`): IDs of the reactions that carry no flux in
+  the callback's own checks. mptool deletes a reaction without a solve only
+  if it is in this set *and* carries no flux in mptool's own LP solution, so
+  the callback does not need to re-solve the main problem. Return an empty
+  set if no such information is available.
 
 ### The preprocessed namespace