mptool 1.0.0__py3-none-any.whl

mptool/__init__.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# (c) 2019-2026 ETH Zurich, Ove Øyås
+# Licensed under the MIT License. See LICENSE file for details.
+"""
+mptool — enumeration and sampling of minimal pathways in metabolic (sub)networks.
+
+Public functions::
+
+    enumerate_mps         Exhaustively enumerate minimal pathways (MPs) and
+                          minimal cut sets (MCSs) in a reaction subset using
+                          direct or iterative methods.
+    sample_mps            Stochastically sample minimal pathways from the MP
+                          space of a reaction subset (always iterative;
+                          supports weighted and adaptive sampling).  Returns
+                          (mps, acceptance), the unique/total acceptance rate.
+    preprocess_model      Preprocess a model and subset for MP search:
+                          fastercc removal, optional FVA tightening or
+                          compression, MFI, and a preprocessed-to-original
+                          reaction-ID mapping.
+    rerun                 Reconstruct and re-invoke a recorded find-MP run
+                          from an exported run bundle (see the ``export``
+                          option); pure record-and-replay, so the replayed
+                          call behaves identically to the original.
+    validate_mps          Validate that each MP is feasible and support-
+                          minimal against a prepared model (returns one
+                          bool per MP).
+    validate_solutions    Validate that every passed flux vector is feasible
+                          in a model (bounds + constraints); raises on the
+                          first infeasible solution.
+    translate_mps         Translate enumerated/sampled MPs from the
+                          preprocessed namespace back to the original
+                          (union expansion per member).
+    translate_mcs         Translate enumerated MCSs from the
+                          preprocessed namespace back to the original
+                          (Cartesian product + antichain filter).
+    create_lp             Build a Gurobi LP from a COBRApy model.
+    copy_model            Copy a Gurobi model preserving solver parameters.
+    set_bounds            Apply ``{rxn_id: (lb, ub)}`` bounds to a Gurobi LP
+                          in place (e.g. FVA-tight bounds from ``fva``).
+    load_cobra_model      Load a metabolic model (SBML/JSON/MATLAB).
+    load_cobra_models     Load one or more models from files or a directory.
+    load_set, save_set    Read/write a set of reaction IDs from/to text.
+    load_sets, save_sets  Read/write a collection of sets of IDs from/to CSV.
+    load_bounds,          Read/write per-reaction flux bounds from/to CSV.
+    save_bounds
+    load_mapping,         Read/write a preprocessed-to-original reaction
+    save_mapping          mapping (``{new_id: {orig_id: coef}}``) from/to CSV.
+    load_weights          Read per-reaction sampling weights from a
+                          ``reaction_id,weight`` CSV.
+    make_forward_         Split reversible reactions into forward and reverse
+    irreversible          half-reactions with non-negative bounds; returns
+                          the updated subset and a {new_id: {orig_id: coef}}
+                          map.
+    fva                   Flux variability analysis on a Gurobi LP model.
+    compress              Lossless FVA-based network compression: merge
+                          flux-coupled reactions into single variables.
+    fastcc                Identify flux-consistent reactions (fast version).
+    fastercc              Identify flux-consistent reactions (faster).
+
+To apply FVA-tight bounds without compressing, run :func:`mptool.fva` and pass
+the result to :func:`mptool.set_bounds`.
+
+.. note::
+   The name ``mptool.fva`` is the *function* above, not the ``mptool.fva``
+   submodule it is defined in — this module rebinds the attribute on import.
+   So ``mptool.fva.compress`` does not resolve; use :func:`mptool.compress`,
+   or ``from mptool.fva import compress`` to reach it through the submodule.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from .io import (load_cobra_model, load_cobra_models,
+                 load_set, save_set, load_sets, save_sets,
+                 load_bounds, save_bounds, load_mapping, save_mapping,
+                 load_weights)
+from .mapping import translate_mcs, translate_mps
+from .model import create_lp, copy_model, make_forward_irreversible, set_bounds
+from .fva import compress, fva
+from .consistency import fastcc, fastercc
+from .preprocess import preprocess_model
+from .mps import enumerate_mps, sample_mps
+from .reproduce import rerun
+from .validate import validate_mps, validate_solutions
+
+# Single source of truth is ``version`` in setup.cfg, read here from the
+# installed distribution metadata.
+try:
+    __version__ = _pkg_version('mptool')
+except PackageNotFoundError:  # pragma: no cover - package always installed
+    __version__ = 'unknown'  # source tree that was never installed
+
+__all__ = [
+    'enumerate_mps', 'sample_mps', 'preprocess_model',
+    'rerun',
+    'create_lp', 'copy_model', 'set_bounds',
+    'load_cobra_model', 'load_cobra_models',
+    'load_set', 'save_set', 'load_sets', 'save_sets',
+    'load_bounds', 'save_bounds',
+    'load_mapping', 'save_mapping',
+    'load_weights',
+    'make_forward_irreversible', 'fva', 'compress',
+    'fastcc', 'fastercc',
+    'validate_mps', 'validate_solutions',
+    'translate_mps', 'translate_mcs',
+    '__version__',
+]

mptool/__main__.py

@@ -0,0 +1,430 @@
+"""Command-line interface for ``python -m mptool``.
+
+Exposes two subcommands:
+
+* ``python -m mptool enumerate <model> [options]`` —
+  :func:`mptool.enumerate_mps` (exhaustive enumeration of MPs and MCSs).
+* ``python -m mptool sample <model> [options]`` —
+  :func:`mptool.sample_mps` (stochastic sampling of MPs).
+
+Options common to both live on a shared parent parser so they cannot drift.
+The Python-only parameters ``requirements`` (a callback) and ``preprocess`` /
+``return_mapping`` are deliberately not exposed; with compression active the
+preprocessed→original reaction mapping reaches CLI users as ``mapping.csv`` in
+the ``--export`` bundle.
+"""
+
+import argparse
+import os
+import sys
+from importlib.metadata import version as _pkg_version
+
+from mptool import (enumerate_mps, load_bounds, load_cobra_model, load_set,
+                    load_weights, sample_mps)
+
+
+def _int_at_least(minimum):
+    """Return an argparse ``type`` parsing an int that must be >= ``minimum``."""
+    def parse(value):
+        ivalue = int(value)
+        if ivalue < minimum:
+            raise argparse.ArgumentTypeError(
+                f'must be an integer >= {minimum}; got {ivalue}')
+        return ivalue
+    return parse
+
+
+def _float_at_least(minimum):
+    """Return an argparse ``type`` parsing a float that must be >= ``minimum``.
+
+    Used where 0 is a meaningful value (``--max-t 0`` and ``--conv-tol 0``
+    both mean "off"), so the bound is inclusive.
+    """
+    def parse(value):
+        fvalue = float(value)
+        if not fvalue >= minimum:          # also rejects nan
+            raise argparse.ArgumentTypeError(
+                f'must be a number >= {minimum}; got {value}')
+        return fvalue
+    return parse
+
+
+def _float_above(bound):
+    """Return an argparse ``type`` parsing a float that must be > ``bound``.
+
+    Used for tolerances and magnitudes that are inoperative at zero, so the
+    CLI rejects them at parse time rather than surfacing a traceback from
+    deep inside the search.
+    """
+    def parse(value):
+        fvalue = float(value)
+        if not fvalue > bound:             # also rejects nan
+            raise argparse.ArgumentTypeError(
+                f'must be a number > {bound}; got {value}')
+        return fvalue
+    return parse
+
+
+def _build_common_parser():
+    """Build the shared parent parser for options common to both subcommands."""
+    common = argparse.ArgumentParser(add_help=False)
+
+    common.add_argument(
+        'model',
+        help='Path to model file (SBML, JSON, or MATLAB format).',
+    )
+
+    common.add_argument(
+        '--subset',
+        metavar='FILE',
+        default=None,
+        help=(
+            'Path to a text file with one reaction ID per line. '
+            'Reactions in this file are the candidates for MPs. '
+            'If omitted, all model reactions are used.'
+        ),
+    )
+    common.add_argument(
+        '--bounds',
+        metavar='FILE',
+        default=None,
+        help=(
+            'Path to a CSV bounds file (reaction_id,lb,ub per line). '
+            'Overrides model bounds for the listed reactions.'
+        ),
+    )
+
+    common.add_argument(
+        '--chunks',
+        type=_int_at_least(2),
+        default=None,
+        dest='chunks',
+        metavar='N',
+        help=(
+            'Per-iteration deletion strategy.  Omit for single-reaction '
+            'deletion (default); pass an integer >= 2 for chunked deletion '
+            'with that many splits per failed chunk.'
+        ),
+    )
+
+    common.add_argument(
+        '--tighten', action=argparse.BooleanOptionalAction, default=True,
+        help='Tighten bounds via flux variability analysis.',
+    )
+    common.add_argument(
+        '--compress', action=argparse.BooleanOptionalAction, default=True,
+        help=(
+            'Losslessly compress the model via FVA-based flux coupling '
+            'before the search.  Requires --tighten.'
+        ),
+    )
+    common.add_argument(
+        '--verbose', action=argparse.BooleanOptionalAction, default=True,
+        help='Print per-MP progress output.',
+    )
+
+    common.add_argument(
+        '--export', action='store_true', default=False,
+        help='Write a run bundle: log, model, solver settings, bounds, '
+             'manifest, plus MPs, MCSs and mapping when the run produces '
+             'them.  The subset is recorded in the manifest, not as a '
+             'separate file.',
+    )
+
+    common.add_argument(
+        '--flux-tol',
+        type=_float_above(0.0),
+        default=1e-9,
+        metavar='FLUX_TOL',
+        help='Threshold below which a flux value or bound is considered '
+             'zero; also sets the Gurobi solver tolerances.',
+    )
+    common.add_argument(
+        '--merge-tol',
+        type=_float_above(0.0),
+        default=1e-6,
+        metavar='MERGE_TOL',
+        help='Numerical-zero threshold on cluster-cancellation residuals '
+             'in compression (only used with --compress).  Unlike '
+             '--flux-tol, the risky direction is tighter: below the 1e-6 '
+             'default the residuals can make the compressed model '
+             'infeasible, and a warning is emitted.',
+    )
+    common.add_argument(
+        '--inf',
+        type=_float_above(0.0),
+        default=1000.0,
+        metavar='INF',
+        help='Largest allowed flux bound (absolute value).',
+    )
+    common.add_argument(
+        '--threads',
+        type=_int_at_least(0),
+        default=0,
+        metavar='N',
+        help='Number of Gurobi solver threads (0 = all available cores).',
+    )
+    common.add_argument(
+        '--max-t',
+        dest='max_t',
+        type=_float_at_least(0.0),
+        default=0.0,
+        metavar='SECONDS',
+        help='Time limit in seconds for the MP search (0 = no limit). '
+             'Preprocessing runs before the clock starts, so total runtime '
+             'is preprocessing plus this budget.',
+    )
+    common.add_argument(
+        '--output-dir',
+        dest='output_dir',
+        default='',
+        metavar='DIR',
+        help='Directory for exported files. Defaults to the current directory.',
+    )
+    common.add_argument(
+        '--seed',
+        type=_int_at_least(0),
+        default=None,
+        metavar='N',
+        help=(
+            'Seed for the random number generator. Two runs with the same '
+            'seed and identical other parameters produce identical results.'
+        ),
+    )
+
+    return common
+
+
+def _build_parser():
+    """Build and return the argument parser for the mptool CLI."""
+    parser = argparse.ArgumentParser(
+        prog='python -m mptool',
+        description=(
+            'Enumerate or sample minimal pathways (MPs) in a metabolic model.'
+        ),
+    )
+    parser.add_argument(
+        '--version', action='version',
+        version=f'%(prog)s {_pkg_version("mptool")}',
+    )
+
+    common = _build_common_parser()
+    subparsers = parser.add_subparsers(dest='command', required=True)
+
+    # ── enumerate ────────────────────────────────────────────────────────────
+    p_enum = subparsers.add_parser(
+        'enumerate', parents=[common],
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        help='Exhaustively enumerate MPs (and MCSs) in the model.',
+        description=(
+            'Exhaustively enumerate minimal pathways (MPs), and minimal cut '
+            'sets (MCSs) with the iterative method, in a metabolic model.'
+        ),
+    )
+    p_enum.add_argument(
+        '--method',
+        default='iterative',
+        choices=('iterative', 'direct'),
+        help=(
+            'Enumeration method. '
+            "'direct' requires --no-graph and is not compatible with "
+            '--chunks; it also finds no MCSs.'
+        ),
+    )
+    p_enum.add_argument(
+        '--mcs-method',
+        dest='mcs_method',
+        default='bip',
+        choices=('bip', 'berge'),
+        help=(
+            "Algorithm for minimal cut candidates (iterative only). "
+            "'bip' uses a Gurobi BIP; 'berge' uses an alternative incremental "
+            "combinatorial enumerator."
+        ),
+    )
+    p_enum.add_argument(
+        '--graph', action=argparse.BooleanOptionalAction, default=True,
+        help=(
+            'Reaction co-occurrence graph acceleration (iterative method '
+            'only; pass --no-graph with --method direct).'
+        ),
+    )
+    p_enum.add_argument(
+        '--max-mps',
+        dest='max_mps',
+        type=_int_at_least(0),
+        default=0,
+        metavar='N',
+        help='Maximum number of MPs to find (0 = no limit).',
+    )
+
+    # ── sample ───────────────────────────────────────────────────────────────
+    p_sample = subparsers.add_parser(
+        'sample', parents=[common],
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        help='Stochastically sample MPs from the model.',
+        description=(
+            'Stochastically sample minimal pathways (MPs) from a metabolic '
+            'model.  Requires at least one of --n-samples or --max-t.'
+        ),
+    )
+    p_sample.add_argument(
+        '--n-samples',
+        dest='n_samples',
+        type=_int_at_least(0),
+        default=0,
+        metavar='N',
+        help='Target number of MPs to sample (0 = no MP limit; then --max-t '
+             'is required).',
+    )
+    p_sample.add_argument(
+        '--weights',
+        metavar='FILE',
+        default=None,
+        help=(
+            'Path to a CSV weights file (reaction_id,weight per line) biasing '
+            'the random ordering. Higher weight -> reaction more likely to be '
+            'retained in sampled MPs.'
+        ),
+    )
+    p_sample.add_argument(
+        '--adaptive', action='store_true', default=False,
+        help='Update weights adaptively after each sample to reduce length '
+             'bias.',
+    )
+    p_sample.add_argument(
+        '--conv-tol',
+        dest='conv_tol',
+        type=_float_at_least(0.0),
+        default=0.0,
+        metavar='CONV_TOL',
+        help='Early-stopping threshold for adaptive sampling (0 = disabled).',
+    )
+    p_sample.add_argument(
+        '--conv-window',
+        dest='conv_window',
+        type=_int_at_least(1),
+        default=10,
+        metavar='N',
+        help='Rolling window for the adaptive convergence check.',
+    )
+
+    return parser
+
+
+def main(argv=None):
+    """Entry point for ``python -m mptool``.
+
+    Parses ``argv`` (or ``sys.argv[1:]`` when None) and dispatches to
+    :func:`enumerate_mps` or :func:`sample_mps` according to the chosen
+    subcommand.
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.subset is not None and not os.path.isfile(args.subset):
+        parser.error(
+            f'--subset: file not found or not a regular file: {args.subset}'
+        )
+
+    if args.bounds is not None and not os.path.isfile(args.bounds):
+        parser.error(
+            f'--bounds: file not found or not a regular file: {args.bounds}'
+        )
+
+    # Compression always tightens bounds; preprocess_model rejects the
+    # combination.  Catch it here as a clean CLI error before any model work.
+    if args.compress and not args.tighten:
+        parser.error(
+            '--compress requires --tighten (compression always tightens bounds)'
+        )
+
+    # enumerate-specific validation, fail-fast before any model work (mirrors
+    # the checks above and enumerate_mps' own guards).  --graph defaults to
+    # True, so `--method direct` on its own would otherwise reach
+    # enumerate_mps and die with an unhandled ValueError traceback; --chunks
+    # is the same incompatibility, reached only when the user passes it.
+    if args.command == 'enumerate' and args.method == 'direct':
+        if args.graph:
+            parser.error(
+                '--method direct is not compatible with --graph: the '
+                'co-occurrence graph accelerates the iterative method only. '
+                'Add --no-graph, e.g. `python -m mptool enumerate MODEL '
+                '--method direct --no-graph`'
+            )
+        if args.chunks is not None:
+            parser.error(
+                '--method direct is not compatible with --chunks: chunked '
+                'deletion is an iterative-method strategy. Drop --chunks, or '
+                'use --method iterative'
+            )
+
+    # sample-specific validation, fail-fast before any model work (mirrors the
+    # subset/bounds existence checks above and sample_mps' own guard).
+    if args.command == 'sample':
+        if not (args.n_samples or args.max_t):
+            parser.error(
+                'sample requires at least one of --n-samples or --max-t '
+                'to terminate sampling'
+            )
+        if args.weights is not None and not os.path.isfile(args.weights):
+            parser.error(
+                f'--weights: file not found or not a regular file: '
+                f'{args.weights}'
+            )
+
+    cobra_model = load_cobra_model(args.model)
+    bounds = load_bounds(args.bounds) if args.bounds is not None else {}
+    subset = load_set(args.subset) if args.subset is not None else None
+
+    preprocess_kwargs = {
+        'bounds': bounds,
+        'tighten': args.tighten,
+        'compress': args.compress,
+        'merge_tol': args.merge_tol,
+        'inf': args.inf,
+    }
+
+    if args.command == 'enumerate':
+        enumerate_mps(
+            cobra_model,
+            subset=subset,
+            method=args.method,
+            chunks=args.chunks,
+            graph=args.graph,
+            mcs_method=args.mcs_method,
+            threads=args.threads,
+            max_mps=args.max_mps,
+            max_t=args.max_t,
+            seed=args.seed,
+            flux_tol=args.flux_tol,
+            verbose=args.verbose,
+            export=args.export,
+            output_dir=args.output_dir,
+            preprocess_kwargs=preprocess_kwargs,
+        )
+    else:
+        weights = load_weights(args.weights) if args.weights is not None \
+            else None
+        sample_mps(
+            cobra_model,
+            subset=subset,
+            n_samples=args.n_samples,
+            weights=weights,
+            adaptive=args.adaptive,
+            conv_tol=args.conv_tol,
+            conv_window=args.conv_window,
+            chunks=args.chunks,
+            threads=args.threads,
+            max_t=args.max_t,
+            seed=args.seed,
+            flux_tol=args.flux_tol,
+            verbose=args.verbose,
+            export=args.export,
+            output_dir=args.output_dir,
+            preprocess_kwargs=preprocess_kwargs,
+        )
+
+
+if __name__ == '__main__':
+    sys.exit(main())